popsu-d7/sites/all/modules/drush/docs/bootstrap.html

<h1>The Drush Bootstrap Process</h1>
<p>
When preparing to run a command, drush works by "bootstrapping" 
the Drupal environment in very much the same way that is done 
during a normal page request from the web server, so most drush 
commands run in the context of a fully-initialized website.
<p>
For efficiency and convenience, some drush commands can work
without first bootstrapping a Drupal site, or by only partially
bootstrapping a site.  This is more efficient, because there is
sometimes a slight delay involved with bootstrapping, especially
in some of the later stages.  It is also a matter of convenience,
because some commands are useful to use even when you do not
have a working Drupal site available to bootstrap.  For example,
you can use drush to download Drupal with `drush dl drupal`.  This
obviously does not require any bootstrapping to work.
<p>
The drush bootstrapping process is also very closely related with
drush configuration files.  At each bootstrap phase, drush may load
additional configuration files that may contain additional drush
settings.  This has two very important connotations.  First, settings
that are only loaded in a later bootstrap phase are not available
for commands that do not reach that bootstrap phase.  Second, it
is possible to alter drush behavior on a per-site basis by applying
settings in a site-specific configuration file.  See 
`drush topic docs-configuration` for details on drush configuration
files.

<h2>DRUSH_BOOTSTRAP_DRUSH</h2>
<p>
Configuration files loaded during this phase:<ul>
<li>Drush installation folder.
<li>System wide configuration folder (e.g. /etc/drush/drushrc.php).
<li>User's .drush folder (i.e. ~/.drush/drushrc.php).
<li>In any location, as specified by the --config (-c) option.
</ul><p>
Only bootstrap Drush, without any Drupal specific code.
<p>
Any code that operates on the Drush installation, and not specifically
any Drupal directory, should bootstrap to this phase.


<h2>DRUSH_BOOTSTRAP_DRUPAL_ROOT</h2>
<p>
Configuration files loaded during this phase:<ul>
<li>Drupal installation root.
</ul><p>
Set up and test for a valid drupal root, either through the -r/--root options,
or evaluated based on the current working directory.
<p>
Any code that interacts with an entire Drupal installation, and not a specific
site on the Drupal installation should use this bootstrap phase.


<h2>DRUSH_BOOTSTRAP_DRUPAL_SITE</h2>
<p>
Configuration files loaded during this phase:<ul>
<li>Drupal site folder (e.g sites/{default|example.com}/drushrc.php).
</ul><p>
Set up a Drupal site directory and the correct environment variables to
allow Drupal to find the configuration file.
<p>
If no site is specified with the -l / --uri options, Drush will assume the
site is 'default', which mimics Drupal's behaviour.
<p>
If you want to avoid this behaviour, it is recommended that you use the
DRUSH_BOOTSTRAP_DRUPAL_ROOT bootstrap phase instead.
<p>
Any code that needs to modify or interact with a specific Drupal site's
settings.php file should bootstrap to this phase.


<h2>DRUSH_BOOTSTRAP_DRUPAL_CONFIGURATION</h2>
<p>
Load the settings from the Drupal sites directory.
<p>
This phase is analagous to the DRUPAL_BOOTSTRAP_CONFIGURATION bootstrap phase in Drupal
itself, and this is also the first step where Drupal specific code is included.
<p>
This phase is commonly used for code that interacts with the Drupal install API,
as both install.php and update.php start at this phase.


<h2>DRUSH_BOOTSTRAP_DRUPAL_DATABASE</h2>
<p>
Connect to the Drupal database using the database credentials loaded
during the previous bootstrap phase.
<p>
This phase is analogous to the DRUPAL_BOOTSTRAP_DATABASE bootstrap phase in
Drupal.
<p>
Any code that needs to interact with the Drupal database API needs to
be bootstrapped to at least this phase.


<h2>DRUSH_BOOTSTRAP_DRUPAL_FULL</h2>
<p>
Fully initialize Drupal.
<p>
This is the default bootstrap phase all commands will try to reach,
unless otherwise specified.
This is analogous to the DRUPAL_BOOTSTRAP_FULL bootstrap phase in
Drupal.
<p>
Any code that interacts with the general Drupal API should be
bootstrapped to this phase.


<h2>DRUSH_BOOTSTRAP_DRUPAL_LOGIN</h2>
<p>
Log in to the initialiased Drupal site.
<p>
This bootstrap phase is used after the site has been
fully bootstrapped.
<p>
This phase will log you in to the drupal site with the username
or user ID specified by the --user/ -u option.
<p>
Use this bootstrap phase for your command if you need to have access
to information for a specific user, such as listing nodes that might
be different based on who is logged in.


<h2>DRUSH_BOOTSTRAP_MAX</h2>
<p>
This is not an actual bootstrap phase.  Commands that use
DRUSH_BOOTSTRAP_MAX will cause drush to bootstrap as far
as possible, and then run the command regardless of the
bootstrap phase that was reached.  This is useful for drush
commands that work without a bootstrapped site, but that
provide additional information or capabilities in the presence
of a bootstrapped site.  For example, `drush pm-releases modulename`
works without a bootstrapped Drupal site, but will include
the version number for the installed module if a Drupal site
has been bootstrapped.