2. How to use the Compiler Driver

Contents

2.1. Target, Range, and Structure of this Document

This document describes the design and the usage of the COINS compiler driver for the COINS users.
The COINS is a framework of compiler mainly to support users who are to construct their own compiler. Thus, its driver part consists of Java API to create their own compiler driver and a compiler driver with traditionally fashioned command line interface (CLI) using the API.

Section two describes about the design and the structure of the COINS compiler driver. Section three is a users manual of the CLI driver. Section four describes about an outline of the driver API.

2.2. COINS Compiler Driver

2.2.1. The design

We expect that the COINS users can be categorized into following two categories: Users of the former category may intend to: The "new compilers" may require "new compiler drivers". The COINS compiler driver provides a driver programming API.

Hereafter, we call a user of the latter category "operator". When we write "user" without explanation, it doesn't mean the operators.

Operators (and we) must not be willing to follow some ritual procedures to use a compiler. Some of them will try "make CC=newcc", without reading documents. To meet the requirement, a traditionally fashioned CLI driver is provided. This CLI driver has many similarities with the gcc (GNU C compiler) in the command syntax and the basic compile options.

2.2.2. Structure

Figure 2-1 illustrates the structure of the COINS compiler driver.
prepared +---------------------+ +---------------------+ +------------+
by users |driver implementation| |driver user interface| |suffix rules|
         +---------------------+ +---------------------+ +------------+
         +-----------------------------+ +----------------------------+
API      |   tracer API / warning API  | |  compile specification API |
         +-----------------------------+ +----------------------------+
         +------------------------------------------------------------+
         |                           engine                           |
         +------------------------------------------------------------+
Figure 1-1: The structure of the COINS compile driver

Users should prepare the following three parts if needed:

Each API and the engine has following functions:

2.3. How to Use the CLI Driver

2.3.1 CLI Driver

The class coins.driver.Driver provided by the release package is a CLI-based driver implemented by the COINS driver API, which is designed to have many similarities with gcc.

The class coins.driver.Driver is the driver implementation and the class coins.driver.CommandLine is the driver user interface.

2.3.2 Command Syntax

        java [java-option ...] coins.driver.Driver [option | filename]...
The command name 'java' may be 'jre' or other command name according to your Java runtime. 'java-option's are for Java runtime environment, e.g., a -cp option to use COINS classes. If you deployed the COINS classes at /usr/local/coins,
    java -cp /usr/local/coins coins.driver.Driver [option | filename]
will be enough to load COINS classes to the Java runtime.

2.3.3. Options

Following compile options can be specified:

-E
only preprocessing. As for C program, foo.i is generated by processing foo.c. The output file is produced at the directory where the input file (foo.c, in the example) is located. COMPATIBILITY NOTE: gcc produces the output to the stdout.
-S
stops after compilation (in the strict meaning, i.e., the assembler code generation). As for C program, foo.s is generated by processing foo.c. The output file is produced at the directory where the input file (foo.c, in the example) is located. COMPATIBILITY NOTE: gcc produces the output to the current working directory.
-c
don't link. As for C program, foo.o is generated by processing foo.c. The output file is produced at the directory where foo.c is located. COMPATIBILITY NOTE: gcc produces the output to the current working directory.
-help
shows help messages.
-o file
specifies a path name of the output file. The output file means a preprocessed source file when the -E option is specified, an assembly code file when the -S option is specified, an object code file when the -c option is specified, and the executable file when none of the above is specified.
-barch, or -b arch
specifies a target architecture, as well as specifying -coins:target=arch (see -coins:target=arch).
-pipe
uses pipelines instead of temporary files to communicate between passes.
-Wcategory
shows warning messages whose warning category is `category.'
-Wno-category
suppresses warning messages whose warning category is `category.'
-C
preserve comments while preprocessing.
-Dmacro[=definition]
defines a preprocessor macro. `definition' is set to the macro value when specified.
-Ipath
specifies an include path.
-P
inhibits #line directives.
-Umacro
undefines a preprocessor macro.
-O
same as -O1.
-Olevel
specifies an optimization level. The `level' must be a non-negative integer. Optimizations done at each level are following:
-O0
do nothing.
-O1
same as -coins:hirOpt=cf,ssa-opt=prun/cpyp/cstp/dce/ebe/srd3,loopinversion
-O2
same as -coins:hirOpt=cf,ssa-opt=prun/divex/cse/cstp/hli/osr/hli/cstp/cse/dce/srd3,loopinversion
-O3 or more
same as -O2.
-g
preserves symbols in an executable file.
-v
prints a command line when a sub-process is invoked.
-Lpath
specifies an archive search path.
-dynamic
uses dynamic linkage.
-static
uses static linkage.
-larchive
specifies an archive to link.
-coins:option
See the folloing section.

