bootstrap/virtualenv/docs/reference.rst - depot_tools - Git at Google

 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
	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