install.doc 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623
  1. .\" $Header$
  2. .nr LL 7.5i
  3. .nr PD 1v
  4. .TL
  5. Amsterdam Compiler Kit installation guide
  6. .AU
  7. Ed Keizer
  8. .AI
  9. Wiskundig Seminarium
  10. Vrije Universiteit
  11. Amsterdam
  12. .NH
  13. Introduction
  14. .PP
  15. This document
  16. describes the process of installing Amsterdam Compiler Kit.
  17. It depends on your combination of hard- and software how
  18. hard it will be to install the kit.
  19. This description is intended for a PDP 11/44 running
  20. .UX
  21. Version 7.
  22. Installation on other PDP 11's should be easy, as long
  23. as they have separate instruction and data space.
  24. Installation on machine's without this feature, like PDP 11/34,
  25. PDP 11/60 requires extensive surgery on some programs and is
  26. thought of as impossible.
  27. See chapter 6 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 20000 blocks 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. The directories in the tree contain the following information:
  50. .nr PD 1v
  51. .IP "lib" 14
  52. .br
  53. almost all binaries and shell files used by commands and
  54. library em_data.a from misc/data
  55. .IP "lib/ack"
  56. .br
  57. The command descriptor files used by the program ack.
  58. .nr PD 0
  59. .IP "bin"
  60. .br
  61. the few utilities that knot things together
  62. .IP "etc"
  63. .br
  64. The MAIN description of EM sits here.
  65. contains files (e.g. em_table) describing
  66. the opcodes and pseudos in use,
  67. the operands allowed, effect in stack etc. etc.
  68. Make in this directory creates most of the files in h
  69. .IP "include"
  70. .br
  71. More or less system independent include files needed by modules
  72. in the C library from lang/cem/libcc.
  73. Especially needed for "stdio".
  74. .IP "h"
  75. .br
  76. The #include files for:
  77. .nf
  78. as_spec.h Used by EM assembler and interpreters.
  79. em_abs.h Contains trap numbers and address for lin and fil
  80. em_flag.h Definition of bits in array em_flag in lib/em_data.a
  81. Describes parameters effect on flow of instructions
  82. em_mes.h Definition of names for mes pseudo numbers
  83. em_mnem.h instruction => compact mapping.
  84. em_pseu.h pseudo instruction => compact mapping
  85. em_ptyp.h Useful for compact code reading/writing,
  86. defines classes of parameters
  87. em_spec.h Definition of constants used in compact code
  88. local.h Various definitions for local versions
  89. pc_err.h Definitions of error numbers in Pascal
  90. pc_file.h Macro's used in file handling in Pascal
  91. em_path.h Pathnames used by \fIack\fP, intended
  92. for all utilities
  93. pc_size.h Sizes of objects used by Pascal compiler and
  94. run-time system.
  95. em_reg.h Definition of names for register types.
  96. .IP "doc"
  97. .br
  98. Documentation
  99. .nf
  100. cg.doc Use and internal specification of the backend.
  101. .br
  102. regadd.doc Update for cg.doc concerning register variables
  103. .br
  104. regadd.doc Description of steps to add register variables.
  105. .br
  106. ack.doc Layout of description files needed for each machine.
  107. .br
  108. cref.doc C reference manual, addendum
  109. .br
  110. install.doc Ack Installation Guide
  111. .br
  112. pcref.doc Pascal reference manual, addendum
  113. .br
  114. peep.doc Description of the peephole optimizer
  115. .br
  116. em.doc EM reference manual
  117. .br
  118. toolkit.doc A general overview of the toolkit
  119. .br
  120. v7bugs.doc Bugs in the standard V7 system
  121. .br
  122. val.doc Pascal validation suite version 3 report
  123. .nf
  124. .IP "doc/em.doc"
  125. .br
  126. The EM-manual IR-81
  127. .IP "doc/em.doc/int"
  128. .br
  129. The EM interpreter written in pascal
  130. .IP "mkun"
  131. .br
  132. The PUBMAC macro package for nroff/troff from the Katholieke Universiteit at
  133. Nijmegen.
  134. It is used for the EM reference manual,
  135. the Makefile installs the macro package in
  136. /usr/lib/tmac/tmac.mkun*.
  137. This package is in the public domain.
  138. .IP "mach"
  139. .br
  140. just there to group the directories for all machines
  141. these directories have sub-directories named:
  142. .nf
  143. as the assembler ( *.s + libraries => a.out )
  144. cg the new backend ( *.m => *.s )
  145. lib the libraries for all run-time systems
  146. these libraries are used by the assembler.
  147. libpc Used to create Pascal run-time system in 'lib'
  148. libcc Used to create C run-time system in 'lib'
  149. libem Sources for EM runtime system, result sits in 'lib'
  150. test Various tests
  151. dl Down-load programs
  152. int Source for an interpreter
  153. available are:
  154. PMDS II 68000, wordsize 2, ptrsize 4
  155. mach/m68k2
  156. mach/m68k2/as
  157. mach/m68k2/cg
  158. mach/m68k2/libem
  159. mach/m68k2/lib
  160. mach/m68k2/dl
  161. mach/m68k2/libpc
  162. mach/m68k2/libcc
  163. mach/m68k2/libsys
  164. bare 6809
  165. mach/6809
  166. mach/6809/as
  167. 8080, wordsize 2, ptrsize 2
  168. mach/8080
  169. mach/8080/as
  170. mach/8080/test
  171. mach/8080/libcc
  172. mach/8080/lib
  173. bare 8086, wordsize 2, ptrsize 2
  174. mach/i86
  175. mach/i86/as
  176. mach/i86/lib
  177. mach/i86/libcc
  178. mach/i86/dl
  179. mach/i86/libem
  180. mach/i86/libpc
  181. mach/i86/saio (library for stand-alone EM on 86/12A )
  182. pdp 11, UNIX/V7, wordsize 2, ptrsize 2
  183. mach/pdp
  184. mach/pdp/test
  185. mach/pdp/libem
  186. mach/pdp/lib
  187. mach/pdp/libcc
  188. mach/pdp/libpc
  189. mach/pdp/cg
  190. mach/pdp/int -PDP 11/44 EM interpreter
  191. vax 780, UNIX V7, wordsize 4, ptrsize 4
  192. mach/vax4
  193. mach/vax4/cg
  194. mach/vax4/lib
  195. mach/vax4/libcc
  196. mach/vax4/libem
  197. mach/vax4/libpc
  198. z80, CP/M, wordsize 2, ptrsize 2
  199. mach/z80
  200. mach/z80/as
  201. mach/z80/libem
  202. mach/z80/lib
  203. mach/z80/libcc
  204. mach/z80/libpc
  205. mach/z80/int -Z80 EM interpreter
  206. z80, nascom
  207. mach/z80a
  208. mach/z80a/dl
  209. vax 11/780, Berkeley UNIX, wordsize 2, ptrsize 4
  210. mach/vax2
  211. mach/vax2/cg
  212. mach/vax2/lib
  213. mach/vax2/libpc
  214. mach/vax2/libem
  215. bare 6500, wordsize 2, ptrsize 2
  216. mach/6500
  217. mach/6500/as
  218. mach/6500/dl
  219. mach/6500/libem
  220. mach/6500/lib
  221. bare 6800, wordsize 2, ptrsize 2
  222. mach/6800
  223. mach/6800/as
  224. EM virtual machine code, wordsize 2, ptrsize 2
  225. mach/int
  226. mach/int/libcc
  227. mach/int/libpc
  228. mach/int/lib
  229. mach/int/test
  230. The directory proto contains files used by most machines.
  231. e.g. makefiles for libraries for C and Pascal
  232. mach/proto
  233. mach/proto/libg
  234. .fi
  235. .IP "emtest"
  236. .br
  237. Contains prototype of em test set.
  238. .IP "man"
  239. .br
  240. Man files for various utilities
  241. .IP "lang"
  242. .br
  243. just there to group the directories for all front-ends
  244. .IP "lang/pc"
  245. .br
  246. Pascal front-end
  247. .IP "lang/pc/libpc"
  248. .br
  249. Source of Pascal run-time system ( in EM or C )
  250. .IP "lang/pc/test"
  251. .br
  252. Some test programs written in Pascal
  253. .IP "lang/pc/pem"
  254. .br
  255. The compiler proper
  256. .IP "lang/cem"
  257. .br
  258. C front-end
  259. .IP "lang/cem/libcc"
  260. .br
  261. Directories with sources of C runtime system, libraries (in EM or C)
  262. .IP "lang/cem/libcc/gen"
  263. .br
  264. Sources for routines in chapter III of UNIX programmers manual,
  265. excluding STDIO
  266. .IP "lang/cem/libcc/stdio"
  267. .br
  268. STDIO sources
  269. .IP "lang/cem/libcc/mon"
  270. .br
  271. Sources for routines in chapter II, written in EM
  272. .IP "lang/cem/comp"
  273. .br
  274. The compiler proper
  275. .IP "lang/cem/ctest"
  276. .br
  277. C test set
  278. .IP "lang/cem/ctest/cterr"
  279. .br
  280. Programs developed for pinpointing previous errors
  281. .IP "lang/cem/ctest/ct*"
  282. .br
  283. The test programs.
  284. .IP "util"
  285. .br
  286. Contains directories with various utilities
  287. .IP "util/opt"
  288. .br
  289. EM peephole optimizer (*.k => *.m)
  290. .IP "util/misc"
  291. .br
  292. Decode (*.[km] => *.e) + encode (*.e => *.k)
  293. .IP "util/data"
  294. .br
  295. The C-code for `lib/em_data.a`
  296. These sources are created by the Makefile in `etc`
  297. .IP "util/ass"
  298. .br
  299. The EM assembler ( *.[km] + libraries => e.out )
  300. .IP "util/arch"
  301. .br
  302. The archiver to be used for ALL EM utilities
  303. .IP "util/cgg"
  304. .br
  305. A program needed for compiling backends.
  306. .IP "util/cpp"
  307. .br
  308. The V7 C preprocessor.
  309. .LP
  310. All pathnames mentioned in the text of this document are relative to the
  311. working directory, unless they start with '/'.
  312. .PP
  313. The person doing the installation needs permission to write in the
  314. directories of the Amsterdam Compiler Kit distribution tree.
  315. Preferably you should log in as sys (uid=3,gid=0).
  316. .NH
  317. Pathnames
  318. .PP
  319. Absolute pathnames are concentrated in "h/em_path.h".
  320. Only the pascal runtime system and the utility \fIack\fP use
  321. absolute pathnames to access files in the kit.
  322. The tree is distributed with /usr/em as the working
  323. directory.
  324. The definition of EM_HOME in em_path.h should be altered to
  325. specify the root
  326. directory for the Compiler Kit distribution on your system.
  327. The trailing " in the definition of EM_HOME is intentionally
  328. missing!
  329. Em_path.h also specifies which directory should be used for
  330. temporary files.
  331. Most programs from the kit do indeed use that directory
  332. although some remain stubborn and use /tmp or /usr/tmp.
  333. .LP
  334. The shape of the tree should not be altered lightly because
  335. most Makefiles and the
  336. utility \fIack\fP know the shape of the ACK tree.
  337. All pathnames in all Makefiles are relative, that is do not
  338. have "/" as the first character.
  339. The knowledge of the utility \fIack\fP about the shape of the tree is
  340. concentrated in the files in the directory lib/ack.
  341. .NH
  342. Commands
  343. .PP
  344. The kit is distributed with all available commands in the bin
  345. directory.
  346. The commands distributed are:
  347. .IP "\fIack\fP, \fIacc\fP, \fIapc\fP and their links"
  348. .br
  349. They are used to compile the Pascal, C, etc... programs.
  350. .IP \fIarch\fP
  351. .br
  352. The archiver used for the EM- and universal assembler.
  353. .IP "\fIem\fP and \fIeminform\fP"
  354. .br
  355. The EM interpretator for the PDP-11 and the program to unravel
  356. its post-mortem information.
  357. .LP
  358. We currently make the kit available to our users by telling
  359. them that they should include the bin directory of the kit in
  360. their PATH shell variable.
  361. The programs will still work when moved to a different
  362. directory.
  363. The copying should preferably be done with tar, since links are
  364. heavily used.
  365. Renaming of the programs linked to \fIack\fP will not always
  366. produce the desired result.
  367. This program uses its call name as an argument.
  368. Any call name not being \fIcc\fP, \fIacc\fP, \fIpc\fP or \fIapc\fP will be
  369. interpreted as the name of a 'machine description' and the
  370. program will try to find a description file with that name.
  371. All recompilations will only touch the utilities in the bin
  372. directory, not your own copies.
  373. .NH
  374. Options
  375. .PP
  376. There is one important option in h/local.h.
  377. The utility \fIack\fP uses a default machine name when called
  378. as \fIacc\fP, \fIcc\fP, \fIapc\fP, \fIpc\fP or \fIack\fP.
  379. The machine name used for default is determined by the
  380. definition of ACKM in h/local.h.
  381. The current definition is \fIpdp\fP.
  382. .PP
  383. The distribution is tailored to one specific opreating system per CPU type.
  384. For some of these CPU's it is possible to tailor the distribution to another
  385. operating system.
  386. The steps to be taken are described in READ_ME (or README) files in the
  387. subdirectories of the directory in EM_HOME/mach for that particular machine.
  388. For example: The vax2 distribution is tailoerd to BSD4.1, but has #define's
  389. for BSD4.1c and BSD4.2.
  390. For the names and places of these define's look in EM_HOME/mach/vax2/cg and
  391. EM_HOME/mach/vax2/libem.
  392. .NH
  393. Recompilation
  394. .PP
  395. The kit comes with binaries in the directories \fBbin\fP and
  396. \fBlib\fP.
  397. Some directories among mach/*/lib contain archives with object files,
  398. notably mach/pdp/lib.
  399. The binaries and object files are for a PDP 11/44 with floating
  400. point running UNIX V7.
  401. .PP
  402. Almost all directories contain a "Makefile" or a shell command file called
  403. "make".
  404. Apart from commands applying to that specific directory these
  405. files all recognize a few special commands.
  406. When called with one of these they will apply the command to
  407. their own directory and all subdirectories.
  408. The special commands are:
  409. .IP "install" 20
  410. recompile and install all binaries and libraries.
  411. .br
  412. Some Makefiles allow errors to occur in the programs they call.
  413. They ignore such errors and notify the user with the message
  414. "~....... error code n: ignored".
  415. Whenever such a message appears in the output you can ignore it
  416. too.
  417. .br
  418. The installation of the PUBMAC macro package is not done
  419. automatically from the higher level directory.
  420. .IP "cmp"
  421. recompile all binaries and libraries and compare them to the
  422. ones already installed.
  423. .IP pr
  424. print the sources and documentation on the standard output.
  425. .IP opr
  426. make pr | opr
  427. .br
  428. Opr should be an off-line printer daemon.
  429. On some systems it exists under another name e.g. lpr.
  430. The easiest way to call such a spooler is using a shell script
  431. with the name opr that calls lpr.
  432. This script should be placed in /usr/bin or EM_HOME/bin or
  433. one of the directories in your PATH.
  434. .IP clean
  435. remove all files not needed for day-to-day use,
  436. that is binaries not in bin or lib, object files etc.
  437. .LP
  438. Example:
  439. .nf
  440. .sp 1
  441. make install
  442. .sp 1
  443. .fi
  444. given as command in the home directory will cause
  445. recompilation of all programs in the kit.
  446. .LP
  447. Recompilation of the complete kit lasts about 9 hours an a PDP
  448. 11/44.
  449. .NH 2
  450. Recompilation on a different machine.
  451. .PP
  452. Installation on other systems will often require recompilation
  453. of all programs.
  454. The presence of a C compiler is essential for recompilation.
  455. Except the Pascal compiler proper all programs are written in C.
  456. Some modules are derived from \fIyacc\fP sources.
  457. Retranslating these programs from that yacc source is not
  458. necessary, although it might improve performance.
  459. Some versions of \fIyacc\fP 'know' that the resulting C programs will
  460. run on a 32-bit int machine.
  461. C modules produced by such a \fIyacc\fP are not portable and
  462. should not be used to (cross)compile programs for 16-bit machines.
  463. We assume a version UNIX which, apart from the C-compiler,
  464. contains most normal utilities, like ed, sed, grep, make, the
  465. Bourne shell etc.
  466. All Makefiles use the system C-compiler.
  467. The existence of a backend for your system is of course essential
  468. if you wish to produce executable files for that system.
  469. When the backend exists it is also possible to boot the Pascal
  470. Compiler,
  471. that is written in Pascal itself.
  472. The kit contains the compact code files for the 2/2 and 2/4
  473. versions of the Pascal compiler.
  474. The current version of this compiler can only be used on machines
  475. with a 16-bit word size and 16- or 32-bit pointers.
  476. The Makefile automatically tries to boot the Pascal compiler
  477. from one of these compact code files, if the compiler proves
  478. unable to compile itself.
  479. .PP
  480. The native assemblers and loaders are used on PDP-11 and VAX.
  481. The description files in lib/ack for other systems use our
  482. universal assembler.
  483. The load file produced by this assembler is not directly
  484. usable in any system known to us,
  485. but has to be converted before it can be put to use.
  486. The \fIdl\fP programs present for some machines unravel
  487. these load files and transmit commands to load memory
  488. to a microprocessor over a serial line.
  489. The PDP-11 version of our universal assembler is supplied
  490. with a conversion program.
  491. The file man/a.out.5 contains a description of the format of
  492. the universal assembler load file,
  493. it might be useful to those who wish or need to write their
  494. own conversion programs.
  495. .br
  496. Berkeley UNIX for the VAX'en has (at least) three different
  497. versions, BSD4.1a, BSD4.1c and BSD4.2. The READ_ME files in the
  498. directories mach/vax2/cg, mach/vax2/libem, mach/vax4/cg and
  499. mach/vax4/libem tell you how to adapt the vax2 and vax4 backend
  500. to these versions.
  501. .NH 2
  502. Recompiling libraries
  503. .PP
  504. The kit contains sources for part II and III of the C-library, except
  505. the math functions, they are grabbed from our V7 system and sometimes
  506. altered in a EM dependent way or replaced altogether when the original
  507. was in assembly.
  508. These files can be used to make libraries for the Ack C-compiler.
  509. The recompilation process uses a few include files.
  510. The include directory in the EM home directory contains a few more
  511. or less system independent include files.
  512. The system dependent include files are fetched from /usr/include
  513. on the system you use to recompile.
  514. This may lead to several problems.
  515. Sometimes the system differs so much from V7 that certain manifest constants
  516. do not exist any more.
  517. At other times these include files were written for a compiler without
  518. a restriction on name length.
  519. In that case - I've seen it happen - people tend to use differing
  520. identifiers that are identical in the first eight characters.
  521. All these problems you have to solve yourself,
  522. the libraries are only included as an extra and too much system
  523. dependent to give any guarantees.
  524. .NH
  525. Fixes to the UNIX V7 system
  526. .PP
  527. UNIX System V7 has a few bugs that prevent a part of or the whole kit
  528. from working properly.
  529. To be honest, we do not know which of the following changes are
  530. essential to the functioning of our kit.
  531. .PP
  532. The file "doc/v7bugs.doc" gives for each of the following bugs
  533. a small test program and a diff listing of the source files that have to be
  534. modified.
  535. .IP 1
  536. Bug in the C optimizer for unsigned comparison
  537. .nr PD 0
  538. .IP 2
  539. The loader 'ld' fails for large data and text portions
  540. .IP 3
  541. Floating point registers are not saved if more memory is needed.
  542. .IP 4
  543. Floating point registers are not copied to child in fork().
  544. .nr PD 1v
  545. .LP
  546. Use the test programs to see if the errors are present in your system
  547. and to check if the modifications are effective.
  548. .NH
  549. Testing
  550. .PP
  551. Test sets are available in Pascal, C and EM assembly.
  552. .IP em 8
  553. .br
  554. The directory emtest contains a few EM test programs.
  555. The EM assembly files in these tests must be transformed into
  556. load files, thereby avoiding use of the EM optimizer.
  557. These tests use the LIN and NOP instructions to mark the passing of each
  558. test.
  559. The NOP instruction prints the current line number during the
  560. test phase.
  561. Each test notifies its correctness by calling LIN with a unique
  562. number followed by a NOP which prints this line number.
  563. The test finishes normally with 0 as the last number printed
  564. In all other cases a bug showed its
  565. existence.
  566. .IP Pascal
  567. .br
  568. The directory lang/pc/test contains a few pascal test programs.
  569. All these programs print the number of errors found and a
  570. identification of these errors.
  571. .IP C
  572. .br
  573. The sub-directories in lang/cem/ctest contain C test programs.
  574. The idea behind these tests is:
  575. when you have a program called xx.c, compile it into xx.cem.
  576. Run it with standard output to xx.cem.r, compare this file to
  577. xx.cem.g, a file containing the 'ideal' output.
  578. Any differences will point to implementation differences or
  579. bugs.
  580. Giving the command "run gen" or plain "run" starts this
  581. process.
  582. The differences will be presented on standard output.
  583. The contents of the result files depend on the wordsize,
  584. the xx.cem.g files on the distribution are intended for a
  585. 16-bit machine.
  586. .NH
  587. Documentation
  588. .PP
  589. Manual pages for Amsterdam Compiler Kit can be copied
  590. to "/usr/man/man?" by the
  591. following commands:
  592. .DS
  593. cd man
  594. make install
  595. .DE
  596. .LP
  597. Several documents are provided:
  598. .DS
  599. doc/toolkit.doc: a general overview
  600. doc/pcref.doc: the Pascal-frontend reference manual
  601. doc/val.doc: the results of running the Pascal Validation Suite
  602. doc/cref.doc: the C-frontend manual
  603. doc/em.doc: a description of the EM machine architecture
  604. doc/peep.doc: internal documentation for the peephole optimizer
  605. doc/cg.doc: documentation for backend writers and maintainers
  606. doc/regadd.doc: addendum to previous document describing register variables
  607. doc/install.doc: this document
  608. .DE
  609. .LP
  610. The Validation Suite is a collection of more than 200 Pascal programs,
  611. designed by Brian Wichmann and Arthur Sale to test Pascal compilers.
  612. We are not allowed to distribute it, but you may
  613. request a copy from
  614. .DS
  615. Richard J. Cichelli
  616. A.N.P.A.
  617. 1350 Sullivan Trail
  618. P.O. Box 598
  619. Easton, Pennsylvania 18042
  620. USA
  621. .DE
  622. .LP
  623. Good luck.