Basic Usage

This section 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.

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.

See also

bootstrap.cfg 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

See also

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

See also

The virtualenv documentation for more information on virtualenv environments.

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.

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![1]

Footnotes

[1]	This expression is most famously used by Richard M. Stallman.