Metadata-Version: 1.0
Name: bpt
Version: 0.2a
Summary: Tool to create isolated environments
Home-page: http://pypi.python.org/pypi/bpt
Author: Giuseppe Ottaviano
Author-email: giuott@gmail.com
License: UNKNOWN
Description: ==========================
        Boxed Package Tool (BPT)
        ==========================
        
        * `Mercurial repository <http://bitbucket.org/ot/bpt/>`_
        * `Issue tracker <http://bitbucket.org/ot/bpt/issues/>`_
        
        What is BPT
        ===========
        
        BPT is a Python library (``bpt``) and a command line application
        (``box``) to create and manage isolated enviroments, or *boxes*. Boxes
        are *relocatable*, which means that they can be moved to a different
        directory or even distributed to other machines (provided that the
        architecture is compatible). Packages inside the box can be easily
        disabled, enabled and removed, so that different versions of the same
        software can be installed simultaneously, allowing to switch between
        them.
        
        BPT is similar in some ways to `virtualenv
        <http://pypi.python.org/pypi/virtualenv>`_, but it is not restricted
        to Python packages, allowing to install virtually any Unix
        software. It also takes some ideas from `jhbuild
        <http://live.gnome.org/Jhbuild>`_, but without the dependency
        resolution and automatic downloading machinery, and the ``bpt-rules``
        format is inspired by `Gentoo <http://www.gentoo.org/>`_'s ebuilds.
        
        How to use it
        =============
        
        A *box* is a directory whose structure resembles ``/usr/``, that can
        contain one or more software *packages*. Each package is contained in
        a subdirectory of the ``pkgs`` directory in the box. A box contains a
        script, ``env``, which sets up the environment, putting all the
        libraries, executables, etc. in the path.
        
        The command to create a box is::
        
        $ bpt/box create my_first_box
        
        (We assume that the source distribution of BPT is in the directory ``bpt``)
        
        This creates the basic structure::
        
        $ find my_first_box
        my_first_box
        my_first_box/bin
        my_first_box/bpt_meta
        my_first_box/bpt_meta/box_info
        my_first_box/env
        my_first_box/include
        my_first_box/lib
        my_first_box/man
        my_first_box/pkgs
        my_first_box/share
        
        To execute a command within the box environment, use the ``env`` script::
        
        $ my_first_box/env 'echo $PATH'
        /tmp/box_87a482cc-34fc-11de-865a-001ec21bf2c7/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/usr/X11/bin:/usr/local/bin
        
        Even if it may not seem obvious at first, the first path points to the
        box's ``bin``. We'll talk about this later in the `How it works`_
        section. Prefixing ``env`` to every command can be annoying, so
        ``box`` has a ``shell`` command that spawns a shell with the
        environment set up. The ``env`` script exports also an environment
        variable, ``BPT_BOX_PATH``, that ``box`` uses to know the location of
        the current box::
        
        $ bpt/box -b my_first_box/ shell
        (my_first_box) ot@brian ~ $ echo $BPT_BOX_PATH
        /Users/ot/my_first_box
        
        To install packages into a box, ``box`` offers two different commands:
        ``build`` and ``autobuild``. The first works with *sourcedirs*: a
        *sourcedir* is a directory that contains a ``bpt-rules`` file, which
        contains the instructions to build the software. A good practice is to
        install BPT itself into the box (the source distribution of BPT is a
        *sourcedir*)::
        
        (my_first_box) ot@brian ~ $ bpt/box build bpt
        INFO:BPT:Using current box "my_first_box"
        INFO:BPT:Building application bpt, in sourcedir work/experimental/bpt
        ...
        (my_first_box) ot@brian ~ $ which box
        /tmp/box_87a482cc-34fc-11de-865a-001ec21bf2c7/bin/box
        
        Now we can run the shell using the box's ``box``::
        
        $ my_first_box/env box shell
        INFO:BPT:Using current box "my_first_box"
        
        (my_first_box) ot@brian ~ $
        
        Another example of *sourcedir* is given by ``python30`` in the
        ``examples`` directory, which installs python 3.0.1::
        
        (my_first_box) ot@brian ~ $ box build examples/python30/
        ...
        
        (my_first_box) ot@brian ~ $ python3.0 --version
        Python 3.0.1
        
        The ``autobuild`` command instead tries to build and install a
        tarball. It works when the software builds using the usual
        ``configure``/``make`` or ``setup.py``::
        
        (my_first_box) ot@brian ~ $ box autobuild Downloads/ipython-0.9.1.tar.gz
        INFO:BPT:Using current box "my_first_box"
        INFO:BPT:Guessed application name "ipython", version "0.9.1". Unpacking the file...
        INFO:BPT:Building and installing as package ipython-0.9.1
        ...
        
        (my_first_box) ot@brian ~ $ which ipython
        /tmp/box_87a482cc-34fc-11de-865a-001ec21bf2c7/bin/ipython
        
        (my_first_box) ot@brian ~ $ box autobuild Downloads/sqlite-amalgamation-3.6.3.tar.gz
        INFO:BPT:Using current box "my_first_box"
        INFO:BPT:Guessed application name "sqlite-amalgamation", version "3.6.3". Unpacking the file...
        INFO:BPT:Building and installing as package sqlite-amalgamation-3.6.3
        ...
        
        (my_first_box) ot@brian ~ $ which sqlite3
        /tmp/box_87a482cc-34fc-11de-865a-001ec21bf2c7/bin/sqlite3
        
        The ``status`` command shows the installed packages::
        
        (my_first_box) ot@brian ~ $ box status
        INFO:BPT:Using current box "my_first_box"
        
        PACKAGE                       | NAME                | VERSION   | STATUS    |
        
        bpt-0.1                       | bpt                 | 0.1       | enabled   |
        ipython-0.8.4                 | ipython             | 0.8.4     | disabled  |
        ipython-0.9.1                 | ipython             | 0.9.1     | enabled   |
        python30-3.0.1                | python30            | 3.0.1     | enabled   |
        sqlite-amalgamation-3.6.3     | sqlite-amalgamation | 3.6.3     | enabled   |
        
        Packages can be enabled/disabled with the ``enable``/``disable`` commands::
        
        (my_first_box) ot@brian ~ $ box disable python30-3.0.1
        
        (my_first_box) ot@brian ~ $ python3.0
        bash: python3.0: command not found
        
        (my_first_box) ot@brian ~ $ box enable python30-3.0.1
        
        (my_first_box) ot@brian ~ $ python3.0 --version
        Python 3.0.1
        
        Executing ``disable`` with the ``--remove`` switch deletes permanently
        the package files.
        
        
        Features
        ========
        
        TODO
        
        Use cases
        =========
        
        TODO
        
        How it works
        ============
        
        TODO
        
        Writing the ``bpt-rules`` file
        ==============================
        
        TODO
        
        Supported operating systems
        ===========================
        
        BPT should work with any POSIX operating system. It has been tested on
        Mac OS X Leopard and several Ubuntu releases.
        
        License
        =======
        
        BPT is distributed under the terms of the GPL License. The full
        license is in the file COPYING, distributed as part of this software.
        
        Credits
        =======
        
        * Giuseppe Ottaviano <giuott at gmail dot com>
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Operating System :: POSIX
Classifier: Topic :: Software Development :: Build Tools
