ack.doc 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444
  1. .\" $Id$
  2. .nr PD 1v
  3. .tr ~
  4. .TL
  5. Ack Description File
  6. .br
  7. Reference Manual
  8. .AU
  9. Ed Keizer
  10. .AI
  11. Vakgroep Informatica
  12. Vrije Universiteit
  13. Amsterdam
  14. .NH
  15. Introduction
  16. .PP
  17. The program \fIack\fP(I) internally maintains a table of
  18. possible transformations and a table of string variables.
  19. The transformation table contains one entry for each possible
  20. transformation of a file.
  21. Which transformations are used depends on the suffix of the
  22. source file.
  23. Each transformation table entry tells which input suffixes are
  24. allowed and what suffix/name the output file has.
  25. When the output file does not already satisfy the request of the
  26. user (indicated with the flag \fB\-c.suffix\fP), the table is scanned
  27. starting with the next transformation in the table for another
  28. transformation that has as input suffix the output suffix of
  29. the previous transformation.
  30. A few special transformations are recognized, among them is the
  31. combiner, which is
  32. a program combining several files into one.
  33. When no stop suffix was specified (flag \fB\-c.suffix\fP) \fIack\fP
  34. stops after executing the combiner with as arguments the \-
  35. possibly transformed \- input files and libraries.
  36. \fIAck\fP will only perform the transformations in the order in
  37. which they are presented in the table.
  38. .LP
  39. The string variables are used while creating the argument list
  40. and program call name for
  41. a particular transformation.
  42. .NH
  43. Which descriptions are used
  44. .PP
  45. \fIAck\fP always uses two description files: one to define the
  46. front-end transformations and one for the machine dependent
  47. back-end transformations.
  48. Each description has a name.
  49. First the way of determining
  50. the name of the descriptions needed is described.
  51. .PP
  52. When the shell environment variable ACKFE is set \fIack\fP uses
  53. that to determine the front-end table name, otherwise it uses
  54. \fBfe\fP.
  55. .PP
  56. The way the backend table name is determined is more
  57. convoluted.
  58. .br
  59. First, when the last filename in the program call name is not
  60. one of \fIack\fP or the front-end call-names,
  61. this filename is used as the backend description name.
  62. Second, when the \fB\-m\fP is present the \fB\-m\fP is chopped of this
  63. flag and the rest is used as the backend description name.
  64. Third, when both failed the shell environment variable ACKM is
  65. used.
  66. Last, when also ACKM was not present the default backend is
  67. used, determined by the definition of ACKM in h/local.h.
  68. The presence and value of the definition of ACKM is
  69. determined at compile time of \fIack\fP.
  70. .PP
  71. Now, we have the names, but that is only the first step.
  72. \fIAck\fP stores a few descriptions at compile time.
  73. This descriptions are simply files read in at compile time.
  74. At the moment of writing this document, the descriptions
  75. included are: pdp, fe, i86, m68k2, vax2 and int.
  76. The name of a description is first searched for internally,
  77. then in lib/descr/\fIname\fP, then in
  78. lib/\fIname\fP/descr, and finally in the current
  79. directory of the user.
  80. .NH
  81. Using the description file
  82. .PP
  83. Before starting on a narrative of the description file,
  84. the introduction of a few terms is necessary.
  85. All these terms are used to describe the scanning of zero
  86. terminated strings, thereby producing another string or
  87. sequence of strings.
  88. .IP Backslashing 5
  89. .br
  90. All characters preceded by \e are modified to prevent
  91. recognition at further scanning.
  92. This modification is undone before a string is passed to the
  93. outside world as argument or message.
  94. When reading the description files the
  95. sequences \e\e, \e# and \e<newline> have a special meaning.
  96. \e\e translates to a single \e, \e# translates to a single #
  97. that is not
  98. recognized as the start of comment, but can be used in
  99. recognition and finally, \e<newline> translates to nothing at
  100. all, thereby allowing continuation lines.
  101. .nr PD 0
  102. .IP "Variable replacement"
  103. .br
  104. The scan recognizes the sequences {{, {NAME} and {NAME?text}
  105. Where NAME can be any combination if characters excluding ? and
  106. } and text may be anything excluding }.
  107. (~\e} is allowed of course~)
  108. The first sequence produces an unescaped single {.
  109. The second produces the contents of the NAME, definitions are
  110. done by \fIack\fP and in description files.
  111. When the NAME is not defined an error message is produced on
  112. the diagnostic output.
  113. The last sequence produces the contents of NAME if it is
  114. defined and text otherwise.
  115. .PP
  116. .IP "Expression replacement"
  117. .br
  118. Syntax: (\fIsuffix sequence\fP:\fIsuffix sequence\fP=\fItext\fP)
  119. .br
  120. Example: (.c.p.e:.e=tail_em)
  121. .br
  122. If the two suffix sequences have a common member \-~\&.e in this
  123. case~\- the text is produced.
  124. When no common member is present the empty string is produced.
  125. Thus the example given is a constant expression.
  126. Normally, one of the suffix sequences is produced by variable
  127. replacement.
  128. \fIAck\fP sets three variables while performing the diverse
  129. transformations: HEAD, TAIL and RTS.
  130. All three variables depend on the properties \fIrts\fP and
  131. \fIneed\fP from the transformations used.
  132. Whenever a transformation is used for the first time,
  133. the text following the \fIneed\fP is appended to both the HEAD and
  134. TAIL variable.
  135. The value of the variable RTS is determined by the first
  136. transformation used with a \fIrts\fP property.
  137. .IP
  138. Two runtime flags have effect on the value of one or more of
  139. these variables.
  140. The flag \fB\-.suffix\fP has the same effect on these three variables
  141. as if a file with that \fBsuffix\fP was included in the argument list
  142. and had to be translated.
  143. The flag \fB\-r.suffix\fP only has that effect on the TAIL
  144. variable.
  145. The program call names \fIacc\fP and \fIcc\fP have the effect
  146. of an automatic \fB\-.c\fP flag.
  147. \fIApc\fP and \fIpc\fP have the effect of an automatic \fB\-.p\fP flag.
  148. .IP "Line splitting"
  149. .br
  150. The string is transformed into a sequence of strings by replacing
  151. the blank space by string separators (nulls).
  152. .IP "IO replacement"
  153. .br
  154. The > in the string is replaced by the output file name.
  155. The < in the string is replaced by the input file name.
  156. When multiple input files are present the string is duplicated
  157. for each input file name.
  158. .nr PD 1v
  159. .LP
  160. Each description is a sequence of variable definitions followed
  161. by a sequence of transformation definitions.
  162. Variable definitions use a line each, transformations
  163. definitions consist of a sequence of lines.
  164. Empty lines are discarded, as are lines with nothing but
  165. comment.
  166. Comment is started by a # character, and continues to the end
  167. of the line.
  168. Three special two-characters sequences exist: \e#, \e\e and
  169. \e<newline>.
  170. Their effect is described under 'backslashing' above.
  171. Each \- nonempty \- line starts with a keyword, possibly
  172. preceded by blank space.
  173. The keyword can be followed by a further specification.
  174. The two are separated by blank space.
  175. .PP
  176. Variable definitions use the keyword \fIvar\fP and look like this:
  177. .DS X
  178. var NAME=text
  179. .DE
  180. The name can be any identifier, the text may contain any
  181. character.
  182. Blank space before the equal sign is not part of the NAME.
  183. Blank space after the equal is considered as part of the text.
  184. The text is scanned for variable replacement before it is
  185. associated with the variable name.
  186. .br
  187. .sp 2
  188. The start of a transformation definition is indicated by the
  189. keyword \fIname\fP.
  190. The last line of such a definition contains the keyword
  191. \fIend\fP.
  192. The lines in between associate properties to a transformation
  193. and may be presented in any order.
  194. The identifier after the \fIname\fP keyword determines the name
  195. of the transformation.
  196. This name is used for debugging and by the \fB\-R\fP flag.
  197. The keywords are used to specify which input suffices are
  198. recognized by that transformation,
  199. the program to run, the arguments to be handed to that program
  200. and the name or suffix of the resulting output file.
  201. Two keywords are used to indicate which run-time startoffs and
  202. libraries are needed.
  203. The possible keywords are:
  204. .IP \fIfrom\fP
  205. .br
  206. followed by a sequence of suffices.
  207. Each file with one of these suffices is allowed as input file.
  208. Preprocessor transformations do not need the \fIfrom\fP
  209. keyword. All other transformations do.
  210. .nr PD 0
  211. .IP \fIto\fP
  212. .br
  213. followed by the suffix of the output file name or in the case of a
  214. linker
  215. the output file name.
  216. .IP \fIprogram\fP
  217. .br
  218. followed by name of the load file of the program, a pathname most likely
  219. starts with either a / or {EM}.
  220. This keyword must be
  221. present, the remainder of the line
  222. is subject to backslashing and variable replacement.
  223. .IP \fImapflag\fP
  224. .br
  225. The mapflags are used to grab flags given to \fIack\fP and
  226. pass them on to a specific transformation.
  227. This feature uses a few simple pattern matching and replacement
  228. facilities.
  229. Multiple occurrences of this keyword are allowed.
  230. This text following the keyword is
  231. subjected to backslashing.
  232. The keyword is followed by a match expression and a variable
  233. assignment separated by blank space.
  234. As soon as both description files are read, \fIack\fP looks
  235. at all transformations in these files to find a match for the
  236. flags given to \fIack\fP.
  237. The flags \fB\-m\fP, \fB\-o\fP,
  238. \fB\-O\fP, \fB\-r\fP, \fB\-v\fP, \fB\-g\fP, \-\fB\-c\fP, \fB\-t\fP,
  239. \fB\-k\fP, \fB\-R\fP and \-\fB\-.\fP are specific to \fIack\fP and
  240. not handed down to any transformation.
  241. The matching is performed in the order in which the entries
  242. appear in the definition.
  243. The scanning stops after first match is found.
  244. When a match is found, the variable assignment is executed.
  245. A * in the match expression matches any sequence of characters,
  246. a * in the right hand part of the assignment is
  247. replaced by the characters matched by
  248. the * in the expression.
  249. The right hand part is also subject to variable replacement.
  250. The variable will probably be used in the program arguments.
  251. The \fB\-l\fP flags are special,
  252. the order in which they are presented to \fIack\fP must be
  253. preserved.
  254. The identifier LNAME is used in conjunction with the scanning of
  255. \fB\-l\fP flags.
  256. The value assigned to LNAME is used to replace the flag.
  257. The example further on shows the use of all this.
  258. .IP \fIargs\fP
  259. .br
  260. The keyword is followed by the program call arguments.
  261. It is subject to backslashing, variable replacement, expression
  262. replacement, line splitting and IO replacement.
  263. The variables assigned to by \fImapflags\fP will probably be
  264. used here.
  265. The flags not recognized by \fIack\fP or any of the transformations
  266. are passed to the linker and inserted before all other arguments.
  267. .IP \fIstdin\fP
  268. .br
  269. This keyword indicates that the transformation reads from standard input.
  270. .IP \fIstdout\fP
  271. .br
  272. This keyword indicates that the transformation writes on standard output.
  273. .IP \fIoptimizer\fP
  274. .br
  275. The presence of this keyword indicates that this transformation is an optimizer.
  276. It can be followed by a number, indicating the "level" of the
  277. optimizer (see description of the -O option in the ack(1ACK) manual page).
  278. .IP \fIpriority\fP
  279. .br
  280. This \-~optional~\- keyword is followed by a number. Positive priority means
  281. that the transformation is likely to be used, negative priority means that
  282. the transformation is unlikely to be used.
  283. Priorities can also be set with a ack(1ACK) command line option.
  284. Priorities come in handy when there are several implementations of a
  285. certain transformation. They can then be used to select a default one.
  286. .IP \fIlinker\fP
  287. .br
  288. This keyword indicates that this transformation is the linker.
  289. .IP \fIcombiner\fP
  290. .br
  291. This keyword indicates that this transformation is a combiner. A combiner
  292. is a program combining several files into one, but is not a linker.
  293. An example of a combiner is the global optimizer.
  294. .IP \fIprep\fP
  295. .br
  296. This \-~optional~\- keyword is followed an option indicating its relation
  297. to the preprocessor.
  298. The possible options are:
  299. .DS X
  300. always the input files must be preprocessed
  301. cond the input files must be preprocessed when starting with #
  302. is this transformation is the preprocessor
  303. .DE
  304. .IP \fIrts\fP
  305. .br
  306. This \-~optional~\- keyword indicates that the rest of the line must be
  307. used to set the variable RTS, if it was not already set.
  308. Thus the variable RTS is set by the first transformation
  309. executed which such a property or as a result from \fIack\fP's program
  310. call name (acc, cc, apc or pc) or by the \fB\-.suffix\fP flag.
  311. .IP \fIneed\fP
  312. .br
  313. This \-~optional~\- keyword indicates that the rest of the line must be
  314. concatenated to the HEAD and TAIL variables.
  315. This is done once for every transformation used or indicated
  316. by one of the program call names mentioned above or indicated
  317. by the \fB\-.suffix\fP flag.
  318. .br
  319. .nr PD 1v
  320. .NH
  321. Conventions used in description files
  322. .PP
  323. \fIAck\fP reads two description files.
  324. A few of the variables defined in the machine specific file
  325. are used by the descriptions of the front-ends.
  326. Other variables, set by \fIack\fP, are of use to all
  327. transformations.
  328. .PP
  329. \fIAck\fP sets the variable EM to the home directory of the
  330. Amsterdam Compiler Kit.
  331. The variable SOURCE is set to the name of the argument that is currently
  332. being massaged, this is useful for debugging.
  333. The variable SUFFIX is set to the suffix of the argument that is
  334. currently being massaged.
  335. .br
  336. The variable M indicates the
  337. directory in lib/{M}/tail_..... and NAME is the string to
  338. be defined by the preprocessor with \-D{NAME}.
  339. The definitions of {w}, {s}, {l}, {d}, {f} and {p} indicate
  340. EM_WSIZE, EM_SSIZE, EM_LSIZE, EM_DSIZE, EM_FSIZE and EM_PSIZE
  341. respectively.
  342. .br
  343. The variable INCLUDES is used as the last argument to \fIcpp\fP.
  344. It is used to add directories to
  345. the list of directories containing #include files.
  346. .PP
  347. The variables HEAD, TAIL and RTS are set by \fIack\fP and used
  348. to compose the arguments for the linker.
  349. .NH
  350. Example
  351. .PP
  352. Description for front-end
  353. .DS X
  354. .ta 4n 40n
  355. name cpp # the C-preprocessor
  356. # no from, it's governed by the P property
  357. to .i # result files have suffix i
  358. program {EM}/lib/cpp # pathname of loadfile
  359. mapflag \-I* CPP_F={CPP_F?} \-I* # grab \-I.. \-U.. and
  360. mapflag \-U* CPP_F={CPP_F?} \-U* # \-D.. to use as arguments
  361. mapflag \-D* CPP_F={CPP_F?} \-D* # in the variable CPP_F
  362. args {CPP_F?} {INCLUDES?} \-D{NAME} \-DEM_WSIZE={w} \-DEM_PSIZE={p} \e
  363. \-DEM_SSIZE={s} \-DEM_LSIZE={l} \-DEM_FSIZE={f} \-DEM_DSIZE={d} <
  364. # The arguments are: first the \-[IUD]...
  365. # then the include dir's for this machine
  366. # then the NAME and size values finally
  367. # followed by the input file name
  368. stdout # Output on stdout
  369. prep is # Is preprocessor
  370. end
  371. name cem # the C-compiler proper
  372. from .c # used for files with suffix .c
  373. to .k # produces compact code files
  374. program {EM}/lib/em_cem # pathname of loadfile
  375. mapflag \-p CEM_F={CEM_F?} \-Xp # pass \-p as \-Xp to cem
  376. mapflag \-L CEM_F={CEM_F?} \-l # pass \-L as \-l to cem
  377. args \-Vw{w}i{w}p{p}f{f}s{s}l{l}d{d} {CEM_F?}
  378. # the arguments are the object sizes in
  379. # the \-V... flag and possibly \-l and \-Xp
  380. stdin # input from stdin
  381. stdout # output on stdout
  382. prep always # use cpp
  383. rts .c # use the C run-time system
  384. need .c # use the C libraries
  385. end
  386. name decode # make human readable files from compact code
  387. from .k.m # accept files with suffix .k or .m
  388. to .e # produce .e files
  389. program {EM}/lib/em_decode # pathname of loadfile
  390. args < # the input file name is the only argument
  391. stdout # the output comes on stdout
  392. end
  393. .DE
  394. .DS X
  395. .ta 4n 40n
  396. Example of a backend, in this case the EM assembler/loader.
  397. var w=2 # wordsize 2
  398. var p=2 # pointersize 2
  399. var s=2 # short size 2
  400. var l=4 # long size 4
  401. var f=4 # float size 4
  402. var d=8 # double size 8
  403. var M=em22
  404. var NAME=em22 # for cpp (NAME=em22 results in #define em22 1)
  405. var LIB=lib/{M}/tail_ # part of file name for libraries
  406. var RT=lib/{M}/head_ # part of file name for run-time startoff
  407. var SIZE_FLAG=\-sm # default internal table size flag
  408. var INCLUDES=\-I{EM}/include # use {EM}/include for #include files
  409. name asld # Assembler/loader
  410. from .k.m.a # accepts compact code and archives
  411. to e.out # output file name
  412. program {EM}/lib/em_ass # load file pathname
  413. mapflag \-l* LNAME={EM}/{LIB}* # e.g. \-ly becomes
  414. # {EM}/mach/int/lib/tail_y
  415. mapflag \-+* ASS_F={ASS_F?} \-+* # recognize \-+ and \-\-
  416. mapflag \-\-* ASS_F={ASS_F?} \-\-*
  417. mapflag \-s* SIZE_FLAG=\-s* # overwrite old value of SIZE_FLAG
  418. args {SIZE_FLAG} \e
  419. ({RTS}:.c={EM}/{RT}cc) ({RTS}:.p={EM}/{RT}pc) \-o > < \e
  420. (.p:{TAIL}={EM}/{LIB}pc) \e
  421. (.c:{TAIL}={EM}/{LIB}cc.1s {EM}/{LIB}cc.2g) \e
  422. (.c.p:{TAIL}={EM}/{LIB}mon)
  423. # \-s[sml] must be first argument
  424. # the next line contains the choice for head_cc or head_pc
  425. # and the specification of in- and output.
  426. # the last three args lines choose libraries
  427. linker
  428. end
  429. .DE
  430. The command \fIack \-mem22 \-v \-v \-I../h \-L \-ly prog.c\fP
  431. would result in the following
  432. calls (with exec(II)):
  433. .DS X
  434. .ta 4n
  435. 1) /lib/cpp \-I../h \-I/usr/em/include \-Dem22 \-DEM_WSIZE=2 \-DEM_PSIZE=2 \e
  436. \-DEM_SSIZE=2 \-DEM_LSIZE=4 \-DEM_FSIZE=4 \-DEM_DSIZE=8 prog.c
  437. 2) /usr/em/lib/em_cem \-Vw2i2p2f4s2l4d8 \-l
  438. 3) /usr/em/lib/em_ass \-sm /usr/em/lib/em22/head_cc \-o e.out prog.k
  439. /usr/em/lib/em22/tail_y /usr/em/lib/em22/tail_cc.1s
  440. /usr/em/lib/em22/tail_cc.2g /usr/em/lib/em22/tail_mon
  441. .DE