JunC++ion CLI Reference
The code generator GUI is a wonderful tool for interactively defining your solution to a particular Java/C++ integration problem. Yet once you have completed this initial work, you invariably have to integrate your solution into your product's build infrastructure.
Sometimes you are dealing with a static set of Java types that you need to use from C++. The Java types are not expected to change, or at least change so infrequently that you can generate the C++ proxy types interactively and check the generated proxy types into source control. Essentially, you can get away with removing the code generation step from your build and using your manually generated proxy types like primary sources.
In the general case though, the Java types you wish to integrate with are under active development. This means that you really should regenerate the proxy types each time the Java types change. Needless to say that a GUI-based, interactive code generator has no place in an overnightly or CI build. This is when you need to employ one of the automatable, non-interactive code generator variants. The command line interface (CLI) is one of these variants; the ANT interface is the other.
The code generator command line interface is accessed via the same batch/script file that you use for
launching the code generator GUI: xmog. You can find it in JunC++ion's
bin directory.
Basic CLI Invocation
To trigger command line mode, you simply pass the code generator a model file, together with the -cpp code generation command.
This will trigger proxy types being generated without bringing up the GUI. JunC++ion will load the model file, execute
all the commands contained within, apply the C++ transformation, and exit. See the simple
example of an invocation below. It assumes that the xmog code generator script/batch file is on the path.
If not, you simply have to invoke it using the full path name.
xmog -cpp my_project/my_model.cmm
This is often all you need, unless you have invested the effort to introduce build variables into your model files in order to make them host- and user-portable. The following sections provide a reference for those users whose needs are not met by the simple generator invocation.
The CLI Options
The general syntax for invoking the CLI is shown below:
xmog [options] -cpp model_file|expression
The table below contains all CLI options with a brief description for each.
-cmd commandUse the variable name "tos" to refer to the input expression or the model represented by
the model file. For example, to have the code generator print the current time, use
xmog -cmd tos now
To have the code generator print the value of a model's "name" property, use
xmog -cmd tos.name mymodel.jmm
The -cmd option is mutually exclusive with the code generation command.
-Dname=valueThis option is very useful for providing overrides for variables like a product version number, i.e. variables whose value usually changes from build to build.
-downloadThis option allows the headless installation of the C++ runtime library for your platform.
-dumpversion-p filename"name=value" format, one per line.
Properties files are a great way of providing host- or user-specific settings to the code generator. If your model file uses variables to represent settings like the target directory, the JDK directory, etc., a set of properties files can allow the convenient use of the same model file in different code generation environments.
-version
The CLI Runtime Environment
The code generator, whether GUI or CLI, is a pure Java application. The xmog
script/batch file internally just launches a properly configured Java application: Swing-based
for GUI mode, headless for CLI mode.
This design implies that the launcher be able find a Java Runtime Environment and that it be properly configured for your use case. Normally, neither requirement is something you need to worry about.
Occasionally though, the code generator is being run on a host where Java is available but not properly installed, or it is installed in an unexpected location, or the default version of Java is not the one you wish to use. Also, occasionally, users generate large sets of proxy types, necessitating the specification of a larger heap size for the Java runtime.
For the reasons described above, you should at least be aware of several environment variables that can be used to customize the code generator's behavior. The table below lists the most useful environment variables.
JAVA_HOMEOverride this variable to specify the particular Java version you wish the code generator to use. Please note that the code generator GUI might require a particular Java version whereas the CLI version should work with just about any Java version.
Note: On MacOS you will most likely find a JVM at
/Library/Java/JavaVirtualMachines/<name>/Contents/Home.
XMOG_HOMExmog script/batch file resides.
Override to load the code generator resources (jars, etc.) from a different installation.
You should never have to do override this variable.
XMOG_OPTSThis variable allows you to add Java Runtime Environment options to the code generator. You most commonly use this option to increase the code generator's heap size when you generate large sets of proxy types.
As an example, to specify a larger heap size on Windows, you would execute this command in your command shell before invoking the code generator:
set XMOG_OPTS=-Xmx1024mand this command in your bash shell:
export XMOG_OPTS=-Xmx1024m
Environment variables can optionally be specified in special configuration files in a user's home directory. In that case, they will apply to any code generator invocation.
On Unix/Linux systems, the configuration files are:
$HOME/.xmog/xmog.conf$HOME/.xmogrc
On Windows, there is only one configuration file:
%HOME%\xmogrc_pre.bat
Logging
The code generator is configured to run with a logging configuration read from the bin/log.properties
file. Simply set the log level to INFO or even FINEST to get much more feedback obout
what's happening inside during code generation.