Skip to content

Manual_commsdsl2c.md

Latest commit

 

History

History
147 lines (120 loc) · 5.77 KB

Manual_commsdsl2c.md

File metadata and controls

147 lines (120 loc) · 5.77 KB
Raw

Manual of commsdsl2c

Overview

The commsdsl2c is a code generation tool provided by this project. It generates CMake project that can be used to build a library with "C" interface for the protocol definition code generated by the commsdsl2comms.

Command Line Arguments

The commsdsl2c utility has multiple command line arguments, please use -h option for the full list as well as default option values.

$> /path/to/commsdsl2c -h

Below is a summary of most important ones.

Selecting Schema Files

Selecting of the schema files is very similar to how it is done for the commsdsl2comms.

List all the schema files at the end of the command line arguments:

$> /path/to/commsdsl2c <args> schema1.xml schema2.xml schema3.xml ...

The schema files will be processed in order of their listing.

When the input files are listed in the single file:

$> /path/to/commsdsl2c -i schemas_list.txt

When a schemas listing file contains relative paths to the schema files use -p option to specify the absolute path prefix.

$> /path/to/commsdsl2c -i schemas_list.txt -p /path/to/schemas/dir

Output Directory

By default the output CMake project is written to the current directory. It is possible to change that using -o option.

$> /path/to/commsdsl2c -o /some/output/dir schema.xml

Injecting Custom Code

The commsdsl2c utility allows injection of custom code into the generated project in case the default code is incorrect and/or incomplete. For this purpose -c option with path to directory containing custom code snippets is used.

$> /path/to/commsdsl2c -c /path/to/custom/code/snippets schema.xml

In order to see what code injection elements are available using what files, temporarily use --code-inject-comments command line option and review the generated files. The generated code will be populated with // [CODE INJECT]: comment lines indicating places where code injection is possible.

$> /path/to/commsdsl2c --code-inject-comments ...

Please read Custom Code section below for more details on how to format and where to place the custom code.

Changing Main Namespace

The code generated by the commsdsl2c depends on the code generated by the commsdsl2comms. If the code generated by the commsdsl2comms changed its main namespace then it is required to change the main namespace for the code generated by the commsdsl2c as well.

$> /path/to/commsdsl2c -n other_ns_name schema.xml

Selecting Interface

When the protocol defines multiple interfaces, there is a need to select only one that is applicable to the generated solution. To select appropriate interface use --force-interface command line option.

$> /path/to/commsdsl2c --force-interface Interface1 ...

Using Subsets of Messages

The code generated by the commsdsl2comms contains definitions of all the messages defined in the schema file(s). When the protocol is too big and/or there are messages which are inapplicable to the created solution, they can be excluded from the bindings support. To do so there is a need to create a separate file listing all the messages IDs (using their full reference strings including namespaced if applicable). Then the file with the messages list can be provided using the --messages-list command line option.

$> /path/to/commsdsl2c --messages-list /path/to/messages/list/file ...

Selecting Frame Input Messages

Definition of the framing class generated by the commsdsl2comms requires selection of the input messages bundled in std::tuple. The project generated by the commsdsl2comms will have possible input bundles in the <prot_ns>/input directory. It is possible to select a particular input set using --comms-input command line option.

$> /path/to/commsdsl2c --comms-input ClientInputMessages

Providing Types and Functions Prefix

By default all types and functions are prefixed by the main namespace. However, it is possible to change it using -P command line option. Using different name prefixes allows having and using different compile time configurations of the same library.

$> /path/to/commsdsl2c -P some_name

Providing Generated Code Version

It is possible to set a semantic version of the generated code using -V option. The specified version string is expected to be the same as one used with commsdsl2comms.

$> /path/to/commsdsl2c -V 1.2.3

Selecting C++ Code Customization

The C++ protocol definition code generated by the commsdsl2comms can be customized by selecting non-default storage types and/or removing unneeded code to reduce final binary size. To apply such customization use --comms-options command line option with the name of the options residing in the options folder in the project generated by the commsdsl2comms.

$> /path/to/commsdsl2c --comms-options ClientDefaultOptions

If the intended options are not produced by the commsdsl2comms code generator itself, use the code injection functionality of the latter to provide the intended options.

Custom Code

As was already mentioned earlier, commsdsl2c utility allows injection of custom code snippets in the generated code. To better understand what code is injected where, it is recommended to read through the CInterface.md documentation page first.

Similar to the custom code injection defined for the commsdsl2comms the relevant code snippets are expected to reside in the same relative path as the generated code and to have specific extensions. Most useful are

  • .inc - Add extra include statements.
  • .append - Append code at the end of the file.