Create new branch.

src/zc/buildout/bootstrap.txt

@@ -47,7 +47,7 @@ Make sure the bootstrap script actually works::
     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::

src/zc/buildout/buildout.py

@@ -129,6 +129,7 @@ _buildout_default_options = _annotate_section({
     'parts-directory': 'parts',
     'prefer-final': 'false',
     'python': 'buildout',
+    'relative-paths': 'false',
     'socket-timeout': '',
     'unzip': 'false',
     'use-dependency-links': 'true',
@@ -411,9 +412,16 @@ class Buildout(UserDict.DictMixin):
         partsdir = os.path.join(options['parts-directory'], 'buildout')
         if not os.path.exists(partsdir):
             os.mkdir(partsdir)
+        # (Honor the relative-paths option.)
+        relative_paths = options.get('relative-paths', 'false')
+        if relative_paths == 'true':
+            relative_paths = options['directory']
+        else:
+            assert relative_paths == 'false'
+            relative_paths = ''
         zc.buildout.easy_install.sitepackage_safe_scripts(
             options['bin-directory'], ws, options['executable'], partsdir,
-            reqs=['zc.buildout'])
+            reqs=['zc.buildout'], relative_paths=relative_paths)
 
     init = bootstrap
 

src/zc/buildout/buildout.txt

@@ -767,8 +767,9 @@ COMMAND_LINE_VALUE).
         DEFAULT_VALUE
     python= buildout
         DEFAULT_VALUE
-    socket-timeout=
+    relative-paths= false
         DEFAULT_VALUE
+    socket-timeout=
     unzip= false
         DEFAULT_VALUE
     use-dependency-links= true
@@ -2286,6 +2287,7 @@ database is shown.
     parts-directory = /sample-buildout/parts
     prefer-final = false
     python = buildout
+    relative-paths = false
     socket-timeout =
     unzip = false
     use-dependency-links = true
@@ -2349,6 +2351,33 @@ python
    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
+    this policy to to be inconvenient.  Zipped eggs make debugging more
+    difficult and often import more slowly.  You can include an unzip option in
+    the buildout section to change the default unzipping policy ("unzip =
+    true").
+
+use-dependency-links
+    By default buildout will obey the setuptools dependency_links metadata
+    when it looks for dependencies. This behavior can be controlled with
+    the use-dependency-links buildout option::
+
+      [buildout]
+      ...
+      use-dependency-links = false
+
+    The option defaults to true. If you set it to false, then dependency
+    links are only looked for in the locations specified by find-links.
+
 verbosity
    A log-level adjustment.  Typically, this is set via the -q and -v
    command-line options.
@@ -2395,8 +2424,56 @@ buildout or setuptools egg could be installed in the develop-eggs
 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

src/zc/buildout/easy_install.py

@@ -1199,12 +1199,12 @@ def sitepackage_safe_scripts(
     return generated
 
 _script_initialization_template = '''
-import site # imports custom buildout-generated site.py
 import os
-path = %(site_py_dest)r
+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
 %(script_initialization)s'''
 
 # Utilities for the script generation functions.

src/zc/buildout/easy_install.txt

@@ -1498,12 +1498,12 @@ The demo script runs the entry point defined in the demo egg:
         ]
     <BLANKLINE>
     <BLANKLINE>
-    import site # imports custom buildout-generated site.py
     import os
-    path = '/interpreter/parts/interpreter'
+    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 eggrecipedemo
     <BLANKLINE>
@@ -1542,12 +1542,12 @@ Let's see ``script_arguments`` and ``script_initialization`` in action.
       '/interpreter/parts/interpreter',
       ]
     <BLANKLINE>
-    import site # imports custom buildout-generated site.py
     import os
-    path = '/interpreter/parts/interpreter'
+    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
     import os
     os.chdir("foo")
     <BLANKLINE>