Skip to content

The Command Line of the comFramework DBC Code Generator

Jump to bottom
vranken edited this page Nov 29, 2024 · 2 revisions

Version

This overview has been generated for codeGenerator version 1.13.0.

Command line interface of codeGenerator

The code generator's command line arguments mainly relate to logging and in- and output files. How the output files look like is mainly a matter of the contents of the specified input files, both network databases and StringTemplate V4 template group files.

The command line interface of the code generator has the following concept: The arguments are organized in groups of successive arguments. Such a group specifies one item of the application configuration. A group of arguments can specify an input file, another group can specify another input file or an output file and so on. The beginning of a group of arguments is recognized by a specific argument, the principal argument of the group. The usage text typically says "this argument opens the context of ...". The order of arguments inside a group, i.e. between two principal arguments, doesn't normally matter.

Additionally to the use of command line arguments in the context of a group, one can put the same prior to opening the first group context: Now they have the character of a default value for all later groups, which do not themselves specify these particular arguments.

Finally, there are "traditional" command line arguments, which relate to the run of the application as a whole, like logging and verbosity settings. The location of these arguments doesn't matter and they must not be used repeatedly. (Whereas most others can re-appear in different instances of the same context.)

Please note, different to the common GNU command line interface this application demands a blank between the argument and its value. For example -oMyOutputFile.c would be rejected, whereas -o MyOutputFile.c would be the correct specification of a generated output file. There are more differences, short arguments can't be concatenated like -abc and the values of long arguments can't be assigned with =.

Unlike other command line arguments do Boolean arguments not accept a value. They are true if put onto the command line and false otherwise. This means implicitly that the Boolean arguments are generally optional and that their default value is generally false.

Usage

The usage of the tool is explained in the built-in help text. Get an up-to-date overview for your revision of the code generator with command line option --help.

Logging

The Apache log4j logging engine is integrated into the application. A reasonable configuration of the logger is available by default. Some elements of the configuration, file name and log level in the first place, can be adjusted through the command line. The order and position of these arguments on the command line don't matter.

  • -h, --help: Print the built-in help to the console and terminate.
  • -v, --verbosity: Verbosity of all logging. Specify one out of OFF, FATAL, ERROR, WARN, or INFO as value. Optional, default is INFO if the argument is not given.
  • -l, --log-file: If given, a log file is written containing general program flow messages.
  • -p, --log4j-pattern: A pattern for the log file entries may be specified, e.g. "%d %p: [%t]: %m%n". See Java on-line help of class Log4j.PatternLayout for details. The default will be most often sufficient.

The logging facilities of the back-end, the StringTemplate V4 template engine can be accessed and configured to a very limitted extend only:

  • -vt, --string-template-verbose: The template engine integrated for output generation has a debug mode to report details of searching addressed files and templates. Use this Boolean argument to enable the verbose mode of StringTemplate. See http://www.stringtemplate.org/ for more. Must be given in the global context only. Optional, default is false

The global network context

The data model of the code generator knows a single communication network. Consequently, the network related settings don't require an own, repeatable command line context, they are expected in the global context. Note, the network arguments need to be found first on the command line; the global context is left forever once another context is opened.

  • -c, --cluster-name: The name of the complete network cluster. The specified name is meaningless but it is put into the data model as field Cluster.name and can be referenced from a template. It'll likely be used to tag symbol names and more in order to shape a namespace for the objects of this network. If the application's standard templates are used then the cluster name needs to be a valid identifier of the programming language C.

    Optional, may be given once in the global context. Default is "cluster".

  • -me, --node-name: The name of the network node code is generated for. The name needs to match an element from the node name list in the network databases. The match is required to figure out whether a frame or signal is sent or received or not processed by the generated code.

    The name needs to be passed in in the global context; this is the variant of the name that is put into the data model as field Cluster.nodeName and that is used in the generated code.

    The name can also be passed in in the local context of a bus definition. There it is optional and used only in case the network database of that bus uses a deviating name for the same node. These variants of the name won't show up in the data model.

The CAN bus context

