vendor/rails/railties/doc/guides/html/command_line.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
   3 <head>
   4         <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   5         <title>A Guide to The Rails Command Line</title>
   6         <!--[if lt IE 8]>
   7         <script src="http://ie7-js.googlecode.com/svn/version/2.0(beta3)/IE8.js" type="text/javascript"></script>
   8         <![endif]-->
   9         <link href="stylesheets/base.css" media="screen" rel="Stylesheet" type="text/css" />
  10         <link href="stylesheets/forms.css" media="screen" rel="Stylesheet" type="text/css" />
  11         <link href="stylesheets/more.css" media="screen" rel="Stylesheet" type="text/css" />
  12         <style type="text/css">
  13                 div#container {
  14         max-width: 900px;
  15         padding-bottom: 3em;
  16 }
  17
  18 div#content {
  19         margin-left: 200px;
  20 }
  21
  22 div#container.notoc {
  23         max-width: 600px;
  24 }
  25
  26 .notoc div#content {
  27         margin-left: 0;
  28 }
  29
  30 pre {
  31         line-height: 1.4em;
  32 }
  33
  34 #content p tt {
  35         background: #eeeeee;
  36         border: solid 1px #cccccc;
  37         padding: 3px;
  38 }
  39
  40 dt {
  41         font-weight: bold;
  42 }
  43
  44 #content dt tt {
  45         font-size: 10pt;
  46 }
  47
  48 dd {
  49         margin-left: 3em;
  50 }
  51
  52 #content dt tt, #content pre tt {
  53         background: none;
  54         padding: 0;
  55         border: 0;
  56 }
  57
  58 #content .olist ol {
  59         margin-left: 2em;
  60 }
  61
  62 #header {
  63         position: relative;
  64         max-width: 840px;
  65         margin-left: auto;
  66         margin-right: auto;
  67 }
  68
  69 #header.notoc {
  70         max-width: 580px;
  71 }
  72
  73 #logo {
  74         position: absolute;
  75         left: 10px;
  76         top: 10px;
  77         width: 110px;
  78         height: 140px;
  79 }
  80
  81 div#header h1#site_title {
  82         background: url('images/ruby_on_rails_by_mike_rundle2.gif') top left no-repeat;
  83         position: absolute;
  84         width: 392px;
  85         height: 55px;
  86         left: 145px;
  87         top: 20px;
  88         margin: 0;
  89         padding: 0;
  90 }
  91
  92 #site_title span {
  93         display: none;
  94 }
  95
  96 #site_title_tagline {
  97         display: none;
  98 }
  99
 100 ul#navMain {
 101         position: absolute;
 102         margin: 0;
 103         padding: 0;
 104         top: 97px;
 105         left: 145px;
 106 }
 107
 108 .left-floaty, .right-floaty {
 109         padding: 15px;
 110 }
 111
 112 .admonitionblock,
 113 .tableblock {
 114         margin-left: 1em;
 115         margin-right: 1em;
 116         margin-top: 0.25em;
 117         margin-bottom: 1em;
 118 }
 119
 120 .admonitionblock .icon {
 121         padding-right: 8px;
 122 }
 123
 124 .admonitionblock .content {
 125         border: solid 1px #ffda78;
 126         background: #fffebd;
 127         padding: 10px;
 128         padding-top: 8px;
 129         padding-bottom: 8px;
 130 }
 131
 132 .admonitionblock .title {
 133         font-size: 140%;
 134         margin-bottom: 0.5em;
 135 }
 136
 137 .tableblock table {
 138         border: solid 1px #aaaaff;
 139         background: #f0f0ff;
 140 }
 141
 142 .tableblock th {
 143         background: #e0e0e0;
 144 }
 145
 146 .tableblock th,
 147 .tableblock td {
 148         padding: 3px;
 149         padding-left: 5px;
 150         padding-right: 5px;
 151 }
 152
 153 .sidebarblock {
 154         margin-top: 0.25em;
 155         margin: 1em;
 156         border: solid 1px #ccccbb;
 157         padding: 8px;
 158         background: #ffffe0;
 159 }
 160
 161 .sidebarblock .sidebar-title {
 162         font-size: 140%;
 163         font-weight: 600;
 164         margin-bottom: 0.3em;
 165 }
 166
 167 .sidebarblock .sidebar-content > .para:last-child > p {
 168         margin-bottom: 0;
 169 }
 170
 171 .sidebarblock .sidebar-title a {
 172         text-decoration: none;
 173 }
 174
 175 .sidebarblock .sidebar-title a:hover {
 176         text-decoration: underline;
 177 }
 178
 179         </style>
 180 </head>
 181 <body>
 182         <div id="header" >
 183                 <div id="logo">
 184                         <a href="index.html" title="Ruby on Rails"><img src="images/rails_logo_remix.gif" alt="Rails" height="140" width="110" /></a>
 185                 </div>
 186
 187                 <h1 id="site_title"><span>Ruby on Rails</span></h1>
 188                 <h2 id="site_title_tagline">Sustainable productivity for web-application development</h2>
 189
 190                 <ul id="navMain">
 191                         <li class="first-child"><a href="http://www.rubyonrails.org/" title="Ruby on Rails" class="ruby_on_rails">Ruby on Rails</a></li>
 192                         <li><a class="manuals" href="index.html" title="Manuals Index">Guides Index</a></li>
 193                 </ul>
 194         </div>
 195
 196         <div id="container">
 197
 198                 <div id="sidebar">
 199                         <h2>Chapters</h2>
 200                         <ol>
 201                                         <li>
 202                                         <a href="#_command_line_basics">Command Line Basics</a>
 203                                                 <ul>
 204
 205                                                         <li><a href="#_rails">rails</a></li>
 206
 207                                                         <li><a href="#_server">server</a></li>
 208
 209                                                         <li><a href="#_generate">generate</a></li>
 210
 211                                                 </ul>
 212                                         </li>
 213                         </ol>
 214                 </div>
 215
 216                 <div id="content">
 217                                 <h1>A Guide to The Rails Command Line</h1>
 218                         <div id="preamble">
 219 <div class="sectionbody">
 220 <div class="para"><p>Rails comes with every command line tool you'll need to</p></div>
 221 <div class="ilist"><ul>
 222 <li>
 223 <p>
 224 Create a Rails application
 225 </p>
 226 </li>
 227 <li>
 228 <p>
 229 Generate models, controllers, database migrations, and unit tests
 230 </p>
 231 </li>
 232 <li>
 233 <p>
 234 Start a development server
 235 </p>
 236 </li>
 237 <li>
 238 <p>
 239 Mess with objects through an interactive shell
 240 </p>
 241 </li>
 242 <li>
 243 <p>
 244 Profile and benchmark your new creation
 245 </p>
 246 </li>
 247 </ul></div>
 248 <div class="para"><p>&#8230; and much, much more! (Buy now!)</p></div>
 249 <div class="para"><p>This tutorial assumes you have basic Rails knowledge from reading the Getting Started with Rails Guide.</p></div>
 250 </div>
 251 </div>
 252 <h2 id="_command_line_basics">1. Command Line Basics</h2>
 253 <div class="sectionbody">
 254 <div class="para"><p>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:</p></div>
 255 <div class="ilist"><ul>
 256 <li>
 257 <p>
 258 console
 259 </p>
 260 </li>
 261 <li>
 262 <p>
 263 server
 264 </p>
 265 </li>
 266 <li>
 267 <p>
 268 rake
 269 </p>
 270 </li>
 271 <li>
 272 <p>
 273 generate
 274 </p>
 275 </li>
 276 <li>
 277 <p>
 278 rails
 279 </p>
 280 </li>
 281 </ul></div>
 282 <div class="para"><p>Let's create a simple Rails application to step through each of these commands in context.</p></div>
 283 <h3 id="_rails">1.1. rails</h3>
 284 <div class="para"><p>The first thing we'll want to do is create a new Rails application by running the <tt>rails</tt> command after installing Rails.</p></div>
 285 <div class="admonitionblock">
 286 <table><tr>
 287 <td class="icon">
 288 <img src="./images/icons/note.png" alt="Note" />
 289 </td>
 290 <td class="content">You know you need the rails gem installed by typing <tt>gem install rails</tt> first, right? Okay, okay, just making sure.</td>
 291 </tr></table>
 292 </div>
 293 <div class="listingblock">
 294 <div class="content"><!-- Generator: GNU source-highlight 2.9
 295 by Lorenzo Bettini
 296 http://www.lorenzobettini.it
 297 http://www.gnu.org/software/src-highlite -->
 298 <pre><tt>$ rails commandsapp
 299
 300      create
 301      create  app/controllers
 302      create  app/helpers
 303      create  app/models
 304      <span style="color: #990000">...</span>
 305      <span style="color: #990000">...</span>
 306      create  log/production<span style="color: #990000">.</span>log
 307      create  log/development<span style="color: #990000">.</span>log
 308      create  log/test<span style="color: #990000">.</span>log
 309 </tt></pre></div></div>
 310 <div class="para"><p>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.</p></div>
 311 <div class="admonitionblock">
 312 <table><tr>
 313 <td class="icon">
 314 <img src="./images/icons/note.png" alt="Note" />
 315 </td>
 316 <td class="content">This output will seem very familiar when we get to the <tt>generate</tt> command. Creepy foreshadowing!</td>
 317 </tr></table>
 318 </div>
 319 <h3 id="_server">1.2. server</h3>
 320 <div class="para"><p>Let's try it! The <tt>server</tt> 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.</p></div>
 321 <div class="admonitionblock">
 322 <table><tr>
 323 <td class="icon">
 324 <img src="./images/icons/note.png" alt="Note" />
 325 </td>
 326 <td class="content">WEBrick isn't your only option for serving Rails. We'll get to that in a later section. [XXX: which section]</td>
 327 </tr></table>
 328 </div>
 329 <div class="para"><p>Here we'll flex our <tt>server</tt> command, which without any prodding of any kind will run our new shiny Rails app:</p></div>
 330 <div class="listingblock">
 331 <div class="content"><!-- Generator: GNU source-highlight 2.9
 332 by Lorenzo Bettini
 333 http://www.lorenzobettini.it
 334 http://www.gnu.org/software/src-highlite -->
 335 <pre><tt>$ cd commandsapp
 336 $ <span style="color: #990000">.</span>/script/server
 337 <span style="color: #990000">=&gt;</span> Booting WEBrick<span style="color: #990000">...</span>
 338 <span style="color: #990000">=&gt;</span> Rails <span style="color: #993399">2.2</span><span style="color: #990000">.</span><span style="color: #993399">0</span> application started on http<span style="color: #990000">://</span><span style="color: #993399">0.0</span><span style="color: #990000">.</span><span style="color: #993399">0.0</span><span style="color: #990000">:</span><span style="color: #993399">3000</span>
 339 <span style="color: #990000">=&gt;</span> Ctrl-C to shutdown server<span style="color: #990000">;</span> call with --help <span style="font-weight: bold"><span style="color: #0000FF">for</span></span> options
 340 <span style="color: #990000">[</span><span style="color: #993399">2008</span>-<span style="color: #993399">11</span>-<span style="color: #993399">04</span> <span style="color: #993399">10</span><span style="color: #990000">:</span><span style="color: #993399">11</span><span style="color: #990000">:</span><span style="color: #993399">38</span><span style="color: #990000">]</span> INFO  WEBrick <span style="color: #993399">1.3</span><span style="color: #990000">.</span><span style="color: #993399">1</span>
 341 <span style="color: #990000">[</span><span style="color: #993399">2008</span>-<span style="color: #993399">11</span>-<span style="color: #993399">04</span> <span style="color: #993399">10</span><span style="color: #990000">:</span><span style="color: #993399">11</span><span style="color: #990000">:</span><span style="color: #993399">38</span><span style="color: #990000">]</span> INFO  ruby <span style="color: #993399">1.8</span><span style="color: #990000">.</span><span style="color: #993399">5</span> <span style="color: #990000">(</span><span style="color: #993399">2006</span>-<span style="color: #993399">12</span>-<span style="color: #993399">04</span><span style="color: #990000">)</span> <span style="color: #990000">[</span>i486-linux<span style="color: #990000">]</span>
 342 <span style="color: #990000">[</span><span style="color: #993399">2008</span>-<span style="color: #993399">11</span>-<span style="color: #993399">04</span> <span style="color: #993399">10</span><span style="color: #990000">:</span><span style="color: #993399">11</span><span style="color: #990000">:</span><span style="color: #993399">38</span><span style="color: #990000">]</span> INFO  WEBrick<span style="color: #990000">::</span>HTTPServer<span style="font-style: italic"><span style="color: #9A1900">#start: pid=18994 port=3000</span></span>
 343 </tt></pre></div></div>
 344 <div class="para"><p>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 <a href="http://localhost:3000">http://localhost:3000</a>. I'll wait.</p></div>
 345 <div class="para"><p>See? Cool! It doesn't do much yet, but we'll change that.</p></div>
 346 <h3 id="_generate">1.3. generate</h3>
 347 <div class="para"><p>The <tt>generate</tt> command uses templates to create a whole lot of things. You can always find out what's available by running <tt>generate</tt> by itself. Let's do that:</p></div>
 348 <div class="listingblock">
 349 <div class="content"><!-- Generator: GNU source-highlight 2.9
 350 by Lorenzo Bettini
 351 http://www.lorenzobettini.it
 352 http://www.gnu.org/software/src-highlite -->
 353 <pre><tt>$ <span style="color: #990000">.</span>/script/generate
 354 Usage<span style="color: #990000">:</span> <span style="color: #990000">.</span>/script/generate generator <span style="color: #990000">[</span>options<span style="color: #990000">]</span> <span style="color: #990000">[</span>args<span style="color: #990000">]</span>
 355
 356 <span style="color: #990000">...</span>
 357 <span style="color: #990000">...</span>
 358
 359 Installed Generators
 360   Builtin<span style="color: #990000">:</span> controller<span style="color: #990000">,</span> integration_test<span style="color: #990000">,</span> mailer<span style="color: #990000">,</span> migration<span style="color: #990000">,</span> model<span style="color: #990000">,</span> observer<span style="color: #990000">,</span> performance_test<span style="color: #990000">,</span> plugin<span style="color: #990000">,</span> resource<span style="color: #990000">,</span> scaffold<span style="color: #990000">,</span> session_migration
 361
 362 <span style="color: #990000">...</span>
 363 <span style="color: #990000">...</span>
 364 </tt></pre></div></div>
 365 <div class="admonitionblock">
 366 <table><tr>
 367 <td class="icon">
 368 <img src="./images/icons/note.png" alt="Note" />
 369 </td>
 370 <td class="content">You can install more generators through generator gems, portions of plugins you'll undoubtedly install, and you can even create your own!</td>
 371 </tr></table>
 372 </div>
 373 <div class="para"><p>Using generators will save you a large amount of time by writing <strong>boilerplate code</strong> for you &#8212; necessary for the darn thing to work, but not necessary for you to spend time writing. That's what we have computers for, right?</p></div>
 374 <div class="para"><p>Let's make our own controller with the controller generator. But what command should we use? Let's ask the generator:</p></div>
 375 <div class="admonitionblock">
 376 <table><tr>
 377 <td class="icon">
 378 <img src="./images/icons/note.png" alt="Note" />
 379 </td>
 380 <td class="content">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 <tt>rails</tt> or <tt>./script/generate</tt>). For others, you can try adding <tt>&#8212;help</tt> or <tt>-h</tt> to the end, as in <tt>./script/server &#8212;help</tt>.</td>
 381 </tr></table>
 382 </div>
 383 <div class="listingblock">
 384 <div class="content"><!-- Generator: GNU source-highlight 2.9
 385 by Lorenzo Bettini
 386 http://www.lorenzobettini.it
 387 http://www.gnu.org/software/src-highlite -->
 388 <pre><tt>$ <span style="color: #990000">.</span>/script/generate controller
 389 Usage<span style="color: #990000">:</span> <span style="color: #990000">.</span>/script/generate controller ControllerName <span style="color: #990000">[</span>options<span style="color: #990000">]</span>
 390
 391 <span style="color: #990000">...</span>
 392 <span style="color: #990000">...</span>
 393
 394 Example<span style="color: #990000">:</span>
 395     `<span style="color: #990000">.</span>/script/generate controller CreditCard open debit credit close`
 396
 397     Credit card controller with URLs like /credit_card/debit<span style="color: #990000">.</span>
 398         Controller<span style="color: #990000">:</span> app/controllers/credit_card_controller<span style="color: #990000">.</span>rb
 399         Views<span style="color: #990000">:</span>      app/views/credit_card/debit<span style="color: #990000">.</span>html<span style="color: #990000">.</span>erb <span style="color: #990000">[...]</span>
 400         Helper<span style="color: #990000">:</span>     app/helpers/credit_card_helper<span style="color: #990000">.</span>rb
 401         Test<span style="color: #990000">:</span>       test/functional/credit_card_controller_test<span style="color: #990000">.</span>rb
 402
 403 Modules Example<span style="color: #990000">:</span>
 404     `<span style="color: #990000">.</span>/script/generate controller <span style="color: #FF0000">'admin/credit_card'</span> <span style="font-weight: bold"><span style="color: #0000FF">suspend</span></span> late_fee`
 405
 406     Credit card admin controller with URLs /admin/credit_card/suspend<span style="color: #990000">.</span>
 407         Controller<span style="color: #990000">:</span> app/controllers/admin/credit_card_controller<span style="color: #990000">.</span>rb
 408         Views<span style="color: #990000">:</span>      app/views/admin/credit_card/debit<span style="color: #990000">.</span>html<span style="color: #990000">.</span>erb <span style="color: #990000">[...]</span>
 409         Helper<span style="color: #990000">:</span>     app/helpers/admin/credit_card_helper<span style="color: #990000">.</span>rb
 410         Test<span style="color: #990000">:</span>       test/functional/admin/credit_card_controller_test<span style="color: #990000">.</span>rb
 411 </tt></pre></div></div>
 412 <div class="para"><p>Ah, the controller generator is expecting parameters in the form of <tt>generate controller ControllerName action1 action2</tt>. Let's make a <tt>Greetings</tt> controller with an action of <strong>hello</strong>, which will say something nice to us.</p></div>
 413 <div class="listingblock">
 414 <div class="content"><!-- Generator: GNU source-highlight 2.9
 415 by Lorenzo Bettini
 416 http://www.lorenzobettini.it
 417 http://www.gnu.org/software/src-highlite -->
 418 <pre><tt>$ <span style="color: #990000">.</span>/script/generate controller Greeting hello
 419      exists  app/controllers<span style="color: #990000">/</span>
 420      exists  app/helpers<span style="color: #990000">/</span>
 421      create  app/views/greeting
 422      exists  test/functional<span style="color: #990000">/</span>
 423      create  app/controllers/greetings_controller<span style="color: #990000">.</span>rb
 424      create  test/functional/greetings_controller_test<span style="color: #990000">.</span>rb
 425      create  app/helpers/greetings_helper<span style="color: #990000">.</span>rb
 426      create  app/views/greetings/hello<span style="color: #990000">.</span>html<span style="color: #990000">.</span>erb
 427 </tt></pre></div></div>
 428 <div class="para"><p>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!</p></div>
 429 </div>
 430
 431                 </div>
 432         </div>
 433 </body>
 434 </html>