Welcome to ape’s documentation!¶

Bootstrapping a container mode environment¶

Make sure you have pip and virtualenv installed. If not, try:

$ easy_install pip $ pip install virtualenv

On Debian/Ubuntu, these are also available as system packages python-pip and python-virtualenv.

Fetch the script to bootstrap ape in container mode:

$ wget https://raw.github.com/henzk/ape/master/bin/bootstrape
$ chmod 0755 bootstrape

Now, run bootstrape to create the container structure in a folder called aperoot(change this to your liking):

$ bootstrape aperoot

To install the development version, run this instead:

$ bootstrape --dev aperoot

After the process has finished a folder aperoot is available. It contains all necessary files and dependencies. A virtualenv has been created at aperoot/_ape/venv. To activate the container mode, source the activation script for ape in your shell (requires bash):

$ . aperoot/_ape/activape

Congratulations! ape is now installed and container mode is activated.

Installing ape globally¶

To install the latest version of ape, use pip:

$ pip install ape

To get the development version of ape directly from github, use:

$ pip install git+https://github.com/henzk/ape.git#egg=ape

Now, ape should be available on your PATH:

$ ape
Error running ape:
Either the PRODUCT_EQUATION or PRODUCT_EQUATION_FILENAME environment variable needs to be set!

Container Mode¶

In container mode, ape manages your features and products in a directory structure. It provides special tasks to switch between products.

All files managed by ape are placed inside a directory that we will refer to as APE_ROOT_DIR in the following. If you followed the installation instructions, this folder is called aperoot.

It contains:

• a directory named _ape. This directory contains the activation script and other global ressources like the global virtualenv.
• multiple SPL Containers. These are installations of specific versions of software product lines you manage using ape.

Standalone Mode¶

In standalone mode, ape checks the environment variable PRODUCT_EQUATION to get the list of features in composition order.

It needs to contain the names of the features seperated by spaces, e.g. "basic_tasks extra_tasks my_adjustments". For details on how features are specified, see Feature modules.

Feature modules need to be placed on the PYTHONPATH so ape can find them. In container mode, ape can manage that for you.

Layout¶

Feature modules are Python Packages that contain a module called tasks, so a minimal feature called myfeature would look like this:

myfeature/
    __init__.py
    tasks.py

Feature modules need to be placed on the PYTHONPATH.

When using container mode, this part is managed for you.

Introducing tasks¶

Tasks are introduced by implementing the task as a python function in your feature`s tasks module. The function must be decorated with ape.tasks.register to become a task:

#myfeature/tasks.py

from ape import tasks

@tasks.register
def mynewtask(a, b, c=1):
    """description of mynewtask"""
    print a, b, c

To make the task available from the command line, we need to select myfeature by setting the PRODUCT_EQUATION shell variable:

$ export PRODUCT_EQUATION="myfeature"

Now, make sure mynewtask is listed in the output of:

$ ape help

Finally, let`s invoke it:

$ ape mynewtask 1 2 --c 5
1 2 5
$ ape mynewtask 1 2
1 2 1

Refining a task¶

Here, we refine mynewtask in another feature. To do that, we need to specify a higher order function called refine_mynewtask that returns the refined task function. The refined function can access the original implementation as original.

#anotherfeature/tasks.py

def refine_mynewtask(original):
    def mynewtask(a, b, c=7):
        """updated description of mynewtask"""
        print 'refined task'
        original(a, b, c=c)
    return mynewtask

So, to refine a task, we need to define a “factory” that accepts the original task as parameter and returns a wrapper —the refined task. The factory must be named refine_ followed by the name of the task to refine — in the example above, this results in refine_mynewtask. When the feature composer encounters this function, it applies the refinement.

ape uses featuremonkey to compose the feature modules. For a more detailed description on the composition process, please see the featuremonkey documentation at http://featuremonkey.readthedocs.org.

Calling other tasks¶

Often, tasks need to call other tasks. Functions decorated with ape.tasks.register cannot be called directly. This is a safety mechanism to protect against calling partially composed tasks.

To call another task called mynewtask call ape.tasks.mynewtask:

#somefeature/tasks.py

@tasks.register
def taskcallingtask():
    #call mynewtask
    tasks.mynewtask(1, 2, c=3)

Running ape¶