Metadata-Version: 1.0
Name: buildout.dumppickedversions
Version: 0.4
Summary: Dump buildout picked versions.
Home-page: http://svn.plone.org/svn/collective/buildout/buildout.dumppickedversions
Author: Mustapha Benali
Author-email: mustapha@headnet.dk
License: GPL
Description: buildout.dumppickedversions
        ===========================
        
        Q: What is a buildout extension ?
        
        A: http://pypi.python.org/pypi/zc.buildout#extensions
        
        The problem
        -----------
        
        When using a zc.buildout based deployment system you want to be able to
        reproduce the same setup with the same set of egg versions one month later.
        Without pinning all eggs the task is impossible.
        
        
        Solution
        --------
        
        ``buildout.dumppickedversions`` is a buildout extension that does just that. It
        can print or generate a versions.cfg file with all not pinned eggs.
        
        It adds also a comment before each egg picked by zc.buildout as requirment for
        other eggs containing the list of eggs that required it.
        
        
        buildout.dumppickedversions options
        -----------------------------------
        
        dump-picked-versions-file
        A file name you want ``buildout.dumppickedversions`` to write to.
        If not given ``buildout.dumppickedversions`` will dump the versions to the
        screen.
        
        overwrite-picked-versions-file
        If set to ``true``, ``buildout.dumppickedversions`` will overwrite the file
        defined in ``dump-picked-versions-file`` if it exists. Defaults to True.
        
        
        Detailed Documentation
        ======================
        
        
        Let's create an egg to use it in our tests::
        
        >>> mkdir('myegg')
        >>> write('myegg', 'setup.py',
        ... '''
        ... from setuptools import setup
        ... setup(name='myegg', version='1.0',)
        ... ''')
        >>> write('myegg', 'README', '')
        >>> print system(buildout+' setup myegg bdist_egg'), # doctest: +ELLIPSIS
        Running setup script 'myegg/setup.py'.
        ...
        
        Now let's create a buildout to install the egg and to use
        buildout.dumppickedversions::
        
        >>> write('buildout.cfg',
        ... '''
        ... [buildout]
        ... extensions = buildout.dumppickedversions
        ... parts = foo
        ... find-links = %s
        ... index = http://pypi.python.org/simple
        ... [foo]
        ... recipe = zc.recipe.egg
        ... eggs = myegg
        ... ''' % join('myegg', 'dist'))
        
        Running the buildout will print information about picked versions::
        
        >>> print system(buildout), # doctest: +ELLIPSIS
        Getting distribution for 'buildout.dumppickedversions'.
        ...
        *************** PICKED VERSIONS ****************
        [versions]
        myegg = N.N
        setuptools = N.N
        zc.buildout = N.N
        zc.recipe.egg = N.N
        <BLANKLINE>
        *************** /PICKED VERSIONS ***************
        
        To dump picked versions to a file, we just add an ``dump-picked-versions-file``
        option and give a file name::
        
        >>> write('buildout.cfg',
        ... '''
        ... [buildout]
        ... extensions = buildout.dumppickedversions
        ... dump-picked-versions-file = versions.cfg
        ... parts = foo
        ... find-links =
        ...     %s
        ... index = http://pypi.python.org/simple
        ... [foo]
        ... recipe = zc.recipe.egg
        ... eggs =
        ...     myegg
        ... ''' % join('myegg', 'dist'))
        
        >>> print system(buildout), # doctest: +ELLIPSIS
        Uninstalling foo.
        Installing foo.
        *********************************************
        Writing picked versions to versions.cfg
        *********************************************
        
        And here is the content of the file versions.cfg::
        
        >>> cat('versions.cfg')
        [versions]
        myegg = N.N
        setuptools = N.N
        zc.buildout = N.N
        zc.recipe.egg = N.N
        <BLANKLINE>
        
        Next time we run the buildout the file will be overwritten::
        
        >>> print system(buildout), # doctest: +ELLIPSIS
        Updating foo.
        *********************************************
        Overwriting versions.cfg
        *********************************************
        
        When we don't want to overwrite the file we just add an
        ``overwrite-picked-versions-file`` and set it to false::
        
        >>> write('buildout.cfg',
        ... '''
        ... [buildout]
        ... extensions = buildout.dumppickedversions
        ... dump-picked-versions-file = versions.cfg
        ... overwrite-picked-versions-file = false
        ... parts = foo
        ... find-links =
        ...     %s
        ... index = http://pypi.python.org/simple
        ... [foo]
        ... recipe = zc.recipe.egg
        ... eggs =
        ...     myegg
        ... ''' % join('myegg', 'dist'))
        
        >>> print system(buildout), # doctest: +ELLIPSIS
        Updating foo.
        *********************************************
        Skipped: File versions.cfg already exists.
        *********************************************
        
        If an eggA is installed as requirment for other eggs, you will get a comment
        line just before eggA with the list of eggs that required it.
        
        Let's show an example. We will install zope.component::
        
        >>> write('buildout.cfg',
        ... '''
        ... [buildout]
        ... extensions = buildout.dumppickedversions
        ... dump-picked-versions-file = versions.cfg
        ... parts = foo
        ... index = http://pypi.python.org/simple
        ... [foo]
        ... recipe = zc.recipe.egg
        ... eggs = zope.component
        ... ''')
        
        >>> print system(buildout), # doctest: +ELLIPSIS
        Uninstalling foo.
        Installing foo.
        Getting distribution for 'zope.component'.
        ...
        *********************************************
        Overwriting versions.cfg
        *********************************************
        
        and let's see the content of the versions.cfg file::
        
        >>> cat('versions.cfg')
        [versions]
        zc.buildout = N.N
        zc.recipe.egg = N.N
        zope.component = N.N
        <BLANKLINE>
        #Required by:
        #zope.event N.N
        #zope.interface N.N
        #zope.component N.N
        setuptools = N.N
        <BLANKLINE>
        #Required by:
        #zope.component N.N
        zope.event = N.N
        <BLANKLINE>
        #Required by:
        #zope.component N.N
        zope.interface = N.N
        
        
        Change history
        ==============
        
        0.4 2009-05-03
        ----------------
        
        - Removed duplicated comment lines [mustapha]
        
        0.3 (2009-05-03)
        ----------------
        
        - Added comments in the generated versions file about what eggs
        required the picked egg if any. [mustapha]
        
        0.2 (2009-03-15)
        ----------------
        
        - Removed the buildout header from the dumped file [mustapha]
        
        - Added overwrite-picked-versions-file option [mustapha]
        
        0.1 (2009-02-07)
        ----------------
        
        - Created recipe with ZopeSkel.
        [mustapha]
        
        Contributors
        ============
        
        - Mustapha Benali, Author
        
        
Keywords: buildout extension dump picked versions
Platform: UNKNOWN
Classifier: Framework :: Buildout
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
