ack.doc 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420
  1. .\" $Header$
  2. .nr LL 7.5i
  3. .tr ~
  4. .nr PD 1v
  5. .TL
  6. Ack Description File
  7. .br
  8. Reference Manual
  9. .AU
  10. Ed Keizer
  11. .AI
  12. Wiskundig Seminarium
  13. Vrije Universiteit
  14. Amsterdam
  15. .NH
  16. Introduction
  17. .PP
  18. The program \fIack\fP(I) internally maintains a table of
  19. possible transformations and a table of string variables.
  20. The transformation table contains one entry for each possible
  21. transformation of a file.
  22. Which transformations are used depends on the suffix of the
  23. source file.
  24. Each transformation table entry tells which input suffixes are
  25. allowed and what suffix/name the output file has.
  26. When the output file does not already satisfy the request of the
  27. user, with the flag \fB-c.suffix\fP, the table is scanned
  28. starting with the next transformation in the table for another
  29. transformation that has as input suffix the output suffix of
  30. the previous transformation.
  31. A few special transformations are recognized, among them is the
  32. combiner.
  33. A program combining several files into one.
  34. When no stop suffix was specified (flag \fB-c.suffix\fP) \fIack\fP
  35. stops after executing the combiner with as arguments the -
  36. possibly transformed - input files and libraries.
  37. \fIAck\fP will only perform the transformations in the order in
  38. which they are presented in the table.
  39. .LP
  40. The string variables are used while creating the argument list
  41. and program call name for
  42. a particular transformation.
  43. .NH
  44. Which descriptions are used
  45. .PP
  46. \fIAck\fP always uses two description files: one to define the
  47. front-end transformations and one for the machine dependent
  48. back-end transformations.
  49. Each description has a name.
  50. First the way of determining
  51. the name of the descriptions needed is described.
  52. .PP
  53. When the shell environment variable ACKFE is set \fIack\fP uses
  54. that to determine the front-end table name, otherwise it uses
  55. \fBfe\fP.
  56. .PP
  57. The way the backend table name is determined is more
  58. convoluted.
  59. .br
  60. First, when the last filename in the program call name is not
  61. one of \fIack\fP, \fIcc\fP, \fIacc\fP, \fIpc\fP or \fIapc\fP,
  62. this filename is used as the backend description name.
  63. Second, when the \fB-m\fP is present the \fB-m\fP is chopped of this
  64. flag and the rest is used as the backend description name.
  65. Third, when both failed the shell environment variable ACKM is
  66. used.
  67. Last, when also ACKM was not present the default backend is
  68. used, determined by the definition of ACKM in h/local.h.
  69. The presence and value of the definition of ACKM is
  70. determined at compile time of \fIack\fP.
  71. .PP
  72. Now, we have the names, but that is only the first step.
  73. \fIAck\fP stores a few descriptions at compile time.
  74. This descriptions are simply files read in at compile time.
  75. At the moment of writing this document, the descriptions
  76. included are: pdp, fe, i86, m68k2, vax2 and int.
  77. The name of a description is first searched for internally,
  78. then in the directory lib/ack 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. .LP
  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\fB 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, those with the \fBP\fP property
  209. after the \fIprop\fP keyword, do not need the \fIfrom\fP
  210. keyword. All other transformations do.
  211. .nr PD 0
  212. .IP \fIto\fP
  213. .br
  214. followed by the suffix of the output file name or in the case of a
  215. linker -~indicated by C option after the \fIprop\fP keyword~-
  216. the output file name.
  217. .IP \fIprogram\fP
  218. .br
  219. followed by name of the load file of the program, a pathname most likely
  220. starts with either a / or {EM}.
  221. This keyword must be
  222. present, the remainder of the line
  223. is subject to backslashing and variable replacement.
  224. .IP \fImapflag\fP
  225. .br
  226. The mapflags are used to grab flags given to \fIack\fP and
  227. pass them on to a specific transformation.
  228. This feature uses a few simple pattern matching and replacement
  229. facilities.
  230. Multiple occurences of this keyword are allowed.
  231. This text following the keyword is
  232. subjected to backslashing.
  233. The keyword is followed by a match expression and a variable
  234. assignment separated by blank space.
  235. As soon as both description files are read, \fIack\fP looks
  236. at all transformations in these files to find a match for the
  237. flags given to \fIack\fP.
  238. The flags \fB-m\fP, \fB-o\fP,
  239. \fI-O\fP, \fB-r\fP, \fB-v\fP, \fB-g\fP, -\fB-c\fP, \fB-t\fP,
  240. \fB-k\fP, \fB-R\fP and -\f-.\fP are specific to \fIack\fP and
  241. not handed down to any transformation.
  242. The matching is performed in the order in which the entries
  243. appear in the definition.
  244. The scanning stops after first match is found.
  245. When a match is found, the variable assignment is executed.
  246. A * in the match expression matches any sequence of characters,
  247. a * in the right hand part of the assignment is
  248. replaced by the characters matched by
  249. the * in the expression.
  250. The right hand part is also subject to variable replacement.
  251. The variable will probably be used in the program arguments.
  252. The \fB-l\fP flags are special,
  253. the order in which they are presented to \fIack\fP must be
  254. preserved.
  255. The identifier LNAME is used in conjunction with the scanning of
  256. \fB-l\fP flags.
  257. The value assigned to LNAME is used to replace the flag.
  258. The example further on shows the use all this.
  259. .IP \fIargs\fP
  260. .br
  261. The keyword is followed by the program call arguments.
  262. It is subject to backslashing, variable replacement, expression
  263. replacement, line splitting and IO replacement.
  264. The variables assigned to by \fImapflags\P will probably be
  265. used here.
  266. The flags not recognized by \fIack\fP or any of the transformations
  267. are passed to the linker and inserted before all other arguments.
  268. .IP \fIprop\fB
  269. .br
  270. This -~optional~- keyword is followed by a sequence of options,
  271. each option is indicated by one character
  272. signifying a special property of the transformation.
  273. The possible options are:
  274. .DS X
  275. < the input file will be read from standard input
  276. > the output file will be written on standard output
  277. p the input files must be preprocessed
  278. m the input files must be preprocessed when starting with #
  279. O this transformation is an optimizer and may be skipped
  280. P this transformation is the preprocessor
  281. C this transformation is the linker
  282. .DE
  283. .IP \fIrts\fP
  284. .br
  285. This -~optional~- keyword indicates that the rest of the line must be
  286. used to set the variable RTS, if it was not already set.
  287. Thus the variable RTS is set by the first transformation
  288. executed which such a property or as a result from \fIack\fP's program
  289. call name (acc, cc, apc or pc) or by the \fB-.suffix\fP flag.
  290. .IP \fIneed\fP
  291. .br
  292. This -~optional~- keyword indicates that the rest of the line must be
  293. concatenated to the NEEDS variable.
  294. This is done once for every transformation used or indicated
  295. by one of the program call names mentioned above or indicated
  296. by the \fB-.suffix\fP flag.
  297. .br
  298. .nr PD 1v
  299. .NH
  300. Conventions used in description files
  301. .PP
  302. \fIAck\fP reads two description files.
  303. A few of the variables defined in the machine specific file
  304. are used by the descriptions of the front-ends.
  305. Other variables, set by \fack\fB, are of use to all
  306. transformations.
  307. .PP
  308. \fIAck\fP sets the variable EM to the home directory of the
  309. Amsterdam Compiler Kit.
  310. The variable SOURCE is set to the name of the argument that is currently
  311. being massaged, this is usefull for debugging.
  312. .br
  313. The variable M indicates the
  314. directory in mach/{M}/lib/tail_..... and NAME is the string to
  315. be defined by the preprocessor with -D{NAME}.
  316. The definitions of {w}, {s}, {l}, {d}, {f} and {p} indicate
  317. EM_WSIZE, EM_SSIZE, EM_LSIZE, EM_DSIZE, EM_FSIZE and EM_PSIZE
  318. respectively.
  319. .br
  320. The variable INCLUDES is used as the last argument to \fIcpp\fP,
  321. it is currently used to add the directory {EM}/include to
  322. the list of directories containing #include files.
  323. {EM}/include contains a few files used by the library routines
  324. for part III from the
  325. .UX
  326. manual.
  327. These routines are included in the kit.
  328. .PP
  329. The variables HEAD, TAIL and RTS are set by \fIack\fP and used
  330. to compose the arguments for the linker.
  331. .NH
  332. Example
  333. .sp 1
  334. description for front-end
  335. .DS X
  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} \
  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. Example of a backend, in this case the EM assembler/loader.
  374. var w=2 # wordsize 2
  375. var p=2 # pointersize 2
  376. var s=2 # short size 2
  377. var l=4 # long size 4
  378. var f=4 # float size 4
  379. var d=8 # double size 8
  380. var M=int # Unused in this example
  381. var NAME=int22 # for cpp (NAME=int results in #define int 1)
  382. var LIB=mach/int/lib/tail_ # part of file name for libraries
  383. var RT=mach/int/lib/head_ # part of file name for run-time startoff
  384. var SIZE_FLAG=-sm # default internal table size flag
  385. var INCLUDES=-I{EM}/include # use {EM}/include for #include files
  386. name asld # Assembler/loader
  387. from .k.m.a # accepts compact code and archives
  388. to e.out # output file name
  389. program {EM}/lib/em_ass # load file pathname
  390. mapflag -l* LNAME={EM}/{LIB}* # e.g. -ly becomes
  391. # {EM}/mach/int/lib/tail_y
  392. mapflag -+* ASS_F={ASS_F?} -+* # recognize -+ and --
  393. mapflag --* ASS_F={ASS_F?} --*
  394. mapflag -s* SIZE_FLAG=-s* # overwrite old value of SIZE_FLAG
  395. args {SIZE_FLAG} \
  396. ({RTS}:.c={EM}/{RT}cc) ({RTS}:.p={EM}/{RT}pc) -o > < \
  397. (.p:{TAIL}={EM}/{LIB}pc) \
  398. (.c:{TAIL}={EM}/{LIB}cc.1s {EM}/{LIB}cc.2g) \
  399. (.c.p:{TAIL}={EM}/{LIB}mon)
  400. # -s[sml] must be first argument
  401. # the next line contains the choice for head_cc or head_pc
  402. # and the specification of in- and output.
  403. # the last three args lines choose libraries
  404. prop C # This is the final stage
  405. end
  406. .DE
  407. The command "ack -mint -v -v -I../h -L -ly prog.c"
  408. would result in the following
  409. calls (with exec(II)):
  410. .DS X
  411. 1) /lib/cpp -I../h -I/usr/em/include -Dint22 -DEM_WSIZE=2 -DEM_PSIZE=2
  412. -DEM_SSIZE=2 -DEM_LSIZE=4 -DEM_FSIZE=4 -DEM_DSIZE=8 prog.c
  413. 2) /usr/em/lib/em_cem -Vw2i2p2f4s2l4d8 -l
  414. 3) /usr/em/lib/em_ass -sm /usr/em/mach/int/lib/head_cc -o e.out prog.k
  415. /usr/em/mach/int/lib/tail_y /usr/em/mach/int/lib/tail_cc.1s
  416. /usr/em/mach/int/lib/tail_cc.2g /usr/em/mach/int/lib/tail_mon
  417. .DE