2.3.4. -coins Options

    -coins:option,option,...
option is a COINS option. Any string not including `,' can be specified as option. More than one COINS option can be specified by delimiting them by `,'s, e.g.
               -coins:debug,trace=HIR.8,suffix=/tmp/mysuffixes
is same as
               -coins:debug -coins:trace=HIR.8 -coins:suffix=/tmp/mysuffixes

Standard COINS options (which means the options that affects driver API behavior) are as follows:

-coins:target=arch
-coins:target=arch-convention
specifies a target archtecture. Equivalent to -b arch, or to -b arch-convention.

"-coins:target=arch" is equivalent to

-coins:target=arch-standard
 
and "-coins:target=arch-convention" is equivalent to
-coins:target-arch=arch,target-convention=convention
 

            -coins:target-arch=arch
specifies a target architecture name. arch must be one of: When this option is specified, the COINS Compiler Driver specifies -D__arch__ as a preprocessor option, and specifies the arch to LIR module invocation as a target architecture name, which will be `sparc' when this option is not specified.
            -coins:target-convention=convention
specifies a target convention name. convention can be: When this option is specified, the COINS Compiler Driver specifies the convention to LIR module invocation as a target architecture convention name, which will be `standard' when this option is not specfied.

Cygwin users usually need to specify a following option, as well as -b x86-cygwin:

    -coins:assembler=as
And, depending on the cygwin installation, there may be a case which requires following option:
    -coins:preprocessor="cpp -I/usr/include"
-coins:hirOpt=hiroptspec
-coins:hirOpt=hiroptspec/hiroptspec/...
Do basic optimizations on HIR. hiroptspec must be one of following:
                    cf    // constant folding
                    cpf   // constant propagation and folding
                    cse   // common subexpression elimination
                    dce   // dead code elimination
                    fromc // simple optimizations done by C parser
		    gt    // global variable temporalization within basic block
		    pre   // partial redundancy elimination
		alias=opt   // optimistic alias analysis
		loopexp  // loop expansion
		inlain   // inline expansion
See 5.1. How to Use HIR Basic Optimizer for detail.
-coins:ssa-opt=ssa_opt
-coins:ssa-opt=ssa_opt/..
specifies SSA optimization options. The options are defined as follows: See 8.2. SSA OPTIONS for detail.
-coins:debug
Tells that the compiler is under debugging. Same as -coins:preserveFiles,testHir,testSym.
-coins:preserveFiles
Preserves temporary files.
-coins:trace=tracespec
-coins:trace=tracespec/tracespec/..
Tracer options.
There are two types of trace messages: categorized trace messages and generic trace messages. A categorized trace message have a message category, and a generic trace message doesn't have message category.
A trace message may have a message level which is a non-negative integer value. A trace message without a message level are treated as level zero.
In the above form, each tracespec can be in form of
                    level
or
                    category.level
where a level is non-negative integer which represents a trace level, and the category is a sequence of letters and digits which represents a message category. The former form specifies the trace level of a generic trace message (hereafter, a generic trace level). A generic trace message is printed only if its message level is less than or equals to the generic trace level. The latter form specifies the trace level of categorized messages whose message category is category. A trace message whose message category is category is printed only if its message level is less than or equals to the trace level. For example,
                    -coins:trace=2
prints generic trace messages whose message level is less than or equals to 2;
                    -coins:trace=HIR.8
prints trace messages of category `HIR' whose message level is less than or equals to 8. When more than one generic trace levels are specified, or more than one trace levels are specified for a same category, the latter one overwrites the former one. For example,
                    -coins:trace=4/8
prints generic trace messages whose message level is less than or equals to 8, not 4;
                    -coins:trace=HIR.6/HIR.3
prints HIR trace messages whose message level is less than or equals to 3, not 6. A special category `default' is provided to specify a trace level of all trace messages other than trace messages whose trace levels are explicitly specified in the other tracespecs. For example,
                    -coins:trace=default.5/HIR.8
prints HIR trace messages whose message level is less than or equals to 8, and all non-HIR messages (and generic trace messages) whose message level is less than or equals to 5. Note that a large trace level (e.g. 7, 8, 9, etc.) may produce huge amount of traces. Examples of available trace categories are:
                     HIR, LIR, Sym, SSA, TMD.
-coins:libdir=path
specifies a library directory path. See section 2.4.6 about the library directory. When more than one -coins:libdir options are specified, only the last one is valid.
-coins:property=path
specifies property file path name. By default, a file named `property' located at the library directory is the property file.
See section 2.4.7 about the property file. When more than one -coins:property options are specified, only the last one is valid.
-coins:suffix=path
specifies a path name of a suffix database file. By default, a file name `suffixes' located at the library directory is the suffix database file.
See section 2.4.8 about the suffix database file. When more than one -coins:suffix options are specified, only the last one is valid.
-coins:suffixoption=option
specifies a suffix option. See section 2.4.8 about the suffix option. When more than one -coins:suffixoption options are specified and are conflicting, the latter one overrides the former one.
-coins:hirAnal
Do HIR flow analysis.
-coins:hir2c=t1
-coins:hir2c=t1/t2/.../tn
translates HIR into a C program at specified timing. t1, t2, ..., tn must be one of
                   new ... just after HIR creation,
                   flo ... just after data flow analysis on HIR has
                           been done, and
                   opt ... after all optimizations on HIR.
When more than one timing specifiers are specified, HIR is translated at all specified timings. Generated files are named as r-hir-t.c, where `r' is the file name root of original source file, and `t' is the timing specifier. For example,
                   java coins.driver.Driver -coins:hir2c=new foo.c
will produce foo-hir-new.c as the hir2c result. Invalid timing specifiers are ignored and the corresponding file is not generated.
-coins:lir2c=t1
-coins:lir2c=t1/t2/.../tn
translates LIR into a C program at specified timing. t1, t2, ..., tn must be one of
                   new ... just after LIR creation,
                   opt ... after all optimizations.
When more than one timing specifiers are specified, LIR is translated at all specified timings. Generated files are named as r-lir-t.c, where `r' is the file name root of original source file, and `t' is the timing specifier. For example,
                   java coins.driver.Driver -coins:lir2c=new foo.c
will produce foo-lir-new.c as the lir2c result. Invalid timing specifiers are ignored and the corresponding file is not generated.
-coins:stopafterhir2c
-coins:stopafterlir2c
quits compilation of each compile unit just after generating C source files at all specified timings by the hir2c/lir2c option. When some invalid timing specifiers are specified in hir2c/lir2c option, however, the behavior of the compiler is undefined.
-coins:testHir
Tests HIR integrity after HIR optimization and parallelization and before converting HIR to LIR.
-coins:testSym
Tests symbol table integrity after HIR optimization and parallelization and before converting HIR to LIR.
-coins:preprocessor=preprocessor-command
-coins:assembler=assembler-command
-coins:linker=linker-command
specifies alternative commands of preprocessor, assembler, and linker.
In default, the COINS Compiler Driver uses cpp, gas, and gcc as preprocessor, assembler, and linker. You can override them by specifying these options. Following example sets `as' as the assembler.
                    -coins:assembler=as
Blanks appeared in the command name works as a word delimiter: e.g., following example sets the gcc as the preprocessor and an option -E is given to it.
                    -coins:preprocessor=gcc -E
Do not forget to escape the blanks from your command interpreter, if it treats blanks as a word delimiter, too. For example, most of Unix shells can escape blanks using quotations, e.g.,
                    -coins:preprocessor="gcc -E"
                    -coins:preprocessor='gcc -E'
                    '-coins:preprocessor=gcc -E'
Double quotations will work on Windows, too. A quotation mark (' and ") and a next appearing same quotation mark are removed from the string and characters between them are interpreted as follows: This rule can be used to avoid the above rule which interprets a blank as a word delimiter. For example, in an environment where the file and directory names can have blanks in its name, quotation marks can escape the blank in the command name as follows:
                    -coins:preprocessor='my cc' -E
In this example, a program 'my cc' is invoked as a preprocessor with an option '-E'. Do not forget to escape quotation marks and blanks from your command interpreter. For example, in Windows, double quotations will be required as follows:
                    -coins:preprocessor="'my cc' -E"
Any character following a backslash (`\') is interpreted as the character itself. A backslash can be given by a backslash following a backslash. A quotation mark can be interpreted as itself losing the special effect described above by following a backslash. This escape rule can be used to escape a blank from being interpreted as a word delimiter. For example, if your environment allows you to include blanks in file/directory name, you can escape them by backslashes: e.g.,
                    -coins:linker=c:\\Program\ Files\\bin_utils\\ld
will set `c:\Program Files\bin_utils\ld' as a linker. Again, never forget to escape `\'s and blanks from your command interpreter, if necessary; e.g., in Windows,
                    -coins:linker="c:\\Program\ Files\\bin_utils\\ld"
-coins:max-recovered-errors=n When the number of recovered compile errors exceeds n while executing a compile step of a compile unit, a compile error is issued. Or, if 0 is specified as n, no compile error is issued only by increasing the number of recovered compile errors. A compile step here is one of preprocess, compile, assemble, and link.
-coins:max-warnings=n
When the number of warnings exceeds n while executing a compile step of a compile unit, a compile error is issued. Or, if 0 is specified as n, no compile error is issued only by increasing the number of warnings. A compile step here is one of preprocess, compile, assemble, and link.
-coins:compile-parallel
Compilation of all compile units are executed concurrently. Do not specify this option while using a compiler driver which is not implemented in thread-safe way.
-coins:loopinversion
specifies to invert a loop end condition when the loop ends with an unconditional jump.
-coins:mdf
specified to invoke the Coarse Grain Parallelizing Module. See doc-en/README.MDF.en.txt in the COINS release package.

2.3.5. Input Files

Input files can be listed among options. The engine determines which passes should be applied to an input file according to its suffix. As for this suffix rule, see coins.driver.SuffixFactory.

Each output file is generated at the directory where its source file exists, unless -o option is specified.

2.3.6. Exit Status

The CLI driver returns exit status as follows: `Abnormal termination' includes I/O error, compile error, etc.

2.3.7 Some Simple Examples

In all examples below, it is assumed that the CLASSPATH environment variable is set appropriately:
    java coins.driver.Driver foo.c
will compile foo.c and generate a.out.
    java coins.driver.Driver -o foo foo.c
will compile foo.c and generate foo as an executable binary.
    java coins.driver.Driver -c foo.c
will compile foo.c and generate foo.o as an object file.
    java coins.driver.Driver -E foo/bar.c baz/boo.c
will preprocess foo/bar.c and baz/boo.c and generate foo/bar.i and baz/boo.i where `.i' is a suffix meaning `preprocessed C source' in the default suffix rule.
    java coins.driver.Driver -S foo.c bar.i
will compile foo.c and bar.i and generate foo.s and bar.s.

Generally speaking, aliasing `java coins.driver.Driver' as `cc', you can use COINS C compiler like an ordinary C compiler except some exceptions; e.g., cc -E will not work as cpp.

2.4. The Driver API

This document describes an abstract. For a full description, see JavaDoc's of each API class.

2.4.1. Driver User Interface

The function of the driver user interface is as follows: