From 27f0add3f93510c1aee2491467dffbb1e4015bc6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= Date: Mon, 12 Dec 2011 15:18:19 +0100 Subject: Improve docs for Rails::Application and add routes_reloader_hook and app_reloader_hooks. --- railties/lib/rails/application.rb | 63 +++++++++++++++++++++++++---- railties/lib/rails/application/bootstrap.rb | 7 ---- railties/lib/rails/application/finisher.rb | 36 ++++++++++------- 3 files changed, 77 insertions(+), 29 deletions(-) (limited to 'railties/lib') diff --git a/railties/lib/rails/application.rb b/railties/lib/rails/application.rb index f5f47acfbc..f1d546fc59 100644 --- a/railties/lib/rails/application.rb +++ b/railties/lib/rails/application.rb @@ -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 @@ module Rails 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 Rails::Railtie.rake_tasks for more info. def load_tasks(app=self) initialize_tasks super self end + # Load the application console and invoke the registered hooks. + # Check Rails::Railtie.console for more info. def load_console(app=self) initialize_console super @@ -129,7 +175,8 @@ module Rails }) 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,13 +198,13 @@ module Rails 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 @@ -165,7 +212,7 @@ module Rails self end - def helpers_paths + def helpers_paths #:nodoc: config.helpers_paths end @@ -222,7 +269,7 @@ module Rails end end - def initialize_tasks + def initialize_tasks #:nodoc: self.class.rake_tasks do require "rails/tasks" task :environment do @@ -232,7 +279,7 @@ module Rails end end - def initialize_console + def initialize_console #:nodoc: require "pp" require "rails/console/app" require "rails/console/helpers" diff --git a/railties/lib/rails/application/bootstrap.rb b/railties/lib/rails/application/bootstrap.rb index 1ae90056d9..e189009cc5 100644 --- a/railties/lib/rails/application/bootstrap.rb +++ b/railties/lib/rails/application/bootstrap.rb @@ -59,13 +59,6 @@ module Rails 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 diff --git a/railties/lib/rails/application/finisher.rb b/railties/lib/rails/application/finisher.rb index fc7d205a6f..df2853498a 100644 --- a/railties/lib/rails/application/finisher.rb +++ b/railties/lib/rails/application/finisher.rb @@ -20,12 +20,6 @@ module Rails 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,14 +32,22 @@ module Rails 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) @@ -53,15 +55,21 @@ module Rails 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 -- cgit v1.2.3