genom3 - software component source code generator
genom3 [-l] [-h] [--version]
genom3 [-I dir] [-D macro=value] [-E | -n] file.gen […]
genom3 [general options] template [template options] file.gen […]
genom3 generates the source code of the software components described in the formal description file.gen input file.
The input file.gen is expected to contain the description of the services, input and output ports, data types definitions and execution contexts of a software component, written in the dotgen language.
The dotgen specification is first processed by a C preprocessor before it is parsed by genom3 and transformed into an abstract syntax tree. libexec/genom-pcpp is the default program, but this can be changed with the CPP environment variable. genom3 accepts -I and -D options that are passed inchanged to the cpp program.
The abstract syntax tree is exported in a format suitable to a generator engine that is in charge of a template execution for actual source code generation. The generator engine provides a scripting language and a set of procedures for use by templates. The directory where source code for the generator engine is searched can be changed with the -s option.
Templates are a set of source files that serve as the basis for source code generation. They are interpreted by the generator engine, and contain either code written with a scripting language, or regular source code that is appended directly to the generated code. Intermediate files and scripts are saved in a temporary directory before they are copied to the final destination directory. The -T option changes the path of the temporary directory. The -d option will keep all temporary files instead of deleting them once the program terminates. This is useful only for template development and debugging.
The choice of a template depends on the kind of source code that is wanted by the user. Refer to the documentation of the templates for a description on what they do. The names of the available templates can be listed with the -l option. The directory in which templates are looked for can be changed with the -t option.
The genom3 program accepts general options that affect the general program behaviour. genom3 can also pass template options to the template. These options will only affect the template behaviour and are documented separately, in each template documentation.
Add the directory dir to the list of directories to be searched
for included files. The dir argument is passed as-is to the cpp
program via the same -I option.
Predefine macro to value if given, or 1 if value is omitted, in the same way as a #define directive would do it. This option is passed as-is to the cpp program.
If you are invoking genom from the shell, you may have to use the shell quoting character to protect shell’s special characters such as spaces.
An implicit macro __GENOM__ is always defined and contains the version of the genom program. This can be used to divert some lines in source files meant to be included by other tools that genom, and that contain syntax that genom does not understand.
Stop after the preprocessing stage, and do not run genom proper. The output of cpp is sent to the standard output. genom exits with a non-zero status if there are any preprocessing errors, such as a non-existent included file.
Stop after the input file parsing stage, and do not invoke any template. This is useful to check the syntax of the input file. Any errors or warning are reported and genom exits with a non-zero status if there are errors.
Stop after the input file parsing stage, do not invoke any template and dump the parsed specification in dotgen format. This is mostly useful for debugging genom itself or to view the actual specification built by genom from a complex (set of) file(s). Any errors or warning are reported and genom exits with a non-zero status if there are errors.
Change to directory dir before reading the input files. If multiple -C options are specified, each is interpreted relative to the previous one.
Print to the standard output the list of available templates, one per line.
By default, the standard templates directory is searched, but any -t option will be taken into account.
Use path as the directory containing templates. This can be a colon separated list of directories which are searched in order.
This option is useful only for templates not installed in the genom standard directories, i.e. share/genom/templates or share/genom/site-templates.
Each component of path is searched for files matching */template.tcl, where * is interpreted as the template name.
Use dir as the directory holding genom engine files. This option is useful if non-standard engines are to be used. The default value is share/genom/engines.
dir should contain directories named after the engine name.
Use dir as the temporary directory holding intermediate files. See also the environment variable TMPDIR.
Force genom to be more verbose while processing input files.
Activate some debugging options. In particular, temporary files are not deleted. Useful for debugging genom itself or generator engines.
Display the version number of the invoked GenoM.
Print usage summary and exit.
Templates might define their own specific options. The -h option is always defined, and prints a summary of supported options. See the template manual for a detailed description. Template options should be passed after the template name, and before the input file name.
Define the C preprocessor program to use. The default is libexec/genom-pcpp. The GENOM_CPP program must recognize -I and -D arguments.
Define the path to the pkg-config(1) program. pkg-config(1) may be spawned by genom-pcpp for handling the #pragma require directive. The default is to search in the PATH variable.
The value of GENOM_TMPL_PATH is a colon-separated list of directories, much like PATH, where genom3 looks for templates. Paths set by any -t option takes precedence over this variable.
Path to the directory holding temporary files. Defaults to /tmp.
<prefix>/libexec/genom-pcpp Default C preprocessor.
<prefix>/share/doc/genom HTML and asciidoc documentations.
<prefix>share/genom/site-templates Default directory for additional templates.
<prefix>/share/genom/templates Builtin template directory.
Genom development was initiated by Sara Fleury and Matthieu Herrb in 1994. The first opensource version, labelled version 2.x, was released in 2004. The reflexion and development of version 3 was started by Anthony Mallet in 2009, with the great help of Cédric Pasteur who quickly developed the first prototype in the context of his master training period.
Sara Fleury, Matthieu Herrb, Anthony Mallet, Cédric Pasteur and and people working on the LAAS openrobots projet <openrobots@laas.fr>.
Bug and problem reports are always apreciated. Please send an e-mail with detailed information about the problem and the context in which it appeared to <openrobots@laas.fr>.