kotovalexarian-likes-github/rails--rails
1
0
Fork 0
mirror of https://github.com/rails/rails.git synced 2022-11-09 12:12:34 -05:00
Code Releases Activity

Clarify autoload_paths and eager_load in guides per current usage. [CI SKIP]

Browse source
This commit is contained in:
Tim Diggins 2018-01-21 21:18:20 +00:00
parent cf1c48478d
commit f349ffac27
2 changed files with 31 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
guides/source/autoloading_and_reloading_constants.md
View file

@ -8,7 +8,7 @@ This guide documents how constant autoloading and reloading works.
After reading this guide, you will know: After reading this guide, you will know:
* Key aspects of Ruby constants * Key aspects of Ruby constants
* What is `autoload_paths` * What are the `autoload_paths` and how does eager loading work in production?
* How constant autoloading works * How constant autoloading works
* What is `require_dependency` * What is `require_dependency`
* How constant reloading works * How constant reloading works
@ -430,8 +430,8 @@ if `House` is still unknown when `app/models/beach_house.rb` is being eager
loaded, Rails autoloads it. loaded, Rails autoloads it.
autoload_paths autoload_paths and eager_load_paths
-------------- -----------------------------------
As you probably know, when `require` gets a relative file name: As you probably know, when `require` gets a relative file name:
@ -451,7 +451,7 @@ the idea is that when a constant like `Post` is hit and missing, if there's a
`post.rb` file for example in `app/models` Rails is going to find it, evaluate `post.rb` file for example in `app/models` Rails is going to find it, evaluate
it, and have `Post` defined as a side-effect. it, and have `Post` defined as a side-effect.
Alright, Rails has a collection of directories similar to `$LOAD_PATH` in which All right, Rails has a collection of directories similar to `$LOAD_PATH` in which
to look up `post.rb`. That collection is called `autoload_paths` and by to look up `post.rb`. That collection is called `autoload_paths` and by
default it contains: default it contains:
@ -465,17 +465,22 @@ default it contains:
* The directory `test/mailers/previews`. * The directory `test/mailers/previews`.
Also, this collection is configurable via `config.autoload_paths`. For example, `eager_load_paths` is initially the `app` paths above
`lib` was in the list years ago, but no longer is. An application can opt-in
by adding this to `config/application.rb`:
```ruby How files are autoloaded depends on `eager_load` and `cache_classes` config settings which typically vary in development, production, and test modes:
config.autoload_paths << "#{Rails.root}/lib"
``` * In **development**, you want quicker startup with incremental loading of application code. So `eager_load` should be set to `false`, and rails will autoload files as needed (see [Autoloading Algorithms](#autoloading-algorithms) below) -- and then reload them when they change (see [Constant Reloading](#constant-reloading) below).
* In **production**, however you want consistency and thread-safety and can live with a longer boot time. So `eager_load` is set to `true`, and then during boot (before the app is ready to receive requests) rails loads all files in the `eager_load_paths` and then turns off auto loading (NB: autoloading may be needed during eager loading). Not autoloading after boot is a `good thing`, as autoloading can cause the app to be have thread-safety problems.
* In **test**, for speed of execution (of individual tests) `eager_load` is `false`, so rails follows development behaviour.
What is described above are the defaults with a newly generated rails app. There are multiple ways this can be configured differently (see [Configuring Rails Applications](configuring.html#rails-general-configuration).
). But using `autoload_paths` on its own in the past (pre-rails 5) developers might configure `autoload_paths` to add in extra locations (e.g. `lib` which used to be an autoload path list years ago, but no longer is). However this is now discouraged for most purposes, as it is likely to lead to production-only errors. It is possible to add new locations to both `config.eager_load_paths` and `config.autoload_paths` but use at your own risk.
See also ([Autoloading in the Test Environment](#autoloading-in-the-test-environment).
`config.autoload_paths` is not changeable from environment-specific configuration files. `config.autoload_paths` is not changeable from environment-specific configuration files.
The value of `autoload_paths` can be inspected. In a just generated application The value of `autoload_paths` can be inspected. In a just-generated application
it is (edited): it is (edited):
``` ```
@ -1329,3 +1334,17 @@ class C < BasicObject
end end
end end
``` ```
### Autoloading in the Test Environment
When configuring the `test` environment for autoloading you might consider multiple factors.
For example it might be worth running your tests with an identical setup to production (`config.eager_load = true`, `config.cache_classes = true`) in order to catch any problems before they hit production (this is compensation for the lack of dev-prod parity). However this will slow down the boot time for individual tests on a dev machine (and is not immediately compatible with spring see below). So one possibility is to do this on a
[CI](https://en.wikipedia.org/wiki/Continuous_integration) machine only (which should run without spring).
On a development machine you can then have your tests running with whatever is fastest (ideally `config.eager_load = false`).
With the [Spring](https://github.com/rails/spring) pre-loader (included with new rails apps), you ideally keep `config.eager_load = false` as per development. Sometimes you may end up with a hybrid configuration (`config.eager_load = true`, `config.cache_classes = true` AND `config.enable_dependency_loading = true`), see [spring issue](https://github.com/rails/spring/issues/519#issuecomment-348324369). However it might be simpler to keep the same configuration as development, and work out whatever it is that is causing autoloading to fail (perhaps by the results of your CI test results).
Occasionally you may need to explictly eager_load by using `Rails
.application.eager_load!` in the setup of your tests -- this might occur if your [tests involve multithreading](https://stackoverflow.com/questions/25796409/in-rails-how-can-i-eager-load-all-code-before-a-specific-rspec-test).

2
guides/source/configuring.md
View file

@ -62,7 +62,7 @@ These configuration methods are to be called on a `Rails::Railtie` object, such
* `config.autoload_once_paths` accepts an array of paths from which Rails will autoload constants that won't be wiped per request. Relevant if `config.cache_classes` is `false`, which is the case in development mode by default. Otherwise, all autoloading happens only once. All elements of this array must also be in `autoload_paths`. Default is an empty array. * `config.autoload_once_paths` accepts an array of paths from which Rails will autoload constants that won't be wiped per request. Relevant if `config.cache_classes` is `false`, which is the case in development mode by default. Otherwise, all autoloading happens only once. All elements of this array must also be in `autoload_paths`. Default is an empty array.
* `config.autoload_paths` accepts an array of paths from which Rails will autoload constants. Default is all directories under `app`. * `config.autoload_paths` accepts an array of paths from which Rails will autoload constants. Default is all directories under `app`. It is no longer recommended to adjust this. See [Autoloading and Reloading Constants](autoloading_and_reloading_constants.html#autoload-paths-and-eager-load-paths)
* `config.cache_classes` controls whether or not application classes and modules should be reloaded on each request. Defaults to `false` in development mode, and `true` in test and production modes. * `config.cache_classes` controls whether or not application classes and modules should be reloaded on each request. Defaults to `false` in development mode, and `true` in test and production modes.