Updated for DZUG.

git-svn-id: http://svn.zope.org/repos/main/zc.buildout/trunk@76281 62d5b8a3-27da-0310-9561-8e5933582275

doc/tutorial.txt

@@ -10,7 +10,7 @@ Introduction to zc.buildout
 
 Jim Fulton, Zope Corporation
 
-PyCon 2007
+DZUG 2007
 
 What is zc.buildout?
 ====================
@@ -125,7 +125,7 @@ Working with eggs
 
      I often switch between develop and non-develop eggs.  I may be
      using a regular egg and realize I need to fix it.  I checkout the
-     eggs project into my buildout and tell buildout to treat it as a
+     egg's project into my buildout and tell buildout to treat it as a
      develop egg.  It creates the egg link in develop eggs and will
      load the develop egg in preference to the non-develop egg.
 
@@ -161,23 +161,6 @@ zc.buildout current status
 
 - A number of "recipes" available
 
-- Error reporting needs **a lot** of improvement
-
-  .. class:: handout
-
-     This will be a focus in the coming weeks.
-
-- Need a way to record versions used for repeatability
-
-  .. class:: handout
-
-     A benefit of using eggs is that dependencies are installed
-     automatically.  To make buildouts repeatable, we need a way to
-     capture the versions used in development, so we can include them
-     in a buildout specification that we can check in.  Of course, we
-     can do this manually today, but it needs to be automated.
-
-
 A Python Egg Primer
 ===================
 
@@ -193,7 +176,7 @@ Eggs are simple!
 
   - dependencies
 
-  - entry point
+  - entry points
 
 - May be distributed as source distributions
 
@@ -204,7 +187,6 @@ Eggs are simple!
      source distributions are more convenient to distribute in a lot
      of ways.
 
-
 - Automatic discovery through PyPI
 
 Egg jargon
@@ -346,7 +328,7 @@ Buildout overview
 
   .. class:: handout
 
-     If a part is removed from a specification, or is uninstalled.
+     If a part is removed from a specification, it is uninstalled.
 
      If a part's recipe or configuration changes, it is uninstalled
      and reinstalled.
@@ -483,9 +465,9 @@ zope.event buildout.cfg
 
      eggs = zope.event
 
-   The zc.recipe.testrunnner recipe has an eggs option for specifying which eggs should
-   be tested.  The generated test script will load these eggs along
-   with their dependencies.
+   The zc.recipe.testrunnner recipe has an eggs option for specifying
+   which eggs should be tested.  The generated test script will load
+   these eggs along with their dependencies.
 
    For more information on the ``zc.recipe.testrunner`` recipe, see
    http://www.python.org/pypi/zc.recipe.testrunner.
@@ -521,7 +503,7 @@ Buildout steps
 
   ::
 
-    bin/buildout setup . egg_info -r sdist register upload
+    bin/buildout setup . egg_info -rbdev sdist register upload
 
   .. class:: handout
 
@@ -547,7 +529,10 @@ Buildout steps
      The egg_info command allows control of egg meta-data.  The -r
      option to the egg_info command causes the distribution to have a
      version number that includes the subversion revision number of
-     the project.  This is useful when making development releases.
+     the project.  The -b option specified a revision tag. Here we
+     specified a revision tag of "dev", which marks the release as a
+     devlopment release. These are useful when making development
+     releases.
 
 Exercise 1
 ===========
@@ -736,26 +721,6 @@ Polished ``setup.py`` (1/3)
   def read(*rnames):
       return open(os.path.join(os.path.dirname(__file__), *rnames)).read()
 
-  name='zope.event'
-  setup(
-      name=name,
-      version='3.3.0',
-      url='http://www.python.org/pypi/'+name,
-      license='ZPL 2.1',
-      description='Zope Event Publication',
-      author='Zope Corporation and Contributors',
-      author_email='zope3-dev@zope.org',
-
-
-.. class:: handout
-
-In the polished version we flesh out the meta data a bit more.
-
-Polished ``setup.py`` (2/3)
-===========================
-
-  .. code-block:: Python
-
   long_description=(
           read('README.txt')
           + '\n' +
@@ -766,18 +731,33 @@ Polished ``setup.py`` (2/3)
           + '\n' +
           'Download\n'
           '**********************\n'
-          ),
+          )
+
+  open('documentation.txt', 'w').write(long_description)
 
 .. class:: handout
 
-   When I create distributions that I consider ready for broader use
-   and upload to PyPI, I like to include the full documentation in the
-   long description so PyPI serves it for me.
+In the polished version we flesh out the meta data a bit more.
+
+When I create distributions that I consider ready for broader use and
+upload to PyPI, I like to include the full documentation in the long
+description so PyPI serves it for me.
 
-Polished ``setup.py`` (3/3)
+Polished ``setup.py`` (2/3)
 ===========================
 
-  .. code-block:: Python
+.. code-block:: Python
+
+  name='zope.event'
+  setup(
+      name=name,
+      version='3.3.0',
+      url='http://www.python.org/pypi/'+name,
+      license='ZPL 2.1',
+      description='Zope Event Publication',
+      author='Zope Corporation and Contributors',
+      author_email='zope3-dev@zope.org',
+      long_description=long_description,
 
       packages=find_packages('src'),
       package_dir = {'': 'src'},
@@ -825,7 +805,6 @@ Extras
    zope.component adds lots of depenencies that we don't want to
    impose on people that don't use it.
 
-
 ``zc.recipe.egg``
 =================
 
@@ -971,6 +950,7 @@ Custom egg building
   find-links = http://www.python.org/other/spread/
   include-dirs = ${spreadtoolkit:location}/include
   library-dirs = ${spreadtoolkit:location}/lib
+  rpath = ${spreadtoolkit:location}/lib
 
 .. class:: handout
 
@@ -1478,10 +1458,16 @@ RPM experiments
 
 Initial work creating RPMs for deployment in our hosting environment:
 
+- Separation of software and configuration
+
 - Buildout used to create rpm containing software 
 
 - Later, the installed buildout is used to set up specific processes
 
+  - Run as root in offline mode
+
+  - Uses network configuration server
+
 .. class:: handout
 
    Our philosophy is to separate software and configuration.  We
@@ -1641,6 +1627,34 @@ ZRS spec file (3/3)
    We specify the files to be installed. This is just the buildout
    directory and a configuration script.
 
+Repeatability
+=============
+
+We want to be able to check certtain configuration into svn that can
+be checked out and reproduced.
+
+- We let buildout tell is what versions it picked for distributions
+
+  - Run with -v
+  
+  - Look for outout lines of form:
+  
+    ::
+
+      Picked: foo = 1.2
+
+- Include a versions section:
+
+  ::
+
+    [buildout]
+    ...
+    versions = myversions
+
+    [myversions]
+    foo = 1.2
+    ...
+ 
 Deployment issues
 =================