2. How to use the Compiler Driver

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 have 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
same as -coins:hirOpt=noSimplify
that does 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/cpyp/preqp/cstp/rpe/dce/srd3,loopinversion
After coins-1.4.4.3, includes the following additional options:
-coins:regpromote,schedule-after
-O3
same as -coins:hirOpt=inline/cf/pre,ssa-opt= prun/divex/cse/cstp/hli/osr/hli/cstp/cpyp/preqp/cstp/rpe/dce/srd3,loopinversion
After coins-1.4.5.2, includes the following additional options:
-coins:regpromote-ex,schedule,pipelining
-O4
same as -coins:hirOpt=inline/loopexp/cf/cpf/pre,ssa-opt= prun/divex/cse/cstp/hli/osr/hli/cstp/cpyp/preqp/cstp/rpe/dce/srd3,loopinversion
After coins-1.4.5.2, includes the following additional options:
-coins:regpromote-ex,schedule,pipelining
-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 following 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.1,suffix=/tmp/mysuffixes
is same as
    -coins:debug -coins:trace=HIR.1 -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 architecture. 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.

Note:
All of above target options have been tested by using test programs under the directory test/c and succeeded to execute correctly except for a few number of special cases. As for the sparc and x86, the compiler passed the test by comprehensive test program set composed of 8000 programs and successfully executed the SPEC CPU 2000 benchmark programs. (When -O3 option is specified, some programs in SPEC CPU 2000 fail yet.) When target=arm is specified, a few programs in SPEC CPU 2000 can be executed successfully but others failed because of restrictions from test environment and remaining defects in code generation. As for other targets (mb, mips, ppc, sh4, thumb, alpha, x86_64), test by SPEC CPU2000 is not yet tried.

The code generators for sparc and x86 support the "long long" type, while the others do not support it.

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

-coins:preprocessor=prep
-coins:assembler=asm
-coins:linker=link
specify the preprocessor, assembler, and linker.

The default preprocessor is 'cpp', the default assembler is 'as', and the default linker is 'gcc'. (The default assembler has been 'gas' until coins-1.4.4.4.) If the specified architecture requires different names from these default names, the required names must be specified as shown in the following examples:

specification of header files
The stdarg.h file for sparc, x86, x86_64, and arm, is in COINS-directory/lang/c/include/stdarg.h. The following command option
  -coins:preprocessor="cpp -I../lang/c/include"
specifies to use this file.

For x86_64-mac, a program which contains
#include <stdio.h>
may cause a syntax error. In that case, the program can be compiled by using simplified header files. Examples of simplified header files are in COINS-directory/lang/c/include/samples/

Cygwin users may need to specify the following option:
    -coins:preprocessor="cpp-3 -I/usr/include"
    (-coins:preprocessor="cpp -I/usr/include" 
          -- in case of using java version older than java 1.6)
-coins:hirOpt=hiroptspec
-coins:hirOpt=hiroptspec/hiroptspec/...
Do optimizations on HIR. hiroptspec must be one of following: See "5.1. How to Use HIR Basic Optimizer" in 5. Optimization for HIR for detail.

-coins:ssa-opt=option/..
specifies SSA optimization options. The options are defined as follows: After coins-1.4.4.2, the following optimizations for non-SSA forms can be specified: After coins-1.5, the following optimizations for non-SSA forms can be specified: See "8.2. SSA OPTIONS" in 8. SSA Optimization for LIR for detail.
-coins:lir-opt=option/..
-coins:lirOpt=option/..
These can be used after coins-1.4.4.3. Options are the same as the options of ssa-opt.
-coins:parallelDoAll=OpenMP
analyze for-loops and generate OpenMP program written in C to be executed in parallel. See "6.1. Loop Parallelizer" in 6. Parallelization for HIR for detail.
-coins:parallelDoAll=n -S
where n is an integer number indicating maximum degree of parallelization. This option specifies to analyze for-loops and generate assembly language program that can be executed in parallel by linking with execution time routines prepared for parallelization. See "6.1. Loop Parallelizer" in 6. Parallelization for HIR for detail.
-coins:coarseGrainParallel
-coins:cgParallel
specified to invoke the Coarse Grain Parallelizing Module. See "6.2. Coarse Grain Parallelizing Module" in 6. Parallelization for HIR 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. Trace messages 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.2
prints trace messages of category `HIR' whose message level is less than or equals to 2.
The available trace categories are:
Control  -- What phases and (principal) modules are executed
HIR      -- HIR (High level Intermediate Representation) information
Sym      -- Sym and symbol table information
Flow     -- Control flow and data flow information
Alias    -- Alias analysis information
Parse    -- C Parser information
ToHir    -- C-AST (abstract syntax tree of C) to HIR transformation inf
HIR2C    -- HIR-to-C transformation information
Opt1     -- HIR optimizer information
Para1    -- Loop parallelizer information
TMD      -- Code Generation information
LIR      -- LIR (Low level Intermediate Representation) information

When multiple categories are specified separating by / delimiter, then trace information for each specified category is printed. For example,
    -coins:trace=Sym.1/HIR.1
prints the symbol table and HIR that are handed from the front-end to the back-end. When optimization level and Flow, Opt1 categories are specified in such a way as
   -O3 -coins:trace=Sym.1/HIR.2/Flow.1/Opt1.4
then, information of the symbol table, HIR, control flow, data flow, and optimization process will be printed.
Trace information is useful for understanding the process of compilation as well as debugging the compiler itself.

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.4/HIR.2
prints HIR trace messages whose message level is less than or equals to 2, not 4. 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.2/HIR.4
prints HIR trace messages whose message level is less than or equals to 4, and all non-HIR messages (and generic trace messages) whose message level is less than or equals to 2. Note that a large trace level (e.g. 7, 8, 9, etc.) may produce huge amount of traces.
-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
Compilations 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:regpromote
can be used after coins-1.4.4.3. It specifies register promotion (the attach option is not needed). See "11.2.3. Example 3: Register Promotion" in 11. Structure and Extensions of the Backend Process for detail.
-coins:regpromote-ex
can be used after coins-1.4.5.2. It specifies extended register promotion (the attach option is not needed) that promote more variables to registers based on pointer analysis.
-coins:schedule
-coins:schedule-after
can be used after coins-1.4.4.3 (the attach option is not needed). schedule specifies instruction scheduline before and after the register allocation. schedule-after specifies instruction scheduline after the register allocation. See "11.2.1. Example 1: Instruction Scheduler" in 11. Structure and Extensions of the Backend Process for detail.
-coins:pipelining
can be used after coins-1.4.4.3 (the attach option is not needed). It specifies software pipelining. See "11.2.2. Example 2: Software Pipelining" in 11. Structure and Extensions of the Backend Process for detail.
-coins:gprof
specifies to generate profiling information just like gcc. This option should be accompanied with the option
    -coins:linker="gcc -pg"
By executing the execution-file (a.out, a.exe, etc.), gmon.out will be generated and user can get profiling information by executing following command
    gprof execution-file
just like gcc.
The test scripts test/c/testdriver_gprof, test/c/testdriverw_gprof.sh are available to do automatic test and profiling for a set of test programs.
The gprof option is effective only for sparc and x86 at present.
See
gprof manual
'gprof: A Call Graph Execution Profiler' by S. Graham, P. Kessler, M. McKusick

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:

The compile specification object must implements an interface coins.driver.CompileSpecification.
In the CLI driver, the methods main() and go() of class coins.driver.Driver correspond the driver user interface. They are described as follows:

  protected void go(String[] args) {
    CompileSpecification spec = new CommandLine(args);
    int status = new CompilerDriver(spec).go(this);
    System.exit(status);
  }

  public static void main(String[] args) {
    new Driver().go(args);
  }
The class coins.driver.CommandLine is a compile specification class for the CLI driver. The class coins.driver.CompilerDriver is the engine. Since the class coins.driver.Driver is a driver implementation class, it passes an instance of itself as a driver implementation.

If you are to build a compiler driver which has a same user interface as the CLI driver, the above code segment will be reused without change.

2.4.2. Driver Implementation

The driver implementation provides following services called from the engine: An interface coins.driver.CompilerImplementation is defining the interface to be implemented by the driver implementations.

In case of the CLI driver, the class coins.driver.Driver is the driver implementation. The CLI driver is providing the above four services. Three of the four, i.e., preprocess, assemble, and link are just call an external program.

2.4.3. Compile Specification

The compile specification must implement an interface coins.driver.CompileSpecification.
In case of the CLI driver, the class coins.driver.CommandLine is the compile specification.

2.4.4. Tracer API

Tracer API interprets trace options specified by an operator, determines whether a trace message should be printed or not, and prints it if it should.

A driver implementation, and compiler modules called from it, can use the trace API to put a trace message, specifying a message category and a message level. A message category can be an arbitrary string of letters and digits. A message level must be a non-negative integer.

A trace option is a set of pairs of a trace category and a trace level. The tracer API prints a trace message if its message level is less than or equal to the trace level of the trace category which is a same string with the message category.

To obtain an instance of a Tracer API, which knows trace options specified by an operator, use a method

CompileSpecification#getTrace().

2.4.5. Warning API

Warning API interprets warning options specified by an operator, determines whether a warning message should be printed or not, and prints it if it should.

A driver implementation, and compile modules called from it, can use the warning API to put a warning message, specifying a warning category. A warning category can be an arbitrary string of letters and digits.

A warning option is a set of warning categories which should be printed and a set of warning categories which should not be printed. The warning API prints warnings specified to be printed.

To obtain an instance of Warning API which knows warning options specified by an operator, use a method

CompileSpecification#getWarning(). 

2.4.6. Library Directory

Compiler modules can be designed configurable and thus require configuration files for them. For example, the driver API is designed to allow operators preparing following configuration file: A library directory is a directory at where the configuration files should be located.

A compiler module can ask the COINS driver API where the library directory is, i.e., use a method CoinsOptions#getLibDir() to an instance of class.driver.CoinsOptions, which can be obtained by a method CompileSpecification#getCoinsOptions(). A COINS user can let an operator to prepare a configuration file at his/her library directory and let a compiler module to read the file using the API.

If a -coins:libdir=path option, which is one of the COINS options, is specified, the driver API returns path as the library directory path name. If not specified, the driver API searches a directory named `coins' at the operators home directory (`user.home' property value returned by the Java runtime) and returns its path name if it is found. If not found, a relative path name which represents a current working directory is returned as the library directory path name.

