Permalink
Browse files

Improve docs for Rails::Application and add routes_reloader_hook and …

…app_reloader_hooks.
  • Loading branch information...
1 parent 57e0c03 commit 27f0add3f93510c1aee2491467dffbb1e4015bc6 @josevalim josevalim committed Dec 12, 2011
@@ -33,6 +33,24 @@ module Rails
#
# The Application is also responsible for building the middleware stack.
#
+ # == Booting process
+ #
+ # The application is also responsible for setting up and executing the booting
+ # process. From the moment you require "config/application.rb" in your app,
+ # the booting process goes like this:
+ #
+ # 1) require "config/boot.rb" to setup load paths
+ # 2) require railties and engines
+ # 3) Define Rails.application as "class MyApp::Application < Rails::Application"
+ # 4) Run config.before_configuration callbacks
+ # 5) Load config/environments/ENV.rb
+ # 6) Run config.before_initialize callbacks
+ # 7) Run Railtie#initializer defined by railties, engines and application.
+ # One by one, each engine sets up its load paths, routes and runs its initializer files.
+ # 8) Build the middleware stack and run to_prepare callbacks
+ # 9) Run config.before_eager_load and eager_load if cache classes is true
+ # 10) Run config.after_initialize callbacks
+ #
class Application < Engine
autoload :Bootstrap, 'rails/application/bootstrap'
autoload :Configuration, 'rails/application/configuration'
@@ -83,27 +101,55 @@ def require_environment! #:nodoc:
require environment if environment
end
+ # Reload application routes regardless if they changed or not.
def reload_routes!
routes_reloader.reload!
end
- def routes_reloader
+ def routes_reloader #:nodoc:
@routes_reloader ||= RoutesReloader.new
end
- def initialize!(group=:default)
+ # A routes reloader hook that is used to setup to_prepare callbacks.
+ # A plugin may override this if they desire to provide a more
+ # exquisite route reloading.
+ # :api: plugin
+ def routes_reloader_hook
+ app = self
+ lambda { app.routes_reloader.execute_if_updated }
+ end
+
+ # An app reloader hook that is used to setup to_cleanup callbacks.
+ # A plugin may override this if they desire to provide a more exquisite app reloading.
+ # :api: plugin
+ def app_reloader_hook
+ lambda {
+ ActiveSupport::DescendantsTracker.clear
+ ActiveSupport::Dependencies.clear
+ }
+ end
+
+ # Initialize the application passing the given group. By default, the
+ # group is :default but sprockets precompilation passes group equals
+ # to assets if initialize_on_precompile is false to avoid booting the
+ # whole app.
+ def initialize!(group=:default) #:nodoc:
raise "Application has been already initialized." if @initialized
run_initializers(group, self)
@initialized = true
self
end
+ # Load the application and its railties tasks and invoke the registered hooks.
+ # Check <tt>Rails::Railtie.rake_tasks</tt> for more info.
def load_tasks(app=self)
initialize_tasks
super
self
end
+ # Load the application console and invoke the registered hooks.
+ # Check <tt>Rails::Railtie.console</tt> for more info.
def load_console(app=self)
initialize_console
super
@@ -129,7 +175,8 @@ def env_config
})
end
- def ordered_railties
+ # Returns the ordered railties for this application considering railties_order.
+ def ordered_railties #:nodoc:
@ordered_railties ||= begin
order = config.railties_order.map do |railtie|
if railtie == :main_app
@@ -151,21 +198,21 @@ def ordered_railties
end
end
- def initializers
+ def initializers #:nodoc:
Bootstrap.initializers_for(self) +
super +
Finisher.initializers_for(self)
end
- def config
+ def config #:nodoc:
@config ||= Application::Configuration.new(find_root_with_flag("config.ru", Dir.pwd))
end
def to_app
self
end
- def helpers_paths
+ def helpers_paths #:nodoc:
config.helpers_paths
end
@@ -222,7 +269,7 @@ def default_middleware_stack
end
end
- def initialize_tasks
+ def initialize_tasks #:nodoc:
self.class.rake_tasks do
require "rails/tasks"
task :environment do
@@ -232,7 +279,7 @@ def initialize_tasks
end
end
- def initialize_console
+ def initialize_console #:nodoc:
require "pp"
require "rails/console/app"
require "rails/console/helpers"
@@ -59,13 +59,6 @@ module Bootstrap
end
end
- initializer :set_clear_dependencies_hook, :group => :all do
- ActionDispatch::Reloader.to_cleanup do
- ActiveSupport::DescendantsTracker.clear
- ActiveSupport::Dependencies.clear
- end
- end
-
# Sets the dependency loading mechanism.
# TODO: Remove files from the $" and always use require.
initializer :initialize_dependency_mechanism, :group => :all do
@@ -20,12 +20,6 @@ module Finisher
end
end
- initializer :add_to_prepare_blocks do
- config.to_prepare_blocks.each do |block|
- ActionDispatch::Reloader.to_prepare(&block)
- end
- end
-
initializer :add_builtin_route do |app|
if Rails.env.development?
app.routes.append do
@@ -38,30 +32,44 @@ module Finisher
build_middleware_stack
end
- initializer :run_prepare_callbacks do
- ActionDispatch::Reloader.prepare!
- end
-
initializer :define_main_app_helper do |app|
app.routes.define_mounted_helper(:main_app)
end
+ initializer :add_to_prepare_blocks do
+ config.to_prepare_blocks.each do |block|
+ ActionDispatch::Reloader.to_prepare(&block)
+ end
+ end
+
+ # This needs to happen before eager load so it happens
+ # in exactly the same point regardless of config.cache_classes
+ initializer :run_prepare_callbacks do
+ ActionDispatch::Reloader.prepare!
+ end
+
initializer :eager_load! do
if config.cache_classes && !$rails_rake_task
ActiveSupport.run_load_hooks(:before_eager_load, self)
eager_load!
end
end
+ # All initialization is done, including eager loading in production
initializer :finisher_hook do
ActiveSupport.run_load_hooks(:after_initialize, self)
end
- # Force routes to be loaded just at the end and add it to to_prepare callbacks
- # This needs to be after the finisher hook to ensure routes added in the hook
- # are still loaded.
+ # Set app reload just after the finisher hook to ensure
+ # paths added in the hook are still loaded.
+ initializer :set_clear_dependencies_hook, :group => :all do |app|
+ ActionDispatch::Reloader.to_cleanup(&app.app_reloader_hook)
+ end
+
+ # Set app reload just after the finisher hook to ensure
+ # routes added in the hook are still loaded.
initializer :set_routes_reloader do |app|
- reloader = lambda { app.routes_reloader.execute_if_updated }
+ reloader = app.routes_reloader_hook
reloader.call
ActionDispatch::Reloader.to_prepare(&reloader)
end

0 comments on commit 27f0add

Please sign in to comment.