The CAN bus context specifies bus related options, the name of the network database file in the first place. A network database can be filtered; a sub-set of frames to be read can be defined and all other frames would be ignored.

  • -b, --bus-name: The name of a single bus in the cluster. The specified name is meaningless but it is put into the data model and can be referenced from a template. It'll likely be used to tag symbol names and more in order to shape a namespace for the objects of this bus. If the code generator's standard templates are used then the bus name needs to be a valid identifier of the programming language C.

    This argument opens the local context of a new bus specification. It can be used repeatedly to define several buses. This parameter is mandatory, at least one bus must be defined in the cluster.

  • -dbc, --network-file-name: The name of the network database file, which specifies the currently defined bus. Must be given in the context of a bus definition only. This parameter is mandatory for each bus specification

  • -inv, --invert-transmission-direction: The data model entries related to the transmission direction are all inverted if this Boolean argument is set. Use case is code generation for residual bus simulation. The name of the device under test is specified with the other command line argument node-name. Frames, which are received by that node will be put in the data model with field Frame.isSent set to true and frames, which are sent by that node will have the flag Frame.isReceived set to true. Accordingly for PDU and signal objects. Code generated from the data model will expose appropriate transmission behavior for the test device, which is intended to talk to that node.

    This argument must be given in the bus context only. Optional, default is false.

  • -id, --include-frame-id: A frame ID or a range (a colon separated pair) of those. The frames with the given ID or with an ID in the given range (both boundaries are including) are added to the set of included frames. All frames with an ID not belonging to this set will be ignored during processing of the network database file.

    If no include condition is given (neither by this argument nor by re-include-frame-name) then all frames in the input file form the set of included frames.

    This argument can be used any number of times in the context of a bus specification. It must not be used in the global context; there's no common default for all buses or network database files.

  • -fr, --re-include-frame-name: Add frames by name to the set of included frames. All frames whose names match with this regular expression are elements of the set. See argument include-frame-id for more details.

    Optional. This argument can be used once in the context of a bus specification. It can be set once in the global context, too, then it becomes the default value for all bus specifications that do not set the value themselves.

  • -ex, --exclude-frame-id: A frame ID or a range (a colon separated pair) of those. The frames with the given ID or with an ID in the given range (both boundaries are including) are added to the set of excluded frames.

    Note, this option doesn't discriminate between 11 Bit standard and 29 Bit extended IDs. It'll not be possible to selectively exclude either standard or extended IDs in the number range 0..2047.

    All frames from the set of included frames, which do not belong to the set of excluded frames, form the set of supported frames. Only the supported frames will be considered during processing of the network database file.

    This argument can be used any number of times in the context of a bus specification. It must not be used in the global context; there's no common default for all buses or network database files.

  • -exfr, --re-exclude-frame-name: Add frames by name to the set of excluded frames. All frames whose names match with this regular expression are elements of the set. See argument exclude-frame-id for more details.

    Optional. This argument can be used once in the context of a bus specification. It can be set once in the global context, too, then it becomes the default value for all bus specifications that do not set the value themselves.

  • -s, --special-signal-name: The name of a special signal. The intended use case are signals, which have a meaning to the implementation of the generated CAN interface, e.g. checksum signals or sequence counters. If identified these signals become directly accessible in the data model (and are not just a signal somewhere in a list of all signals). If a frame is found to have a signal with matching name then a description of this signal is added to the data model under the name specified with argument special-signal-name.

    Code examples how to access a matching signal in the data model can be found in the Javadoc of field Pdu.specialSignalMap.

    It is considered an error if several signals of a single frame would match -- then the regular expression re-special-signal should be refined.

    This argument is used in the context of a bus definition and it opens the sub-context of a special signal request. It can be used repeatedly to select several different signals of interest.

    The argument can be used in the global context, too, then it becomes the default value for all bus specifications that do not set the value themselves (together with the related re-special-signal).

    Optional, no special signal is requested if not used at all.

  • -re, --re-special-signal: The special signal is the very one of a frame, which matches against this regular expression; the entire name must match. In simple cases the regular expression can be identical with the name special-signal-name of the special signal but if the signal has differing names in different frames than this regular expression can be applied to filter all of them.

    This argument must be used only in the context of a special signal request. It can be used once for each special signal request; if used it needs to immediately follow the name of the special signal.

    Optional, by default the regular expression is identical to the special-signal-name.

