util/ack/ack.1.X

   1 .\" $Id: ack.1.X,v 2.25 1994/06/24 10:12:23 ceriel Exp $
   2 .de SB
   3 .\" SuBheader
   4 .sp 1
   5 .PP
   6 .nr Sf \\n(.f
   7 .ft B
   8 \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
   9 .ft \\n(Sf
  10 .sp 1
  11 ..
  12 .TH ACK 1 "$Revision: 2.25 $"
  13 .ad
  14 .SH NAME
  15 ack \- Amsterdam Compiler Kit
  16 .SH SYNOPSIS
  17 \fBack\fP arguments
  18 .br
  19 \fBacc\fP arguments
  20 .br
  21 \fBapc\fP arguments
  22 .br
  23 \fBabc\fP arguments
  24 .br
  25 \fBm2\fP arguments
  26 .br
  27 \fBocm\fP arguments
  28 .br
  29 \fBf2c\fP arguments
  30 .br
  31 \fImachine\fP arguments
  32 .SH DESCRIPTION
  33 This program transforms sources in several
  34 languages to load files for a variety of machines,
  35 internally using several phases.
  36 The transformation can be stopped at any phase.
  37 Combining sources from several languages is allowed.
  38 The run-time system of the first language mentioned,
  39 either in the program call name or in the arguments,
  40 is automatically included.
  41 The libraries of all other languages mentioned,
  42 containing most of the run-time systems,
  43 are also automatically included.
  44 Two types of load files can be distinguished,
  45 \fIa.out\fP files containing machine code and \fIe.out\fP
  46 files containing virtual EM machine code.
  47 The last type is designed for interpretation; it is obtained by calling
  48 the compiler as \fIem22\fP, \fIem24\fP, or \fIem44\fP.
  49 Compilation time for interpretation is fast and gives many
  50 runtime checks,
  51 but execution with \fIem\fP(1) is about seven times slower.
  52 Execution with \fIint\fP(1) is even slower than that, but available on
  53 more machines.
  54 Which combinations of languages and machines are allowed varies
  55 in time and depends on the installation.
  56 .PP
  57 The actions of \fIack\fP are to repeatedly transform files with a
  58 particular suffix into files with another suffix,
  59 finally combining the results into a single file.
  60 .PP
  61 Different machines can use different suffices,
  62 but the following are recognized by most machines:
  63 .IP .p
  64 Pascal program.
  65 .IP .c
  66 C module.
  67 .IP .b
  68 Basic program.
  69 .IP .ocm
  70 Occam program.
  71 .IP .mod
  72 Modula-2 module.
  73 .IP .f
  74 Fortran module.
  75 .IP .e
  76 EM assembly module in human readable form.
  77 .IP .k
  78 Compact EM assembly code.
  79 .IP .m
  80 Optimized compact EM assembly code.
  81 .IP .s
  82 Machine assembly language code.
  83 .IP .o
  84 Object file.
  85 .PP
  86 \fIAck\fP accepts the following flags:
  87 .SB machine used
  88 .IP \-m\fImachine\fP
  89 This flag tells \fIack\fP to generate a load file for \fImachine\fP.
  90 \fIMachine\fP can also be used as the program call
  91 name, instead of \fIack\fP.
  92 e.g. \fIack \-mi86 file.p\fP is equivalent to \fIi86
  93 file.p\fP.
  94 .SB output files
  95 .IP \-o
  96 Use the next argument as the name of the resulting file.
  97 \fIAck\fP produces \fIa.out\fP or \fIe.out\fP by default.
  98 This flag can always be used when \fIack\fP produces a single output file,
  99 as in
 100 .br
 101 .ti +5
 102 \fBack -c.s main.c -o new.s\fP.
 103 .br
 104 The output is produced on \fInew.s\fP instead of \fImain.s\fP.
 105 .IP \-c\fI.suffix\fP
 106 .IP \-c
 107 \fIAck\fP tries to transform each source into a file with the \fIsuffix\fP.
 108 When no \fIsuffix\fP is specified \fIack\fP stops just
 109 before the phase where it combines all arguments into a load file,
 110 thereby transforming the sources into \fI.k\fP, \fI.s\fP,
 111 \&\fI.o\fP or \fI.m\fP files.
 112 One extra \fIsuffix\fP is recognized here, \fI.i\fP,
 113 this tells \fIack\fP to only preprocess all human readable sources,
 114 producing files with \fIsuffix\fP \fI.i\fP.
 115 .br
 116 Note: \fIack\fP refuses to overwrite argument \fI.e\fP files.
 117 .IP \-t
 118 Preserve all intermediate files.
 119 If two \fB\-t\fP are used,
 120 \fIack\fP also preserves core dumps and output of failed transformations.
 121 .SB messages
 122 .IP \-w
 123 Suppress all warning messages.
 124 .IP \-v
 125 Verbose.
 126 Print information while juggling with files.
 127 .IP \-KR
 128 Tell the C-compiler to conform to "Kernighan & Ritchie" C.
 129 .IP \-ansi
 130 Tell \fIack\fP to use the ANSI C compiler instead of the old one.
 131 .IP \-fp
 132 Use the software floating point package, if present.
 133 .SB preprocessing
 134 .IP \-I\fIdir\fP
 135 \&\`#include\' files whose names do not begin with \`/\' are
 136 always sought first in the directory of the \fIfile\fP argument,
 137 then in the directories named in \fB\-I\fP options,
 138 then in directories on a standard list.
 139 .IP \-D\fIname=def\fP
 140 .IP \-D\fIname\fP
 141 Define the \fIname\fP to the preprocessor,
 142 as if by \`#define\'.
 143 If no definition is given the \fIname\fP is defined as 1.
 144 .IP \-U\fIname\fP
 145 Remove any initial definition of \fIname\fP, before
 146 preprocessing.
 147 .IP \-P
 148 Don't generate line directives.
 149 .IP \-C
 150 Leave C-comments in.
 151 .SB debugging
 152 .IP \-p
 153 This flag tells both the Pascal and C front ends to include
 154 code enabling the user to do some monitoring/debugging.
 155 Each time a routine is entered the routine \fBprocentry\fP
 156 is called and just before each return \fBprocexit\fP is called.
 157 These routines are supplied with one parameter, a pointer
 158 to a string containing the name of the routine.
 159 .SB optimizing
 160 .IP \-O
 161 .IP \-O\fInum\fP
 162 .IP \-O\fIopt1,opt2,...\fP
 163 Try to use the named optimizers, or, if no optimizers are given,
 164 try to use the optimizers with optimization level <= \fInum\fP (default 1).
 165 For optimizer names, see the table at the end of this manual page.
 166 Currently, only the global optimizer has a level > 1.
 167 Higher levels will invoke more passes of the global optimizer.
 168 For the global optimizer, it is also possible to indicate explicitly which
 169 phases must be executed, using the following flags:
 170 .RS
 171 .IP \-EGO-IL
 172 Inline substitution.
 173 .IP \-EGO-CS
 174 Common subexpression elimination.
 175 .IP \-EGO-SR
 176 Strength reduction.
 177 .IP \-EGO-UD
 178 Use definition analysis.
 179 .IP \-EGO-LV
 180 Live variable analysis.
 181 .IP \-EGO-RA
 182 Register allocation.
 183 .IP \-EGO-SP
 184 Stack pollution.
 185 .IP \-EGO-BO
 186 Branch optimization.
 187 .IP \-EGO-CJ
 188 Cross jumping.
 189 .RE
 190 .IP ""
 191 Also, the following flags may be used:
 192 .RS
 193 .IP \-s<num>
 194 Give an indication to the inline substitution phase,
 195 how much bigger the program may get,
 196 in percentage. This is only used as a rough indication.
 197 The inline substitution phase will not make the program bigger when given \-s0.
 198 .IP \-a
 199 Indicate to the inline substitution phase that it is offered the whole program.
 200 This allows it to throw away routines that it has substituted inline.
 201 .IP \-Q
 202 Give some statistics.
 203 .IP \-T
 204 Optimize for time.
 205 .IP \-S
 206 Optimize for size.
 207 .RE
 208 .IP ""
 209 In principle, the optimization phases can be run in any order; a phase
 210 may even be run more than once. However, the following rules must be obeyed:
 211 .RS
 212 .IP -
 213 the Live Variable analysis phase (LV) must be run prior to the
 214 Register Allocation phase (SA), as SA uses information produced by LV.
 215 .IP -
 216 SA should be the last phase.
 217 .RE
 218 .IP ""
 219 Also, the following may be of use:
 220 .RS
 221 .IP -
 222 Inline Substitution (IL) may create new opportunities for most other phases,
 223 so it should be run as early as possible.
 224 .IP -
 225 Use Definition analysis (UD) may introduce opportunities for LV.
 226 .IP -
 227 Strength Reduction (SR) may create opportunities for UD.
 228 .RE
 229 .IP ""
 230 The global optimizer is a combiner, so it should be offered all the source
 231 files of the program. This is not strictly necessary, but it makes the
 232 global optimizer more effective.
 233 The current default optimization phases are:
 234 .RS
 235 .IP -
 236 for \-O2: CJ, BO, SP;
 237 .IP -
 238 for \-O3: CS, SR, CJ, BO, SP, UD, LV, RA;
 239 .IP -
 240 for \-O4: IL, CS, SR, CJ, BO, SP, UD, LV, RA;
 241 .IP -
 242 for higher levels: as for \-O4.
 243 .RE
 244 .IP \-L
 245 Disable the generation of code by the front ends to
 246 record line number and source file name at run-time.
 247 (This is the default for C and Fortran).
 248 .SB libraries
 249 .IP \-l\fIname\fP
 250 Tells \fIack\fP to insert a library module at this point.
 251 For example: the library \fImon\fP contains the
 252 routines for systems calls needed by both C and Pascal.
 253 .IP \-.\fIsuffix\fP
 254 When linking multiple \fI.o\fP or \fI.m\fP files created by
 255 separate calls of \fIack\fP together, \fIack\fP cannot deduce
 256 the run-time system needed,
 257 unless called as \fIapc\fP, \fIabc\fP, \fIocm\fP, \fIm2\fP, \fIf2c\fP, or \fIacc\fP.
 258 This flag serves to tell \fIack\fP which runtime system is
 259 needed in such a case.
 260 For example: "ack \-c x.c ; ack \-.c x.o".
 261 .IP \-r.\fIsuffix\fP
 262 Most frontends and backends use one or
 263 more run-time libraries.
 264 These flags tell \fIack\fP to include the libraries needed when
 265 a file with \fIsuffix\fP would be included in the arguments.
 266 .IP \-LIB
 267 This flag tells the peephole optimizer
 268 .RF em_opt 6
 269 to add information about the visibility of the names used
 270 to each output module.
 271 This is needed by
 272 assembler/linkers when these modules are to be inserted
 273 in libraries.
 274 .SB interpreter
 275 .IP \-{xxx}
 276 The string starting after \`{\' and terminated by a \`}\' is passed
 277 as an option string to the Pascal compiler and supersedes corresponding
 278 options given in the source file.
 279 See the ACK reference manual [4] for a list of options.
 280 .IP "\-+xxx, \-\-xxx"
 281 When interpreting programs, these flags are used to select some
 282 options during interpretation, like test, profile, flow, extra and count.
 283 A short description of these flags follows:
 284 .RS
 285 .IP "  t(est)" 12
 286 test for undefined, overflow, array bound etc.
 287 .IP "  f(low)"
 288 keep track of executed source lines.
 289 .IP "  c(ount)"
 290 count the number of times a source line is executed.
 291 .IP "  p(rofile)"
 292 count the memory cycles executed per source line.
 293 .RE
 294 .IP "" 5
 295 Test is on by default, the others are off. Normally, these
 296 flag options are given each time the interpreter is run.
 297 The EM assembler/linker offers the opportunity to change
 298 the defaults per program.
 299 The changed options are recorded in the "e.out" header.
 300 These flags \-\- and \-+ are passed to the assembler for this purpose.
 301 So, \-\-t and \-+pfce invert the defaults.
 302 .SB general
 303 .IP \-R\fIprogram=xxx\fP
 304 Replace the \fIprogram\fP by the pathname \fIxxx\fP.
 305 The program names referred to later in this manual are allowed here.
 306 .IP \-R\fIprogram\-xxx\fP
 307 The flag argument \fI\-xxx\fP is given to \fIprogram\fP.
 308 .IP \-R\fIprogram:n\fP
 309 Set the priority of the indicated transformation to \fIn\fP.
 310 The default priority is 0, setting it to -1 makes it highly
 311 unlikely the the phase will be used, setting it to 1 makes
 312 it very likely that the phase will be used.
 313 .IP \-k
 314 Do not stop when an error occurs, but try to transform all
 315 other arguments as far as possible.
 316 .IP \-g
 317 Instruct the front-end and back-end to produce symbolic debugger information
 318 for \fIgrind\fP(1). This is currently supported by the following front-ends:
 319 C, ANSI-C, Pascal, Modula-2, and the following back-ends: Motorola M68020,
 320 Sparc, Vax, Intel 80386.
 321 .IP \-gdb
 322 Instruct the front-end and back-end to produce symbolic debugger information
 323 for \fIgdb\fP. This is currently supported by the following front-ends:
 324 C, ANSI-C, Pascal, Modula-2, and the following back-ends: Motorola M68020,
 325 Sparc, Vax, Intel 80386.
 326 .PP
 327 All arguments without a suffix or with an unrecognized suffix
 328 are passed to the loaders, as for flags.
 329 .SH PREPROCESSOR
 330 All C source programs are run through the preprocessor
 331 before they are fed to the compiler proper.
 332 On larger machines, the compiler has a built in preprocessor.
 333 Other human readable sources (Modula-2, Pascal, or Basic programs and
 334 machine assembly) are only preprocessed when they start with a \`#\'.
 335 .PP
 336 \fIAck\fP adds a few macro definitions when it calls the
 337 preprocessor.
 338 These macro\'s contain the word- and pointer-size and the sizes
 339 of some basic types used by the Pascal, Basic and/or C compiler.
 340 All sizes are in bytes.
 341 .sp 1
 342 .TS
 343 tab(:);
 344 l l l l.
 345 EM_WSIZE:wordsize:EM_PSIZE:pointer size
 346 EM_SSIZE:size of shorts (C):EM_LSIZE:size of longs (C+Pascal)
 347 EM_FSIZE:size of floats (C):EM_DSIZE:size of doubles (C+Pascal)
 348 .TE
 349 .sp 1
 350 The name of the \fImachine\fP or something like it when
 351 the machine name is numeric is also defined (as 1).
 352 As the ANSI C rules forbid this, in ANSI C, underscores are prepended to
 353 these names.
 354 .PP
 355 The default directories searched for include files differ for each machine.
 356 .SH PROGRAMS
 357 \fIAck\fP uses one or more programs in each phase of the
 358 transformation.
 359 The table below gives the names \fIack\fP uses for these
 360 programs.
 361 Internally \fIack\fP maintains a mapping of these names to pathnames
 362 for load files.
 363 The table specifies which type of files are accepted by each
 364 program as input and the file type produced as output.
 365 .sp 1
 366 .in +2
 367 .TS
 368 tab(:);
 369 l l l l.
 370 input:name:output:description
 371 \&.f:f77:.c:Fortran-to-C front end
 372 \&.c:cem:.k:C front end [4,5,6]
 373 \&.p:pc:.k:Pascal front end [2,3,6]
 374 \&.b:abc:.k:Basic front end [6,8]
 375 \&.ocm:ocm:.k:Occam front end [9]
 376 \&.mod:m2:.k:Modula-2 front end [11]
 377 \&.e:encode:.k:Compactify EM assembly language [1]
 378 \&.k:opt:.m:EM peephole optimizer
 379 \&.k .m:decode:.e:Produce human readable EM assembly
 380 \&.k .m:emass:e.out:Linker producing EM machine code [1]
 381 \&.m:ego:.gk:EM global optimizer [10]
 382 \&.gk:opt2:.g:Second EM peephole optimizer
 383 \&.m .g:be:.s:backend
 384 \&.s:asopt:.so:target optimizer
 385 \&.s .so:asld:.out:Assembler/linker, Ack object format
 386 \&.s .so:as:.o:Assembler, relocatable object
 387 \&.o:ld:a.out:Linker, machine a.out format
 388 \&.o:led:.out:Linker, Ack object format
 389 \&.o:cv:a.out:Conversion from Ack object to machine object
 390 .TE
 391 .in -2
 392 .SH "ENVIRONMENT VARIABLES"
 393 .IP ACKDIR
 394 If set, this environment variable overrides ack's idea of its home
 395 directory.
 396 .IP ACKM
 397 If set, this environment variable overrides ack's idea of the default
 398 machine it compiles for.
 399 .IP ACKFE
 400 If set, this environment variable tells ack where to get the front-end
 401 description file.
 402 .SH "SEE ALSO"
 403 .PD 0
 404 em_opt(6), em_ass(6), em_cg(6), ack.out(5)
 405 .IP [1]
 406 A.S. Tanenbaum, Hans van Staveren, Ed Keizer and Johan
 407 Stevenson, \fIDescription of a machine architecture for use with
 408 block structured languages\fP, Informatica rapport IR-81.
 409 .IP [2]
 410 K. Jensen and N. Wirth,
 411 \fIPASCAL, User manual and report\fP Springer Verlag.
 412 .IP [3]
 413 The ISO Pascal standard proposal ISO/TC97/SC5-N462.
 414 .IP [4]
 415 B.W. Kernighan and D.M. Ritchie, \fIThe C Programming
 416 language\fP, Prentice-Hall, 1978
 417 .IP [5]
 418 D.M. Ritchie, \fI C Reference Manual\fP
 419 .IP [6]
 420 Amsterdam Compiler Kit, reference manuals and UNIX manual pages.
 421 .IP [7]
 422 E.G. Keizer, Ack description file reference manual.
 423 .IP [8]
 424 M.L. Kersten a.o., \fIThe ABC compiler\fP.
 425 .IP [9]
 426 Kees Bot and Edwin Scheffer, \fIAn Occam Compiler\fP, IM-6.
 427 .IP [10]
 428 H.E. Bal, \fIThe design and implementation of the EM Global Optimizer\fP,
 429 Informatica rapport IR-99.
 430 .IP [11]
 431 C.J.H. Jacobs, \fIThe ACK Modula-2 Compiler\fP.
 432 .PD
 433 .SH DIAGNOSTICS
 434 .PD
 435 The diagnostics are intended to be self\-explanatory.
 436 .SH BUGS
 437 Not all warning messages are superseded by \fB\-w\fP.
 438 .br
 439 Argument assembly files are not preprocessed when fed into the
 440 universal assembler/loader.
 441 .SH AUTHOR
 442 Ed Keizer, Vrije Universiteit, Amsterdam