From 2cd181073e4a6a569197f1ce95fb0a17d66e95be Mon Sep 17 00:00:00 2001 From: Mike McCallister Date: Tue, 12 Jul 2011 23:19:29 -0500 Subject: Added documentation on how to set up a virtualenv with Bcfg2 code. --- doc/development/setup.txt | 75 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 73 insertions(+), 2 deletions(-) (limited to 'doc') 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 +`_. 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. -- cgit v1.2.3-1-g7c22