install.doc 36 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218
  1. .\" $Header$
  2. .if n .nr PD 1v
  3. .if n .nr LL 78m
  4. .if n .ll 78m
  5. .TL
  6. Amsterdam Compiler Kit Installation Guide
  7. .AU
  8. Ed Keizer
  9. (revised for 3rd and 4th distribution by Ceriel Jacobs)
  10. .AI
  11. Vakgroep Informatica
  12. Vrije Universiteit
  13. Amsterdam
  14. .NH
  15. Introduction
  16. .PP
  17. This document
  18. describes the process of installing Amsterdam Compiler Kit.
  19. It depends on your combination of hard- and software how
  20. hard it will be to install the Kit.
  21. This description is intended for a VAX running BSD 4.1
  22. .UX
  23. \.
  24. Installation on VAX BSD4.2/4.3 systems,
  25. Sun-2 or Sun-3 systems running Release 3.0 or newer, and some System V systems
  26. should be easy.
  27. Installation on PDP 11's running
  28. .UX
  29. Version 7, BSD 2.8, or 2.9
  30. should also be easy, as long
  31. as they have separate instruction and data space.
  32. Installation on machine's without this feature, like PDP 11/34,
  33. PDP 11/60 requires extensive surgery on some programs and is
  34. thought of as impossible.
  35. See section 7 for installation on other systems.
  36. .PP
  37. On small machines, like the PDP-11, the Modula-2 front-end is only available
  38. for 2 byte integer, 2 byte pointer machines, so you can not cross-compile
  39. Modula-2 programs for f.i. a MC68000, on a PDP-11.
  40. .NH
  41. Restoring tree
  42. .PP
  43. The process of installing Amsterdam Compiler Kit is quite simple.
  44. It is important that the original Amsterdam Compiler Kit
  45. distribution tree structure is restored.
  46. Proceed as follows
  47. .IP " \-" 10
  48. Create a directory, for example /usr/em, on a device
  49. with at least 25 Megabytes left.
  50. .IP " \-"
  51. Change to that directory (cd ...); it will be the working directory.
  52. .IP " \-"
  53. Extract all files from the distribution medium, for instance
  54. magtape:
  55. \fBtar x\fP.
  56. .IP " \-"
  57. Keep a copy of the original distribution to be able to repeat the process
  58. of installation in case of disasters.
  59. This copy is also useful as a reference point for diff-listings.
  60. .LP
  61. .bp
  62. The directories in the tree contain the following information:
  63. .sp 1
  64. .nr PD 0
  65. .IP "bin" 14
  66. .br
  67. the few utilities that knot things together.
  68. See the section about "Commands".
  69. .IP "lib"
  70. .br
  71. root of a tree containing almost all binaries and libraries used by
  72. commands.
  73. All files specific to a certain machine are collected in one subtree
  74. per machine. E.g. "lib/pdp", "lib/z8000".
  75. The names used here are the same names as used for subtrees
  76. of "mach".
  77. .IP "lib/descr"
  78. .br
  79. Command descriptor files used by the program ack.
  80. .IP "lib/LLgen"
  81. .br
  82. Files used by the LL(1) Parser-generator.
  83. .br
  84. .IP "lib/ego"
  85. .br
  86. Files used by the global optimizer.
  87. .br
  88. .IP "etc"
  89. .br
  90. The main description of EM sits here.
  91. Files (e.g. em_table) describing
  92. the opcodes and pseudos in use,
  93. the operands allowed, effect in stack etc. etc.
  94. Make in this directory creates most of the files in "h"
  95. and "util/data".
  96. This make should only be called when the EM definition is
  97. changed.
  98. .IP "include/_tail_cc"
  99. .br
  100. Include files needed by modules
  101. in the C library from lang/cem/libcc.
  102. Especially needed for "stdio".
  103. .IP "include/_tail_mon"
  104. .br
  105. More or less system independent include files needed by modules
  106. in the library lang/cem/libcc/mon.
  107. .IP "h"
  108. .br
  109. The #include files for:
  110. .TS
  111. l l.
  112. arch.h Definition of the ACK archive format.
  113. as_spec.h Used by EM assembler and interpreters.
  114. bc_io.h Used by the Basic run-time system.
  115. bc_string.h Used by the Basic run-time system.
  116. cg_pattern.h Used by the backend program "cg" and its bootstrap.
  117. cgg_cg.h Used by the backend program "ncg" and its bootstrap.
  118. em_abs.h Contains trap numbers and address for lin and fil
  119. em_flag.h Definition of bits in array em_flag in lib/em_data.a
  120. Describes parameters effect on flow of instructions
  121. em_mes.h Definition of names for mes pseudo numbers
  122. em_mnem.h instruction => compact mapping.
  123. em_path.h Pathnames used by \fIack\fP, intended
  124. for all utilities
  125. em_pseu.h pseudo instruction => compact mapping
  126. em_ptyp.h Useful for compact code reading/writing,
  127. defines classes of parameters
  128. em_reg.h Definition of mnemonics indicating register type.
  129. em_spec.h Definition of constants used in compact code
  130. local.h Various definitions for local versions
  131. pc_err.h Definitions of error numbers in Pascal
  132. pc_file.h Macro's used in file handling in Pascal
  133. pc_size.h Sizes of objects used by Pascal compiler and
  134. run-time system.
  135. em_reg.h Definition of names for register types.
  136. ocm_chan.h Used by the occam run-time system
  137. ocm_parco.h Used by the occam run-time system
  138. ocm_proc.h Used by the occam run-time system
  139. m2_traps.h Used by the Modula-2 run-time system
  140. .TE
  141. .IP "modules"
  142. .br
  143. root of a tree containing modules for compiler writers.
  144. .IP "modules/man"
  145. .br
  146. manual pages for all modules.
  147. .IP "modules/lib"
  148. .br
  149. contains module objects.
  150. .IP "modules/src"
  151. .br
  152. contains sources of the modules, each module in its own directory.
  153. .IP "modules/h"
  154. .br
  155. include files for some of the modules.
  156. .IP "modules/pkg"
  157. .br
  158. include files for some of the modules.
  159. .IP "doc"
  160. .br
  161. This directory contains the unformatted documents for the Kit.
  162. A list of the available documents can be found in the last section.
  163. .IP "doc/em"
  164. .br
  165. The EM-manual IR-81.
  166. .IP "doc/em/int"
  167. .br
  168. The EM interpreter written in Pascal.
  169. .IP "mkun"
  170. .br
  171. The PUBMAC macro package for nroff/troff from the Katholieke Universiteit at
  172. Nijmegen.
  173. It is used for the EM reference manual.
  174. The Makefile installs the macro package in
  175. /usr/lib/tmac.
  176. This package is in the public domain.
  177. .IP "mach"
  178. .br
  179. just there to group the directories with all sources for each machine.
  180. The section about "Machines" of this manual indicates which subdirectories
  181. are used for which systems.
  182. .br
  183. These directories have subdirectories named:
  184. .in +3n
  185. .TS
  186. l l.
  187. cg the backend (*.m => *.s)
  188. ncg the new backend (*.m => *.s)
  189. as the assembler (*.s => *.o) or
  190. assembler/linker (*.s + libraries => a.out)
  191. cv Conversion programs for a.out files.
  192. dl Down-load programs
  193. top the target optimizer
  194. libem Sources for EM runtime system, only depending on CPU type
  195. libbc Used to create Basic run-time system and libraries
  196. libcc Used to create C run-time system and libraries
  197. libpc Used to create Pascal run-time system and libraries
  198. liboc Used to create Occam run-time system and libraries
  199. libm2 Used to create Modula-2 run-time system and libraries
  200. libfp Used to create floating point library
  201. libsys Sources for system-dependent EM library
  202. test Various tests
  203. int Source for an interpreter
  204. .TE
  205. .in -3n
  206. The directory proto contains files used by most machines,
  207. like machine-independent sources and Makefiles.
  208. .in +3n
  209. .TS
  210. l l.
  211. mach/proto/cg Current backend sources.
  212. mach/proto/ncg New backend sources.
  213. mach/proto/as Assembler sources.
  214. mach/proto/top Target optimizer sources.
  215. mach/proto/fp FLoating point package sources.
  216. mach/proto/libg Makefile for compiling libraries.
  217. .TE
  218. .IP "emtest"
  219. .br
  220. Contains prototype of em test set.
  221. .IP "man"
  222. .br
  223. Man files for various utilities
  224. .IP "lang"
  225. .br
  226. Just there to group the directories for all front-ends
  227. .IP "lang/pc"
  228. .br
  229. Pascal front-end
  230. .IP "lang/pc/libpc"
  231. .br
  232. Source of Pascal run-time system (in EM or C)
  233. .IP "lang/pc/test"
  234. .br
  235. Some test programs written in Pascal
  236. .IP "lang/pc/pem"
  237. .br
  238. The Pascal compiler proper
  239. .IP "lang/cem"
  240. .br
  241. C front-end
  242. .IP "lang/cem/libcc"
  243. .br
  244. Directories with sources of C runtime system, libraries (in EM or C)
  245. .IP "lang/cem/libcc/gen"
  246. .br
  247. Sources for routines in chapter III of UNIX programmers manual,
  248. excluding Stdio
  249. .IP "lang/cem/libcc/stdio"
  250. .br
  251. Stdio sources
  252. .IP "lang/cem/libcc/mon"
  253. .br
  254. Sources for routines in chapter II, written in EM
  255. .IP "lang/cem/cemcom"
  256. .br
  257. The compiler proper
  258. .IP "lang/cem/ctest"
  259. .br
  260. C test set
  261. .IP "lang/cem/ctest/cterr"
  262. .br
  263. Programs developed for pinpointing previous errors
  264. .IP "lang/cem/ctest/ct*"
  265. .br
  266. The test programs.
  267. .IP "lang/basic/src"
  268. .br
  269. The compiler proper.
  270. .IP "lang/basic/lib"
  271. .br
  272. Basic run-time library source.
  273. .IP "lang/basic/test"
  274. .br
  275. Various Basic programs.
  276. .IP "lang/occam"
  277. .br
  278. Occam front-end.
  279. .IP "lang/occam/comp"
  280. .br
  281. The compiler proper.
  282. .IP "lang/occam/lib"
  283. .br
  284. Source of Occam run-time system (in EM or C).
  285. .IP "lang/occam/test"
  286. .br
  287. Some Occam programs.
  288. .IP "lang/m2"
  289. .br
  290. Modual-2 front-end.
  291. .IP "lang/m2/comp"
  292. .br
  293. The compiler proper.
  294. .IP "lang/m2/libm2"
  295. .br
  296. Source of Modula-2 run-time system (in EM, C and Modula-2).
  297. .IP "lang/m2/m2mm"
  298. .br
  299. Modula-2 makefile generator.
  300. .IP "lang/m2/test"
  301. .br
  302. Some Modula-2 example programs.
  303. .IP "util"
  304. .br
  305. Contains directories with sources for various utilities
  306. .IP "util/ack"
  307. .br
  308. The program used for translation with the Kit.
  309. .IP "util/opt"
  310. .br
  311. EM peephole optimizer (*.k => *.m).
  312. .IP "util/ego"
  313. .br
  314. The global optimizer.
  315. .IP "util/topgen"
  316. .br
  317. The target optimizer generator..
  318. .IP "util/misc"
  319. .br
  320. Decode (*.[km] => *.e) + encode (*.e => *.k).
  321. .IP "util/data"
  322. .br
  323. The C-code for `lib/em_data.a`.
  324. These sources are created by the Makefile in `etc`.
  325. .IP "util/ass"
  326. .br
  327. The EM assembler (*.[km] + libraries => e.out).
  328. .IP "util/arch"
  329. .br
  330. The archivers to be used for ALL EM utilities.
  331. .IP "util/cgg"
  332. .br
  333. A program needed for compiling backends.
  334. .IP "util/ncgg"
  335. .br
  336. A program needed for compiling the newest backends.
  337. .IP "util/cpp"
  338. .br
  339. The C preprocessor.
  340. .IP "util/shf"
  341. .br
  342. Various shell files.
  343. .IP "util/LLgen"
  344. .br
  345. The extended LL(1) parser generator.
  346. .IP "util/amisc"
  347. .br
  348. Contains some programs handling ACK a.out format, such as anm, asize.
  349. .IP "util/cmisc"
  350. .br
  351. Contains some programs to help in resolving name conflicts, and
  352. a dependency generator for makefiles.
  353. .IP "util/led"
  354. .br
  355. The ACK link-editor, reading ACK relocatable a.out format, and writing
  356. ACK a.out format.
  357. .ne 4
  358. .LP
  359. All pathnames mentioned in the text of this document are relative to the
  360. ACK home directory, unless they start with '/'.
  361. .sp 1
  362. .NH
  363. Adapting ACK to your system
  364. .PP
  365. Before compiling the sources in the Kit some installation dependent
  366. actions have to be taken.
  367. Most of these are performed by an interactive shell script in the file
  368. .I first
  369. in a directory of the same name.
  370. .LP
  371. These actions are:
  372. .sp 1
  373. .IP \-
  374. Automatically checking whether you included the ACK bin directory in your
  375. shell PATH.
  376. See also the section on "commands".
  377. .IP \-
  378. Automatically setting the pathname of the parent directory in ../h/em_path.h.
  379. See also the section on "pathnames".
  380. .IP \-
  381. Discovering how to call
  382. .I cc
  383. to get it to include the
  384. .I lex
  385. library.
  386. .IP \-
  387. Asking you for the type of system you have
  388. and creating the shell script "ack_sys" in the Kit's bin directory.
  389. Several utilities make use of "ack_sys" to determine the type of
  390. system you have.
  391. The current choice is between:
  392. .sp 1
  393. .TS
  394. c c c
  395. l l l.
  396. answer system type default machine
  397. pdp_v7 PDP11 with sep I/D and version 7 pdp
  398. vax_bsd4_1a VAX11 with BSD4.1a vax4
  399. vax_bsd4_2 VAX11 with BSD4.2 vax4
  400. vax_sysV_2 VAX11 with System V.2 vax4
  401. pc_ix IBM PC with PC/IX i86
  402. xenix3 IBM AT with Microsoft Xenix V3.2 xenix3
  403. m68_unisoft Motorola 68000 with Unisoft UNIX m68k2
  404. m68_pmds Philips PMDS pmds
  405. m68_sysV_0 68000 with Uniplus UNIX System V.0 mantra
  406. sun3 Sun 3 Motorola 68020 workstation sun3
  407. sun2 Sun 2 Motorola 68010 workstation sun2
  408. ANY Neither of the above m68k2
  409. .TE
  410. .sp 1
  411. For some of these, the installation procedure has not been tested, as
  412. we don't have them.
  413. For others, the installation procedure has only been tested with earlier
  414. distributions, as we don't have those systems anymore.
  415. However,
  416. the pdp_v7, vax_bsd4_1a, sun3 and m68 systems are known to behave
  417. reasonably.
  418. The Sun systems should run Release 3.0 or newer.
  419. For ANY you can use any name you fancy,
  420. but the Kit will not be able to compile programs for your system.
  421. If you want to do that you have to read the section about "compilation
  422. on a different machine".
  423. .IP \-
  424. Automatically setting the default machine for which code is
  425. produced to your own type of system according to the table above.
  426. This in done in the file "h/local.h".
  427. See also the section 8.2.
  428. .IP \-
  429. Automatically editing a few description files that tell
  430. ACK to use your system's assembler.
  431. On the VAX the Kit uses the native assembler and linker.
  432. The description file lib/vax4/descr has to be altered to prevent
  433. attempts to assemble programs with unsuitable assemblers.
  434. The original descr file is copied to descr.orig.
  435. .IP \-
  436. The VAX backend cannot be booted on systems
  437. with a 16-bit address space systems.
  438. The program lib/cgg needs more memory than available to transform
  439. the table into files suitable for the C-compiler.
  440. Therefore files tables1.h and tables1.c have been provided in
  441. the directory mach/vax4/cg.
  442. These must be copied to tables.h and tables.c
  443. to get working code-generators for the VAX on PDP11's.
  444. You will hardly be able to use these, because the
  445. code generated by these programs cannot be
  446. assembled and loaded without a native VAX assembler,
  447. but its nice to be able to look at the code produced.
  448. The same problem occurs for the m68k2 backend and the m68020 backend,
  449. and the same solution is chosen.
  450. .IP \-
  451. On machines with a 16-bit address space, the C-compiler has no
  452. builtin preprocessor. Arangements are made to this effect.
  453. .IP \-
  454. On the PDP,
  455. .I ranlib
  456. is not used, because it does not work properly,
  457. at least, on our 2.9 BSD system it does'nt.
  458. This is done by creating a dummy shell script
  459. .I ranlib
  460. in the ACK bin directory.
  461. If you are sure that your
  462. .I ranlib
  463. does work properly, you can just remove the shell script before
  464. installing the Kit.
  465. .LP
  466. .sp 1
  467. Some actions still have to be done by hand.
  468. .sp 1
  469. .IP \-
  470. The installation of the PUBMAC macro package is not done
  471. automatically because you need super-user privileges to do
  472. that on most systems.
  473. This macro package is used with several of the documents
  474. provided in the Kit.
  475. .IP \-
  476. UNIX V7 as originally distributed contains a few bugs that
  477. prevent correct execution of some of the larger programs.
  478. See the section named "Fixes for the UNIX V7 system"
  479. about what to do.
  480. Berkeley 2.8 or 2.9 may also have some of these bugs.
  481. .IP \-
  482. The manual files for the Kit can be copied to their
  483. appropriate place in the system by giving the command "make install"
  484. in the man directory, but only
  485. .B after
  486. running the installation of the
  487. Kit itself.
  488. .NH
  489. Compiling the Kit
  490. .PP
  491. The next step in the installation process is to compile
  492. the sources in the Kit and install them in their places
  493. in the lib and bin directories.
  494. .PP
  495. Most directories containing sources have Makefiles
  496. used to compile and install the programs in that
  497. directory.
  498. All programs needed for compilation and/or cross compilation
  499. with the Kit are installed in the directories "bin" and "lib"
  500. by these Makefiles.
  501. These Makefiles adhere to a standard which is described in the
  502. section 9.
  503. .LP
  504. You do not have to start all these Makefiles separately.
  505. We wrote a shell script calling the make's needed to install
  506. the whole Kit.
  507. This script consists of the file TakeAction in the Kit's root
  508. directory and a few files called Action in some directories.
  509. The Action files describe in a very simple form which actions
  510. have to be performed in which directories.
  511. The default action is to start "make install && make clean".
  512. The output of each make is diverted to a file called "Out"
  513. in the same directory as the make was started in.
  514. If the make was successful (return code 0) the Out file is removed
  515. and the script TakeAction produces a small message telling you
  516. that it succeeded in fulfilling its goal.
  517. If the make was not successful (any other return code) the Out file
  518. is left alone for further examination and a small message telling you
  519. to look at that file is produced by TakeAction.
  520. .LP
  521. For some programs the scripts already know they can't be
  522. installed on your type of system.
  523. In that case they produce a message "Sorry, ....." and
  524. happily proceed with further installation commands.
  525. .PP
  526. Compilation of the whole Kit might take anything from a few
  527. hours to more than a day.
  528. If you do not want to install libraries etc. for a particular
  529. machine you can edit the file Action and remove the relevant entries.
  530. .PP
  531. If this compilation went reasonably successful you should be able
  532. to use the Kit.
  533. Read the next section and the manuals provided
  534. with the Kit (in the man directory) on how to use it.
  535. .NH 2
  536. Problems you may meet
  537. .NH 3
  538. on Unisoft m68000 systems.
  539. .PP
  540. The Unisoft C compiler has a bug which impedes the correct
  541. translation of the peephole optimizer.
  542. For a more detailed description of this phenomenen see
  543. the file "mach/m68k2/Unisoft_bug".
  544. .NH 3
  545. with backends
  546. .PP
  547. The backends for the PDP11, VAX with BSD4.1, Motorola 68000 and
  548. Intel 8086 have been heavily used by ourselves and are well tested.
  549. The backends for the other machines are known to run our own
  550. test programs,
  551. but might reveal errors when more heavily used.
  552. .NH 2
  553. An example output of TakeAction.
  554. .PP
  555. .DS
  556. System definition -- done
  557. EM definition -- done
  558. LL(1) Parser generator -- done
  559. EM definition library -- done
  560. C utilities -- done
  561. system-call interface module -- done
  562. string routines module -- done
  563. formatted print module -- done
  564. assertion module -- done
  565. memory allocation module -- done
  566. fast, linear time malloc -- done
  567. EM messages generation module -- done
  568. identifier table module -- done
  569. input module -- done
  570. ACK-object reading and writing module -- done
  571. EM-code reading module -- done
  572. EM code generation module -- done
  573. Modules -- done
  574. C preprocessor -- done
  575. ACK object utilities -- done
  576. Encode/Decode -- done
  577. Shell files in bin -- done
  578. EM assembler -- done
  579. EM Peephole optimizer -- done
  580. .
  581. .
  582. .
  583. EM Global optimizer -- done
  584. ACK archiver -- done
  585. Program 'ack' -- done
  586. Bootstrap for backend tables -- done
  587. Bootstrap for newest form of backend tables -- done
  588. LED link editor -- done
  589. TOPGEN target optimizer generator -- done
  590. C frontend -- done
  591. Basic frontend -- done
  592. Occam frontend -- done
  593. Intel 8086 assembler -- done
  594. Intel 8086 backend -- done
  595. Intel 8086 C libraries -- done
  596. Intel 8086 EM library -- done
  597. Intel 8086 Pascal library -- done
  598. Intel 8086 PC/IX systemcall library -- done
  599. Intel 8086 Basic library -- done
  600. Intel 8086 Occam library -- done
  601. Intel 8086 conversion program from ack.out --> PC/IX a.out -- done
  602. Intel 8086 support -- done
  603. .
  604. .
  605. .
  606. Motorola 68000 assembler -- done
  607. Motorola 68000 2-4 backend -- done
  608. Motorola 68000 2-4 conversion program -- done
  609. Motorola 68000 target optimizer -- done
  610. Motorola 68000 2-4 C libraries -- done
  611. Motorola 68000 2-4 EM library -- done
  612. Motorola 68000 2-4 Pascal library -- done
  613. Motorola 68000 2-4 System library -- done
  614. Motorola 68000 2-4 Basic library -- done
  615. Motorola 68000 2-4 Occam library -- done
  616. Sorry, Motorola 68000 interpreters can only be made on m68* systems
  617. Motorola 68000 2-4 support -- done
  618. .
  619. .
  620. .
  621. PDP 11 assembler -- done
  622. PDP 11 backend -- done
  623. PDP 11 target optimizer -- done
  624. Sorry, PDP 11 interpreter can only be made on pdp* systems
  625. Sorry, PDP 11 C libraries can only be made on pdp* systems
  626. Sorry, PDP 11 EM library can only be made on pdp* systems
  627. Sorry, PDP 11 systemcall library can only be made on pdp* systems
  628. Sorry, PDP 11 Pascal library can only be made on pdp* systems
  629. Sorry, PDP 11 Basic library can only be made on pdp* systems
  630. Sorry, PDP 11 Occam library can only be made on pdp* systems
  631. PDP 11 support -- done
  632. .
  633. .
  634. .
  635. Vax 4-4 backend -- done
  636. Sorry, Vax 4-4 C libraries can only be made on vax* systems
  637. Sorry, Vax 4-4 EM library can only be made on vax* systems
  638. Sorry, Vax 4-4 Occam library can only be made on vax* systems
  639. Sorry, Vax 4-4 Basic library can only be made on vax* systems
  640. Sorry, Vax 4-4 systemcall interface can only be made on vax* systems
  641. Vax target optimizer -- done
  642. Vax 4-4 support -- done
  643. M68020 assembler -- done
  644. M68020 backend -- done
  645. M68020 EM library -- done
  646. M68020 system call library -- done
  647. M68020 C libraries -- done
  648. M68020 PC library -- done
  649. M68020 Basic library -- done
  650. M68020 Occam library -- done
  651. Sorry, M68020 VME131 System V/68 R2V2.1 conversion can only be made on m68020 systems
  652. M68020 System V/68 support -- done
  653. Ack.out --> Sun 3 M68020 a.out format conversion program -- done
  654. Sun 3 M68020 systemcall library -- done
  655. Sun 3 M68020 C libraries -- done
  656. Sun 3 M68020 support -- done
  657. Ack.out --> Sun 2 M68000 a.out format conversion program -- done
  658. Sun 2 M68000 systemcall library -- done
  659. Sun 2 M68000 C libraries -- done
  660. Sun 2 M68000 support -- done
  661. .
  662. .
  663. .
  664. Failed for Pascal frontend, see lang/pc/pem/Out
  665. .DE
  666. .PP
  667. The lines starting with "Sorry, " tell you that certain programs cannot
  668. be translated on your machine.
  669. The lines starting with "Failed for" tell
  670. you that certain programs/libraries which were expected to,
  671. but did not compile.
  672. Only the Pascal frontend failed to compile in this example.
  673. If you want to repeat a certain part of the installation, look in
  674. the Action file for the directory in which that part is to be found.
  675. If that directory contains an Action file issue the command
  676. "sh EM_DIR/TakeAction", otherwise type "make install".
  677. .NH
  678. Commands
  679. .PP
  680. The following commands are available in the bin directory after compilation
  681. of the Kit:
  682. .sp 1
  683. .IP "\fIack\fP, \fIacc\fP, \fIabc\fP, \fIapc\fP, \fIocm\fP, \fIm2\fP and their links"
  684. .br
  685. The names mentioned here can be used to compile Pascal, C, etc... programs.
  686. Most of the links can be used to generate code for a particular
  687. machine.
  688. See also the section about "Machines".
  689. .IP \fIarch\fP
  690. .br
  691. The archiver used for the EM- and universal assembler/loader.
  692. .IP \fIaal\fP
  693. .br
  694. The archiver used for ACK objects.
  695. .IP \fIem\fP
  696. .br
  697. This program selects a interpreter to execute an e.out file.
  698. Interpreters exist for PDP-11 and Motorola 68000 systems.
  699. .IP \fIeminform\fP
  700. .br
  701. The program to unravel the post-mortem information of
  702. the EM interpretator for the PDP-11.
  703. .IP \fILLgen\fP
  704. .br
  705. The LL(1) parser generator.
  706. .IP \fIack_sys\fP
  707. .br
  708. A shell script producing an identification of your system.
  709. Used by some utilities to determine what is, and what is
  710. not feasible on your system. (Like translating PDP assembly).
  711. .IP \fImarch\fP
  712. .br
  713. A shell script used while compiling libraries.
  714. .IP "\fIasize\fP, \fIanm\fP, \fIastrip\fP"
  715. .br
  716. Do the same as \fIsize\fP, \fInm\fP and \fIstrip\fP, but for ACK object format.
  717. .IP \fImkdep\fP
  718. .br
  719. A dependency generator for makefiles.
  720. .IP "\fIcid\fP, \fIprid\fP, \fIcclash\fP"
  721. .br
  722. Some utilities for handling name clashes in C programs. Some
  723. systems have C-compilers with only 7 or 8 characters significant in
  724. identifiers.
  725. .sp 1
  726. .LP
  727. We currently make the Kit available to our users by telling
  728. them that they should include the bin directory of the Kit in
  729. their PATH shell variable.
  730. The programs will still work when moved to a different
  731. directory or linked to.
  732. Copying should preferably be done with tar, since links are
  733. heavily used.
  734. Renaming of the programs linked to \fIack\fP will not always
  735. produce the desired result.
  736. This program uses its call name as an argument.
  737. Any call name not being \fIcc\fP, \fIacc\fP, \fIabc\fP, \fIpc\fP,
  738. \fIocm\fP, \fIm2\fP, or \fIapc\fP will be
  739. interpreted as the name of a 'machine description' and the
  740. program will try to find a description file with that name.
  741. The installation process will only touch the utilities in the Kit's bin
  742. directory, not your own copies.
  743. .NH
  744. Machines
  745. .PP
  746. Underneath you will find a table with entries for all commands in
  747. the bin directory used to (cross)compile for a particular machine.
  748. The name in the first column give the name in the bin directory.
  749. The column headed dir indicates which subdirectories of
  750. lib are needed for compilation.
  751. The column head i/p contains the integer and pointer size used in units of
  752. bytes.
  753. The subdirectories with the same name in mach contain the sources.
  754. A * in the column headed 'fp' indicates that floating point can be used
  755. for that particular machine. A + in that column indicates that floating
  756. point is only available under the '-fp' option. In this case, software
  757. floating point emulation is used.
  758. .TS
  759. c c c c c c c
  760. l l l l l l l.
  761. command system i/p languages fp dir remarks
  762. pdp PDP/UNIX V7 2/2 C * pdp needs sep. I/D
  763. Pascal No assembler
  764. Basic
  765. Occam
  766. Modula-2
  767. vax4 VAX/BSD 4.? 4/4 C * vax4 No assembler
  768. System V.2 Pascal
  769. Basic
  770. Occam
  771. Modula-2
  772. m68k2 M68000/Unisoft 2/4 C + m68k2
  773. Pascal
  774. Basic
  775. Occam
  776. Modula-2
  777. m68k4 M68000/Unisoft 4/4 C + m68k4
  778. Pascal m68k2
  779. Basic
  780. Occam
  781. Modula-2
  782. pmds M68000/PMDS 2/4 C + pmds Philips Micro
  783. Pascal m68k2 Devel. System
  784. Basic
  785. Occam
  786. Modula-2
  787. pmds4 M68000/PMDS 4/4 C + pmds4 Philips Micro
  788. Pascal m68k2 Devel. System
  789. Basic m68k4
  790. Occam
  791. Modula-2
  792. mantra M68000/SysV.0 4/4 C + mantra
  793. Pascal m68k2
  794. Basic m68k4
  795. Occam
  796. Modula-2
  797. m68020 M68020/V/68 4/4 C + m68020
  798. R2V2.1 Pascal
  799. Basic
  800. Occam
  801. Modula-2
  802. sun3 SUN 3 R3.0 4/4 C + sun3
  803. Pascal m68020
  804. Basic
  805. Occam
  806. Modula-2
  807. sun2 SUN 2 R3.0 4/4 C + sun2
  808. Pascal m68k4
  809. Basic m68k2
  810. Occam
  811. Modula-2
  812. i86 IBM PC/IX 2/2 C + i86 IBM PC with PC/IX
  813. Pascal Causes kernel crashes
  814. Basic
  815. Occam
  816. Modula-2
  817. xenix3 Microsoft Xenix V3 2/2 C + xenix3 IBM AT with Xenix
  818. Pascal i86
  819. Basic
  820. Occam
  821. Modula-2
  822. minix Minix PC 2/2 C + minix IBM PC running Minix
  823. Pascal i86
  824. Basic
  825. Occam
  826. Modula-2
  827. minixST ST Minix 2/4 C + minixST Atari ST running Minix
  828. Pascal m68k2
  829. Basic
  830. Occam
  831. Modula-2
  832. z8000 Zilog 8000 2/2 C z8000 Central Data
  833. Pascal CPU board
  834. Basic Uses assembler/loader
  835. Occam
  836. Modula-2
  837. em22 EM machine 2/2 C * em22 Needs interpreter
  838. Pascal
  839. Basic
  840. Occam
  841. Modula-2
  842. em24 EM machine 2/4 C * em24 Needs interpreter
  843. Pascal
  844. Basic
  845. Occam
  846. Modula-2
  847. em44 EM machine 4/4 C * em44 Needs interpreter
  848. Pascal
  849. Basic
  850. Occam
  851. Modula-2
  852. 6500 6502/BBC 2/2 C 6500 Uses assembler/loader
  853. Pascal
  854. Basic
  855. Occam
  856. Modula-2
  857. 6800 Bare 6800 6800 Assembler only
  858. 6805 Bare 6805 6805 Assembler only
  859. 6809 Bare 6809 6809 Assembler only
  860. ns Bare NS16032 4/4 C ns
  861. Pascal
  862. Basic
  863. Occam
  864. Modula-2
  865. i80 Hermac/z80 2/2 C i80
  866. Pascal
  867. Basic
  868. Occam
  869. Modula-2
  870. z80 Hermac/z80 2/2 C z80 \fIi80\fP is faster
  871. Pascal
  872. Basic
  873. Occam
  874. Modula-2
  875. s2650 Signetics 2650 s2650 Assembler only
  876. .TE
  877. .PP
  878. The commands \fBem22\fP, \fBem24\fP and \fBem44\fP
  879. produce e.out files with EM machine code which must be interpreted.
  880. The Kit contains two interpreters: one running under PDP 11/V7 UNIX,
  881. and one for the M68000, running under the PMDS system, SUN systems,
  882. the Mantra system, etc.
  883. The first one can only interpret 2/2 e.out files,
  884. the other takes 2/4 and 4/4 files.
  885. The PDP 11 interpreter executes floating point instructions.
  886. The interpreter for the M68000 traps if you try to use floating point.
  887. .LP
  888. The program \fBem\fP in the bin directory calls the appropriate
  889. interpreter.
  890. The interpreters are sought in the em22, em24 and em44
  891. subdirectories of lib.
  892. .NH
  893. Compilation on a different machine.
  894. .PP
  895. The Kit be installed and used as a cross-compiler
  896. for C and Basic programs on any UNIX machine.
  897. The presence of most UNIX utilities is essential for compilation.
  898. A few of the programs you certainly need are: C-compiler, Yacc, sed,
  899. make and lex.
  900. Except for the Pascal compiler proper all programs
  901. can be translated on a normal UNIX system, like V7, BSD4.1.
  902. .NH 2
  903. Backend
  904. .PP
  905. The existence of a backend with a system call library
  906. for your system is essential
  907. if you wish to produce executable files for that system.
  908. Rewriting the system call library if the one supplied does
  909. not work on your system is fairly straightforward.
  910. If no backend exists for your CPU type you have to write one yourself
  911. which is a major undertaking.
  912. .NH 2
  913. Pascal
  914. .PP
  915. When you can produce executable code it is also possible to boot the Pascal
  916. Compiler,
  917. which is written in Pascal itself.
  918. The Kit contains the compact code files for the 2/2, 4/4 and 2/4
  919. versions of the Pascal compiler.
  920. The Makefile automatically tries to boot the Pascal compiler
  921. from one of these compact code files, if the compiler proves
  922. unable to compile itself.
  923. .NH 2
  924. Universal assembler/loader, link editor
  925. .PP
  926. The native assemblers and loaders are used on PDP-11 and VAX.
  927. The description files in lib/*/descr for other systems use our
  928. universal assembler and for most machines our link editor.
  929. The load file produced is not directly
  930. usable in any system known to us,
  931. but has to be converted before it can be put to use.
  932. The \fIcv\fP programs convert our a.out format into
  933. executable files.
  934. The \fIdl\fP programs present for some machines unravel
  935. our a.out files and transmit commands to load memory
  936. to a microprocessor over a serial line.
  937. The file man/ack.out.5 contains a description of the format of
  938. the universal assembler load file.
  939. It might be useful to those who wish or need to write their
  940. own conversion programs.
  941. Also, a module is included to read and write our a.out format.
  942. See modules/man/object.3.
  943. .NH 2
  944. Compiling libraries
  945. .PP
  946. The Kit contains sources for part II and III of the C-library.
  947. These files can be used to make libraries for the Ack C-compiler.
  948. The recompilation process uses a few include files.
  949. The include directory in the EM home directory contains the include files
  950. it needs.
  951. An effort has been made to make the part III stuff as system independent as
  952. possible.
  953. .NH
  954. Options
  955. .NH 2
  956. Default machine
  957. .PP
  958. There is one important option in h/local.h.
  959. The utility \fIack\fP uses a default machine name when called
  960. as \fIacc\fP, \fIcc\fP, \fIabc\fP, \fIapc\fP, \fIpc\fP, \fIocm\fP,
  961. \fIm2\fP, or \fIack\fP.
  962. The machine name used for default is determined by the
  963. definition of ACKM in h/local.h.
  964. The Kit is distributed with "vax4" as the default machine,
  965. but the shell script "first" in the directory "first" alters this
  966. to suit your own system.
  967. There is nothing against using the Kit as a cross-compiler
  968. and by default produce code that can't run on your own system.
  969. But...., you have to alter the Makefile for the Pascal frontend
  970. in that case.
  971. That Makefile assumes that calling \fBapc\fP and \fBacc\fP will
  972. produce a.out's that can run on your own system.
  973. Change the definitions of ACC and APC in that Makefile according to your
  974. needs.
  975. .NH 2
  976. Pathnames
  977. .PP
  978. Absolute pathnames are concentrated in "h/em_path.h".
  979. Only the Pascal runtime system and the utilities \fIack\fP and \fILLgen\fP use
  980. absolute pathnames to access files in the Kit.
  981. The tree is distributed with /usr/em as the working
  982. directory.
  983. The definition of EM_DIR in em_path.h should be altered to
  984. specify the root
  985. directory for the Compiler Kit distribution on your system.
  986. This is done automatically the the shell script "first" in the
  987. directory "first".
  988. Em_path.h also specifies which directory should be used for
  989. temporary files.
  990. Most programs from the Kit do indeed use that directory
  991. although some remain stubborn and use /tmp or /usr/tmp.
  992. .LP
  993. The shape of the tree should not be altered lightly because
  994. most Makefiles and the
  995. utility \fIack\fP know the shape of the ACK tree.
  996. All pathnames in all Makefiles are relative, that is do not
  997. have "/" as the first character.
  998. The knowledge of the utility \fIack\fP about the shape of the tree is
  999. concentrated in the files in the directory lib/*/descr and lib/descr/*.
  1000. .NH
  1001. Makefiles
  1002. .PP
  1003. Most directories contain a "Makefile".
  1004. Apart from commands applying to that specific directory these
  1005. files all recognize a few special commands.
  1006. When called with one of these they will apply the command to
  1007. their own directory and all subdirectories.
  1008. The special commands are:
  1009. .sp 1
  1010. .IP "install" 20
  1011. recompile and install all binaries and libraries.
  1012. .br
  1013. Some Makefiles allow errors to occur in the programs they call.
  1014. They ignore such errors and notify the user with the message
  1015. "~....... error code n: ignored".
  1016. Whenever such a message appears in the output you can ignore it
  1017. too.
  1018. .IP "cmp"
  1019. recompile all binaries and libraries and compare them to the
  1020. ones already installed.
  1021. .IP pr
  1022. print the sources and documentation on the standard output.
  1023. .IP opr
  1024. make pr | opr
  1025. .br
  1026. Opr should be an off-line printer daemon.
  1027. On some systems it exists under another name e.g. lpr.
  1028. The easiest way to call such a spooler is using a shell script
  1029. with the name opr that calls lpr.
  1030. This script should be placed in /usr/bin or EM_DIR/bin or
  1031. one of the directories in your PATH.
  1032. .IP clean
  1033. remove all files not needed for day-to-day use,
  1034. that is binaries not in bin or lib, object files etc.
  1035. .LP
  1036. Example:
  1037. .nf
  1038. .sp 1
  1039. make install
  1040. .sp 1
  1041. .fi
  1042. given as command in the home directory will cause
  1043. compilation of all programs in the directory and copying of the results
  1044. to the bin and lib directories.
  1045. .NH
  1046. Fixes for the UNIX V7 system
  1047. .PP
  1048. UNIX System V7 has a few bugs that prevent a part of or the whole Kit
  1049. from working properly. Berkeley 2.8 and/or 2.9 may also suffer from this
  1050. problem.
  1051. To be honest, we do not know which of the following changes are
  1052. essential to the functioning of our Kit. The change to "ld" is.
  1053. .PP
  1054. The file "doc/v7bugs.doc" gives for each of the following bugs
  1055. a small test program and a diff listing of the source files that have to be
  1056. modified.
  1057. .IP 1
  1058. Bug in the C optimizer for unsigned comparison
  1059. .nr PD 0
  1060. .IP 2
  1061. The loader 'ld' fails for large data and text portions
  1062. .IP 3
  1063. Floating point registers are not saved if more memory is needed.
  1064. .IP 4
  1065. Floating point registers are not copied to child in fork().
  1066. .nr PD 1v
  1067. .LP
  1068. Use the test programs to see if the errors are present in your system
  1069. and to check if the modifications are effective.
  1070. .PP
  1071. You may also have to change /usr/src/cmd/cc.c (/bin/cc) to pass the
  1072. .B -i
  1073. flag to
  1074. .I ld.
  1075. Also, /usr/src/cmd/ld.c (/bin/ld) may have to be changed to increase the
  1076. number of library positions it can hold.
  1077. On our (2.9 BSD) version, this is the constant
  1078. .I NROUT.
  1079. It must be at least 400.
  1080. This may require separate I&D.
  1081. Also, our version does not check that the table does not overflow.
  1082. .NH
  1083. Testing
  1084. .PP
  1085. Test sets are available in Pascal, C, Basic and EM assembly.
  1086. .IP em 8
  1087. .br
  1088. The directory emtest contains a few EM test programs.
  1089. The EM assembly files in these tests must be transformed into
  1090. load files.
  1091. These tests use the LIN and NOP instructions to mark the passing of each
  1092. test.
  1093. The NOP instruction prints the current line number during the
  1094. test phase.
  1095. Each test notifies its correctness by calling LIN with a unique
  1096. number followed by a NOP which prints this line number.
  1097. The test finishes normally with 0 as the last number printed
  1098. In all other cases a bug showed its
  1099. existence.
  1100. .IP Pascal
  1101. .br
  1102. The directory lang/pc/test contains a few Pascal test programs.
  1103. All these programs print the number of errors found and a
  1104. identification of these errors.
  1105. .sp 1
  1106. .ti +4
  1107. We also tested Pascal with the Validation Suite.
  1108. The Validation Suite is a collection of more than 200 Pascal programs,
  1109. designed by Brian Wichmann and Arthur Sale to test Pascal compilers.
  1110. We are not allowed to distribute it, but you may
  1111. request a copy from
  1112. .DS
  1113. Richard J. Cichelli
  1114. A.N.P.A.
  1115. 1350 Sullivan Trail
  1116. P.O. Box 598
  1117. Easton, Pennsylvania 18042
  1118. USA
  1119. .DE
  1120. .IP C
  1121. .br
  1122. The sub-directories in lang/cem/ctest contain C test programs.
  1123. The idea behind these tests is:
  1124. when you have a program called xx.c, compile it into xx.cem.
  1125. Run it with standard output to xx.cem.r, compare this file to
  1126. xx.cem.g, a file containing the 'ideal' output.
  1127. Any differences will point to implementation differences or
  1128. bugs.
  1129. Giving the command "run gen" or plain "run" starts this
  1130. process.
  1131. The differences will be presented on standard output.
  1132. The contents of the result files depend on the wordsize,
  1133. the xx.cem.g files on the distribution are intended for a
  1134. 32-bit machine.
  1135. .IP Basic
  1136. .br
  1137. The directory lang/basic/test contains some forty basic programs.
  1138. Not all of these programs are correct, some have syntactic errors,
  1139. some simply don't work.
  1140. The Makefile in that directory attempts to compile and run
  1141. these tests.
  1142. If it compiles its output is compared to a file with suffix .g
  1143. which contains the output to be expected.
  1144. The make should be started with its standard input diverted
  1145. to /dev/null.
  1146. An example of the output of a make is present in the file Out.std.
  1147. .NH
  1148. Documentation
  1149. .PP
  1150. Manual pages for Amsterdam Compiler Kit can be copied
  1151. to "/usr/man/man?" by the
  1152. following commands:
  1153. .DS
  1154. cd man
  1155. make install
  1156. .DE
  1157. but do this \fBafter\fR compiling the Kit.
  1158. .LP
  1159. Several documents are provided:
  1160. .TS
  1161. l l.
  1162. doc/toolkit.doc general overview (CACM article)
  1163. doc/em description of the EM machine architecture
  1164. doc/ack.doc format of machine description files (lib/*/descr)
  1165. doc/basic.doc Basic reference manual
  1166. doc/pcref.doc Pascal-frontend reference manual
  1167. doc/val.doc results of running the Pascal Validation Suite
  1168. doc/crefman.doc C-frontend description
  1169. doc/LLgen description of the LL(1) parser generator.
  1170. doc/peep.doc internal documentation for the peephole optimizer
  1171. doc/cg.doc documentation for backend writers and maintainers
  1172. doc/regadd.doc addendum to previous document describing register variables
  1173. doc/ncg.doc documentation for the newest backends
  1174. doc/v7bugs.doc bugs in the V7 system and how to fix them
  1175. doc/6500.doc MSC 6500 backend description.
  1176. doc/i80.doc Intel 8080 backend description.
  1177. doc/z80.doc Zilog Z80 backend description.
  1178. doc/m68020.doc Motorola M68000/M68020 backend description
  1179. doc/occam Occam-frontend description
  1180. doc/ego Global Optimizer description
  1181. doc/top Target Optimizer description
  1182. doc/m2ref.doc Modula-2 frontend description
  1183. doc/install.doc this document
  1184. doc/install.pr this document (formatted)
  1185. .TE
  1186. .PP
  1187. The names in this list without a suffix are in fact a subdirectory.
  1188. Use the Makefile to get readable copies.
  1189. .LP
  1190. Good luck.