Skip to content

Latest commit

 

History

History
122 lines (99 loc) · 4.86 KB

Manual_commsdsl2swig.md

File metadata and controls

122 lines (99 loc) · 4.86 KB

Manual of commsdsl2swig

Overview

The commsdsl2swig is a code generation tool provided by this project. It generates CMake project that can be used to build bindings allowing usage of the protocol definition C++ code, generated by the commsdsl2comms, to be used in other higher level programming languages, such as Python, Java, C#, etc...

Command Line Arguments

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

$> /path/to/commsdsl2swig -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/commsdsl2swig <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/commsdsl2swig -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/commsdsl2swig -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/commsdsl2swig -o /some/output/dir schema.xml

Injecting Custom Code

The commsdsl2swig 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/commsdsl2swig -c /path/to/custom/code/snippets schema.xml

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 commsdsl2swig 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 commsdsl2swig as well.

$> /path/to/commsdsl2swig -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/commsdsl2swig --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/commsdsl2swig --messages-list /path/to/messages/list/file ...

Custom Code

As was already mentioned earlier, commsdsl2swig 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 OtherLanguagesSupport.md documentation page first.

The generated CMakeLists.txt does NOT contain any code applicable to set up the required languages that need to be processed. The custom injected code is expected to have the following files defined:

  • CMakeListst.txt.prepend - Contain the lines required to find the necessary packages.
  • CMakeLists.txt.prepend_lang - Contain the lines that sat appropriate swig flags based on the used languages.
  • CMakeLists.txt.append - Contain the lines linking appropriate libraries to the generated compilation target.

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

  • .public - Add extra public code to the class definition.
  • .private - Add extra private code to the class definition.

For example:

  • include/demo/field/SomeField.h.public
  • include/demo/field/SomeField.h.private

The swig interface definition file itself (<prot_name>.i) allows injection extra code at the beginning and at the end of files using .prepend and .append files accordingly. Prepending can be useful to add some extra language specific definitions if needed.

For example:

  • demo.i.prepend
  • demo.i.append