This file is part of melmac. See file COPYING for copyright information. Author: Gergo Barany What is melmac? =============== melmac is a tool for manipulating programs in the ALF representation. Its main use is to generate ALF programs from C programs. Thus, it provides a C frontend to programs that process ALF input. melmac can also perform a few tasks related to ALF macros. It can do macro substitution, so it can be used as an external preprocessor by tools that take ALF input, but which cannot process macros by themselves. melmac lives at http://www.complang.tuwien.ac.at/gergo/melmac/ Building melmac =============== See the file INSTALLATION for information on building melmac. Using melmac ============ melmac is started from the command line. It takes exactly one command telling it what to do, and possibly a number of options telling it how to do it. The main commands all convert an input file into an output file. These commands take two mandatory file name parameters, input first. When converting ALF to ALF, it should usually be OK to specify the same name for both; the output will then overwrite the input file. melmac's --help command gives you detailed information about all the supported command line flags. The melmac config file ---------------------- Several parameters related to ALF code generation (mostly sizes of data types) are controlled by a configuration file. When melmac is invoked, it will look for this file in a number of default places. You can tell it which file to use by using the --config command line flag. The file src/melmac_config.pl in the melmac distribution is a thoroughly documented example config file. You can use it as the basis of rolling your own. Generating ALF from C --------------------- melmac generates ALF programs from an intermediate representation called Termite. melmac does not itself generate Termite from C, as there are other programs for that. SATIrE ( http://www.complang.tuwien.ac.at/satire/ ) includes a program called "c2term" which does this. The melmac distribution contains a few small C files, and the corresponding Termite files, in the example_terms directory. You can play around with these to get started. To generate an ALF program from a Termite term, use the --term-to-alf command, which takes two file names as described above. You can abbreviate this command as -t. When using the --term-to-alf (-t) command, the output file name may actually be treated as a prefix; if the input Termite term was created from more than one C file (representing a whole project), then for each C file name: - all directories are stripped; - any '.c' extension is stripped; - the resulting base name is prefixed with the given prefix and suffixed with a '.alf' extension. For example, if term foobar.term was built from source files foodir/foo.c and bardir/bar.c, and the second argument to -t is 'outdir/out_', then melmac will make sure the directory outdir exists, and will put two files out_foo.alf and out_bar.alf into that directory. It is (currently) the user's responsibility to ensure that base names are unique. In the future, melmac will also take a --c-to-alf (-c) command, which will hide the intermediate step of converting C to a Termite term. However, this will still require c2term or some similar external program, so it won't buy you much compared to --term-to-alf. ALF macro processing -------------------- melmac includes a macro processor for ALF. There are three commands related to macro processing: --macro-replace (-m) replaces all macro calls in the input program by their expansions. You can use this to "preprocess" ALF files before handing them to programs that cannot perform macro replacement by themselves. --macro-strip (-s) replaces macros like --macro-replace, but it also removes the macro definitions themselves from the ALF code. This might be appropriate as a preprocessing step for tools that absolutely refuse to even look at macro definitions, even if the macros are never called. --macro-abstract is backwards macro replacement: Given the macro definitions in the input file, melmac tries to find all code patterns that could be expansions of one of the macros, and replaces all these patterns by appropriate macro calls. This can be used to obtain nicer looking ALF by introducing some abbreviation as a macro. It is probably mostly a toy. Other command line flags ------------------------ The --help commands prints a usage message, then exits; the --version command gives information about the version of melmac you are using. The --quiet (-q) option can be used with any command to suppress informational output. The opposite of --quiet is --verbose (-v). The --config option can be used to specify a config file to be used for ALF generation. The --unique_variables (-u) option, when used with --term-to-alf, causes melmac to rename all variables in the program to unique names. A variable named 'n' will typically be renamed to something like 'n::N' where the integer N uniquely identifies the variable. This option can only be used with Termite terms where all variable references and declarations are annotated with SATIrE's variable IDs (this is typically the case for terms generated using SATIrE). The --aral (-a) option, when used with --term-to-alf, causes melmac to output analysis information in the ARAL format. The name of the ARAL file is a mandatory parameter to this flag. The analysis data must be present in the term file. This option implies --unique_variables and its requirements. The --labels (-l) option, when used with --term-to-alf, causes melmac to output a semicolon-separated table of mappings from labels in the ALF code to source code locations. The name of the file to be written is a mandatory parameter to this flag. The table contains one record per line, where the structure of each record is "alf_label;filename;line;column". It is in the user's interest to ensure that file names do not contain semicolons. Currently, only expression statements (including some, but not all, expressions in loop heads) and return statements are labeled in this way. Testing melmac -------------- Type "make check" in the melmac distribution to run a few automated tests using the runtests script. This takes whatever term files there are in the example_terms directory and generates ALF code from them. Then, it checks that the generated files are valid ALF by trying to parse them. The melmac_driver script ======================== The melmac distribution contains a script called melmac_driver which is meant to automate the important task of turning a number of C files into ALF and at the same time computing an ARAL annotation file for those files. melmac_driver allows you to achieve this using a simple call rather than separate calls to SATIrE's satire_driver and melmac itself, using a number of complicated and obscure command line options to make these two tools cooperate nicely. License conditions ================== melmac is open source software. See the file COPYING for details. Other information ================= If you have any questions about melmac, feel free to contact the author: Gergo Barany Acknowledgements ================ The developent of melmac is supported by the research project "Integrating European Timing Analysis Technology" (ALL-TIMES) under contract No. 215068 funded by the 7th EU R&D Framework Programme. See http://www.all-times.org for more information about ALL-TIMES.