Command Line DBC Code Generator

• The command line of the comFramework DBC code generator
  • Version
  • Command line interface of codeGenerator
  • Usage
    • Logging
    • The global network context
    • The CAN bus context
    • The user options context
    • The output file context
• The data model
• The manual of the StringTemplate V4 engine

The command line of the comFramework DBC code generator

Version

This overview has been generated for codeGenerator version 1.8.1.210.

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. This name is not meaningless; it 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 application'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.

  
  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.

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

• -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 http://www.stringtemplate.org/ or find a printable
version of the manual as
https://svn.code.sf.net/p/comframe/code/codeGenerator/trunk/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.