Adding New Build Types

The current release of catkin_tools supports building two types of packages:

  • Catkin – CMake packages that use the Catkin CMake macros
  • CMake – “Plain” CMake packages

In order to fully support additional build types, numerous additions need to be made to the command-line interfaces so that the necessary parameters can be passed to the build verb. For partial support, however, all that’s needed is to add a build type identifier and a function for generating build jobs.

The supported build types are easily extendable using the setuptools entry_points interface without modifying the catkin_tools project, itself. Regardless of what package the entry_point is defined in, it will be defined in the setup.py of that package, and will take this form:

from setuptools import setup

setup(
    ...
    entry_points={
        ...
        'catkin_tools.jobs': [
            'mybuild = my_package.some.module:description',
        ],
    },
)

This entry in the setup.py places a file in the PYTHONPATH when either the install or the develop verb is given to setup.py. This file relates the key (in this case mybuild) to a module and attribute (in this case my_package.some.module and description).

Then the catkin command will use the pkg_resources modules to retrieve these mapping at run time. Any entry for the catkin_tools.jobs group must point to a description attribute of a module, where the description attribute is a dict. The description dict should take this form:

description = dict(
    build_type='mybuild',
    description="Builds a package with the 'mybuild' build type",
    create_build_job=create_mybuild_build_job
)

This dict defines all the information that the catkin command needs to create jobs for the mybuild build type. The build_type key takes a string which is the build type identifier. The description key takes a string which briefly describes the build type. The create_build_job key takes a callable (function) factory which is called in order to create a Job to build a package of type mybuild.

The signature of the factory callable should be similar to the following:

def create_mybuild_build_job(context, package, package_path, dependencies, **kwargs):
    # Initialize empty list of build stages
    stages = []

    # Add stages required to build ``mybuild``-type packages,
    # based on the configuration context.
    # ...

    # Create and return new build Job
    return Job(
        jid=package.name,
        deps=dependencies,
        stages=stages)