diff options
author | Prem Sichanugrist <s@sikachu.com> | 2012-09-01 21:37:59 -0400 |
---|---|---|
committer | Prem Sichanugrist <s@sikac.hu> | 2012-09-17 15:54:23 -0400 |
commit | 31ef4cf656785a190723d2d8fb4c0fd06f4009bc (patch) | |
tree | 582a93b9441b41c1150ae421a2a878194af6475e /guides/source/initialization.md | |
parent | ed62b1bf0b6fff53524c168f9615af84dea99537 (diff) | |
download | rails-31ef4cf656785a190723d2d8fb4c0fd06f4009bc.tar.gz rails-31ef4cf656785a190723d2d8fb4c0fd06f4009bc.tar.bz2 rails-31ef4cf656785a190723d2d8fb4c0fd06f4009bc.zip |
Convert all inline codes to Markdown syntax
Diffstat (limited to 'guides/source/initialization.md')
-rw-r--r-- | guides/source/initialization.md | 170 |
1 files changed, 85 insertions, 85 deletions
diff --git a/guides/source/initialization.md b/guides/source/initialization.md index 6fbaa6a4a7..203080cc1d 100644 --- a/guides/source/initialization.md +++ b/guides/source/initialization.md @@ -4,7 +4,7 @@ The Rails Initialization Process This guide explains the internals of the initialization process in Rails as of Rails 4. It is an extremely in-depth guide and recommended for advanced Rails developers. -* Using +rails server+ +* Using `rails server` -------------------------------------------------------------------------------- @@ -17,18 +17,18 @@ server+ to boot your app. NOTE: Paths in this guide are relative to Rails or a Rails application unless otherwise specified. TIP: If you want to follow along while browsing the Rails "source -code":https://github.com/rails/rails, we recommend that you use the +t+ +code":https://github.com/rails/rails, we recommend that you use the `t` key binding to open the file finder inside GitHub and find files quickly. Launch! ------- -A Rails application is usually started with the command +rails server+. +A Rails application is usually started with the command `rails server`. -### +bin/rails+ +### `bin/rails` -The actual +rails+ command is kept in _bin/rails_: +The actual `rails` command is kept in _bin/rails_: ```ruby #!/usr/bin/env ruby @@ -40,10 +40,10 @@ end require "rails/cli" ``` -This file will first attempt to push the +railties/lib+ directory if -present, and then requires +rails/cli+. +This file will first attempt to push the `railties/lib` directory if +present, and then requires `rails/cli`. -### +railties/lib/rails/cli.rb+ +### `railties/lib/rails/cli.rb` This file looks like this: @@ -66,7 +66,7 @@ else end ``` -The +rbconfig+ file from the Ruby standard library provides us with the +RbConfig+ class which contains detailed information about the Ruby environment, including how Ruby was compiled. We can see this in use in +railties/lib/rails/script_rails_loader+. +The `rbconfig` file from the Ruby standard library provides us with the `RbConfig` class which contains detailed information about the Ruby environment, including how Ruby was compiled. We can see this in use in `railties/lib/rails/script_rails_loader`. ```ruby require 'pathname' @@ -81,15 +81,15 @@ module Rails end ``` -The +rails/script_rails_loader+ file uses +RbConfig::Config+ to obtain the +bin_dir+ and +ruby_install_name+ values for the configuration which together form the path to the Ruby interpreter. The +RbConfig::CONFIG["EXEEXT"]+ will suffix this path with ".exe" if the script is running on Windows. This constant is used later on in +exec_script_rails!+. As for the +SCRIPT_RAILS+ constant, we'll see that when we get to the +in_rails_application?+ method. +The `rails/script_rails_loader` file uses `RbConfig::Config` to obtain the `bin_dir` and `ruby_install_name` values for the configuration which together form the path to the Ruby interpreter. The `RbConfig::CONFIG["EXEEXT"]` will suffix this path with ".exe" if the script is running on Windows. This constant is used later on in `exec_script_rails!`. As for the `SCRIPT_RAILS` constant, we'll see that when we get to the `in_rails_application?` method. -Back in +rails/cli+, the next line is this: +Back in `rails/cli`, the next line is this: ```ruby Rails::ScriptRailsLoader.exec_script_rails! ``` -This method is defined in +rails/script_rails_loader+: +This method is defined in `rails/script_rails_loader`: ```ruby def self.exec_script_rails! @@ -106,7 +106,7 @@ rescue SystemCallError end ``` -This method will first check if the current working directory (+cwd+) is a Rails application or a subdirectory of one. This is determined by the +in_rails_application?+ method: +This method will first check if the current working directory (`cwd`) is a Rails application or a subdirectory of one. This is determined by the `in_rails_application?` method: ```ruby def self.in_rails_application? @@ -114,7 +114,7 @@ def self.in_rails_application? end ``` -The +SCRIPT_RAILS+ constant defined earlier is used here, with +File.exists?+ checking for its presence in the current directory. If this method returns +false+ then +in_rails_application_subdirectory?+ will be used: +The `SCRIPT_RAILS` constant defined earlier is used here, with `File.exists?` checking for its presence in the current directory. If this method returns `false` then `in_rails_application_subdirectory?` will be used: ```ruby def self.in_rails_application_subdirectory?(path = Pathname.new(Dir.pwd)) @@ -122,24 +122,24 @@ def self.in_rails_application_subdirectory?(path = Pathname.new(Dir.pwd)) end ``` -This climbs the directory tree until it reaches a path which contains a +script/rails+ file. If a directory containing this file is reached then this line will run: +This climbs the directory tree until it reaches a path which contains a `script/rails` file. If a directory containing this file is reached then this line will run: ```ruby exec RUBY, SCRIPT_RAILS, *ARGV if in_rails_application? ``` -This is effectively the same as running +ruby script/rails [arguments]+, where +[arguments]+ at this point in time is simply "server". +This is effectively the same as running `ruby script/rails [arguments]`, where `[arguments]` at this point in time is simply "server". Rails Initialization -------------------- Only now we finally start the real initialization process, beginning -with +script/rails+. +with `script/rails`. -TIP: If you execute +script/rails+ directly from your Rails app you will +TIP: If you execute `script/rails` directly from your Rails app you will skip executing all the code that we've just described. -### +script/rails+ +### `script/rails` This file is as follows: @@ -149,11 +149,11 @@ require File.expand_path('../../config/boot', __FILE__) require 'rails/commands' ``` -The +APP_PATH+ constant will be used later in +rails/commands+. The +config/boot+ file referenced here is the +config/boot.rb+ file in our application which is responsible for loading Bundler and setting it up. +The `APP_PATH` constant will be used later in `rails/commands`. The `config/boot` file referenced here is the `config/boot.rb` file in our application which is responsible for loading Bundler and setting it up. -### +config/boot.rb+ +### `config/boot.rb` -+config/boot.rb+ contains: +`config/boot.rb` contains: ```ruby # Set up gems listed in the Gemfile. @@ -162,10 +162,10 @@ ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', __FILE__) require 'bundler/setup' if File.exists?(ENV['BUNDLE_GEMFILE']) ``` -In a standard Rails application, there's a +Gemfile+ which declares all -dependencies of the application. +config/boot.rb+ sets -+ENV['BUNDLE_GEMFILE']+ to the location of this file. If the Gemfile -exists, +bundler/setup+ is then required. +In a standard Rails application, there's a `Gemfile` which declares all +dependencies of the application. `config/boot.rb` sets +`ENV['BUNDLE_GEMFILE']` to the location of this file. If the Gemfile +exists, `bundler/setup` is then required. The gems that a Rails 4 application depends on are as follows: @@ -197,9 +197,9 @@ TODO: change these when the Rails 4 release is near. * treetop (1.4.9) * tzinfo (0.3.23) -### +rails/commands.rb+ +### `rails/commands.rb` -Once +config/boot.rb+ has finished, the next file that is required is +rails/commands+ which will execute a command based on the arguments passed in. In this case, the +ARGV+ array simply contains +server+ which is extracted into the +command+ variable using these lines: +Once `config/boot.rb` has finished, the next file that is required is `rails/commands` which will execute a command based on the arguments passed in. In this case, the `ARGV` array simply contains `server` which is extracted into the `command` variable using these lines: ```ruby ARGV << '--help' if ARGV.empty? @@ -220,7 +220,7 @@ command = aliases[command] || command TIP: As you can see, an empty ARGV list will make Rails show the help snippet. -If we used `s` rather than +server+, Rails will use the +aliases+ defined in the file and match them to their respective commands. With the +server+ command, Rails will run this code: +If we used `s` rather than `server`, Rails will use the `aliases` defined in the file and match them to their respective commands. With the `server` command, Rails will run this code: ```ruby when 'server' @@ -239,7 +239,7 @@ when 'server' } ``` -This file will change into the root of the directory (a path two directories back from +APP_PATH+ which points at +config/application.rb+), but only if the +config.ru+ file isn't found. This then requires +rails/commands/server+ which sets up the +Rails::Server+ class. +This file will change into the root of the directory (a path two directories back from `APP_PATH` which points at `config/application.rb`), but only if the `config.ru` file isn't found. This then requires `rails/commands/server` which sets up the `Rails::Server` class. ```ruby require 'fileutils' @@ -250,16 +250,16 @@ module Rails class Server < ::Rack::Server ``` -+fileutils+ and +optparse+ are standard Ruby libraries which provide helper functions for working with files and parsing options. +`fileutils` and `optparse` are standard Ruby libraries which provide helper functions for working with files and parsing options. -### +actionpack/lib/action_dispatch.rb+ +### `actionpack/lib/action_dispatch.rb` Action Dispatch is the routing component of the Rails framework. It adds functionalities like routing, session, and common middlewares. -### +rails/commands/server.rb+ +### `rails/commands/server.rb` -The +Rails::Server+ class is defined in this file as inheriting from +Rack::Server+. When +Rails::Server.new+ is called, this calls the +initialize+ method in +rails/commands/server.rb+: +The `Rails::Server` class is defined in this file as inheriting from `Rack::Server`. When `Rails::Server.new` is called, this calls the `initialize` method in `rails/commands/server.rb`: ```ruby def initialize(*) @@ -268,13 +268,13 @@ def initialize(*) end ``` -Firstly, +super+ is called which calls the +initialize+ method on +Rack::Server+. +Firstly, `super` is called which calls the `initialize` method on `Rack::Server`. -### Rack: +lib/rack/server.rb+ +### Rack: `lib/rack/server.rb` -+Rack::Server+ is responsible for providing a common server interface for all Rack-based applications, which Rails is now a part of. +`Rack::Server` is responsible for providing a common server interface for all Rack-based applications, which Rails is now a part of. -The +initialize+ method in +Rack::Server+ simply sets a couple of variables: +The `initialize` method in `Rack::Server` simply sets a couple of variables: ```ruby def initialize(options = nil) @@ -283,9 +283,9 @@ def initialize(options = nil) end ``` -In this case, +options+ will be +nil+ so nothing happens in this method. +In this case, `options` will be `nil` so nothing happens in this method. -After +super+ has finished in +Rack::Server+, we jump back to +rails/commands/server.rb+. At this point, +set_environment+ is called within the context of the +Rails::Server+ object and this method doesn't appear to do much at first glance: +After `super` has finished in `Rack::Server`, we jump back to `rails/commands/server.rb`. At this point, `set_environment` is called within the context of the `Rails::Server` object and this method doesn't appear to do much at first glance: ```ruby def set_environment @@ -293,7 +293,7 @@ def set_environment end ``` -In fact, the +options+ method here does quite a lot. This method is defined in +Rack::Server+ like this: +In fact, the `options` method here does quite a lot. This method is defined in `Rack::Server` like this: ```ruby def options @@ -301,7 +301,7 @@ def options end ``` -Then +parse_options+ is defined like this: +Then `parse_options` is defined like this: ```ruby def parse_options(args) @@ -318,7 +318,7 @@ def parse_options(args) end ``` -With the +default_options+ set to this: +With the `default_options` set to this: ```ruby def default_options @@ -333,7 +333,7 @@ def default_options end ``` -There is no +REQUEST_METHOD+ key in +ENV+ so we can skip over that line. The next line merges in the options from +opt_parser+ which is defined plainly in +Rack::Server+ +There is no `REQUEST_METHOD` key in `ENV` so we can skip over that line. The next line merges in the options from `opt_parser` which is defined plainly in `Rack::Server` ```ruby def opt_parser @@ -341,7 +341,7 @@ def opt_parser end ``` -The class *is* defined in +Rack::Server+, but is overwritten in +Rails::Server+ to take different arguments. Its +parse!+ method begins like this: +The class *is* defined in `Rack::Server`, but is overwritten in `Rails::Server` to take different arguments. Its `parse!` method begins like this: ```ruby def parse!(args) @@ -354,20 +354,20 @@ def parse!(args) ... ``` -This method will set up keys for the +options+ which Rails will then be -able to use to determine how its server should run. After +initialize+ -has finished, we jump back into +rails/server+ where +APP_PATH+ (which was +This method will set up keys for the `options` which Rails will then be +able to use to determine how its server should run. After `initialize` +has finished, we jump back into `rails/server` where `APP_PATH` (which was set earlier) is required. -### +config/application+ +### `config/application` -When +require APP_PATH+ is executed, +config/application.rb+ is loaded. +When `require APP_PATH` is executed, `config/application.rb` is loaded. This file exists in your app and it's free for you to change based on your needs. -### +Rails::Server#start+ +### `Rails::Server#start` -After +congif/application+ is loaded, +server.start+ is called. This method is defined like this: +After `congif/application` is loaded, `server.start` is called. This method is defined like this: ```ruby def start @@ -401,14 +401,14 @@ end ``` This is where the first output of the Rails initialization happens. This -method creates a trap for +INT+ signals, so if you +CTRL-C+ the server, +method creates a trap for `INT` signals, so if you `CTRL-C` the server, it will exit the process. As we can see from the code here, it will -create the +tmp/cache+, +tmp/pids+, +tmp/sessions+ and +tmp/sockets+ -directories. It then calls +wrapped_app+ which is responsible for +create the `tmp/cache`, `tmp/pids`, `tmp/sessions` and `tmp/sockets` +directories. It then calls `wrapped_app` which is responsible for creating the Rack app, before creating and assigning an -instance of +ActiveSupport::Logger+. +instance of `ActiveSupport::Logger`. -The +super+ method will call +Rack::Server.start+ which begins its definition like this: +The `super` method will call `Rack::Server.start` which begins its definition like this: ```ruby def start &blk @@ -454,7 +454,7 @@ def start &blk end ``` -The interesting part for a Rails app is the last line, +server.run+. Here we encounter the +wrapped_app+ method again, which this time +The interesting part for a Rails app is the last line, `server.run`. Here we encounter the `wrapped_app` method again, which this time we're going to explore more (even though it was executed before, and thus memorized by now). @@ -462,7 +462,7 @@ thus memorized by now). @wrapped_app ||= build_app app ``` -The +app+ method here is defined like so: +The `app` method here is defined like so: ```ruby def app @@ -478,7 +478,7 @@ def app end ``` -The +options[:config]+ value defaults to +config.ru+ which contains this: +The `options[:config]` value defaults to `config.ru` which contains this: ```ruby # This file is used by Rack-based servers to start the application. @@ -488,41 +488,41 @@ run <%= app_const %> ``` -The +Rack::Builder.parse_file+ method here takes the content from this +config.ru+ file and parses it using this code: +The `Rack::Builder.parse_file` method here takes the content from this `config.ru` file and parses it using this code: ```ruby app = eval "Rack::Builder.new {( " <plus> cfgfile <plus> "\n )}.to_app", TOPLEVEL_BINDING, config ``` -The +initialize+ method of +Rack::Builder+ will take the block here and execute it within an instance of +Rack::Builder+. This is where the majority of the initialization process of Rails happens. The +require+ line for +config/environment.rb+ in +config.ru+ is the first to run: +The `initialize` method of `Rack::Builder` will take the block here and execute it within an instance of `Rack::Builder`. This is where the majority of the initialization process of Rails happens. The `require` line for `config/environment.rb` in `config.ru` is the first to run: ```ruby require ::File.expand_path('../config/environment', __FILE__) ``` -### +config/environment.rb+ +### `config/environment.rb` -This file is the common file required by +config.ru+ (+rails server+) and Passenger. This is where these two ways to run the server meet; everything before this point has been Rack and Rails setup. +This file is the common file required by `config.ru` (`rails server`) and Passenger. This is where these two ways to run the server meet; everything before this point has been Rack and Rails setup. -This file begins with requiring +config/application.rb+. +This file begins with requiring `config/application.rb`. -### +config/application.rb+ +### `config/application.rb` -This file requires +config/boot.rb+, but only if it hasn't been required before, which would be the case in +rails server+ but *wouldn't* be the case with Passenger. +This file requires `config/boot.rb`, but only if it hasn't been required before, which would be the case in `rails server` but *wouldn't* be the case with Passenger. Then the fun begins! Loading Rails ------------- -The next line in +config/application.rb+ is: +The next line in `config/application.rb` is: ```ruby require 'rails/all' ``` -### +railties/lib/rails/all.rb+ +### `railties/lib/rails/all.rb` This file is responsible for requiring all the individual frameworks of Rails: @@ -551,17 +551,17 @@ explore them on your own. For now, just keep in mind that common functionality like Rails engines, I18n and Rails configuration is all being defined here. -### Back to +config/environment.rb+ +### Back to `config/environment.rb` -When +config/application.rb+ has finished loading Rails, and defined -your application namespace, you go back to +config/environment.rb+, +When `config/application.rb` has finished loading Rails, and defined +your application namespace, you go back to `config/environment.rb`, where your application is initialized. For example, if you application was called -+Blog+, here you would find +Blog::Application.initialize!+, which is -defined in +rails/application.rb+ +`Blog`, here you would find `Blog::Application.initialize!`, which is +defined in `rails/application.rb` -### +railties/lib/rails/application.rb+ +### `railties/lib/rails/application.rb` -The +initialize!+ method looks like this: +The `initialize!` method looks like this: ```ruby def initialize!(group=:default) #:nodoc: @@ -577,15 +577,15 @@ As you can see, you can only initialize an app once. This is also where the init TODO: review this The initializers code itself is tricky. What Rails is doing here is it -traverses all the class ancestors looking for an +initializers+ method, -sorting them and running them. For example, the +Engine+ class will make -all the engines available by providing the +initializers+ method. +traverses all the class ancestors looking for an `initializers` method, +sorting them and running them. For example, the `Engine` class will make +all the engines available by providing the `initializers` method. -After this is done we go back to +Rack::Server+ +After this is done we go back to `Rack::Server` ### Rack: lib/rack/server.rb -Last time we left when the +app+ method was being defined: +Last time we left when the `app` method was being defined: ```ruby def app @@ -601,7 +601,7 @@ def app end ``` -At this point +app+ is the Rails app itself (a middleware), and what +At this point `app` is the Rails app itself (a middleware), and what happens next is Rack will call all the provided middlewares: ```ruby @@ -616,16 +616,16 @@ def build_app(app) end ``` -Remember, +build_app+ was called (by wrapped_app) in the last line of +Server#start+. +Remember, `build_app` was called (by wrapped_app) in the last line of `Server#start`. Here's how it looked like when we left: ```ruby server.run wrapped_app, options, &blk ``` -At this point, the implementation of +server.run+ will depend on the +At this point, the implementation of `server.run` will depend on the server you're using. For example, if you were using Mongrel, here's what -the +run+ method would look like: +the `run` method would look like: ```ruby def self.run(app, options={}) |