install.doc 32 KB

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