The user options context

  • -op, --user-option-name: The name of a user option, which is put into the data model and this way passed into the StringTemplate V4 template as additional attribute. The value of this attribute can be used in the template to conditionally control the code generation.

    The value of the option (or template attribute) is specified with the other command line argument user-option-value.

    This argument opens the local context of an option specification. It can be a sub-context of the global context or of the bus or output generation block. It can be used any number of times in each of these contexts. All options specified in the global context will become default values for all buses and output generation blocks but they may be redefined or overridden in those contexts.

  • -ov, --user-option-value: Specify the value of a user option or attribute (see user-option-name).

    This is the only other (and optional) command line argument in the sub-context of a user option. Consequently, if given it needs to immediately follow user-option-name.

    The value is passed into the StringTemplate V4 template as an object of best suiting Java type; numbers are passed in as either Integer or Double and the literals true/false as Boolean. If none of these fits then the template receives a String with the literal text from the command line.

    This argument is optional. If omitted then the template will receive the value Boolean(true). This means that Boolean code generation control switches can be passed in by simply putting -op <nameOfSwitch> on the command line.

The output file context

  • -o, --output-file-name: The name of a generated output file. This argument opens the context of an output generation block. This block of arguments describes how a single output file is generated from the network database files under control of a template file. Any number of output files can be generated if the output generation block is repeatedly given.

    Note, directories missing in the path to the designated file will be created by the application.

    The generated output can be written into a standard console stream, too. Two file names are reserved to do so:

    - stdout
- stderr

    If the output of the information rendering process is redirected to the console then you should raise the logging level to WARN at minimum; if rendering is successful then the rendered data model won't be intermingled with application progress information.

  • -t, --template-file-name: The name of the StringTemplate V4 template file, which is applied to render the contents of the network database files. Only group template files are supported. Please, refer to http://www.stringtemplate.org/ for a manual how to write a valid template.

    Note, the template engine locates template files through the Java class path. This is the class path defined when starting the code generator application. The launch scripts in the diverse samples demonstrate how to set the class path appropriately. Consider using argument string-template-verbose if locating files causes trouble.

    The argument must be used once and only once in the context of an output generation block.

  • -tn, --template-name: A StringTemplate V4 template file typically contains a set of (nested) templates. This argument names the root template, which is used by the application to render the contents of the network database files.

    The argument can be used once in the context of an output generation block.

    The argument can be used once in the global context, too, then the global value becomes the default for all output generation blocks that do not specify the value themselves. Optional, the default is "renderCluster" if this argument is not used at all.

  • -tc, --template-arg-name-cluster: The contents of the network database files are passed to the selected template as a template argument. This command line argument names the template argument.

    The command line argument can be used once in the context of an output generation block.

    The argument can be used once in the global context, too, then the global value becomes the default for all output generation blocks that do not specify the value themselves. Optional, the default is "cluster" if this argument is not used at all.

  • -ti, --template-arg-name-info: Some general information (date and time, file names, etc.) is passed to the selected template as a template argument. This command line argument names the template argument.

    The command line argument can be used once in the context of an output generation block.

    The argument can be used once in the global context, too, then the global value becomes the default for all output generation blocks that do not specify the value themselves. Optional, the default is "info" if this argument is not used at all.

  • -w, --template-wrap-column: This integer argument is passed to the render function of StringTemplate V4. The templates can be written such that the generated lines of output are wrapped after this column; please, refer to http://www.stringtemplate.org/ for details.

    The argument can be used once in the context of an output generation block.

    The argument can be used once in the global context, too, then the global value becomes the default for all output generation blocks that do not specify the value themselves. Optional, the default is not to wrap lines if this argument is not used at all.

The data model

Each run of the code generator requires the knowledge of the "data model", the internal representation of the information parsed from the network database files. The data model is documented as a Javadoc of the complete data structure.

Here, you find the documentation of all public elements of the data structure that are accessible from the StringTemplate V4 templates. The data structure is deeply nested, and actually, it are even two data structures, which are passed to the rendering process:

  • The parsed information forms an object of class Cluster
  • The information about output files plus some environmental information is put into an object of class Info

You will study the Javadoc pages to see, which pieces of information to be used from within a template.

Another source for this knowledge is the investigation of the sample templates: codeGenerator/samples/.../*.stg.

The manual of the StringTemplate V4 engine

All output is generated under control of StringTemplate V4 templates. The two objects of class Cluster and Info from the data model are passed to the StringTemplate V4 template engine and how to write templates for this engine is fully documented.

Please refer to https://github.com/antlr/stringtemplate4/blob/master/doc/index.md or find a printable version of the manual as https://github.com/PeterVranken/comFramework/tree/main/codeGenerator/doc/ST4-270115-0836-52.pdf.

Please note, as a matter of experience, you will have to read the StringTemplate V4 manual entirely before you can start to successfully develop your first useful template. StringTemplate V4 is powerful and convenient but not self-explaining.

Clone this wiki locally