ACK(1)

NAME
ack - Amsterdam Compiler Kit

SYNOPSIS
ack arguments

DESCRIPTION
This program transforms sources in several languages to load files for a variety of machines, internally using several phases. The transformation can be stopped at any phase. Combining sources from several languages is allowed. The run-time system of the first language mentioned, either in the program call name or in the arguments, is automatically included. The libraries of all other languages mentioned, containing most of the run-time systems, are also automatically included. Two types of load files can be distinguished, a.out files containing machine code and e.out files containing virtual EM machine code. The last type is designed for interpretation; it is obtained by calling the compiler as em22, em24, or em44. Compilation time for interpretation is fast and gives many runtime checks, but execution with em(1) is about seven times slower. Execution with int(1) is even slower than that, but available on more machines. Which combinations of languages and machines are allowed varies in time and depends on the installation.

The actions of ack are to repeatedly transform files with a particular suffix into files with another suffix, finally combining the results into a single file.

Different machines can use different suffices, but the following are recognized by most machines:

.p .pas
    Pascal program.

.c  C module.

.bas
    Basic program.

.ocm
    Occam program.

.mod
    Modula-2 module.

.f  Fortran module.

.e  EM assembly module in human readable form.

.k  Compact EM assembly code.

.m  Optimized compact EM assembly code.

.s  Machine assembly language code.

.o  Object file.

OPTIONS
Ack accepts the following flags:

-mmachine
    This flag tells ack to generate a load file for machine.

-o  Use the next argument as the name of the resulting file. Ack produces a.out or e.out by default. This flag can always be used when ack produces a single output file, as in
    ack -c.s main.c -o new.s.
    The output is produced on new.s instead of main.s.

-c.suffix

-c  Ack tries to transform each source into a file with the suffix. When no suffix is specified ack stops just before the phase where it combines all arguments into a load file, thereby transforming the sources into .k, .s, .o or .m files. One extra suffix is recognized here, .i, this tells ack to only preprocess all human readable sources, producing files with suffix .i.
    Note: ack refuses to overwrite argument .e files.

-t  Preserve all intermediate files. If two -t are used, ack also preserves output of failed transformations.

-w  Suppress all warning messages.

-v  Verbose. Print information while juggling with files.

-KR Tell the C-compiler to conform to "Kernighan & Ritchie" C.

-ansi
    Tell ack to use the ANSI C compiler instead of the old one.

-fp Use the software floating point package, if present.

-Idir
    `#include' files whose names do not begin with `/' are always sought first in the directory of the file argument, then in the directories named in -I options, then in directories on a standard list.

-Dname=def

