eggs/zc.buildout-1.5.2-py2.6.egg/README.txt
changeset 69 c6bca38c1cbf
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/eggs/zc.buildout-1.5.2-py2.6.egg/README.txt	Sat Jan 08 11:20:57 2011 +0530
@@ -0,0 +1,202 @@
+********
+Buildout
+********
+
+.. contents::
+
+The Buildout project provides support for creating applications,
+especially Python applications.  It provides tools for assembling
+applications from multiple parts, Python or otherwise.  An application
+may actually contain multiple programs, processes, and configuration
+settings.
+
+The word "buildout" refers to a description of a set of parts and the
+software to create and assemble them.  It is often used informally to
+refer to an installed system based on a buildout definition.  For
+example, if we are creating an application named "Foo", then "the Foo
+buildout" is the collection of configuration and application-specific
+software that allows an instance of the application to be created.  We
+may refer to such an instance of the application informally as "a Foo
+buildout".
+
+To get a feel for some of the things you might use buildouts for, see
+the `Buildout examples`_.
+
+To lean more about using buildouts, see `Detailed Documentation`_.
+
+To see screencasts, talks, useful links and more documentation, visit
+the `Buildout website <http://www.buildout.org>`_.
+
+Recipes
+*******
+
+Existing recipes include:
+
+`zc.recipe.egg <http://pypi.python.org/pypi/zc.recipe.egg>`_
+   The egg recipe installes one or more eggs, with their
+   dependencies.  It installs their console-script entry points with
+   the needed eggs included in their paths.  It is suitable for use with
+   a "clean" Python: one without packages installed in site-packages.
+
+`z3c.recipe.scripts <http://pypi.python.org/pypi/z3c.recipe.scripts>`_
+  Like zc.recipe.egg, this recipe builds interpreter scripts and entry
+  point scripts based on eggs.  It can be used with a Python that has
+  packages installed in site-packages, such as a system Python.  The
+  interpreter also has more features than the one offered by
+  zc.recipe.egg.
+
+`zc.recipe.testrunner <http://pypi.python.org/pypi/zc.recipe.testrunner>`_
+   The testrunner egg creates a test runner script for one or
+   more eggs.
+
+`zc.recipe.zope3checkout <http://pypi.python.org/pypi/zc.recipe.zope3checkout>`_
+   The zope3checkout recipe installs a Zope 3 checkout into a
+   buildout.
+
+`zc.recipe.zope3instance <http://pypi.python.org/pypi/zc.recipe.zope3instance>`_
+   The zope3instance recipe sets up a Zope 3 instance.
+
+`zc.recipe.filestorage <http://pypi.python.org/pypi/zc.recipe.filestorage>`_
+   The filestorage recipe sets up a ZODB file storage for use in a
+   Zope 3 instance created by the zope3instance recipe.
+
+Buildout examples
+*****************
+
+Here are a few examples of what you can do with buildouts.  We'll
+present these as a set of use cases.
+
+Try out an egg
+==============
+
+Sometimes you want to try an egg (or eggs) that someone has released.
+You'd like to get a Python interpreter that lets you try things
+interactively or run sample scripts without having to do path
+manipulations.  If you can and don't mind modifying your Python
+installation, you could use easy_install, otherwise, you could create
+a directory somewhere and create a buildout.cfg file in that directory
+containing::
+
+  [buildout]
+  parts = mypython
+
+  [mypython]
+  recipe = zc.recipe.egg
+  interpreter = mypython
+  eggs = theegg
+
+where theegg is the name of the egg you want to try out.
+
+Run buildout in this directory.  It will create a bin subdirectory
+that includes a mypython script.  If you run mypython without any
+arguments you'll get an interactive interpreter with the egg in the
+path. If you run it with a script and script arguments, the script
+will run with the egg in its path.  Of course, you can specify as many
+eggs as you want in the eggs option.
+
+If the egg provides any scripts (console_scripts entry points), those
+will be installed in your bin directory too.
+
+Work on a package
+=================
+
+I often work on packages that are managed separately.  They don't have
+scripts to be installed, but I want to be able to run their tests
+using the `zope.testing test runner
+<http://www.python.org/pypi/zope.testing>`_.  In this kind of
+application, the program to be installed is the test runner.  A good
+example of this is `zc.ngi <http://svn.zope.org/zc.ngi/trunk/>`_.
+
+Here I have a subversion project for the zc.ngi package.  The software
+is in the src directory.  The configuration file is very simple::
+
+  [buildout]
+  develop = .
+  parts = test
+
+  [test]
+  recipe = zc.recipe.testrunner
+  eggs = zc.ngi
+
+I use the develop option to create a develop egg based on the current
+directory.  I request a test script named "test" using the
+zc.recipe.testrunner recipe.  In the section for the test script, I
+specify that I want to run the tests in the zc.ngi package.
+
+When I check out this project into a new sandbox, I run bootstrap.py
+to get setuptools and zc.buildout and to create bin/buildout.  I run
+bin/buildout, which installs the test script, bin/test, which I can
+then use to run the tests.
+
+This is probably the most common type of buildout.
+
+If I need to run a previous version of zc.buildout, I use the
+`--version` option of the bootstrap.py script::
+
+    $ python bootstrap.py --version 1.1.3
+
+The `zc.buildout project <http://svn.zope.org/zc.buildout/trunk>`_
+is a slightly more complex example of this type of buildout.
+
+Install egg-based scripts
+=========================
+
+A variation of the `Try out an egg`_ use case is to install scripts
+into your ~/bin directory (on Unix, of course).  My ~/bin directory is
+a buildout with a configuration file that looks like::
+
+
+  [buildout]
+  parts = foo bar
+  bin-directory = .
+
+  [foo]
+  ...
+
+where foo and bar are packages with scripts that I want available.  As
+I need new scripts, I can add additional sections.  The bin-directory
+option specified that scripts should be installed into the current
+directory.
+
+Multi-program multi-machine systems
+===================================
+
+Using an older prototype version of the buildout, we've build a number
+of systems involving multiple programs, databases, and machines.  One
+typical example consists of:
+
+- Multiple Zope instances
+
+- Multiple ZEO servers
+
+- An LDAP server
+
+- Cache-invalidation and Mail delivery servers
+
+- Dozens of add-on packages
+
+- Multiple test runners
+
+- Multiple deployment modes, including dev, stage, and prod,
+  with prod deployment over multiple servers
+
+Parts installed include:
+
+- Application software installs, including Zope, ZEO and LDAP
+  software
+
+- Add-on packages
+
+- Bundles of configuration that define Zope, ZEO and LDAP instances
+
+- Utility scripts such as test runners, server-control
+  scripts, cron jobs.
+
+Questions and Bug Reporting
+***************************
+
+Please send questions and comments to the
+`distutils SIG mailing list <mailto://distutils-sig@python.org>`_.
+
+Report bugs using the `zc.buildout Launchpad Bug Tracker
+<https://launchpad.net/zc.buildout/+bugs>`_.