==========================
pyutilib.virtualenv README
==========================

This Python package includes the **vpy_create** script, which is
used to create **virtualenv** bootstrap scripts that automate the installation of
**virtualenv** along with other Python packages.

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

Overview
~~~~~~~~

The **vpy_create** script integrates a Python module into a **virtualenv**
bootstrap script.  A user defines a **configure()** function in this module to
control the configuration of the **virtualenv** installation.  For example, the
following function declares the default installation directory, and that the
virtual Python repository contains the **virtualenv** and **nose** Python packages::

  def configure(installer):
        installer.default_dirname = 'venv'
        installer.add_repository('virtualenv', pypi='virtualenv')
        installer.add_repository('nose', pypi='nose')
        installer.add_repository(
                        'coopr', 
                        pyname='Coopr', 
                        root='https://software.sandia.gov/svn/public/coopr', 
                        dev=True)
        return installer

The **add_repository** method can specify a PyPI package with the *pypi*
option.  Alternatively, the root of a subversion repository can be specified
with the *root* option.  If the *dev* option is specified, then this
repository is checked out and installed in the **<root>/src** directory.
Further, this package is installed in *develop* mode.


A virtual Python bootstrap script is created by calling
**vpy_create** and specifying the Python module and script
name.::

  vpy_create venv.py venv_install

The bootstrap script, **venv_install**, creates the virtual Python
installation in the specified directory, **venv**:

  venv_install

The user can also specify the installation directory::

  venv_install venvdir


By default, the bootstrap script installs the latest software release.
In PyPI, this is the latest revision.  In subversion, this is the latest
revision in either the *tags* or *releases* directory.  The trunk branch of
the subversion repository can also be installed using the **--trunk** option::

  venv_install --trunk venv

Similarly, the bootstrap script recognizes stable branches, which can
be installed with the **--stable** option.  Note that if stable branches are
not available, then the latest release is installed.


Internet Connectivity
~~~~~~~~~~~~~~~~~~~~~

By default, the bootstrap script uses an internet connection to download the 
Python packages that are installed.  Note that a proxy server may be needed
for the bootstrap script to work correctly.  The user can define the
HTTP_PROXY environmental variable to specify the name of a proxy server.
Alternatively, the **--proxy** option can be specified.

The bootstrap script also provides a mechanism for enabling offline virtualenv
installations.  This requires a two-stage process.  First, the
**--preinstall** option is used to create a ZIP file that contains the Python
packages.  For example, the command::

  venv_install --preinstall

creates a **venv** directory, which includes the file **venv/venv.zip**.
The preinstall step must be executed on a machine with internet
connectivity.  However, this ZIP file can be used to perform an off-line
installation with the **--offline** option.  For example, the following
command will uses the **venv.zip** file to perform off-line installation
in the **temp** directory::

  venv_install --offline --zip=venv.zip test

Note that this technique also installs the **setuptools** packages offline.
Thus, the bootstrap script generated by **vpy_create** 
supports a purely offline setup of virtualenv environments, which is not supported
by the **virtualenv** bootstrap process.


A Configurable Installer
~~~~~~~~~~~~~~~~~~~~~~~~

The **vpy_install** script provided with **pyutilib.virtualenv** is a **virtualenv**
bootstrap script that can be configured with INI files.  For example, the
consider the following INI file::

    ;
    ; This INI file can be used by vpy_install to create a virtual
    ; Python installation.
    ;
    [installer]
    description=This is an example.
    README="#
    # This is a README file created by the bootstrap script.
    #"

    [nose]
    pypi=nose

    [coopr]
    pyname=Coopr
    root=https://software.sandia.gov/svn/public/coopr
    dev=True

The default installation directory for **vpy_install** is **python**.
This INI file will install the **nose** and **coopr** packages, and the
**coopr** package will be installed in **python/src/coopr** as an editable
*develop* package.


-------
License
-------

BSD.  See the LICENSE.txt file.


------------
Organization
------------

+ Directories

  * pyutilib - The root directory for PyUtilib source code

+ Documentation and Bug Tracking

  * Trac wiki: https://software.sandia.gov/trac/pyutilib
 
  * Examples in the pyutilib.virtualenv/example directory

+ Authors

  * See the AUTHORS.txt file.

+ Project Managers

  * William E. Hart, wehart@sandia.gov

+ Mailing List

  * PyUtilib is managed with the Acro Project. A separate checkins mailing
    list is managed for PyUtilib, but otherwise the main Acro mailing lists
    are used to manage the development of this software:

    - acro-developers@software.sandia.gov
    - acro-users@software.sandia.gov

--------------------
Third Party Software
--------------------

The pyutilib.virtualenv package depends on the following Python packages:
    - virtualenv

