diff options
author | Colin Curtin <colin@procore.com> | 2008-11-12 16:00:27 -0800 |
---|---|---|
committer | Colin Curtin <colin@procore.com> | 2008-11-12 16:00:27 -0800 |
commit | bb0fead1dbc1470717019efcabe6c90da3cf934d (patch) | |
tree | 25cdcc8c68b4a76a719dd91bc18eabca83fa8dc3 /railties | |
parent | af320ef2202feaca376f759968aa4f5d977b0db3 (diff) | |
download | rails-bb0fead1dbc1470717019efcabe6c90da3cf934d.tar.gz rails-bb0fead1dbc1470717019efcabe6c90da3cf934d.tar.bz2 rails-bb0fead1dbc1470717019efcabe6c90da3cf934d.zip |
The beginnings of a command line tutorial
Diffstat (limited to 'railties')
-rw-r--r-- | railties/doc/guides/source/command_line.txt | 147 |
1 files changed, 147 insertions, 0 deletions
diff --git a/railties/doc/guides/source/command_line.txt b/railties/doc/guides/source/command_line.txt new file mode 100644 index 0000000000..5f7c6ceff5 --- /dev/null +++ b/railties/doc/guides/source/command_line.txt @@ -0,0 +1,147 @@ +A Guide to The Rails Command Line +================================= + +Rails comes with every command line tool you'll need to + +* Create a Rails application +* Generate models, controllers, database migrations, and unit tests +* Start a development server +* Mess with objects through an interactive shell +* Profile and benchmark your new creation + +... and much, much more! (Buy now!) + +This tutorial assumes you have basic Rails knowledge from reading the Getting Started with Rails Guide. + +== Command Line Basics == + +There are a few commands that are absolutely critical to your everyday usage of Rails. In the order of how much you'll probably use them are: + +* console +* server +* rake +* generate +* rails + +Let's create a simple Rails application to step through each of these commands in context. + +=== rails === + +The first thing we'll want to do is create a new Rails application by running the `rails` command after installing Rails. + +NOTE: You know you need the rails gem installed by typing `gem install rails` first, right? Okay, okay, just making sure. + +[source,shell] +------------------------------------------------------ +$ rails commandsapp + + create + create app/controllers + create app/helpers + create app/models + ... + ... + create log/production.log + create log/development.log + create log/test.log +------------------------------------------------------ + +Rails will set you up with what seems like a huge amount of stuff for such a tiny command! You've got the entire Rails directory structure now with all the code you need to run our simple application right out of the box. + +NOTE: This output will seem very familiar when we get to the `generate` command. Creepy foreshadowing! + +=== server === + +Let's try it! The `server` command launches a small web server written in Ruby named WEBrick which was also installed when you installed Rails. You'll use this any time you want to view your work through a web browser. + +NOTE: WEBrick isn't your only option for serving Rails. We'll get to that in a later section. [XXX: which section] + +Here we'll flex our `server` command, which without any prodding of any kind will run our new shiny Rails app: + +[source,shell] +------------------------------------------------------ +$ cd commandsapp +$ ./script/server +=> Booting WEBrick... +=> Rails 2.2.0 application started on http://0.0.0.0:3000 +=> Ctrl-C to shutdown server; call with --help for options +[2008-11-04 10:11:38] INFO WEBrick 1.3.1 +[2008-11-04 10:11:38] INFO ruby 1.8.5 (2006-12-04) [i486-linux] +[2008-11-04 10:11:38] INFO WEBrick::HTTPServer#start: pid=18994 port=3000 +------------------------------------------------------ + +WHOA. With just three commands we whipped up a Rails server listening on port 3000. Go! Go right now to your browser and go to http://localhost:3000. I'll wait. + +See? Cool! It doesn't do much yet, but we'll change that. + +=== generate === + +The `generate` command uses templates to create a whole lot of things. You can always find out what's available by running `generate` by itself. Let's do that: + +[source,shell] +------------------------------------------------------ +$ ./script/generate +Usage: ./script/generate generator [options] [args] + +... +... + +Installed Generators + Builtin: controller, integration_test, mailer, migration, model, observer, performance_test, plugin, resource, scaffold, session_migration + +... +... +------------------------------------------------------ + +NOTE: You can install more generators through generator gems, portions of plugins you'll undoubtedly install, and you can even create your own! + +Using generators will save you a large amount of time by writing *boilerplate code* for you -- necessary for the darn thing to work, but not necessary for you to spend time writing. That's what we have computers for, right? + +Let's make our own controller with the controller generator. But what command should we use? Let's ask the generator: + +NOTE: All Rails console utilities have help text. For commands that require a lot of input to run correctly, you can just try the command without any parameters (like `rails` or `./script/generate`). For others, you can try adding `--help` or `-h` to the end, as in `./script/server --help`. + +[source,shell] +------------------------------------------------------ +$ ./script/generate controller +Usage: ./script/generate controller ControllerName [options] + +... +... + +Example: + `./script/generate controller CreditCard open debit credit close` + + Credit card controller with URLs like /credit_card/debit. + Controller: app/controllers/credit_card_controller.rb + Views: app/views/credit_card/debit.html.erb [...] + Helper: app/helpers/credit_card_helper.rb + Test: test/functional/credit_card_controller_test.rb + +Modules Example: + `./script/generate controller 'admin/credit_card' suspend late_fee` + + Credit card admin controller with URLs /admin/credit_card/suspend. + Controller: app/controllers/admin/credit_card_controller.rb + Views: app/views/admin/credit_card/debit.html.erb [...] + Helper: app/helpers/admin/credit_card_helper.rb + Test: test/functional/admin/credit_card_controller_test.rb +------------------------------------------------------ + +Ah, the controller generator is expecting parameters in the form of `generate controller ControllerName action1 action2`. Let's make a `Greetings` controller with an action of *hello*, which will say something nice to us. + +[source,shell] +------------------------------------------------------ +$ ./script/generate controller Greeting hello + exists app/controllers/ + exists app/helpers/ + create app/views/greeting + exists test/functional/ + create app/controllers/greetings_controller.rb + create test/functional/greetings_controller_test.rb + create app/helpers/greetings_helper.rb + create app/views/greetings/hello.html.erb +------------------------------------------------------ + +Look there! Now what all did this generate? It looks like it made sure a bunch of directories were in our application, and created a controller file, a functional test file, a helper for the view, and a view file. All from one command! + |