-Dname
    Define the name to the preprocessor, as if by `#define'. If no definition is given the name is defined as 1.

-Uname
    Remove any initial definition of name, before preprocessing.

-P  Don't generate line directives.

-C  Leave C-comments in.

-p  This flag tells both the Pascal and C front ends to include code enabling the user to do some monitoring/debugging. Each time a routine is entered the routine procentry is called and just before each return procexit is called. These routines are supplied with one parameter, a pointer to a string containing the name of the routine.

-O

-Onum

-Oopt1,opt2,...
    Try to use the named optimizers, or, if no optimizers are given, try to use the optimizers with optimization level <= num (default 1). For optimizer names, see the table at the end of this manual page. Currently, only the global optimizer has a level > 1. Higher levels will invoke more passes of the global optimizer. For the global optimizer, it is also possible to indicate explicitly which phases must be executed, using the following flags:

    -EGO-IL
        Inline substitution.

    -EGO-CS
        Common subexpression elimination.

    -EGO-SR
        Strength reduction.

    -EGO-UD
        Use definition analysis.

    -EGO-LV
        Live variable analysis.

    -EGO-RA
        Register allocation.

    -EGO-SP
        Stack pollution.

    -EGO-BO
        Branch optimization.

    -EGO-CJ
        Cross jumping.

    Also, the following flags may be used:

    -s<num>
        Give an indication to the inline substitution phase, how much bigger the program may get, in percentage. This is only used as a rough indication. The inline substitution phase will not make the program bigger when given -s0.

    -a  Indicate to the inline substitution phase that it is offered the whole program. This allows it to throw away routines that it has substituted inline.

    -Q  Give some statistics.

    -T  Optimize for time.

    -S  Optimize for size.

    In principle, the optimization phases can be run in any order; a phase may even be run more than once. However, the following rules must be obeyed:

    -   the Live Variable analysis phase (LV) must be run prior to the Register Allocation phase (SA), as SA uses information produced by LV.

    -   SA should be the last phase.

    Also, the following may be of use:

    -   Inline Substitution (IL) may create new opportunities for most other phases, so it should be run as early as possible.

    -   Use Definition analysis (UD) may introduce opportunities for LV.

    -   Strength Reduction (SR) may create opportunities for UD.

    The global optimizer is a combiner, so it should be offered all the source files of the program. This is not strictly necessary, but it makes the global optimizer more effective. The current default optimization phases are:

    -   for -O2: CJ, BO, SP;

    -   for -O3: CS, SR, CJ, BO, SP, UD, LV, RA;

    -   for -O4: IL, CS, SR, CJ, BO, SP, UD, LV, RA;

    -   for higher levels: as for -O4.

-L  Disable the generation of code by the front ends to record line number and source file name at run-time. (This is the default for C and Fortran).

-lname
    Tells ack to insert a library module at this point. For example: the library mon contains the routines for systems calls needed by both C and Pascal.

-.suffix
    When linking multiple .o or .m files created by separate calls of ack together, ack cannot deduce the run-time system needed, unless called as apc, abc, ocm, m2, f2c, or acc. This flag serves to tell ack which runtime system is needed in such a case. For example: "ack -c x.c ; ack -.c x.o".

-r.suffix
    Most frontends and backends use one or more run-time libraries. These flags tell ack to include the libraries needed when a file with suffix would be included in the arguments.

-LIB
    This flag tells the peephole optimizer em_opt(6) to add information about the visibility of the names used to each output module. This is needed by assembler/linkers when these modules are to be inserted in libraries.

-{xxx}
    The string starting after `{' and terminated by a `}' is passed as an option string to the Pascal compiler and supersedes corresponding options given in the source file. See the ACK reference manual [4] for a list of options.

-+xxx, --xxx
    When interpreting programs, these flags are used to select some options during interpretation, like test, profile, flow, extra and count. A short description of these flags follows:

    t(est)
        test for undefined, overflow, array bound etc.

    f(low)
        keep track of executed source lines.

    c(ount)
        count the number of times a source line is executed.

    p(rofile)
        count the memory cycles executed per source line.

    Test is on by default, the others are off. Normally, these flag options are given each time the interpreter is run. The EM assembler/linker offers the opportunity to change the defaults per program. The changed options are recorded in the "e.out" header. These flags -- and -+ are passed to the assembler for this purpose. So, --t and -+pfce invert the defaults.

-Rprogram=xxx
    Replace the program by the pathname xxx. The program names referred to later in this manual are allowed here.

-Rprogram-xxx
    The flag argument -xxx is given to program.

-Rprogram:n
    Set the priority of the indicated transformation to n. The default priority is 0, setting it to -1 makes it highly unlikely the the phase will be used, setting it to 1 makes it very likely that the phase will be used.

-k  Do not stop when an error occurs, but try to transform all other arguments as far as possible.

-g  Instruct the front-end and back-end to produce symbolic debugger information for grind(1). This is currently supported by the following front-ends: C, ANSI-C, Pascal, Modula-2, and the following back-ends: Motorola M68020, Sparc, Vax, Intel 80386.

-gdb
    Instruct the front-end and back-end to produce symbolic debugger information for gdb. This is currently supported by the following front-ends: C, ANSI-C, Pascal, Modula-2, and the following back-ends: Motorola M68020, Sparc, Vax, Intel 80386.

All arguments without a suffix or with an unrecognized suffix are passed to the loaders, as for flags.

PREPROCESSOR
All C source programs are run through the preprocessor before they are fed to the compiler proper. On larger machines, the compiler has a built in preprocessor. Other human readable sources (Modula-2, Pascal, or Basic programs and machine assembly) are only preprocessed when they start with a `#'.

Ack adds a few macro definitions when it calls the preprocessor. These macro's contain the word- and pointer-size and the sizes of some basic types used by the Pascal, Basic and/or C compiler. All sizes are in bytes.

EM_WSIZE | wordsize | EM_PSIZE | pointer size
EM_SSIZE | size of shorts (C) | EM_LSIZE | size of longs (C+Pascal)
EM_FSIZE | size of floats (C) | EM_DSIZE | size of doubles (C+Pascal)

The name of the machine or something like it when the machine name is numeric is also defined (as 1). As the ANSI C rules forbid this, in ANSI C, underscores are prepended to these names.

The default directories searched for include files differ for each machine.

PROGRAMS
Ack uses one or more programs in each phase of the transformation. The table below gives the names ack uses for these programs. Internally ack maintains a mapping of these names to pathnames for load files. The table specifies which type of files are accepted by each program as input and the file type produced as output.

input | name | output | description
.f | f77 | .c | Fortran-to-C front end
.c | cem | .k | C front end [4,5,6]
.p .pas | pc | .k | Pascal front end [2,3,6]
.b | basic | .k | Basic front end [6,8]
.ocm | ocm | .k | Occam front end [9]
.mod | m2 | .k | Modula-2 front end [11]
.e | encode | .k | Compactify EM assembly language [1]
.k | opt | .m | EM peephole optimizer
.k .m | decode | .e | Produce human readable EM assembly
.k .m | emass | e.out | Linker producing EM machine code [1]
.m | ego | .gk | EM global optimizer [10]
.gk | opt2 | .g | Second EM peephole optimizer
.m .g | be | .s | backend
.s | asopt | .so | target optimizer
.s .so | asld | .out | Assembler/linker, Ack object format
.s .so | as | .o | Assembler, relocatable object
.o | ld | a.out | Linker, machine a.out format
.o | led | .out | Linker, Ack object format
.o | cv | a.out | Conversion from Ack object to machine object

ENVIRONMENT VARIABLES

ACKDIR
    If set, this environment variable overrides ack's idea of its home directory.

ACKM
    If set, this environment variable overrides ack's idea of the default machine it compiles for.

ACKFE
    If set, this environment variable tells ack where to get the front-end description file.

SEE ALSO
em_opt(6), em_ass(6), em_cg(6), ack.out(5)

[1] A.S. Tanenbaum, Hans van Staveren, Ed Keizer and Johan Stevenson, Description of a machine architecture for use with block structured languages, Informatica rapport IR-81.
[2] K. Jensen and N. Wirth, PASCAL, User manual and report Springer Verlag.
[3] The ISO Pascal standard proposal ISO/TC97/SC5-N462.
[4] B.W. Kernighan and D.M. Ritchie, The C Programming language, Prentice-Hall, 1978
[5] D.M. Ritchie, C Reference Manual
[6] Amsterdam Compiler Kit, reference manuals and UNIX manual pages.
[7] E.G. Keizer, Ack description file reference manual.
[8] M.L. Kersten a.o., The ABC compiler.
[9] Kees Bot and Edwin Scheffer, An Occam Compiler, IM-6.
[10]
    H.E. Bal, The design and implementation of the EM Global Optimizer, Informatica rapport IR-99.
[11]
    C.J.H. Jacobs, The ACK Modula-2 Compiler.

DIAGNOSTICS
The diagnostics are intended to be self-explanatory.

BUGS
Not all warning messages are superseded by -w.

Argument assembly files are not preprocessed when fed into the universal assembler/loader.

AUTHOR
Ed Keizer, Vrije Universiteit, Amsterdam