aboutsummaryrefslogtreecommitdiffstats
path: root/guides/source/initialization.md
diff options
context:
space:
mode:
authorPrem Sichanugrist <s@sikachu.com>2012-09-01 21:37:59 -0400
committerPrem Sichanugrist <s@sikac.hu>2012-09-17 15:54:23 -0400
commit31ef4cf656785a190723d2d8fb4c0fd06f4009bc (patch)
tree582a93b9441b41c1150ae421a2a878194af6475e /guides/source/initialization.md
parented62b1bf0b6fff53524c168f9615af84dea99537 (diff)
downloadrails-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.md170
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={})