Debugging buildouts

===================

Buildouts can be pretty complex.  When things go wrong, it isn't

always obvious why.  Errors can occur due to problems in user input or

due to bugs in zc.buildout or recipes.  When an error occurs, Python's

post-mortem debugger can be used to inspect the state of the buildout

or recipe code where the error occurred.  To enable this, use the -D

option to the buildout.  Let's create a recipe that has a bug:

    >>> mkdir(sample_buildout, 'recipes')

    >>> write(sample_buildout, 'recipes', 'mkdir.py',

    ... """

    ... import os, zc.buildout

    ...

    ... class Mkdir:

    ...

    ...     def __init__(self, buildout, name, options):

    ...         self.name, self.options = name, options

    ...         options['path'] = os.path.join(

    ...                               buildout['buildout']['directory'],

    ...                               options['path'],

    ...                               )

    ...

    ...     def install(self):

    ...         directory = self.options['directory']

    ...         os.mkdir(directory)

    ...         return directory

    ...

    ...     def update(self):

    ...         pass

    ... """)

    >>> write(sample_buildout, 'recipes', 'setup.py',

    ... """

    ... from setuptools import setup

    ...

    ... setup(name = "recipes",

    ...       entry_points = {'zc.buildout': ['mkdir = mkdir:Mkdir']},

    ...       )

    ... """)

And create a buildout that uses it:

    >>> write(sample_buildout, 'buildout.cfg',

    ... """

    ... [buildout]

    ... develop = recipes

    ... parts = data-dir

    ...

    ... [data-dir]

    ... recipe = recipes:mkdir

    ... path = mystuff

    ... """)

If we run the buildout, we'll get an error:

    >>> print system(buildout),

    Develop: '/sample-buildout/recipes'

    Installing data-dir.

    While:

      Installing data-dir.

    Error: Missing option: data-dir:directory

If we want to debug the error, we can add the -D option. Here's we'll

supply some input:

    >>> print system(buildout+" -D", """\

    ... up

    ... p self.options.keys()

    ... q

    ... """),

    Develop: '/sample-buildout/recipes'

    Installing data-dir.

    > /zc/buildout/buildout.py(925)__getitem__()

    -> raise MissingOption("Missing option: %s:%s" % (self.name, key))

    (Pdb) > /sample-buildout/recipes/mkdir.py(14)install()

    -> directory = self.options['directory']

    (Pdb) ['path', 'recipe']

    (Pdb) While:

      Installing data-dir.

    Traceback (most recent call last):

      File "/zc/buildout/buildout.py", line 1352, in main

        getattr(buildout, command)(args)

      File "/zc/buildout/buildout.py", line 383, in install

        installed_files = self[part]._call(recipe.install)

      File "/zc/buildout/buildout.py", line 961, in _call

        return f()

      File "/sample-buildout/recipes/mkdir.py", line 14, in install

        directory = self.options['directory']

      File "/zc/buildout/buildout.py", line 925, in __getitem__

        raise MissingOption("Missing option: %s:%s" % (self.name, key))

    MissingOption: Missing option: data-dir:directory

    <BLANKLINE>

    Starting pdb: