8 The CIL Driver
We have packaged CIL as an application cilly that contains certain
example modules, such as logwrites.ml (a module
that instruments code to print the addresses of memory locations being
written). Normally, you write another module like that, add command-line
options and an invocation of your module in src/main.ml. Once you compile
CIL you will obtain the file obj/cilly.asm.exe.
We wrote a driver for this executable that makes it easy to invoke your
analysis on existing C code with very little manual intervention. This driver
is bin/cilly and is quite powerful. Note that the cilly script
is configured during installation with the path where CIL resides. This means
that you can move it to any place you want.
A simple use of the driver is:
bin/cilly -D HAPPY_MOOD -I myincludes hello.c -o hello
This performs the following actions:
-
preprocessing using the -D and -I arguments with the resulting file left in hello.i,
- the invocation of the cilly.asm application which parses hello.i
converts it to CIL and the pretty-prints it to hellocil.c
- another round of preprocessing with the result placed in hellocil.i
- the true compilation with the result in hellocil.o
- a linking phase with the result in hello
Note that cilly behaves like the gcc compiler with the additional
effect that CIL sees all the source code. This makes it easy
to use it with existing Makefiles:
make CC="bin/cilly" LD="bin/cilly"
cilly can also behave as the Microsoft Visual C compiler, if the first
argument is --mode=MSVC:
bin/cilly --mode=MSVC /D HAPPY_MOOD /I myincludes hello.c /Fe hello.exe
(This in turn will pass a --MSVC flag to the underlying cilly.asm
process which will make it understand the Microsoft Visual C extensions)
cilly can also behave as the archiver ar, if it is passed an
argument --mode=AR. Note that only the cr mode is supported (create a
new archive and replace all files in there). Note that the previous version of
the archive is lost.
Furthermore, cilly allows you to pass some arguments on to the
underlying cilly.asm process. As a general rule all arguments that start
with -- and that cilly itself does not process, are passed on. For
example,
bin/cilly --dologwrites -D HAPPY_MOOD -I myincludes hello.c -o hello.exe
will produce a file hellocil.c that prints all the memory addresses
written by the application.
The most powerful feature of cilly is that it can collect all the
sources in your project, merge them into one file and then apply CIL. This
makes it a breeze to do whole-program analysis and transformation. All you
have to do is to pass the --merge flag to cilly:
make CC="bin/cilly --dologwrites --merge"
You can even leave some files untouched:
make CC="bin/cilly --dologwrites --merge --leavealone=foo --leavealone=bar"
This will merge all the files except those with the basename foo and
bar. Those files will be compiled as usual and then linked in at the very
end.
The sequence of actions performed by cilly depends on whether merging
is turned on or not:
-
If merging is off
-
For every file file.c to compile
-
Preprocess the file with the given arguments to
produce file.i
- Invoke cilly.asm to produce a filecil.c
- Preprocess to filecil.i
- Invoke the underlying compiler to produce filecil.o
- Link the resulting objects
- If merging is on
-
For every file file.c to compile
-
Preprocess the file with the given arguments to
produce file.i
- Save the preprocessed source as file.o
- When linking executable hello.exe, look at every object
file that must be linked and see if it actually
contains preprocessed source. Pass all those files to a
special merging application (described in
Section 14) to produce hello.exe_comb.c
- Invoke cilly.asm to produce a hello.exe_combcil.c
- Preprocess to hello.exe_combcil.i
- Invoke the underlying compiler to produce hello.exe_combcil.o
- Invoke the actual linker to produce hello.exe
Note that files that you specify with --leavealone are not merged and
never presented to CIL. They are compiled as usual and then are linked in at
the end.
And a final feature of cilly is that it can substitute copies of the
system's include files:
make CC="bin/cilly --includedir=myinclude"
This will force the preprocessor to use the file myinclude/xxx/stdio.h
(if it exists) whenever it encounters #include <stdio.h>. The xxx is
a string that identifies the compiler version you are using. This modified
include files should be produced with the patcher script (see
Section 15).
8.1 cilly Options
Among the options for the cilly you can put anything that can normally
go in the command line of the compiler that cilly is impersonating.
cilly will do its best to pass those options along to the appropriate
subprocess. In addition, the following options are supported (a complete and
up-to-date list can always be obtained by running cilly --help):
-
--mode=mode This must be the first argument if present. It makes
cilly behave as a given compiled. The following modes are recognized:
-
GNUCC - the GNU C Compiler. This is the default.
- MSVC - the Microsoft Visual C compiler. Of course, you should
pass only MSVC valid options in this case.
- AR - the archiver ar. Only the mode cr is supported and
the original version of the archive is lost.
- --help Prints a list of the options supported.
- --verbose Prints lots of messages about what is going on.
- --stages Less than --verbose but lets you see what cilly
is doing.
- --merge This tells cilly to first attempt to collect into one
source file all of the sources that make your application, and then to apply
cilly.asm on the resulting source. The sequence of actions in this case is
described above and the merger itself is described in Section 14.
- --leavealone=xxx. Do not merge and do not present to CIL the files
whose basename is "xxx". These files are compiled as usual and linked in at
the end.
- --includedir=xxx. Override the include files with those in the given
directory. The given directory is the same name that was given an an argument
to the patcher (see Section 15). In particular this means that
that directory contains subdirectories named based on the current compiler
version. The patcher creates those directories.
- --usecabs. Do not CIL, but instead just parse the source and print
its AST out. This should looked like the preprocessed file. This is useful
when you suspect that the conversion to CIL phase changes the meaning of the
program.
- --save-temps. Temporay files are preserved.
8.2 cilly.asm Options
All of the options that start with -- and are not understood by
cilly are passed on to cilly.asm. The following options are
supported:
-
--out <xxx>. The name of the pretty-printed file.
- --verbose. Print lots of random stuff. This is passed on from
cilly.
- -help. Print the help. Actually cilly will do this if you
pass it --help.
- --check. Run a consistency check over the CIL after every operation.
- --MSVC. Enable the MSVC extensions and pretty-print for consumption
by MSVC.
- --warnall. Print all the warnings.
- --log=xxx. Set xxx to be the name of the log file for the CIL
application. By default stderr is used.
- --keepunused. Do not attempt to remove the unused variables and
types from CIL.
- --noPrintLn. Do not print line numbers.
- --commPrintLn. Print line numbers but in comments.
- --printCilAsIs. Do not attempt to simplify the program while
printing. If this is turned on, then all loops will be printed as
``while(1)'', as they are in the internal language.
- --extrafiles <xxx>. Give the name of a text file that contains
whitespace-separated named of additional files to process.
- --dologcalls. Insert code in the processed source to print the name of
functions as are called. Implemented in src/ext/logcalls.ml.
- --dologwrites. Insert code in the processed source to print the
address of all memory writes. Implemented in src/ext/logwrites.ml.
- --dooneRet. Make each function have at most one 'return'.
Implemented in src/ext/oneret.ml.
- --dostackGuard. Instrument function calls and returns to
maintain a separate stack for return addresses. Implemeted in
src/ext/heapify.ml.
- --domakeCFG. Make the program look more like a CFG. Implemented
in src/cil.ml.
- --dopartial. Do interprocedural partial evaluation and
constant folding. Implemented in src/ext/partial.ml.
- --dosimpleMem. Simplify all memory expressions. Implemented in
src/ext/simplemem.ml.
For an up-to-date list of available options, run cilly.asm --help.