Ruby on Rails | Screencasts | Download | Documentation | Weblog | Community | Source

Changeset 4905

Show
Ignore:
Timestamp:
09/02/06 19:44:16 (2 years ago)
Author:
david
Message:

Modernize the main README (closes #6002)

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/railties/README

    r4888 r4905  
    1414layer entitled Active Record. This layer allows you to present the data from 
    1515database rows as objects and embellish these data objects with business logic 
    16 methods. You can read more about Active Record in  
     16methods. You can read more about Active Record in 
    1717link:files/vendor/rails/activerecord/README.html. 
    1818 
    …… 
    2222unlike the relationship between the Active Record and Action Pack that is much 
    2323more separate. Each of these packages can be used independently outside of 
    24 Rails.  You can read more about Action Pack in  
     24Rails.  You can read more about Action Pack in 
    2525link:files/vendor/rails/actionpack/README.html. 
    2626 
    …… 
    2828== Getting started 
    2929 
    30 1. Start the web server: <tt>ruby script/server</tt> (run with --help for options) 
    31 2. Go to http://localhost:3000/ and get "Welcome aboard: You’re riding the Rails!" 
    32 3. Follow the guidelines to start developing your application 
     301. At the command prompt, start a new rails application using the rails command 
     31   and your application name. Ex: rails myapp 
     32   (If you've downloaded rails in a complete tgz or zip, this step is already done) 
     332. Change directory into myapp and start the web server: <tt>script/server</tt> (run with --help for options) 
     343. Go to http://localhost:3000/ and get "Welcome aboard: You’re riding the Rails!" 
     354. Follow the guidelines to start developing your application 
    3336 
    3437 
    35 == Web servers 
     38== Web Servers 
    3639 
    37 Rails uses the built-in web server in Ruby called WEBrick by default, so you don't 
    38 have to install or configure anything to play around.  
     40By default, Rails will try to use Mongrel and lighttpd if they are installed, otherwise 
     41Rails will use the WEBrick, the webserver that ships with Ruby. When you run script/server, 
     42Rails will check if Mongrel exists, then lighttpd and finally fall back to WEBrick. This ensures 
     43that you can always get up and running quickly. 
    3944 
    40 If you have lighttpd installed, though, it'll be used instead when running script/server. 
    41 It's considerably faster than WEBrick and suited for production use, but requires additional 
     45Mongrel is a Ruby-based webserver with a C-component (which requires compilation) that is 
     46suitable for development and deployment of Rails applications. If you have Ruby Gems installed, 
     47getting up and running with mongrel is as easy as: <tt>gem install mongrel</tt>. 
     48More info at: http://mongrel.rubyforge.org 
     49 
     50If Mongrel is not installed, Rails will look for lighttpd. It's considerably faster than 
     51Mongrel and WEBrick and also suited for production use, but requires additional 
    4252installation and currently only works well on OS X/Unix (Windows users are encouraged 
    43 to start with WEBrick). We recommend version 1.4.11 and higher. You can download it from 
     53to start with Mongrel). We recommend version 1.4.11 and higher. You can download it from 
    4454http://www.lighttpd.net. 
    4555 
    46 If you want something that's halfway between WEBrick and lighttpd, we heartily recommend 
    47 Mongrel. It's a Ruby-based web server with a C-component (so it requires compilation) that 
    48 also works very well with Windows. See more at http://mongrel.rubyforge.org/. 
     56And finally, if neither Mongrel or lighttpd are installed, Rails will use the built-in Ruby 
     57web server, WEBrick. WEBrick is a small Ruby web server suitable for development, but not 
     58for production. 
    4959 
    50 But of course its also possible to run Rails with the premiere open source web server Apache. 
    51 To get decent performance, though, you'll need to install FastCGI. For Apache 1.3, you want 
    52 to use mod_fastcgi. For Apache 2.0+, you want to use mod_fcgid. 
    53  
    54 See http://wiki.rubyonrails.com/rails/pages/FastCGI for more information on FastCGI. 
    55  
    56 == Example for Apache conf 
    57  
    58   <VirtualHost *:80> 
    59     ServerName rails 
    60     DocumentRoot /path/application/public/ 
    61     ErrorLog /path/application/log/server.log 
    62    
    63     <Directory /path/application/public/> 
    64       Options ExecCGI FollowSymLinks 
    65       AllowOverride all 
    66       Allow from all 
    67       Order allow,deny 
    68     </Directory> 
    69   </VirtualHost> 
    70  
    71 NOTE: Be sure that CGIs can be executed in that directory as well. So ExecCGI 
    72 should be on and ".cgi" should respond. All requests from 127.0.0.1 go 
    73 through CGI, so no Apache restart is necessary for changes. All other requests 
    74 go through FCGI (or mod_ruby), which requires a restart to show changes. 
     60But of course its also possible to run Rails on any platform that supports FCGI. 
     61Apache, LiteSpeed, IIS are just a few. For more information on FCGI, 
     62please visit: http://wiki.rubyonrails.com/rails/pages/FastCGI 
    7563 
    7664 
    7765== Debugging Rails 
    7866 
    79 Have "tail -f" commands running on both the server.log, production.log, and 
    80 test.log files. Rails will automatically display debugging and runtime 
    81 information to these files. Debugging info will also be shown in the browser 
    82 on requests from 127.0.0.1. 
     67Have "tail -f" commands running on the server.log and development.log. Rails will 
     68automatically display debugging and runtime information to these files. Debugging 
     69info will also be shown in the browser on requests from 127.0.0.1. 
    8370 
    8471 
    …… 
    9582    end 
    9683  end 
    97    
     84 
    9885So the controller will accept the action, run the first line, then present you 
    9986with a IRB prompt in the breakpointer window. Here you can do things like: 
    …… 
    10289 
    10390  >> @posts.inspect 
    104   => "[#<Post:0x14a6be8 @attributes={\"title\"=>nil, \"body\"=>nil, \"id\"=>\"1\"}>,  
     91  => "[#<Post:0x14a6be8 @attributes={\"title\"=>nil, \"body\"=>nil, \"id\"=>\"1\"}>, 
    10592       #<Post:0x14a6620 @attributes={\"title\"=>\"Rails you know!\", \"body\"=>\"Only ten..\", \"id\"=>\"2\"}>]" 
    10693  >> @posts.first.title = "hello from a breakpoint" 
    …… 
    10996...and even better is that you can examine how your runtime objects actually work: 
    11097 
    111   >> f = @posts.first  
     98  >> f = @posts.first 
    11299  => #<Post:0x13630c4 @attributes={"title"=>nil, "body"=>nil, "id"=>"1"}> 
    113100  >> f. 
    …… 
    119106== Console 
    120107 
    121 You can interact with the domain model by starting the console through script/console.  
     108You can interact with the domain model by starting the console through <tt>script/console</tt>. 
    122109Here you'll have all parts of the application configured, just like it is when the 
    123110application is running. You can inspect domain models, change values, and save to the 
    …… 
    128115 
    129116 
    130  
    131117== Description of contents 
    132118 
    …… 
    135121 
    136122app/controllers 
    137   Holds controllers that should be named like weblog_controller.rb for 
    138   automated URL mapping. All controllers should descend from 
    139   ActionController::Base. 
     123  Holds controllers that should be named like weblogs_controller.rb for 
     124  automated URL mapping. All controllers should descend from ApplicationController 
     125  which itself descends from ActionController::Base. 
    140126 
    141127app/models 
    142128  Holds models that should be named like post.rb. 
    143129  Most models will descend from ActiveRecord::Base. 
    144    
     130 
    145131app/views 
    146132  Holds the template files for the view that should be named like 
    147   weblog/index.rhtml for the WeblogController#index action. All views use eRuby 
    148   syntax. This directory can also be used to keep stylesheets, images, and so on 
    149   that can be symlinked to public. 
    150    
     133  weblogs/index.rhtml for the WeblogsController#index action. All views use eRuby 
     134  syntax. 
     135 
     136app/views/layouts 
     137  Holds the template files for layouts to be used with views. This models the common 
     138  header/footer method of wrapping views. In your views, define a layout using the 
     139  <tt>layout :default</tt> and create a file named default.rhtml. Inside default.rhtml, 
     140  call <% yield %> to render the view using this layout. 
     141 
    151142app/helpers 
    152   Holds view helpers that should be named like weblog_helper.rb. 
    153  
    154 app/apis 
    155   Holds API classes for web services. 
     143  Holds view helpers that should be named like weblogs_helper.rb. These are generated 
     144  for you automatically when using script/generate for controllers. Helpers can be used to 
     145  wrap functionality for your views into methods. 
    156146 
    157147config 
    …… 
    165155  the sequence of Migrations for your schema. 
    166156 
     157doc 
     158  This directory is where your application documentation will be stored when generated 
     159  using <tt>rake doc:app</tt> 
     160 
    167161lib 
    168162  Application specific libraries. Basically, any kind of custom code that doesn't 
    169163  belong under controllers, models, or helpers. This directory is in the load path. 
    170      
     164 
    171165public 
    172166  The directory available for the web server. Contains subdirectories for images, stylesheets, 
    173   and javascripts. Also contains the dispatchers and the default HTML files. 
     167  and javascripts. Also contains the dispatchers and the default HTML files. This should be 
     168  set as the DOCUMENT_ROOT of your web server. 
    174169 
    175170script 
    …… 
    177172 
    178173test 
    179   Unit and functional tests along with fixtures. 
     174  Unit and functional tests along with fixtures. When using the script/generate scripts, template 
     175  test files will be generated for you and placed in this directory. 
    180176 
    181177vendor