summaryrefslogtreecommitdiffstats
path: root/doc/development
diff options
context:
space:
mode:
authorMike McCallister <mike@mccllstr.com>2011-07-12 23:19:29 -0500
committerMike McCallister <mike@mccllstr.com>2011-07-12 23:19:29 -0500
commit2cd181073e4a6a569197f1ce95fb0a17d66e95be (patch)
tree04b6c77d48692c6d8190731af5dc538144de2457 /doc/development
parenta0b576a4c9f7b59123901f58550ba7f294acd5d8 (diff)
downloadbcfg2-2cd181073e4a6a569197f1ce95fb0a17d66e95be.tar.gz
bcfg2-2cd181073e4a6a569197f1ce95fb0a17d66e95be.tar.bz2
bcfg2-2cd181073e4a6a569197f1ce95fb0a17d66e95be.zip
Added documentation on how to set up a virtualenv with Bcfg2 code.
Diffstat (limited to 'doc/development')
-rw-r--r--doc/development/setup.txt75
1 files changed, 73 insertions, 2 deletions
diff --git a/doc/development/setup.txt b/doc/development/setup.txt
index ad53e5da2..e9fc6e1e5 100644
--- a/doc/development/setup.txt
+++ b/doc/development/setup.txt
@@ -2,9 +2,11 @@
.. _development-setup:
-
Environment setup for development
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+=================================
+
+Checking Out a Copy of the Code
+-------------------------------
* Check out a copy of the code::
@@ -17,3 +19,72 @@ Environment setup for development
* Add :file:`bcfg2/src/sbin` to your :envvar:`PATH` environment variable
* Add :file:`bcfg2` to your :envvar:`PYTHONPATH` environment variable
+
+
+Using a Virtual Environment for Development
+-------------------------------------------
+
+Bcfg2 is a pure Python program, and Python makes available certain
+tools that simplify creating isolated environments. Such environments
+are useful for running code under development, running code that needs
+to be installed without actually installing it in system locations, or
+running parallel, independent installations of the same packages.
+
+One popular tool for doing this is `virtualenv
+<http://pypi.python.org/pypi/virtualenv>`_. The following commands
+will bootstrap an isolated environment where the Bcfg2 server can
+run. They assume you are starting from an empty directory, on a
+Posix-like system that has Python and the ``virtualenv`` package
+installed (e.g., on Debian it is available as ``python-virtualenv``):
+
+.. code-block:: sh
+
+ # Work in a scratch directory
+ mkdir test_env
+ cd test_env
+
+ # This creates the environment
+ virtualenv .
+
+ # "Activate" the environment. From this point forward, Python
+ # and its libraries will first be searched for in test_env and
+ # its subdirectories. When you begin a new session that should
+ # use this environment, re-execute this command.
+ . bin/activate
+
+ # The pip command is useful for installing python code from a
+ # variety of locations, including directly from git repositories
+ easy_install pip
+
+ # Install Bcfg2 from git. The -e puts the source in an editable
+ # git clone under the "src" dir.
+ pip install -e git://git.mcs.anl.gov/bcfg2.git#egg=Bcfg2
+
+ # Install a newer version of the Cheetah library, for example
+ pip install --upgrade cheetah
+
+ # If you want to run IPython from within the virtual
+ # environment, it will need to be installed locally, even if it
+ # is already available on the system, or else it won't find .
+ pip install --upgrade ipython
+
+ # Note, if you install IPython, deactivate and reactivate the
+ # virtualenv before attempting to use it.
+ deactivate
+ . bin/activate
+
+.. note::
+
+ One caveat about this environment is that it assumes you have
+ already installed Bcfg2's dependencies on the system itself. Pip is
+ capable of building packages such as ``lxml`` that include native
+ code, but you will need to be sure its build-time prerequisites are
+ available.
+
+Consider using the above commands to create an isolated Bcfg2
+environment in the same directory as your Bcfg2
+:term:`repository`. Copy your :file:`/etc/bcfg2.conf` file into a
+local :file:`etc` directory, tweak the paths as needed and you can run
+an independent Bcfg2 server as a non-root user. This is useful for
+confirming a new release of Bcfg2 and all its tools works against your
+current :term:`repository` before upgrading.