MANAGE.PY(1)

NAME
manage.py - plainbox provider management script

SYNOPSIS

        manage.py [--help] [--version] [options]

DESCRIPTION

Per-provider management script

This manual page documents the typical aspects of the manage.py file initially generated for each Plainbox provider by plainbox startprovider. It is not to be confused by manage.py files used by web applications written using the Django framework.

OPTIONS

Optional arguments:

    --version
        show program's version number and exit

    -v, --verbose
        be more verbose (same as --log-level=INFO)

    -D, --debug
        enable DEBUG messages on the root logger

    -C, --debug-console
        display DEBUG messages in the console

    -T, --trace
        enable DEBUG messages on the specified logger (can be used multiple times)

    -P, --pdb
        jump into pdb (python debugger) when a command crashes

    -I, --debug-interrupt
        crash on SIGINT/KeyboardInterrupt, useful with --pdb

SUB-COMMANDS

    manage.py info [-h]
        display basic information about this provider

    manage.py validate [-h] [-s] [-d] [-l] [-L]
        perform various static analysis and validation

    manage.py develop [-h] [-u] [-f] [-d DIRECTORY]
        install/remove this provider, only for development

    manage.py install [-h] [--prefix PREFIX] [--layout {flat,relocatable,unix}]
                          [--root ROOT] install this provider in the system

    manage.py sdist [-h]
        create a source tarball

    manage.py i18n [-h] [-n] [--dont-update-pot] [--dont-merge-po]
                       [--dont-build-mo] update, merge and build translation catalogs

    manage.py build [-h]
        build provider specific executables from source

    manage.py clean [-h]
        clean build results

    manage.py packaging [-h]
        generate packaging meta-data

WORKING WITH PROVIDERS

Plainbox is pretty flexible and allows developers and tests alike to work with providers in several different ways. First of all, providers are typically packaged into Debian packages. Such packages are installed in system-wide locations (look at the output of ./manage.py install --help).

One particular file that is a part of such providers, that you don't typically see in the source directory, is a file with the extension .provider. Plainbox looks for files like that in several places (see plainbox(1) discussion of PROVIDERPATH). When working on a provider (either writing a new provider from scratch or extending an existing provider) that would be a quite tedious process to go through. For that you can use the manage.py develop command to create a .provider file in your $XDG_DATA_HOME/plainbox-providers-1/ directory. Plainbox will automatically pick it up and and you will be able to run jobs from it directly, without having to reinstall.

CAVEATS

The behavior of each management script may be different. Plainbox offers APIs to extend or override available commands so this man page should be seen as a spiritual intent rather than concrete behavior.

BUILDING PROVIDER-SPECIFIC EXECUTABLES

Plainbox assists in building provider-specific executables. Those are additional architecture-specific binary executables that can be used in job scripts.

Typically such additional executables are written in C and built with make. If your provider doesn't require any sophisticated build system then all you need to do is to create a src/ directory (alongside all the other provider directories) and create at least the following files inside:

    Makefile:
        The makefile that will build your executables. This assumes it is not generated (for example, with automake). It should place resulting executables int the current directory. It will be invoked from a different directory though, with make -f /path/to/Makefile, so be aware of that when writing your rules. Fortunately makefiles tend to just work so this is not an issue in practice.

    EXECUTABLES:
        This file lists all the executables (one per line) that will be built by the particular build system. It is used to ensure that Plainbox knows up front about executables built from source and to know which files to copy.

    (sources):
        You obviously need to provide source files for your executables. Just add them alongside all the other files in the src/ directory.

Once that is done, you should be able to run ./manage.py build. It will attempt to identify the build system that is being used (it understands C, go and autotools, to some extent) and then carry on to build everything as expected.

Resulting executables will be placed in build/bin. When working in development mode (via manage.py develop) that will all magically just work. Plainbox will figure out where each executable is, coping with files both in build/bin and in bin/ directories transparently. When installing (manage.py install) either locally or as a part of the packaging step that will also just work so you don't have do do anything else.

OVERRIDING / EXTENDING COMMANDS

Plainbox offers a decorator that can be used to extend any of the manage.py subcommands with additional functionality. The general syntax for extending existing commands is (here illustrated by changes to the sdist command):

        from plainbox.provider_manager import SourceDistributionCommand
        from plainbox.provider_manager import manage_py_extension

        @manage_py_extension
        class SourceDistributionCommandExt(SourceDistributionCommand):
            __doc__ = SourceDistributionCommand.__doc__

            def invoked(self, ns):
                super().invoked(ns)
                # Do something else as well

Note that in some cases you need to define the command name to match the original command name (for example, the install command requires this). Otherwise Plainbox will derive the command name from the class name which may be not what you expected:

        from plainbox.provider_manager import InstallCommand
        from plainbox.provider_manager import manage_py_extension

        @manage_py_extension
        class InstallCommandExt(InstallCommand):
            __doc__ = InstallCommand.__doc__
            name = 'install'

FURTHER READING

The Checkbox project comes with a number of providers that use various niche and under-documented features. It's always good to learn from existing examples. Have a look at the project source directory, go to providers/ and explore each provider there.

AUTHOR
Zygmunt Krynicki & Checkbox Contributors

COPYRIGHT
2012-2014 Canonical Ltd