Metadata-Version: 1.1
Name: ubuild
Version: 0.1.1
Summary: A no-frills build script framework.
Home-page: https://github.com/jeffrimko/Ubuild
Author: Jeff Rimko
Author-email: jeffrimko@gmail.com
License: MIT
Description: A no-frills build script framework.
        
        Introduction
        ============
        
        This project provides a Python 3.3+ library/utility for creating build
        scripts. The main features of Ubuild are:
        
        -  Streamlines the discoverability of build steps/tasks.
        
        -  Build step/task details are captured in Python functions.
        
        -  Provides a CLI menu to show available build steps/tasks.
        
        -  Provides a CLI utility ``ubuild`` to locate and run build scripts.
        
        Status
        ======
        
        Currently, this project is in the **development release** stage. While
        this project is suitable for use, please note that there may be
        incompatibilities in new releases.
        
        Release notes are maintained in the project
        `changelog <https://github.com/jeffrimko/Ubuild/blob/master/CHANGELOG.adoc>`__.
        
        Requirements
        ============
        
        Ubuild should run on any Python 3.3+ interpreter with some additional
        third-party libraries.
        
        Installation
        ============
        
        Ubuild is `available on PyPI
        here <https://pypi.python.org/pypi/ubuild>`__ and can be installed with
        pip using the following command: ``pip install ubuild``
        
        Additionally, Ubuild can be installed from source by running:
        ``python setup.py install``
        
        Usage
        =====
        
        Create a ``_Build.py`` file. Import ``ubuild`` and use the ``menu``
        decorator to add functions to the build menu. Use the ``main`` function
        to show the menu. For example:
        
        .. code:: python
        
            from ubuild import menu, main
        
            @menu
            def build():
                ...
        
            @menu
            def clean():
                ...
        
            main()
        
        Running this script will show the following menu:
        
        ::
        
            -- MENU --
              (b) Build
              (c) Clean
              (q) Quit
            [!] Menu loops until quit.
            [?] Enter menu selection:
        
        By default, the menu entry names are based off the function name. For
        example:
        
        -  ``something()`` â‡’ ``(s) Something``
        
        -  ``do_something()`` â‡’ ``(ds) Do Something``
        
        -  ``do_something_else()`` â‡’ ``(dse) Do Something Else``
        
        Because Ubuild is meant to be lightweight and capture build step
        details, often it might be useful to use
        `Auxly <https://github.com/jeffrimko/Auxly>`__ to call other utilities.
        For example:
        
        .. code:: python
        
            @menu
            def build():
                return auxly.shell.call("make")
        
        Note the ``return`` on the call. This allows the exit code from the
        ``make`` call to propagate up through to Ubuild, i.e. if the menu is
        quit after the call, the exit code for Ubuild will be the ``make`` exit
        code.
        
        The ``ubuild`` command line utility can be used in two different ways:
        
        1. Calling ``ubuild`` without arguments in a directory with
           ``_Build.py`` or any of the child directories will show the Ubuild
           menu.
        
        2. Calling ``ubuild`` with arguments in a directory with ``_Build.py``
           or any of the child directories will run that menu entry, e.g.
           ``ubuild b``.
        
        A few additional notes about the ``menu`` decorator:
        
        .. code:: python
        
            @menu("x")  # (x) Build
            def build():
                ...
        
            @menu(name="x")  # (x) Build
            def build():
                ...
        
            @menu(desc="Something")  # (s) Something
            def build():
                ...
        
            @menu("x", desc="Something")  # (x) Something
            def build():
                ...
        
            @menu(desc="Flag Set", args=[True])     # (fs) Flag Set
            @menu(desc="Flag Clear", args=[False])  # (fc) Flag Clear
            def build(flag):
                ...
        
            @menu(desc="Flag Clear", kwargs={'flag':False})  # (fc) Flag Clear
            def build(flag=True):
                ...
        
        Similar
        =======
        
        The following projects are similar and may be worth checking out:
        
        -  `Invoke <https://github.com/pyinvoke/invoke/>`__
        
Keywords: cli menu
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Topic :: Utilities
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
