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)