[Checkins] SVN: zc.buildout/branches/gary-9/src/zc/buildout/b add docs and tests for relative-paths option

[Gary Poster]

Log message for revision 111138:
  add docs and tests for relative-paths option

Changed:
  U   zc.buildout/branches/gary-9/src/zc/buildout/bootstrap.txt
  U   zc.buildout/branches/gary-9/src/zc/buildout/buildout.py
  U   zc.buildout/branches/gary-9/src/zc/buildout/buildout.txt

-=-
Modified: zc.buildout/branches/gary-9/src/zc/buildout/bootstrap.txt
===================================================================
--- zc.buildout/branches/gary-9/src/zc/buildout/bootstrap.txt	2010-04-19 19:19:31 UTC (rev 111137)
+++ zc.buildout/branches/gary-9/src/zc/buildout/bootstrap.txt	2010-04-19 19:19:39 UTC (rev 111138)
@@ -47,7 +47,7 @@
     X...
     d  zc.buildout-...egg
 
-Now trying the `--version` option, that let you define a version for
+Now we will try the `--version` option, which lets you define a version for
 `zc.buildout`. If not provided, bootstrap will look for the latest one.
 
 Let's try with an unknown version::

Modified: zc.buildout/branches/gary-9/src/zc/buildout/buildout.py
===================================================================
--- zc.buildout/branches/gary-9/src/zc/buildout/buildout.py	2010-04-19 19:19:31 UTC (rev 111137)
+++ zc.buildout/branches/gary-9/src/zc/buildout/buildout.py	2010-04-19 19:19:39 UTC (rev 111138)
@@ -128,6 +128,7 @@
     'parts-directory': 'parts',
     'prefer-final': 'false',
     'python': 'buildout',
+    'relative-paths': 'false',
     'unzip': 'false',
     'use-dependency-links': 'true',
     }, 'DEFAULT_VALUE')

Modified: zc.buildout/branches/gary-9/src/zc/buildout/buildout.txt
===================================================================
--- zc.buildout/branches/gary-9/src/zc/buildout/buildout.txt	2010-04-19 19:19:31 UTC (rev 111137)
+++ zc.buildout/branches/gary-9/src/zc/buildout/buildout.txt	2010-04-19 19:19:39 UTC (rev 111138)
@@ -767,6 +767,8 @@
         DEFAULT_VALUE
     python= buildout
         DEFAULT_VALUE
+    relative-paths= false
+        DEFAULT_VALUE
     unzip= false
         DEFAULT_VALUE
     use-dependency-links= true
@@ -2241,6 +2243,7 @@
     parts-directory = /sample-buildout/parts
     prefer-final = false
     python = buildout
+    relative-paths = false
     unzip = false
     use-dependency-links = true
     verbosity = 20
@@ -2414,6 +2417,13 @@
    Python executable.  By default, the buildout section defines the
    default Python as the Python used to run the buildout.
 
+relative-paths
+    The paths generated by zc.buildout are absolute by default, and this
+    option is ``false``.  However, if you set this value to be ``true``,
+    bin/buildout will be generated with code that makes the paths relative.
+    Some recipes, such as zc.recipe.egg and z3c.recipe.scripts, honor this
+    value as well.
+
 unzip
     By default, zc.buildout doesn't unzip zip-safe eggs ("unzip = false").
     This follows the policy followed by setuptools itself.  Experience shows
@@ -2480,9 +2490,57 @@
 directory if the original buildout had develop eggs for either
 buildout or setuptools.)
 
-Note that the buildout script was installed but not run.  To run
-the buildout, we'd have to run the installed buildout script.
+If relative-paths is ``true``, the buildout script uses relative paths.
 
+    >>> write(sample_bootstrapped, 'setup.cfg',
+    ... '''
+    ... [buildout]
+    ... relative-paths = true
+    ... parts =
+    ... ''')
+
+    >>> print system(buildout
+    ...              +' -c'+os.path.join(sample_bootstrapped, 'setup.cfg')
+    ...              +' bootstrap'),
+    Generated script '/sample-bootstrapped/bin/buildout'.
+
+    >>> buildout_script = join(sample_bootstrapped, 'bin', 'buildout')
+    >>> import sys
+    >>> if sys.platform.startswith('win'):
+    ...     buildout_script += '-script.py'
+    >>> print open(buildout_script).read() # doctest: +ELLIPSIS
+    #!... -S
+    <BLANKLINE>
+    import os
+    <BLANKLINE>
+    join = os.path.join
+    base = os.path.dirname(os.path.abspath(os.path.realpath(__file__)))
+    base = os.path.dirname(base)
+    <BLANKLINE>
+    import sys
+    sys.path[0:0] = [
+        join(base, 'parts/buildout'),
+        ]
+    <BLANKLINE>
+    <BLANKLINE>
+    import os
+    path = sys.path[0]
+    if os.environ.get('PYTHONPATH'):
+        path = os.pathsep.join([path, os.environ['PYTHONPATH']])
+    os.environ['PYTHONPATH'] = path
+    import site # imports custom buildout-generated site.py
+    <BLANKLINE>
+    import zc.buildout.buildout
+    <BLANKLINE>
+    if __name__ == '__main__':
+        zc.buildout.buildout.main()
+    <BLANKLINE>
+
+
+Note that, in the above two examples, the buildout script was installed
+but not run.  To run the buildout, we'd have to run the installed
+buildout script.
+
 If we have an existing buildout that already has a buildout.cfg, we'll
 normally use the bootstrap command instead of init.  It will complain
 if there isn't a configuration file: