NML Code Generator

Introduction

The NML Code Generator is a Java program that can be run in four ways.

  1. As an interactive stand-alone graphical program.
  2. As a component of the RCS-Design tool.
  3. As a non-interactive program suitable for use in a makefile.
  4. 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/CodeGenCmdLine.jar mymsgs.hh

OR

java -jar path_to_rcslib_bin/CodeGenCmdLine.jar script=myscript.gen

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:

debug_on=
set to true to print extensive debug output
update_with_name=
set to false to use the older style CMS::update() functions rather than CMS::update_with_name() functions.
create_print_sizes_file=
set to true to create a seperate file just for printing message sizes
select_from_all_files=
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.
sizes_filename=
when creating a file to print sizes, use a name other than print_nmlmsg_sizes.cc
generate_for_c=
when no script is given, generate code for C
generate_for_all_langs=
when no script is given, generate code for C,C++, Ada & Java
generate_for_cpp=
when no script is given, set to false to NOT generate code for C++
generate_for_java=
when no script is given, generate code for Java
generate_for_ada=
when no script is given, generate code for Ada
dla_length_init=
set a default length other than 0 for dynamic length arrays
UseDefaultTypes=
use some default builtin types
print_script=
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.
clear
Deselect all the classes.
exit
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.

  1. Update 15-Jun-2004:#include directives are now followed.
  2. 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.)
  3. #if directives are considered false unless JAVA_DIAG_APPLET_FORCE_TRUE is defined.
  4. Only one variable should be defined on a line.
  5. Surround things that should not be parsed by the tool with #ifndef JAVA_DIAG_APPLET and #endif. This includes:
  6. 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
    

Interactive Operation

  1. 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.
  2. Select NML messages for which update and/or format functions should be created from the "Available Classes" that were found.
  3. Press one or more of the "Add" buttons to create the source code.
  4. Copy and paste the code into a text editor.

Notes:


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@cme.nist.gov