From 38f2d1f6a583d7dbc7aff543c55aa9b32f5fab81 Mon Sep 17 00:00:00 2001 From: Gonzalo de Pedro Date: Wed, 31 Jan 2024 17:15:43 -0300 Subject: [PATCH] Added documentation for code generation Signed-off-by: Gonzalo de Pedro --- .../Advanced/About-Internal-Interfaces.rst | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/source/Concepts/Advanced/About-Internal-Interfaces.rst b/source/Concepts/Advanced/About-Internal-Interfaces.rst index a80cb2b83e8..61ffc76ff92 100644 --- a/source/Concepts/Advanced/About-Internal-Interfaces.rst +++ b/source/Concepts/Advanced/About-Internal-Interfaces.rst @@ -191,3 +191,58 @@ These are mainly used for error handling, commandline argument parsing, and logg The ``rcutils`` |API| and implementation are located in the `ros2/rcutils `_ repository on |GitHub|_ which contains the interface as C headers. For a complete definition of the ``rcutils`` |API|, see `the rcutils docs `_. + +Automatic code generation using template files +============================================== + +As mentioned above, in order to deal with different DDS implementations, code has to be generated. Code generation is handled by a clever usage +of CMake and Ament. To simplify the explanation of this mechanism let's separate ROS2 projects that generate or need code to be generated in two types. + +- ``Generator`` projects, which are the ones that have the templates and logic to generate code. +- ``Client`` projects, which are the ones that need code to be generated, they have the parameters to generate code. + +For instance, typesupport packages that generate code for a particular dds implementation are *Generator* packages, same case that rosidl which +generates code from ros idl (.msg, .action, etc) files. + +*Client* projects are typically projects that define messages, actions and services. Which have .msg files with rosidl defined on them which are +used by *Generator* projects to create code. A package that calls rosidl_generate_interfaces CMake macro is a *Client* project. + +Code generation workflow +------------------------ + +On workspace build, the *generator* packages, registers a portion of CMake code as an ament_extension under 'rosidl_generate_idl_interfaces' key. + +Hook registration on CodeGenerator project build + +.. mermaid:: + + sequenceDiagram + participant CodeGenerator_cmake + participant ament_package + participant ament_register_extension + CodeGenerator_cmake->>ament_package: CONFIG_EXTRAS + ament_package->>ament_register_extension: rosidl_generate_idl_interfaces, cmake_code_hook + Note right of ament_package: Execute a cmake.in template with variables and a cmake code hook. + + +When the *client* package, during its build process, calls the 'rosidl_generate_interfaces' macro, the extensions that were registered for each of the +*generator* packages, get called. Said extensions have the code to generate sources for each of the IDL interfaces. Then, code is added to an artifact +(a library) and dependiences are exported for code to be build and installed. + +.. mermaid:: + + sequenceDiagram + participant project_with_rosidl_files + participant rosidl_generate_interfaces + participant rosidl_generate_idl_interfaces_HOOK + participant generate_arguments_file + participant rosidl_generator + project_with_rosidl_files->>rosidl_generate_interfaces: path_to_idl_files + loop ForEach Hook + rosidl_generate_interfaces->>rosidl_generate_idl_interfaces_HOOK: path_to_idl_files, parameters + rosidl_generate_idl_interfaces_HOOK->>generate_arguments_file: template_parameters + activate generate_arguments_file + generate_arguments_file->>rosidl_generate_idl_interfaces_HOOK: arguments_file + deactivate generate_arguments_file + rosidl_generate_idl_interfaces_HOOK->>rosidl_generator: arguments_file + end