The NML Code Generator is a Java program that can be run in four ways.
- As an interactive stand-alone graphical program.
- As a component of the RCS-Design tool.
- As a non-interactive program suitable for use in a makefile.
- As an applet –– (See http://www.isd.mel.nist.gov/projects/rcslib/diagapplet/CodeGen.html. However this no longer works with the default configuration of most newer browsers, and is therefore not recommended.)
Its purpose is to take definitions of NML messages from C++ header files and create either the corresponding C++ update, format, and constructor functions or Java definitions of those messages.
Currently at least Java 2 Standard Edition 1.4 is generally needed. ( See http://java.sun.com )
Execution from within a Makefile or build script.
Running the command line non-interactive version of the program is recommended for most situations, since it can be run from within a Makefile or build script automatically whenever the header files change just before running the compiler.
There are two options here. One can either write a script in a small language unique the NML Code Generator for controlling the process or accept a default way of doing things and simply pass the generator a C++ header file.
The precompiled copy of CodeGenCmdLine.jar is available at ftp://ftp.isd.mel.nist.gov/pub/rcslib/CodeGenCmdLine.jar.
java -jar path_to_rcslib_bin
java -jar path_to_rcslib_bin
The option "script=yourscript.gen" tells the program to open up the file "myscript.gen" and look there for commands. The file yourscript.gen is a text-file with a series of commands to generate the C++/Java files. In both cases the option "-Isome_directory" can be used to tell the NML Code Generator to look in a given directory for header files that are included within your header file and that define types needed in your messages. To have the generated code be compatible with versions of the RCS library before 2003.9 add the option "update_with_name=false".
Some additional options:
- set to true to print extensive debug output
- set to false to use the older style CMS::update() functions rather than CMS::update_with_name() functions.
- set to true to create a seperate file just for printing message sizes
- if more than one header is given and no script is used set to true to include messages from all headers instead of just the last.
- when creating a file to print sizes, use a name other than print_nmlmsg_sizes.cc
- when no script is given, generate code for C
- when no script is given, generate code for C,C++, Ada & Java
- when no script is given, set to false to NOT generate code for C++
- when no script is given, generate code for Java
- when no script is given, generate code for Ada
- set a default length other than 0 for dynamic length arrays
- use some default builtin types
- set to true to print commands as they are executed from a script.
Here is the list of commands for the ".gen" script.
- # Comment
- Lines that begin with a # are considered comments.
- debug on/off
- Turn on or off the printing of debug messages, useful for finding incompatibilities in your C++ header files.
- load filename
- Read the C++ header file, filename, for NML message definitions.
- select_from_file filename
- Select the classes from the given file for use by later commands.
- cd directory
- Change to the given directory.
- set_format_function format_function_name
- Set the name of the format function to generate.
- package java_package_name
- Set the name of a Java package to put any Java classes into.
- generate java classes >*
- Create Java classes from each of the currently selected C++ classes and place them in separate files.
- generate java dict >filename
- Create an NML Message Dictionary in java using the currently selected classes and put it in the given file.
- generate C++ update >filename
- Create C++ update functions for each of the currently selected classes and append them to the given file.
- generate C++ format >filename
- Create a C++ format function using the currently selected classes and append it to the given file.
- generate C++ constructor >filename
- Create C++ constructors for each of the currently selected classes and append them to the given file.
- Deselect all the classes.
- Causes the code-generator to exit, ignoring any commands after this.
Here's an example script.
# CodeGen Script file to create emoven.cc from emoven.hh load emoven.hh generate C++ format >emoven.cc generate C++ update >emoven.cc generate C++ constructor >emoven.cc exit
Special Rules for the Header Files
The purpose of using C++ header files to provide the type information is to make adding variables to command and status messages or adding new commands and status messages as simple and painless as possible. However the tool is not a C++ compiler and so there are some issues to be aware of.
- Update 15-Jun-2004:#include directives are now followed.
- The types "long long", "unsigned long long", and "long double" are not portable and should therefore be avoided if possible.( See l64notes.html if your application deals with 64 bit integers.)
- #if directives are considered false unless JAVA_DIAG_APPLET_FORCE_TRUE is defined.
- Only one variable should be defined on a line.
- Surround things that should not be parsed by the tool with #ifndef JAVA_DIAG_APPLET and #endif. This includes:
- Multiple line functions and macros. (Most functions don't belong in the header file any way.)
- Variables included in the message but that should not updated in the NML update function.
- Large classes which will never be sent as NML messages and will just slow down the tool and eat up more memory to include.
- Each NML message should have a #define in the same header file giving the unique message type id formed by adding _TYPE to the class name. For example for class NML_TASKEX_INIT there should be a #define NML_TASKEX_INIT_TYPE 101
- Enter the URL or file name of the C++ header file or Diagnostics Configuration file into the text field at the top of the applet.
- Select NML messages for which update and/or format functions should be created from the "Available Classes" that were found.
- Press one or more of the "Add" usa-buttons to create the source code.
- Copy and paste the code into a text editor.
- Once You have generated any C++ code, the tool will not allow you to create Java code or vice-versa until you press the "CLEAR" usa-button.
- Some browsers does not allow java applets to read or write to local files. Microsoft Internet Explorer 3+ and Netscape 4+ have the same restriction unless you see my digital signiture when you load the applet and choose "Yes" Update 15-Jun-2004: I no longer sign the applet, running inside a browser just does not work anymore.
- For information on how to use this code, see The NML Programmer's Guide C++ and/or Java versions.
Last Modified: 15-Jun-2004
If you have questions or comments regarding this page or you would like to be notified of changes to the RCS library via email, please contact Will Shackleford at shackle [at] cme.nist.gov