ack.1.X 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315
  1. .\" $Header$
  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 I
  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. \fBint\fP arguments
  26. .br
  27. \fImachine\fP arguments
  28. .SH DESCRIPTION
  29. This program transforms sources in several
  30. languages to load files for a variety of machines,
  31. internally using several phases.
  32. The transformation can be stopped at any phase.
  33. Combining sources from several languages is allowed.
  34. The run-time system of the first language mentioned,
  35. either in the program call name or in the arguments,
  36. is automatically included.
  37. The libraries of all other languages mentioned,
  38. containing most of the run-time systems,
  39. are also automatically included.
  40. Two types of load files can be distinguished,
  41. \fIa.out\fP files containing machine code and \fIe.out\fP
  42. files containing virtual EM machine code.
  43. The last type is designed for interpretation; it is obtained by calling
  44. the compiler as \fIint\fP.
  45. Compilation time for interpretation is fast and gives many
  46. runtime checks,
  47. but execution is about seven times slower.
  48. Which combinations of languages and machines are allowed varies
  49. in time and depends on the installation.
  50. .PP
  51. The actions of \fIack\fP are to repeatedly transform files with a
  52. particular suffix into files with another suffix,
  53. finally combining the results into a single file.
  54. .PP
  55. Different machines can use different suffices,
  56. but the following are recognized by most machines:
  57. .IP .p
  58. Pascal program.
  59. .IP .c
  60. C module.
  61. .IP .b
  62. Basic program.
  63. .IP .e
  64. EM assembly module in human readable form.
  65. .IP .k
  66. Compact EM assembly code.
  67. .IP .m
  68. Optimized compact EM assembly code.
  69. .IP .s
  70. Machine assembly language code.
  71. .IP .o
  72. Object file.
  73. .PP
  74. \fIAck\fP accepts the following flags:
  75. .SB machine used
  76. .IP \-m\fImachine\fP
  77. This flag tells \fIack\fP to generate a load file for \fImachine\fP.
  78. \fIMachine\fP can also be used as the program call
  79. name, instead of \fIack\fP.
  80. e.g. \fIack \-mi86 file.p\fP is equivalent to \fIi86
  81. file.p\fP.
  82. .SB output files
  83. .IP \-o
  84. Use the next argument as the name of the resulting file.
  85. \fIAck\fP produces \fIa.out\fP or \fIe.out\fP by default.
  86. This flag can always be used when \fIack\fP produces a single output file,
  87. as in
  88. .br
  89. .ti +5
  90. \fBack -c.s main.c -o new.s\fP.
  91. .br
  92. The output is produced on \fInew.s\fP instead of \fImain.s\fP.
  93. .IP \-c\fI.suffix\fP
  94. .IP \-c
  95. \fIAck\fP tries to transform each source into a file with the \fIsuffix\fP.
  96. When no \fIsuffix\fP is specified \fIack\fP stops just
  97. before the phase where it combines all arguments into a load file,
  98. thereby transforming the sources into \fI.k\fP, \fI.s\fP,
  99. \&\fI.o\fP or \fI.m\fP files.
  100. One extra \fIsuffix\fP is recognized here, \fI.i\fP,
  101. this tells \fIack\fP to only preprocess all human readable sources,
  102. producing files with \fIsuffix\fP \fI.i\fP.
  103. .br
  104. Note: \fIack\fP refuses to overwrite argument \fI.e\fP files.
  105. .IP \-t
  106. Preserve all intermediate files.
  107. If two \fB\-t\fP are used,
  108. \fIack\fP also preserves core dumps and output of failed transformations.
  109. .SB messages
  110. .IP \-w
  111. Suppress all warning messages.
  112. .IP \-E
  113. Produce a complete listing of each Pascal source program.
  114. Normally for each error, one message,
  115. including the source line number, is given.
  116. .IP \-e
  117. List only the erroneous lines of each Pascal source program.
  118. .IP \-v
  119. Verbose.
  120. Print information while juggling with files.
  121. .SB preprocessing
  122. .IP \-I\fIdir\fP
  123. \&\`#include\' files whose names do not begin with \`/\' are
  124. always sought first in the directory of the \fIfile\fP argument,
  125. then in the directories named in \fB\-I\fP options,
  126. then in directories on a standard list.
  127. .IP \-D\fIname=def\fP
  128. .IP \-D\fIname\fP
  129. Define the \fIname\fP to the preprocessor,
  130. as if by \`#define\'.
  131. If no definition is given the \fIname\fP is defined as 1.
  132. .IP \-U\fIname\fP
  133. Remove any initial definition of \fIname\fP, before
  134. preprocessing.
  135. .SB debugging
  136. .IP \-p
  137. This flag tells both the Pascal and C front ends to include
  138. code enabling the user to do some monitoring/debugging.
  139. Each time a routine is entered the routine \fBprocentry\fP
  140. is called and just before each return \fBprocexit\fP is called.
  141. These routines are supplied with one parameter, a pointer
  142. to a string containing the name of the routine.
  143. .SB optimizing
  144. .IP \-O
  145. Use as many optimizers as possible.
  146. \fIAck\fP can almost always use the EM peephole optimizer.
  147. Sometimes the global optimizer or machine-dependent
  148. optimizers can be used.
  149. .IP \-L
  150. Disable the generation of code by the front ends to
  151. record line number and source file name at run-time.
  152. .SB libraries
  153. .IP \-l\fIname\fP
  154. Tells \fIack\fP to insert a library module at this point.
  155. For example: the library \fImon\fP contains the
  156. routines for systems calls needed by both C and Pascal.
  157. .IP \-.\fIsuffix\fP
  158. When linking multiple \fI.o\fP or \fI.m\fP files created by
  159. separate calls of \fIack\fP together, \fIack\fP cannot deduce
  160. the run-time system needed,
  161. unless called as \fIapc\fP or \fIacc\fP.
  162. This flag serves to tell \fIack\fP which runtime system is
  163. needed in such a case.
  164. For example: "ack \-c x.c ; ack \-.c x.o".
  165. .IP \-r.\fIsuffix\fP
  166. Most frontends and backends use one or
  167. more run-time libraries.
  168. These flags tell \fIack\fP to include the libraries needed when
  169. a file with \fIsuffix\fP would be included in the arguments.
  170. .IP \-LIB
  171. This flag tells the peephole optimizer
  172. .RF em_opt VI
  173. to add information about the visibility of the names used
  174. to each output module.
  175. This is needed by most
  176. assembler/linkers when these modules are to be inserted
  177. in libraries.
  178. .SB interpreter
  179. .IP \-{xxx}
  180. The string starting after \`{\' and terminated by a \`}\' is passed
  181. as an option string to the Pascal compiler and supersedes corresponding
  182. options given in the source file.
  183. See the ACK reference manual [4] for a list of options.
  184. .IP "\-+xxx, \-\-xxx"
  185. When you want to interpret your program, you may select some
  186. options during interpretation, like test, profile, flow, extra and count.
  187. A short description of these flags follows:
  188. .RS
  189. .IP " t(est)" 12
  190. test for undefined, overflow, array bound etc.
  191. .IP " f(low)"
  192. keep track of executed source lines.
  193. .IP " c(ount)"
  194. count the number of times a source line is executed.
  195. .IP " p(rofile)"
  196. count the memory cycles executed per source line.
  197. .RE
  198. .IP "" 5
  199. Test is on by default, the others are off. Normally, you give these
  200. flag options each time you run the interpreter.
  201. The EM assembler/linker gives you the opportunity to change
  202. the defaults per program.
  203. The changed options are recorded in the "e.out" header.
  204. These flags \-\- and \-+ are passed to the assembler for this purpose.
  205. So, \-\-t and \-+pfce invert the defaults.
  206. .SB general
  207. .IP \-R\fIprogram=xxx\fP
  208. Replace the \fIprogram\fP by the pathname \fIxxx\fP.
  209. The program names referred to later in this manual are allowed here.
  210. .IP \-R\fIprogram\-xxx\fP
  211. The flag argument \fI\-xxx\fP is given to \fIprogram\fP.
  212. .IP \-R\fIprogram:n\fP
  213. Set the priority of the indicated transformation to \fIn\fP.
  214. The default priority is 0, setting it to -1 makes it highly
  215. inlikely the the phase will be used, setting it to 1 makes
  216. it very likely that the phase will be used.
  217. .IP \-k
  218. Do not stop when an error occurs, but try to transform all
  219. other arguments as far as possible.
  220. .IP \-g
  221. Try to run the resulting load file.
  222. No arguments can be passed this way,
  223. so it is only useful in simple cases.
  224. .PP
  225. All arguments without a suffix or with an unrecognized suffix
  226. are passed to the loaders, as for flags.
  227. .SH PREPROCESSOR
  228. All C source programs are run through the preprocessor
  229. before they are fed to the compiler proper.
  230. Other human readable sources (Pascal programs and
  231. machine assembly) are only preprocessed when they start with a \`#\'.
  232. .PP
  233. \fIAck\fP adds a few macro definitions when it calls the
  234. preprocessor.
  235. These macro\'s contain the word- and pointer-size and the sizes
  236. of some basic types used by the Pascal and/or C compiler.
  237. All sizes are in bytes.
  238. .sp 1
  239. .TS
  240. tab(:);
  241. l l l l.
  242. EM_WSIZE:wordsize:EM_PSIZE:pointer size
  243. EM_SSIZE:size of shorts (C):EM_LSIZE:size of longs (C+Pascal)
  244. EM_FSIZE:size of floats (C):EM_DSIZE:size of doubles (C+Pascal)
  245. .TE
  246. .sp 1
  247. The name of the \fImachine\fP or something like it when
  248. the machine name is numeric is also defined (as 1).
  249. .PP
  250. The default directories searched for include files differ for each machine.
  251. Some machines do not even use \fI/usr/include\fP.
  252. .SH PROGRAMS
  253. \fIAck\fP uses one or more programs in each phase of the
  254. transformation.
  255. The table below gives the names \fIack\fP uses for these
  256. programs.
  257. Internally \fIack\fP maintains a mapping of these names to pathnames
  258. for load files.
  259. The table specifies which type of files are accepted by each
  260. program as input and the file type produced as output.
  261. .sp 1
  262. .in +2
  263. .TS
  264. tab(:);
  265. l l l l.
  266. input:name:output:description
  267. \&.c:cem:.k:C front end [4,5,6]
  268. \&.p:pc:.k:Pascal front end [2,3,6]
  269. \&.b:abc:.k:Basic front end [6,8]
  270. \&.e:encode:.k:Compactify EM assembly language [1]
  271. \&.k:opt:.m:EM peephole optimizer
  272. \&.k .m:decode:.e:Produce human readable EM assembly
  273. \&.k .m:emass:e.out:Linker producing EM machine code [1]
  274. \&.m:be:.s:backend
  275. \&.s:asld:a.out:Assembler/linker producing machine code
  276. \&.s:as:.o:Assembler
  277. \&.o:ld:a.out:Linker producing machine code
  278. .TE
  279. .in -2
  280. .SH "SEE ALSO"
  281. .PD 0
  282. em_opt(VI), em_ass(VI), em_cg(VI)
  283. .IP [1]
  284. A.S. Tanenbaum, Hans van Staveren, Ed Keizer and Johan
  285. Stevenson \fIDescription of a machine architecture for use with
  286. block structured languages\fP Informatica report IR-81.
  287. .IP [2]
  288. K. Jensen and N. Wirth
  289. \fIPASCAL, User manual and report\fP Springer Verlag.
  290. .IP [3]
  291. The ISO Pascal standard proposal ISO/TC97/SC5-N462.
  292. .IP [4]
  293. B.W. Kernighan and D.M. Ritchie, \fIThe C Programming
  294. language\fP, Prentice-Hall, 1978
  295. .IP [5]
  296. D.M. Ritchie, \fI C Reference Manual\fP
  297. .IP [6]
  298. Amsterdam Compiler Kit, reference manuals and UNIX manual pages.
  299. .IP [7]
  300. E.G. Keizer, Ack description file reference manual.
  301. .IP [8]
  302. M.L. Kersten, \fIThe ABC compiler\fP.
  303. .PD
  304. .SH DIAGNOSTICS
  305. .PD
  306. The diagnostics are intended to be self\-explanatory.
  307. .SH BUGS
  308. The -g flag is inoperative.
  309. .br
  310. Not all warning messages are superseded by \fB\-w\fP.
  311. .br
  312. Argument assembly files are not preprocessed when fed into the
  313. universal assembler.
  314. .SH AUTHOR
  315. Ed Keizer, Vrije Universiteit, Amsterdam