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