Guide to the XMC Compiler

System Requirements

In order to compile the xmc compiler, you will need a C compiler (gcc has been tested to work appropriately), but to be able to actually generate executables for your simulation, you will also need an Objective-C compiler (again, gcc will do), and a version of the Swarm package installed on your system. xmc supports three versions of Swarm, 1.0.2, 1.3 and 1.4.1. Finally, if you want to use the -m switch (see below), you will need a /tmp directory (that is, a directory named tmp located in the root of your filesystem) on your computer.

Download notes

If you want to download the compiler, or you want to learn more about installation details, please refer to the compiler download page.

Usage of the XMC compiler

The name of the compiler is xmc, and thus the invocation is done by executing the file named xmc. You must, however, specify the file containing the MAML source code. This file generally has .maml as an extension, but this is not obligatory. As a consequence, you must specify the full filename, as the compiler does not assume any extension by default.

Executing the compiler as described above (assuming that the specified source file exists and contains a correct MAML model) results in a set of Objective-C source files containing your model, that is ready to be compiled against the Swarm package. These files are put into the MAML_target directory under your current working directory.

If you don't find this place convenient enough, you can alter the location of the to-be-generated Objective-C files by specifying a directory name after the name of the source file. This directory name can be absolute or relative to the current working directory. (If the specified directory does not exists, the compiler creates it. Note, however, that it cannot create directories recursively.)

Before moving on to the subject of compiling your model (that is the generated Objective-C files of it) against the Swarm package, let's consider the different versions of that package itself. xmc supports three versions of Swarm. These are version 1.0.2, and version 1.3 and 1.4.1. As the later two versions differ in the structure of their source (Objective-C) files from that of the version 1.0.2, you need the Objective-C version of your model to be generated for the version installed on your system. To select between the two possible structures use the -a and -b switches. The first forces the compiler to produce code for Swarm 1.0.2, while the latter, which is the default, results in code compatible with Swarm 1.3 and Swarm 1.4.1.

The last step that you will take to get the running version of your model, will be to compile the generated Swarm (Objective-C) files against the appropriate version of the Swarm package. This can be done by entering the directory containing the generated files (the one you specified after the MAML source file name, or MAML_target by default), and issuing the make it command there. Provided that your model is correct, this results in an executable called run, which is stored in the current working directory (that is, in the directory where the generated Objective-C files are).

(Instead of the make it command, you can simply use make, but this will leave the object files generated during compilation behind.)

Now after these steps, if you are both lucky and a good programmer, your simulation will be running. If it is not, a bunch of errors will be reported. Compilation errors can occur at two distinct times, in both phases of the MAML to executable compilation. The most obvious errors are discovered by the xmc compiler itself, and reported after the first of the above steps. Some errors, however, can only be discovered when compiling the generated Objective-C files against the Swarm package, namely after issuing the make it (make) command. Furthermore, these latter errors are discovered in the context of the Objective-C files and not in the context of the MAML source itself. Unfortunately, in this case, investigating both the reported error messages and the referenced Objective-C source files does not always reveal which part of the original MAML source was incorrect. xmc, however, is able to localize (most of) these errors. If you use the -m switch of the compiler, in addition to localizing the possible second phase errors in your MAML source, you also avoid performing the two phase compilation process by hand, as xmc automatically invokes the second phase (make it) for you. That is, using the -m switch, you can have your executable (called run) placed in the MAML_target directory (or in the one you specified) in one step.

The other compiler switches are -p, -s, and -c. These switches control the activity performed by the compiler.

The -p makes the compiler preprocess the code (that is, import specified files and substitute the macro definitions) and copy the results to the standard output. (The usage of this switch neglects the effect of all the other switches and parameters, except the source file name.)

The switch, -s, lets the compiler check for first phase errors (see above) without code generation. (The usage of this switch also disables the effect of all the other compiler switches or parameters, except the source file name.)

Switch -c is the default action of the compiler: it compiles the specified MAML source and attempts to generate Objective-C (Swarm) files in the default or specified target directory.

There are certain restrictions on the usage of switches and parameters. The switches should all appear before the name of the file containing the MAML source code. After this file name, only the name of the target directory can stand if present. The order of the switches is irrelevant, but they should be specified separately:

is a correct invocation of the xmc compiler.

Finally, the xmc compiler prints a summary of the issues discussed above, if it was executed without any parameters at all. In the case of usage errors (unambiguous parameters, missing files, etc.), the compiler reports informative error messages. A short summary of xmc usage is presented below.
 

Known bugs