| Index: bootstrap/virtualenv/docs/reference.rst
|
| diff --git a/bootstrap/virtualenv/docs/reference.rst b/bootstrap/virtualenv/docs/reference.rst
|
| deleted file mode 100644
|
| index ca801a007901501063c206b5e0561e21cd6f4456..0000000000000000000000000000000000000000
|
| --- a/bootstrap/virtualenv/docs/reference.rst
|
| +++ /dev/null
|
| @@ -1,256 +0,0 @@
|
| -Reference Guide
|
| -===============
|
| -
|
| -``virtualenv`` Command
|
| -----------------------
|
| -
|
| -.. _usage:
|
| -
|
| -Usage
|
| -~~~~~
|
| -
|
| -:command:`virtualenv [OPTIONS] ENV_DIR`
|
| -
|
| - Where ``ENV_DIR`` is an absolute or relative path to a directory to create
|
| - the virtual environment in.
|
| -
|
| -.. _options:
|
| -
|
| -Options
|
| -~~~~~~~
|
| -
|
| -.. program: virtualenv
|
| -
|
| -.. option:: --version
|
| -
|
| - show program's version number and exit
|
| -
|
| -.. option:: -h, --help
|
| -
|
| - show this help message and exit
|
| -
|
| -.. option:: -v, --verbose
|
| -
|
| - Increase verbosity.
|
| -
|
| -.. option:: -q, --quiet
|
| -
|
| - Decrease verbosity.
|
| -
|
| -.. option:: -p PYTHON_EXE, --python=PYTHON_EXE
|
| -
|
| - The Python interpreter to use, e.g.,
|
| - --python=python2.5 will use the python2.5 interpreter
|
| - to create the new environment. The default is the
|
| - interpreter that virtualenv was installed with
|
| - (like ``/usr/bin/python``)
|
| -
|
| -.. option:: --clear
|
| -
|
| - Clear out the non-root install and start from scratch.
|
| -
|
| -.. option:: --system-site-packages
|
| -
|
| - Give the virtual environment access to the global
|
| - site-packages.
|
| -
|
| -.. option:: --always-copy
|
| -
|
| - Always copy files rather than symlinking.
|
| -
|
| -.. option:: --relocatable
|
| -
|
| - Make an EXISTING virtualenv environment relocatable.
|
| - This fixes up scripts and makes all .pth files relative.
|
| -
|
| -.. option:: --unzip-setuptools
|
| -
|
| - Unzip Setuptools when installing it.
|
| -
|
| -.. option:: --no-setuptools
|
| -
|
| - Do not install setuptools (or pip) in the new
|
| - virtualenv.
|
| -
|
| -.. option:: --no-pip
|
| -
|
| - Do not install pip in the new virtualenv.
|
| -
|
| -.. option:: --extra-search-dir=DIR
|
| -
|
| - Directory to look for setuptools/pip distributions in.
|
| - This option can be specified multiple times.
|
| -
|
| -.. option:: --prompt=PROMPT
|
| -
|
| - Provides an alternative prompt prefix for this
|
| - environment.
|
| -
|
| -.. option:: --never-download
|
| -
|
| - DEPRECATED. Retained only for backward compatibility.
|
| - This option has no effect. Virtualenv never downloads
|
| - pip or setuptools.
|
| -
|
| -.. option:: --no-site-packages
|
| -
|
| - DEPRECATED. Retained only for backward compatibility.
|
| - Not having access to global site-packages is now the
|
| - default behavior.
|
| -
|
| -.. option:: --distribute
|
| -.. option:: --setuptools
|
| -
|
| - Legacy; now have no effect. Before version 1.10 these could be used
|
| - to choose whether to install Distribute_ or Setuptools_ into the created
|
| - virtualenv. Distribute has now been merged into Setuptools, and the
|
| - latter is always installed.
|
| -
|
| -.. _Distribute: https://pypi.python.org/pypi/distribute
|
| -.. _Setuptools: https://pypi.python.org/pypi/setuptools
|
| -
|
| -
|
| -Configuration
|
| --------------
|
| -
|
| -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 use a custom Python binary instead of the
|
| -one virtualenv is run with you can also set an environment variable::
|
| -
|
| - $ export VIRTUALENV_PYTHON=/opt/python-3.3/bin/python
|
| - $ virtualenv ENV
|
| -
|
| -It's the same as passing the option to virtualenv directly::
|
| -
|
| - $ virtualenv --python=/opt/python-3.3/bin/python ENV
|
| -
|
| -This also works for appending command line options, like ``--find-links``.
|
| -Just leave an empty space between the passed values, e.g.::
|
| -
|
| - $ export VIRTUALENV_EXTRA_SEARCH_DIR="/path/to/dists /path/to/other/dists"
|
| - $ virtualenv ENV
|
| -
|
| -is the same as calling::
|
| -
|
| - $ virtualenv --extra-search-dir=/path/to/dists --extra-search-dir=/path/to/other/dists ENV
|
| -
|
| -.. envvar:: VIRTUAL_ENV_DISABLE_PROMPT
|
| -
|
| - Any virtualenv created when this is set to a non-empty value will not have
|
| - it's :ref:`activate` modify the shell prompt.
|
| -
|
| -
|
| -Configuration File
|
| -~~~~~~~~~~~~~~~~~~
|
| -
|
| -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
|
| -``%APPDATA%\virtualenv\virtualenv.ini``.
|
| -
|
| -The names of the settings are derived from the long command line option,
|
| -e.g. the option :option:`--python <-p>` would look like this::
|
| -
|
| - [virtualenv]
|
| - python = /opt/python-3.3/bin/python
|
| -
|
| -Appending options like :option:`--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 :option:`--help <-h>` for a full list
|
| -of supported options.
|
| -
|
| -
|
| -Extending Virtualenv
|
| ---------------------
|
| -
|
| -
|
| -Creating Your Own Bootstrap Scripts
|
| -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| -
|
| -While this creates an environment, it doesn't put anything into the
|
| -environment. Developers may find it useful to distribute a script
|
| -that sets up a particular environment, for example a script that
|
| -installs a particular web application.
|
| -
|
| -To create a script like this, call
|
| -:py:func:`virtualenv.create_bootstrap_script`, and write the
|
| -result to your new bootstrapping script.
|
| -
|
| -.. py:function:: create_bootstrap_script(extra_text)
|
| -
|
| - Creates a bootstrap script from ``extra_text``, which is like
|
| - this script but with extend_parser, adjust_options, and after_install hooks.
|
| -
|
| -This returns a string that (written to disk of course) can be used
|
| -as a bootstrap script with your own customizations. The script
|
| -will be the standard virtualenv.py script, with your extra text
|
| -added (your extra text should be Python code).
|
| -
|
| -If you include these functions, they will be called:
|
| -
|
| -.. py:function:: extend_parser(optparse_parser)
|
| -
|
| - You can add or remove options from the parser here.
|
| -
|
| -.. py:function:: adjust_options(options, args)
|
| -
|
| - You can change options here, or change the args (if you accept
|
| - different kinds of arguments, be sure you modify ``args`` so it is
|
| - only ``[DEST_DIR]``).
|
| -
|
| -.. py:function:: after_install(options, home_dir)
|
| -
|
| - After everything is installed, this function is called. This
|
| - is probably the function you are most likely to use. An
|
| - example would be::
|
| -
|
| - def after_install(options, home_dir):
|
| - if sys.platform == 'win32':
|
| - bin = 'Scripts'
|
| - else:
|
| - bin = 'bin'
|
| - subprocess.call([join(home_dir, bin, 'easy_install'),
|
| - 'MyPackage'])
|
| - subprocess.call([join(home_dir, bin, 'my-package-script'),
|
| - 'setup', home_dir])
|
| -
|
| - This example immediately installs a package, and runs a setup
|
| - script from that package.
|
| -
|
| -Bootstrap Example
|
| -~~~~~~~~~~~~~~~~~
|
| -
|
| -Here's a more concrete example of how you could use this::
|
| -
|
| - import virtualenv, textwrap
|
| - output = virtualenv.create_bootstrap_script(textwrap.dedent("""
|
| - import os, subprocess
|
| - def after_install(options, home_dir):
|
| - etc = join(home_dir, 'etc')
|
| - if not os.path.exists(etc):
|
| - os.makedirs(etc)
|
| - subprocess.call([join(home_dir, 'bin', 'easy_install'),
|
| - 'BlogApplication'])
|
| - subprocess.call([join(home_dir, 'bin', 'paster'),
|
| - 'make-config', 'BlogApplication',
|
| - join(etc, 'blog.ini')])
|
| - subprocess.call([join(home_dir, 'bin', 'paster'),
|
| - 'setup-app', join(etc, 'blog.ini')])
|
| - """))
|
| - f = open('blog-bootstrap.py', 'w').write(output)
|
| -
|
| -Another example is available `here`__.
|
| -
|
| -.. __: https://github.com/socialplanning/fassembler/blob/master/fassembler/create-venv-script.py
|
|
|