ament_nodl

ament_nodl provides CMake macros for registering a node’s NoDL document with the ament resource index, so other tools can locate a node’s interface specification by package and executable name.

For what a NoDL document declares, see NoDL Concepts.

ament_nodl_register

Register a NoDL document with the ament index. This does three things:

  1. Validates the file at build time so authoring errors surface when registering rather than downstream when a consumer reads the spec. If the document uses include, this step also checks that its references resolve.

  2. Installs the file into the ament index under the nodl resource type, keyed <package>__<name>.

  3. Installs the file under share/<package>/nodl/ for direct filesystem access.

find_package(ament_nodl REQUIRED)

ament_nodl_register(my_node
  FILE nodl/my_node.nodl.yaml
)

Includes and build order

A nodl://<package>/<name> reference resolves through the ament index, which holds what is installed. Validation runs before this package is installed, so a referenced package must already be built and be a dependency of this one.

Arguments

executable_name:

Name of the executable the document describes. Combined with PACKAGE to form the resource key.

FILE:

Path to the NoDL file. Absolute, or relative to CMAKE_CURRENT_SOURCE_DIR. Required.

PACKAGE:

Package name used in the resource key. Defaults to ${PROJECT_NAME}.

See the macro source at ament_nodl/cmake/ament_nodl_register.cmake.

Consuming registered documents

Tools retrieve a registered document by its resource key:

from ament_index_python.packages import get_resource

content, path = get_resource('nodl', 'my_package__my_node')