diff options
Diffstat (limited to 'docs/index.txt')
| -rw-r--r-- | docs/index.txt | 105 |
1 files changed, 85 insertions, 20 deletions
diff --git a/docs/index.txt b/docs/index.txt index 4fe4c32..9f81adf 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -27,9 +27,16 @@ Project <http://openplans.org>`_ and is now maintained by a It is licensed under an `MIT-style permissive license <https://github.com/pypa/virtualenv/raw/master/LICENSE.txt>`_. -You can install it with ``easy_install virtualenv``, or the `latest +You can install it with ``pip install virtualenv``, or the `latest development version <https://github.com/pypa/virtualenv/tarball/develop#egg=virtualenv-dev>`_ -with ``easy_install virtualenv==dev``. +with ``pip install virtualenv==dev``. + +You can also use ``easy_install``, or if you have no Python package manager +available at all, you can just grab the single file `virtualenv.py`_ and run +it with ``python virtualenv.py``. + +.. _virtualenv.py: https://raw.github.com/pypa/virtualenv/master/virtualenv.py + What It Does ------------ @@ -79,9 +86,65 @@ Distribute instead of setuptools, just call virtualenv like this:: You can also set the environment variable VIRTUALENV_USE_DISTRIBUTE. A new virtualenv also includes the `pip <http://pypy.python.org/pypi/pip>`_ -installer, so you can use `ENV/bin/pip`` to install additional packages into +installer, so you can use ``ENV/bin/pip`` to install additional packages into the environment. +Environment variables and configuration files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +virtualenv can not only be configured by passing command line options such as +``--distribute`` but also by two other means: + +- Environment variables + + Each command line option is automatically used to look for environment + variables with the name format ``VIRTUALENV_<UPPER_NAME>``. That means + the name of the command line options are capitalized and have dashes + (``'-'``) replaced with underscores (``'_'``). + + For example, to automatically install Distribute instead of setuptools + you can also set an environment variable:: + + $ export VIRTUALENV_USE_DISTRIBUTE=true + $ python virtualenv.py ENV + + It's the same as passing the option to virtualenv directly:: + + $ python virtualenv.py --distribute ENV + + This also works for appending command line options, like ``--find-links``. + Just leave an empty space between the passsed values, e.g.:: + + $ export VIRTUALENV_EXTRA_SEARCH_DIR="/path/to/dists /path/to/other/dists" + $ virtualenv ENV + + is the same as calling:: + + $ python virtualenv.py --extra-search-dir=/path/to/dists --extra-search-dir=/path/to/other/dists ENV + +- Config files + + virtualenv also looks for a standard ini config file. On Unix and Mac OS X + that's ``$HOME/.virtualenv/virtualenv.ini`` and on Windows, it's + ``%HOME%\\virtualenv\\virtualenv.ini``. + + The names of the settings are derived from the long command line option, + e.g. the option ``--distribute`` would look like this:: + + [virtualenv] + distribute = true + + Appending options like ``--extra-search-dir`` can be written on multiple + lines:: + + [virtualenv] + extra-search-dir = + /path/to/dists + /path/to/other/dists + +Please have a look at the output of ``virtualenv --help`` for a full list +of supported options. + Windows Notes ~~~~~~~~~~~~~ @@ -172,7 +235,7 @@ Here's a more concrete example of how you could use this:: f = open('blog-bootstrap.py', 'w').write(output) Another example is available `here -<https://svn.openplans.org/svn/fassembler/trunk/fassembler/create-venv-script.py>`_. +<https://github.com/socialplanning/fassembler/blob/master/fassembler/create-venv-script.py>`_. activate script ~~~~~~~~~~~~~~~ @@ -189,7 +252,7 @@ directory. (You have to use ``source`` because it changes your shell environment in-place.) This is all it does; it's purely a convenience. If you directly run a script or the python interpreter from the virtualenv's ``bin/`` directory (e.g. ``path/to/env/bin/pip`` or -``/path/to/env/bin/python script.py``) there's no need for activation. +``/path/to/env/bin/python script.py``) there's no need for activation. After activating an environment you can use the function ``deactivate`` to undo the changes to your ``$PATH``. @@ -207,15 +270,16 @@ On Windows you just do:: And use ``deactivate.bat`` to undo the changes. -The ``--no-site-packages`` Option -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The ``--system-site-packages`` Option +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you build with ``virtualenv --system-site-packages ENV``, your virtual +environment will inherit packages from ``/usr/lib/python2.7/site-packages`` +(or wherever your global site-packages directory is). -If you build with ``virtualenv --no-site-packages ENV`` it will *not* -inherit any packages from ``/usr/lib/python2.5/site-packages`` (or -wherever your global site-packages directory is). This can be used if -you don't have control over site-packages and don't want to depend on -the packages there, or you just want more isolation from the global -system. +This can be used if you have control over the global site-packages directory, +and you want to depend on the packages there. If you want isolation from the +global system, do not use this flag. Using Virtualenv without ``bin/python`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -236,11 +300,12 @@ can setup the environment like:: This will change ``sys.path`` and even change ``sys.prefix``, but also allow you to use an existing interpreter. Items in your environment will show up first on ``sys.path``, before global items. However, global items will -always be accessible -- this technique does not support the -``--no-site-packages`` flag. Also, this cannot undo the activation of other -environments, or modules that have been imported. You shouldn't try to, for -instance, activate an environment before a web request; you should activate -*one* environment as early as possible, and not do it again in that process. +always be accessible (as if the ``--system-site-packages`` flag had been used +in creating the environment, whether it was or not). Also, this cannot undo +the activation of other environments, or modules that have been imported. +You shouldn't try to, for instance, activate an environment before a web +request; you should activate *one* environment as early as possible, and not +do it again in that process. Making Environments Relocatable ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -277,8 +342,8 @@ libraries on the system, if those C libraries are located somewhere different (either different versions, or a different filesystem layout). -Currently the ``--no-site-packages`` option will not be honored if you -use this on an environment. +If you use this flag to create an environment, currently, the +``--system-site-packages`` option will be implied. The ``--extra-search-dir`` Option ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |