.. This file is part of everyapp.bootstrap.
.. Copyright (C) 2010 Krys Lawrence
..
.. everyapp.bootstrap is free software: you can redistribute it and/or modify
.. it under the terms of the GNU General Public License as published by the
.. Free Software Foundation, either version 3 of the License, or (at your
.. option) any later version.
..
.. everyapp.bootstrap is distributed in the hope that it will be useful, but
.. WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.. or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
.. more details.
..
.. You should have received a copy of the GNU General Public License along with
.. this program.  If not, see <http://www.gnu.org/licenses/>.

.. index:: basic usage, usage; basic usage
.. _basic_usage:

Basic Usage
===========

This |file| provides some basic instructions on how to get started using
*everyapp.bootstrap*.  It also includes descriptions of some of the new
sub-directories that you will find in your project as a result.  Finally, some
pointers on what to do next are provided.

.. index::
   single: getting started
   single: usage; getting started
   single: basic usage; getting started

Getting Started
---------------

*everyapp.bootstrap* consists of one main command-line utility, called
|mkbootstrap|, that generates a bootstrap script and a configuration file.  By
default, the bootstrap script is named |bootstrap.py| and the configuration
file is named |bootstrap.cfg|.

You use |mkbootstrap| both to generate your first bootstrap files and also to
upgrade your |bootstrap.py| when you install newer versions of
*everyapp.bootstrap*.

So, to get started, in your project's root directory, run the command::

  mkbootstrap

This will generate the |bootstrap.py| and |bootstrap.cfg| files.

You can then edit |bootstrap.cfg| as desired, though this is a completely
optional step.  The |bootstrap.cfg| file lets you customize the behaviour of
|bootstrap.py| in several ways like:

* Customizing the default values for |bootstrap.py|'s command-line arguments,
* Specifying additional Python_ distributions (packages) to install using
  either pip_ or easy_install_ or both.
* Specifying additional commands to run after the virtual environment has been
  created and the distributions have been installed.

.. SEEALSO:: |bootstrap.cfg.txt| for information on editing the |bootstrap.cfg|
   file.

Once you have |bootstrap.cfg| set up the way you want, you are ready to
bootstrap the virtualenv_ environment for your project.  To do that, run the
command::

  python bootstrap.py

This will create the virtual environment in the current directory (i.e. the
root directory for your project).

.. NOTE:: If you want to use a different version of Python_ than the default
   one installed on your system, just run |bootstrap.py| using that
   interpreter.  Your virtual environment will then use that version of Python_
   for everything automatically.

The final step is to activate the environment.  This is something you should do
every time you work on your project.  To do it, run the command::

  source ./bin/activate

... or, if you are on Windows, run::

  Scripts\activate.bat

You are now ready to start hacking on your project using an isolated Python_
interpreter and only the distributions installed locally in this virtual
environment.

.. NOTE:: You will probably want to commit |bootstrap.py| and |bootstrap.cfg|
   to your project's version control system (|VCS|).  That way you can easily
   generate a consistent development environment each time you clone/check out
   your project from it's |VCS|.

When you activate your environment, your |PATH| environment variable is
altered so that you will run your local version of Python_ and related commands
by default.  Also, your shell or command line prompt is altered to remind you
that you are in your activated virtual environment.

There is one additional command that is useful from time to time.  If you want
to deactivate your virtual environment and return to your normal shell or
command line, run this command::

  deactivate

.. SEEALSO:: |mkbootstrap.txt|, |bootstrap.py.txt| and |bootstrap.cfg.txt| for
   more specific details on each of the three files mentioned above.

.. SEEALSO:: The `virtualenv documentation
   <http://pypi.python.org/pypi/virtualenv>`_ for more information on
   virtualenv_ environments.

.. index::
   single: directories
   single: usage; directories
   single: basic usage; directories

New Directories
---------------

Once you have bootstrapped your virtual environment, you will find several new
sub-directories in your project's root directory.  They are briefly described
below:

|bin| **or** |Scripts|
  This directory contains the executable programs that are aware of your
  virtual environment.  On Windows the directory is named |Scripts|, everywhere
  else it is named |bin|.  In particular you will find the |python|
  interpreter, as well as the |pip| and |easy_install| commands in this
  directory.
|lib/pythonX.Y| **or** |Lib|
  This (sub-)directory contains a copy of Python_'s standard library, adapted
  to your virtual environment.  You generally won't touch these files.  On
  Windows the directory is named |Lib|, everywhere else it is named
  |lib/pythonX.Y|, where ``X`` and ``Y`` are the version numbers of the Python_
  interpreter you are using.
|lib/pythonX.Y/site-packages| **or** |Lib\site-packages|
  This sub-directory contains the virtual environment's locally installed
  packages.  You can easily install additional packages using pip_ or
  easy_install_ when your virtual environment is activated.  On Windows the
  sub-directory is named |Lib\site-packages|, everywhere else it is named
  |lib/pythonX.Y/site-packages|, where ``X`` and ``Y`` are the version numbers
  of the Python_ interpreter you are using.
|lib64|
  On 64-bit |POSIX| systems (everything except Windows), this symlink_ is
  created.  It points to the above-mentioned |lib| directory.  This is for
  compatibility.

.. NOTE:: Do not commit these directories to your |VCS|.  In fact, you should
   probably mark them to be ignored.  They will all get re-generated every time
   you run |bootstrap.py|.

.. index::
   single: usage; next steps
   pair: basic usage; next steps

Next Steps
----------

Now that you have your project's development environment set up, you are free
continue developing your project as desired.  Just make sure to remember these
few points:

* Always activate your virtual environment before working on your project.
* Do not forget to update your |bootstrap.cfg| file whenever you install or
  upgrade a development package.
* Remember that pacakges installed via |bootstrap.cfg| should only be
  development support packages.  Packages that are actually dependencies of
  your project should be listed in your project's |setup.py| file.

Happy hacking! [#rms1]_

.. rubric:: Footnotes

.. [#rms1] This expression is most famously used by `Richard M. Stallman`_.
