code — Tools for checking out and building code

This submodule contains a few useful tasks for checking out, configuring, and building arbitrary code.

The CheckoutTask task class checks out a version-controlled repository. For the moment, only git repositories are supported. The path to the git executable may be specified through the CheckoutTask.GIT class variable.

Todo

Implement svn and cvs checkout; copy checkout (i.e. copy a directory from somewhere) may also be useful.

The BuildTask task class builds code from a given source directory. A build directory must also be specified and will be created if necessary. For the moment, BuildTask only supports ` cmake builds, but there are plans to add support for autoconf/configure/make builds. The path to the cmake executable may be specified through the BuildTask.CMAKE class variable.

Todo

Implement autoconf/configure/make builds.

To describe the usage of CheckoutTask and BuildTask, let us assume that repo_dir contains a git repository with a CMake project. We use a temporary directory work_dir for our test:

>>> checkout_dir = work_dir / 'checkout'
>>> build_dir = work_dir / 'build'
>>> log_dir = work_dir / 'log'

Now we can build checkout and build tasks for this repository:

>>> from valjean.cosette.code import CheckoutTask, BuildTask
>>> from pprint import pprint
>>> ct = CheckoutTask(name='project_checkout',
...                   repository=repo_dir,
...                   checkout_root=checkout_dir,
...                   log_root=log_dir)
>>> bt = BuildTask(name='project_build',
...                source=ct,
...                build_root=build_dir,
...                build_flags=['--' ,'-j4'],
...                log_root=log_dir)

Note how we passed the ct object directly to the source argument of the BuildTask constructor: we are telling the BuildTask to look for the sources to build in the checkout directory. You can also pass a normal path to the source argument instead.

>>> from valjean.cosette.env import Env
>>> env = Env()
>>> ct_up, ct_status = ct.do(env, config=None)
>>> print(ct_status)
TaskStatus.DONE
>>> pprint(ct_up)
{'project_checkout': {'checkout_log': '.../log/project_checkout.log',
                      'elapsed_time': ...,
                      'output_dir': '.../checkout/project_checkout',
                      'repository': '.../repo'}}
>>> env.apply(ct_up)  # apply CheckoutTask's environment update
...                   # for this example, this is actually optional
>>> bt_up, bt_status = bt.do(env=env, config=None)
>>> print(bt_status)
TaskStatus.DONE
>>> pprint(bt_up)
{'project_build': {'build_log': '.../log/project_build.log',
                   'elapsed_time': ...,
                   'output_dir': '.../build/project_build'}}
class valjean.cosette.code.CheckoutTask(name, *, repository, checkout_root=None, log_root=None, flags=None, ref=None, vcs='git', deps=None, soft_deps=None)[source]

Task to check out code from a version-control system. The actual code checkout is performed when the task is executed.

__init__(name, *, repository, checkout_root=None, log_root=None, flags=None, ref=None, vcs='git', deps=None, soft_deps=None)[source]

Construct a CheckoutTask.

Parameters:

  • name (str) – The name of this task.

  • checkout_root (str) – The directory where the code will be checked out, or None for the configuration default.

  • repository (str) – The repository for checkout.

  • log_root (str) – The path to the log directory, or None for the configuration default.

  • flags (list(str) or None) – The flags to be used at checkout time, as a list of strings.

  • ref (str or None) – The reference to check out.

  • vcs (str or None) – The version-control system to use. Must be one of: 'git' (default), 'svn', 'cvs', 'copy'.

  • deps (list(Task) or None) – The dependencies for this task (see Task.__init__() for the format), or None.

  • soft_deps (list(Task) or None) – The soft dependencies for this task (see Task.__init__() for the format), or None.

GIT = 'git'

Path to the git executable. May be overridden before class instantiation.

class valjean.cosette.code.BuildTask(name, source, *, build_root=None, log_root=None, targets=None, build_system='cmake', configure_flags=None, build_flags=None, deps=None, soft_deps=None)[source]

Task to build an existing source tree. The build is actually performed when the task is executed.

__init__(name, source, *, build_root=None, log_root=None, targets=None, build_system='cmake', configure_flags=None, build_flags=None, deps=None, soft_deps=None)[source]

Construct a BuildTask.

Parameters:

  • name (str) – The name of this task.

  • source (str) – The path to the directory containing the sources, or a CheckoutTask object (in which case the checkout directory will be assumed to contain the sources).

  • build_root (str) – The path to the build directory (a subdirectory will be created).

  • log_root (str) – The path to the log directory.

  • targets (list(str) or None) – A list of targets to build, or None for the default target.

  • build_system (str) – The name of the build system to use. Must be one of: 'cmake' (default), 'configure'.

  • configure_flags (list) – The flags that will be passed to the build tool at configuration time, as a list of strings.

  • build_flags (list) – The flags that will be passed to the build tool at build time, as a list of strings.

  • deps (list(Task) or None) – The dependencies for this task (see Task.__init__() for the type), or None.

  • soft_deps (list(Task) or None) – The soft dependencies for this task (see Task.__init__() for the type), or None.

cmake_build_sys(targets, configure_flags, build_flags)[source]

Return a function that builds a project using cmake.

CMAKE = 'cmake'

Path to the cmake executable. May be overridden before class instantiation.