diff --git a/source/Concepts/Advanced/About-Internal-Interfaces.rst b/source/Concepts/Advanced/About-Internal-Interfaces.rst index 61ffc76ff92..16d021feacf 100644 --- a/source/Concepts/Advanced/About-Internal-Interfaces.rst +++ b/source/Concepts/Advanced/About-Internal-Interfaces.rst @@ -201,16 +201,20 @@ of CMake and Ament. To simplify the explanation of this mechanism let's separate - ``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 +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. +``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 crete code. A package that calls rosidl_generate_interfaces CMake macro is a ``Client`` project. Code generation workflow ------------------------- +------------------------- + +On workspace build, the ``generator`` packages, registers portions of CMake code as an ament_extension under different keys: -On workspace build, the *generator* packages, registers a portion of CMake code as an ament_extension under 'rosidl_generate_idl_interfaces' key. +- ``rosidl_create_type_descriptions_extensions`` : Calls type support description extensions(generate hashes for typessupports) +- ``rosidl_write_generator_arguments_extensions``: Generate the arguments files. +- ``rosidl_generate_idl_interfaces``: After files are generated, create artifacts, export dependencies. Hook registration on CodeGenerator project build @@ -221,28 +225,40 @@ Hook registration on CodeGenerator project build participant ament_package participant ament_register_extension CodeGenerator_cmake->>ament_package: CONFIG_EXTRAS + ament_package->>ament_register_extension: rosidl_create_type_descriptions_extensions, cmake_code_hook + ament_package->>ament_register_extension: rosidl_write_generator_arguments_extensions, cmake_code_hook 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. +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. On 'rosidl_write_generator_arguments_extensions' arguments files are generated with all parameters required to call the templates engine. +After collecting all the arguments files, the extension calls the template engine for all the arguments files at once. Once code is generated, +the 'rosidl_generate_idl_interfaces' extensiones are called to get code added to an artifact (a library) and export dependiences. .. mermaid:: sequenceDiagram participant project_with_rosidl_files participant rosidl_generate_interfaces + participant rosidl_create_type_descriptions_extensions_HOOK participant rosidl_generate_idl_interfaces_HOOK + participant rosidl_write_generator_arguments_extensions_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 + loop ForEach rosidl_create_type_descriptions_extensions Hook + rosidl_generate_interfaces->>rosidl_create_type_descriptions_extensions_HOOK: path_to_idl_files, parameters + end + loop ForEach rosidl_write_generator_arguments_extensions Hook + rosidl_generate_interfaces->>rosidl_write_generator_arguments_extensions_HOOK: path_to_idl_files, parameters activate generate_arguments_file - generate_arguments_file->>rosidl_generate_idl_interfaces_HOOK: arguments_file + rosidl_write_generator_arguments_extensions_HOOK->>generate_arguments_file: path_to_idl_files, parameters + generate_arguments_file->>rosidl_write_generator_arguments_extensions_HOOK: arguments_file deactivate generate_arguments_file - rosidl_generate_idl_interfaces_HOOK->>rosidl_generator: arguments_file + rosidl_write_generator_arguments_extensions_HOOK->>rosidl_generate_interfaces: arguments_file + end + rosidl_generate_interfaces->>rosidl_generator: [arguments_files] + loop ForEach rosidl_generate_idl_interfaces Hook + rosidl_generate_interfaces->>rosidl_generate_idl_interfaces_HOOK: generated_files end