ack.doc 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422
  1. .\" $Header$
  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, 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.
  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, \fIcc\fP, \fIacc\fP, \fIpc\fP or \fIapc\fP,
  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 the directory lib/ack and finally in the current
  78. directory of the user.
  79. .NH
  80. Using the description file
  81. .PP
  82. Before starting on a narrative of the description file,
  83. the introduction of a few terms is necessary.
  84. All these terms are used to describe the scanning of zero
  85. terminated strings, thereby producing another string or
  86. sequence of strings.
  87. .IP Backslashing 5
  88. .br
  89. All characters preceded by \e are modified to prevent
  90. recognition at further scanning.
  91. This modification is undone before a string is passed to the
  92. outside world as argument or message.
  93. When reading the description files the
  94. sequences \e\e, \e# and \e<newline> have a special meaning.
  95. \e\e translates to a single \e, \e# translates to a single #
  96. that is not
  97. recognized as the start of comment, but can be used in
  98. recognition and finally, \e<newline> translates to nothing at
  99. all, thereby allowing continuation lines.
  100. .nr PD 0
  101. .IP "Variable replacement"
  102. .br
  103. The scan recognizes the sequences {{, {NAME} and {NAME?text}
  104. Where NAME can be any combination if characters excluding ? and
  105. } and text may be anything excluding }.
  106. (~\e} is allowed of course~)
  107. The first sequence produces an unescaped single {.
  108. The second produces the contents of the NAME, definitions are
  109. done by \fIack\fP and in description files.
  110. When the NAME is not defined an error message is produced on
  111. the diagnostic output.
  112. The last sequence produces the contents of NAME if it is
  113. defined and text otherwise.
  114. .PP
  115. .IP "Expression replacement"
  116. .br
  117. Syntax: (\fIsuffix sequence\fP:\fIsuffix sequence\fP=\fItext\fP)
  118. .br
  119. Example: (.c.p.e:.e=tail_em)
  120. .br
  121. If the two suffix sequences have a common member \-~\&.e in this
  122. case~\- the text is produced.
  123. When no common member is present the empty string is produced.
  124. Thus the example given is a constant expression.
  125. Normally, one of the suffix sequences is produced by variable
  126. replacement.
  127. \fIAck\fP sets three variables while performing the diverse
  128. transformations: HEAD, TAIL and RTS.
  129. All three variables depend on the properties \fIrts\fP and
  130. \fIneed\fP from the transformations used.
  131. Whenever a transformation is used for the first time,
  132. the text following the \fIneed\fP is appended to both the HEAD and
  133. TAIL variable.
  134. The value of the variable RTS is determined by the first
  135. transformation used with a \fIrts\fP property.
  136. .IP
  137. Two runtime flags have effect on the value of one or more of
  138. these variables.
  139. The flag \fB\-.suffix\fP has the same effect on these three variables
  140. as if a file with that \fBsuffix\fP was included in the argument list
  141. and had to be translated.
  142. The flag \fB\-r.suffix\fP only has that effect on the TAIL
  143. variable.
  144. The program call names \fIacc\fP and \fIcc\fP have the effect
  145. of an automatic \fB\-.c\fP flag.
  146. \fIApc\fP and \fIpc\fP have the effect of an automatic \fB\-.p\fP flag.
  147. .IP "Line splitting"
  148. .br
  149. The string is transformed into a sequence of strings by replacing
  150. the blank space by string separators (nulls).
  151. .IP "IO replacement"
  152. .br
  153. The > in the string is replaced by the output file name.
  154. The < in the string is replaced by the input file name.
  155. When multiple input files are present the string is duplicated
  156. for each input file name.
  157. .nr PD 1v
  158. .LP
  159. Each description is a sequence of variable definitions followed
  160. by a sequence of transformation definitions.
  161. Variable definitions use a line each, transformations
  162. definitions consist of a sequence of lines.
  163. Empty lines are discarded, as are lines with nothing but
  164. comment.
  165. Comment is started by a # character, and continues to the end
  166. of the line.
  167. Three special two-characters sequences exist: \e#, \e\e and
  168. \e<newline>.
  169. Their effect is described under 'backslashing' above.
  170. Each \- nonempty \- line starts with a keyword, possibly
  171. preceded by blank space.
  172. The keyword can be followed by a further specification.
  173. The two are separated by blank space.
  174. .PP
  175. Variable definitions use the keyword \fIvar\fP and look like this:
  176. .DS X
  177. var NAME=text
  178. .DE
  179. The name can be any identifier, the text may contain any
  180. character.
  181. Blank space before the equal sign is not part of the NAME.
  182. Blank space after the equal is considered as part of the text.
  183. The text is scanned for variable replacement before it is
  184. associated with the variable name.
  185. .br
  186. .sp 2
  187. The start of a transformation definition is indicated by the
  188. keyword \fIname\fP.
  189. The last line of such a definition contains the keyword
  190. \fIend\fP.
  191. The lines in between associate properties to a transformation
  192. and may be presented in any order.
  193. The identifier after the \fIname\fP keyword determines the name
  194. of the transformation.
  195. This name is used for debugging and by the \fB\-R\fP flag.
  196. The keywords are used to specify which input suffices are
  197. recognized by that transformation,
  198. the program to run, the arguments to be handed to that program
  199. and the name or suffix of the resulting output file.
  200. Two keywords are used to indicate which run-time startoffs and
  201. libraries are needed.
  202. The possible keywords are:
  203. .IP \fIfrom\fP
  204. .br
  205. followed by a sequence of suffices.
  206. Each file with one of these suffices is allowed as input file.
  207. Preprocessor transformations, those with the \fBP\fP property
  208. after the \fIprop\fP keyword, 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 \-~indicated by C option after the \fIprop\fP keyword~\-
  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 occurences 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 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 \fIprop\fP
  268. .br
  269. This \-~optional~\- keyword is followed by a sequence of options,
  270. each option is indicated by one character
  271. signifying a special property of the transformation.
  272. The possible options are:
  273. .DS X
  274. < the input file will be read from standard input
  275. > the output file will be written on standard output
  276. p the input files must be preprocessed
  277. m the input files must be preprocessed when starting with #
  278. O this transformation is an optimizer and may be skipped
  279. P this transformation is the preprocessor
  280. C this transformation is the linker
  281. .DE
  282. .IP \fIrts\fP
  283. .br
  284. This \-~optional~\- keyword indicates that the rest of the line must be
  285. used to set the variable RTS, if it was not already set.
  286. Thus the variable RTS is set by the first transformation
  287. executed which such a property or as a result from \fIack\fP's program
  288. call name (acc, cc, apc or pc) or by the \fB\-.suffix\fP flag.
  289. .IP \fIneed\fP
  290. .br
  291. This \-~optional~\- keyword indicates that the rest of the line must be
  292. concatenated to the NEEDS variable.
  293. This is done once for every transformation used or indicated
  294. by one of the program call names mentioned above or indicated
  295. by the \fB\-.suffix\fP flag.
  296. .br
  297. .nr PD 1v
  298. .NH
  299. Conventions used in description files
  300. .PP
  301. \fIAck\fP reads two description files.
  302. A few of the variables defined in the machine specific file
  303. are used by the descriptions of the front-ends.
  304. Other variables, set by \fIack\fP, are of use to all
  305. transformations.
  306. .PP
  307. \fIAck\fP sets the variable EM to the home directory of the
  308. Amsterdam Compiler Kit.
  309. The variable SOURCE is set to the name of the argument that is currently
  310. being massaged, this is usefull for debugging.
  311. .br
  312. The variable M indicates the
  313. directory in mach/{M}/lib/tail_..... and NAME is the string to
  314. be defined by the preprocessor with \-D{NAME}.
  315. The definitions of {w}, {s}, {l}, {d}, {f} and {p} indicate
  316. EM_WSIZE, EM_SSIZE, EM_LSIZE, EM_DSIZE, EM_FSIZE and EM_PSIZE
  317. respectively.
  318. .br
  319. The variable INCLUDES is used as the last argument to \fIcpp\fP,
  320. it is currently used to add the directory {EM}/include to
  321. the list of directories containing #include files.
  322. {EM}/include contains a few files used by the library routines
  323. for part III from the
  324. .UX
  325. manual.
  326. These routines are included in the kit.
  327. .PP
  328. The variables HEAD, TAIL and RTS are set by \fIack\fP and used
  329. to compose the arguments for the linker.
  330. .NH
  331. Example
  332. .PP
  333. Description for front-end
  334. .DS X
  335. .ta 4n 40n
  336. name cpp # the C-preprocessor
  337. # no from, it's governed by the P property
  338. to .i # result files have suffix i
  339. program {EM}/lib/cpp # pathname of loadfile
  340. mapflag \-I* CPP_F={CPP_F?} \-I* # grab \-I.. \-U.. and
  341. mapflag \-U* CPP_F={CPP_F?} \-U* # \-D.. to use as arguments
  342. mapflag \-D* CPP_F={CPP_F?} \-D* # in the variable CPP_F
  343. args {CPP_F?} {INCLUDES?} \-D{NAME} \-DEM_WSIZE={w} \-DEM_PSIZE={p} \e
  344. \-DEM_SSIZE={s} \-DEM_LSIZE={l} \-DEM_FSIZE={f} \-DEM_DSIZE={d} <
  345. # The arguments are: first the \-[IUD]...
  346. # then the include dir's for this machine
  347. # then the NAME and size valeus finally
  348. # followed by the input file name
  349. prop >P # Output on stdout, is preprocessor
  350. end
  351. name cem # the C-compiler proper
  352. from .c # used for files with suffix .c
  353. to .k # produces compact code files
  354. program {EM}/lib/em_cem # pathname of loadfile
  355. mapflag \-p CEM_F={CEM_F?} \-Xp # pass \-p as \-Xp to cem
  356. mapflag \-L CEM_F={CEM_F?} \-l # pass \-L as \-l to cem
  357. args \-Vw{w}i{w}p{p}f{f}s{s}l{l}d{d} {CEM_F?}
  358. # the arguments are the object sizes in
  359. # the \-V... flag and possibly \-l and \-Xp
  360. prop <>p # input on stdin, output on stdout, use cpp
  361. rts .c # use the C run-time system
  362. need .c # use the C libraries
  363. end
  364. name decode # make human readable files from compact code
  365. from .k.m # accept files with suffix .k or .m
  366. to .e # produce .e files
  367. program {EM}/lib/em_decode # pathname of loadfile
  368. args < # the input file name is the only argument
  369. prop > # the output comes on stdout
  370. end
  371. .DE
  372. .DS X
  373. .ta 4n 40n
  374. Example of a backend, in this case the EM assembler/loader.
  375. var w=2 # wordsize 2
  376. var p=2 # pointersize 2
  377. var s=2 # short size 2
  378. var l=4 # long size 4
  379. var f=4 # float size 4
  380. var d=8 # double size 8
  381. var M=int # Unused in this example
  382. var NAME=int22 # for cpp (NAME=int results in #define int 1)
  383. var LIB=mach/int/lib/tail_ # part of file name for libraries
  384. var RT=mach/int/lib/head_ # part of file name for run-time startoff
  385. var SIZE_FLAG=\-sm # default internal table size flag
  386. var INCLUDES=\-I{EM}/include # use {EM}/include for #include files
  387. name asld # Assembler/loader
  388. from .k.m.a # accepts compact code and archives
  389. to e.out # output file name
  390. program {EM}/lib/em_ass # load file pathname
  391. mapflag \-l* LNAME={EM}/{LIB}* # e.g. \-ly becomes
  392. # {EM}/mach/int/lib/tail_y
  393. mapflag \-+* ASS_F={ASS_F?} \-+* # recognize \-+ and \-\-
  394. mapflag \-\-* ASS_F={ASS_F?} \-\-*
  395. mapflag \-s* SIZE_FLAG=\-s* # overwrite old value of SIZE_FLAG
  396. args {SIZE_FLAG} \e
  397. ({RTS}:.c={EM}/{RT}cc) ({RTS}:.p={EM}/{RT}pc) \-o > < \e
  398. (.p:{TAIL}={EM}/{LIB}pc) \e
  399. (.c:{TAIL}={EM}/{LIB}cc.1s {EM}/{LIB}cc.2g) \e
  400. (.c.p:{TAIL}={EM}/{LIB}mon)
  401. # \-s[sml] must be first argument
  402. # the next line contains the choice for head_cc or head_pc
  403. # and the specification of in- and output.
  404. # the last three args lines choose libraries
  405. prop C # This is the final stage
  406. end
  407. .DE
  408. The command \fIack \-mint \-v \-v \-I../h \-L \-ly prog.c\fP
  409. would result in the following
  410. calls (with exec(II)):
  411. .DS X
  412. .ta 4n
  413. 1) /lib/cpp \-I../h \-I/usr/em/include \-Dint22 \-DEM_WSIZE=2 \-DEM_PSIZE=2 \e
  414. \-DEM_SSIZE=2 \-DEM_LSIZE=4 \-DEM_FSIZE=4 \-DEM_DSIZE=8 prog.c
  415. 2) /usr/em/lib/em_cem \-Vw2i2p2f4s2l4d8 \-l
  416. 3) /usr/em/lib/em_ass \-sm /usr/em/mach/int/lib/head_cc \-o e.out prog.k
  417. /usr/em/mach/int/lib/tail_y /usr/em/mach/int/lib/tail_cc.1s
  418. /usr/em/mach/int/lib/tail_cc.2g /usr/em/mach/int/lib/tail_mon
  419. .DE