Skip to content

Manual_commsdsl2emscripten.md

Latest commit

 

History

History
127 lines (103 loc) · 5 KB

Manual_commsdsl2emscripten.md

File metadata and controls

127 lines (103 loc) · 5 KB

Manual of commsdsl2emscripten

Overview

The commsdsl2emscripten is a code generation tool provided by this project. It generates CMake project that can be used to build the protocol definition C++ code, generated by the commsdsl2comms, into the javascript / wasm using using the emscripten toolchain.

Command Line Arguments

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

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

Injecting Custom Code

The commsdsl2emscripten 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/commsdsl2emscripten -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/commsdsl2emscripten --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 commsdsl2emscripten 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 commsdsl2emscripten as well.

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

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/commsdsl2emscripten -V 1.2.3 schema.xml

Custom Code

As was already mentioned earlier, commsdsl2emscripten 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 WebAssemblySupport.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.
  • .public - Add extra public code to the class definition.
  • .private - Add extra private code to the class definition.
  • .append - Append code at the end of the file.

When new functions have been added (especially in the .public file) there might be a need to add the functions to the bindings list in the generated .cpp file. To do so use .bind extension.

For example:

  • cc_emscripten/demo/field/SomeField.cpp.bind