MAML -- Multi-Agent Modeling Language
000

[ Initiative ][ Introduction ][ Overview ][ Supported Swarm versions ][ Compiler Download Page ][ Compiler Usage Guide ][ Tutorial ][ Course Outline ][ Examples ][ Reference Manual ][ Papers ][ Comments for Swarmites ][ Technical Manual ] ][ About ]

Guide to the XMC Compiler



System Requirements

The MAML compiler was written in ANSI C using the gcc 2.7.2.1 under Linux. It was tested in this environment, but may run on other platforms, too. It is likely, however, that the Makefile that builds the compiler and the Makefile generated by it for the models will only work under UN*X systems. You also should have Swarm installed on your system to enable youto use our software (for the supported versions see this page).
The MAML compiler also works with the NT version of Swarm under the Cygnus UNIX emulation.

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.

xmc MyModel.maml

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

xmc MyModel.maml PutItHere

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.

 

xmc MyModel.maml PutItHere 
Results in code for Swarm 1.3 and 1.4.1 
xmc -b MyModel.maml PutItHere 
Same as above 
xmc -a MyModel.maml PutItHere 
Produces code for Swarm 1.0.2 
 

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

cd PutItHere or cd MAML_target
make it

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

xmc -m MyModel.maml
xmc -m MyModel.maml PutItHere
xmc -m -a MyModel.maml PutItHere

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:

-ma is equivalent with -m and not with -m -a together.

The reason for separate specification is that only the first character of each switch definition is taken into account:

xmc -massive -alcoholist MyModel.maml

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.
 

Usage: xmc [-pscm] [-ab] filename [target directory]

-p: preprocess and copy source to stdout (target is ignored)

-s: check for syntax error without code generation

-c: compile and generate code in target (default action)

-m: generate code and make executable in target directory

 

-a: use 'Swarm v1.02' code generation algorithm

-b: use 'Swarm v1.3' code generation algorithm (default) 




Known bugs

There are no known compiler bugs yet.


copyright © 1999 agent-lab
Send comments to maml@maml.hu