2.4.7. Property File

When applying COINS to develop a compiler, a relatively long COINS options including tracer, warning, and user own options may be required at each compilation. A `property file' functionality is to improve such a situation by storing the options in a file and give the file to the compiler.

By default, a file named `properties' in the library directory (see section 2.4.6) is treated as a property file.
Since some operators may change the property file location, it is changeable at creating compile specification. Interpretation of the property file is done at that time by class coins.driver.CoinsOptions.

The property file may be written in arbitrary format which can be read by a method java.utils.Properties#load(). An example follows:

        debug:
        trace:        HIR.4
        suffix:       /tmp/mysuffixes
This example is exactly same as giving a following COINS option to the CLI driver.
        -coins:debug,trace=HIR.4,suffix=/tmp/mysuffixes

2.4.8. Suffix Rules

A suffix rule is a rule to determine which pass should be applied to an input file and which suffix should be given to the output file. The COINS release package has a default suffix database file which contains suffix rules for C, Fortran, and Java.

By default, a file named `suffixes' under library directory (see section 4.6) is treated as a suffix database file. If not found, following default is used:

#SRD, 2, Suffix rule DB file, format version 2
c,		C,		C source,				i,s,o
c(out-newlir),	C,		C source,				i,lir,-
i,		C,		preprocessed C source,			-,s,o
cc/cpp/cxx/C,	C++,		C++ source,				ii,s,o
ii,		C++,		preprocessed C++ source,		-,s,o
java,		Java,		Java source,				-,class,-
java(native),	Java,		Java source (native compile),		-,s,o
f,		FORTRAN,	FORTRAN source,				-,s,o
f(out-newlir),	FORTRAN,	FORTRAN source,				-,lir,o
lir,		LIR,		new LIR,				-,s,o
S,		Assembler,	assembly source (need preprocess),	s,-,o
s,		Assembler,	assembly source,			-,-,o
Detail of this file format is described in a JavaDoc document of class coins.driver.SuffixFactory.java. Roughly speaking, it is a sequence of records each of which is in structure of:
suffix, language name, meaning, suffixes after preprocess, compile, and assemble.
Since some operators may change the suffix database file location, it is changeable at creating compile specification. Interpretation of the property file is done at that time by class coins.driver.SuffixFactory.

2.4.9 .`settings' File

While compilation, various information is required because compilation is an essentially complicated process. There can be some information which differs site by site, e.g., a special library path, an OS name, and so on. Thus, there needs a way to read site-local settings. `Settings' file is designed to keep such site-local settings

coins.driver.Driver reads settings file by a method java.utils.Process#load() from a library directory if it exists, and stores the contents to a member variable named `defaultSettings'. For coins.driver.Driver, valid properties are:

The following is an example of the settings file (as for libf2cLocation, see " 4.2.2 Fortran Driver Setup " of How to use Fortran 77 Compiler).
(This example is applicable after coins-1.4.5.)

systemIncludePath    ./lang/c/include ./lang/c/include/samples
defaultLinkerOptions /usr/lib
libf2cLocation       ./lnag/fortran

Compiler modules of COINS and drivers other than coins.driver.Driver can use this mechanism to read their site-local settings.

2.5. Known Bugs and Restrictions

Known bugs and restrictions of release 1.0 is as follows.

2.5.1. Known bugs

2.5.2. Restrictions