: juggernet cli reference

JuggerNET CLI Reference

The code generator GUI is a wonderful tool for interactively defining your solution to a particular Java/.NET 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 .NET. The Java types are not expected to change, or at least change so infrequently that you can generate the .NET 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 JuggerNET's bin directory.

 

Basic CLI Invocation

To trigger command line mode, you simply pass the code generator a model file, together with the -dotnet code generation command. This will trigger proxy types being generated without bringing up the GUI. JuggerNET will load the model file, execute all the commands contained within, apply the .NET 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 -dotnet 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] -dotnet model_file|expression

The table below contains all CLI options with a brief description for each.

Option
Description
-cmd command
Execute an arbitrary command on the model file or expression used as input.

Use 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=value
Define a variable that can be used in a model file or in a command evaluation.

This 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.

-download
Query for download credentials and attempt to download the JuggerNET runtime library for your platform.

This option allows the headless installation of the C++ runtime library for your platform.

-dumpversion
Displays just the JuggerNET version number and exits.
-p filename
Interprets the given file as a properties file, expected to contain name/value pairs in "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
Displays JuggerNET version information and exits.

 

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.

 

Environment Variable
Description
JAVA_HOME
May or may not be set on your build host.

Override 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_HOME
Defaults to the parent directory of the directory in which the xmog 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_OPTS
Defaults to empty.

This 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=-Xmx1024m
and 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:

  1. $HOME/.xmog/xmog.conf
  2. $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.