Metadata-Version: 1.0
Name: collective.recipe.omelette
Version: 0.3
Summary: Creates a unified directory structure of all namespace packages, symlinking to the actual contents, in order to ease navigation.
Home-page: UNKNOWN
Author: David Glick
Author-email: davidglick@onenw.org
License: GPL
Description: Code repository: http://svn.plone.org/svn/collective/buildout/collective.recipe.omelette/trunk
        
        Change history
        **************
        
        0.3 (2008-03-30)
        ================
        
        - Fixed test infrastructure.
        [davisagli]
        
        - Added option to ignore develop eggs
        [claytron]
        
        - Added option to ignore eggs
        [claytron]
        
        - Added option to override the default omelette location.
        [davisagli]
        
        
        0.2 (2008-03-16)
        ================
        
        - Fixed so created directories are not normalized to lowercase.
        [davisagli]
        
        
        0.1 (2008-03-10)
        ================
        
        - Initial basic implementation.
        [davisagli]
        
        - Created recipe with ZopeSkel.
        [davisagli]
        
        Detailed Documentation
        **********************
        
        Introduction
        ============
        
        Namespace packages offer the huge benefit of being able to distribute parts of a large
        system in small, self-contained pieces.  However, they can be somewhat clunky to navigate,
        since you end up with a large list of eggs in your egg cache, and then a seemingly endless
        series of directories you need to open to actually find the contents of your egg.
        
        This recipe sets up a directory structure that mirrors the actual python namespaces, with
        symlinks to the egg contents.  So, instead of this...::
        
        egg-cache/
        my.egg.one-1.0-py2.4.egg/
        my/
        egg/
        one/
        (contents of first egg)
        my.egg.two-1.0-py2.4.egg/
        my/
        egg/
        two/
        (contents of second egg)
        
        ...you get this::
        
        omelette/
        my/
        egg/
        one/
        (contents of first egg)
        two/
        (contents of second egg)
        
        
        **Caveat 1**: Don't try to manually add any eggs to the omelette!
        
        **Caveat 2**: This only works with filesystems that support symlinks (so no go on Windows).
        
        
        Supported options
        =================
        
        The recipe supports the following options:
        
        eggs
        List of eggs which should be included in the omelette.
        
        location
        Override the directory in which the omelette is created (default is parts/[name of buildout part])
        
        ignore-develop
        Ignore eggs that you are currently developing (listed in ${buildout:develop}). Default is False
        
        ignores
        List of eggs to ignore when preparing your omelete.
        
        Example usage
        =============
        
        Usage is pretty basic.  The following installs a buildout and omelette featuring the
        setuptools egg (for the sake of example, since it has no dependencies)::
        
        >>> write('buildout.cfg',
        ... """
        ... [buildout]
        ... eggs = setuptools
        ... parts = omelette
        ...
        ... [omelette]
        ... recipe = collective.recipe.omelette
        ... eggs = ${buildout:eggs}
        ... """)
        
        Running the buildout gives us::
        
        >>> print system(buildout)
        Installing omelette.
        <BLANKLINE>
        
        Now we have an easily navigable link::
        
        >>> import os
        >>> os.path.exists('parts/omelette/setuptools')
        True
        >>> ls('parts/omelette')
        d setuptools
        
        And it points to the real location of the egg's contents::
        
        >>> os.readlink('parts/omelette/setuptools')
        '/sample-buildout/eggs/setuptools-....egg/setuptools'
        
        If we call the part something else, the omelette should be created there instead
        (and the old one removed)::
        
        >>> write('buildout.cfg',
        ... """
        ... [buildout]
        ... eggs = setuptools
        ... parts = frittata
        ...
        ... [frittata]
        ... recipe = collective.recipe.omelette
        ... eggs = ${buildout:eggs}
        ... """)
        >>> print system(buildout + ' -q')
        >>> os.path.exists('parts/omelette')
        False
        >>> os.path.exists('parts/frittata')
        True
        
        You can also override the location of the omelette if you want to put it
        somewhere else entirely::
        
        >>> write('buildout.cfg',
        ... """
        ... [buildout]
        ... eggs = setuptools
        ... parts = omelette
        ...
        ... [omelette]
        ... recipe = collective.recipe.omelette
        ... eggs = ${buildout:eggs}
        ... location = ${buildout:directory}/omelette
        ... """)
        >>> print system(buildout + ' -q')
        >>> os.path.exists('omelette')
        True
        
        You can ignore a particular package:
        
        >>> write('buildout.cfg',
        ... """
        ... [buildout]
        ... eggs = setuptools
        ... parts = omelette
        ...
        ... [omelette]
        ... recipe = collective.recipe.omelette
        ... eggs = ${buildout:eggs}
        ... ignores = setuptools
        ... """)
        >>> print system(buildout + ' -q')
        >>> os.path.exists('parts/omelette/setuptools')
        False
        
        Or ignore all development eggs:
        
        >>> write('buildout.cfg',
        ... """
        ... [buildout]
        ... eggs = collective.recipe.omelette
        ... parts = omelette
        ...
        ... [omelette]
        ... recipe = collective.recipe.omelette
        ... eggs = ${buildout:eggs}
        ... ignore-develop = true
        ... """)
        >>> print system(buildout + ' -q')
        >>> os.path.exists('parts/omelette/collective/recipe/omelette')
        False
        
        Running the tests
        =================
        
        The subversion checkout of collective.recipe.omelette includes a buildout
        which installs a script for running the tests.
        
        Just run:
        python2.4 bootstrap.py
        bin/buildout
        bin/test
        
        Known issue: The tests run buildout in a separate process, so it's currently
        impossible to put a pdb breakpoint in the recipe and debug during the test.
        If you need to do this, set up another buildout which installs an omelette
        part and includes collective.recipe.omelette as a development egg.
        
        
        Reporting bugs or asking questions
        ==================================
        
        There is a shared bugtracker and help desk on Launchpad:
        https://bugs.launchpad.net/collective.buildout/
        
        Contributors
        ************
        
        David Glick [davisagli], Author
        Clayton Parker [claytron], Code Monkey
        
        Download
        ********
        
Keywords: buildout eggs namespace
Platform: UNKNOWN
Classifier: Framework :: Buildout
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
