ack.1.X 14 KB

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