README.md
1# DPS8/M + Multics Continuous Integration Scripts
2
3
4## INTRODUCTION
5
6 The original purpose of these scripts was to provide a build and
7 test environment for Continuous Integration of the DPS8/M simulator.
8 *Charles Anthony* wrote the initial version of these scripts and
9 *Dean Andersom* made significant changes to overcome some of the
10 original issues in the scripts. *Jeffrey Johnson* adapted the process
11 to run in the GitLab CI/CD environment.
12
13
14## REQUIREMENTS
15
16 These scripts were designed to run under **Linux** and have been tested
17 with **Red Hat Enterprise Linux**, **Fedora**, **Ubuntu**, and
18 **OpenSUSE**.
19
20 Other operating systems, specifically IBM **AIX**, Apple **macOS**, Oracle
21 **Solaris**, and illumos **OpenIndiana** have also been used successfuly.
22
23 The following packages are required (beyond the build prerequisites):
24
25 * [Bash](https://www.gnu.org/software/bash/)
26 * [dos2unix](https://waterlan.home.xs4all.nl/dos2unix.html)
27 * [Expect](https://core.tcl-lang.org/expect/)
28 * [GNU Coreutils](https://www.gnu.org/software/coreutils/)
29 * [GNU Diffutils](https://www.gnu.org/software/diffutils/)
30 * [GNU sed](https://www.gnu.org/software/sed/)
31 * [GNU Wget](https://www.gnu.org/software/wget/)
32 * [lzip](https://www.nongnu.org/lzip/)
33 * **BSD**-derived `telnet`, such as,
34 * [Apple Telnet](https://opensource.apple.com/)
35 * [BAN TELNET](https://github.com/BAN-AI-Multics/ban-telnet)
36 * [GNU Inetutils](https://www.gnu.org/software/inetutils/)
37 * [illumos telnet](https://github.com/illumos/illumos-gate/tree/master/usr/src/cmd/cmd-inet)
38 * [NetKit Telnet-SSL](https://github.com/marado/netkit-telnet-ssl)
39
40 In addition, a visual difference comparison tool is highly useful to
41 verify the output. Any of the following tools (*listed alphabetically*)
42 are known to be sufficient for this task:
43
44 * [Beyond Compare](https://www.scootersoftware.com/)
45 * [Code Compare](https://www.devart.com/codecompare)
46 * [Comparison Tool](https://www.eclipse.org/)
47 * [diffoscope](https://diffoscope.org/)
48 * [ExamDiff](https://www.prestosoft.com/)
49 * [Guiffy](https://www.guiffy.com)
50 * [Meld](https://meldmerge.org/)
51 * [Merge](https://www.araxis.com/merge/)
52 * [NeoVim diff](https://neovim.io/doc/user/diff.html)
53 * [P4Merge](https://www.perforce.com/downloads/visual-merge-tool)
54 * [Vim diff](https://vimhelp.org/diff.txt.html)
55 * [WinMerge](https://github.com/winmerge/winmerge)
56 * [Xdiff](https://www.plasticscm.com/features/xmerge)
57 * [xxdiff](https://furius.ca/xxdiff/)
58
59
60## USAGE
61
62 1. Run the initialization script to check for prerequisite utilities and
63 copy the required tape images from /var/cache/tapes (or download them
64 if they are not available):
65```sh
66 ./init
67```
68
69 2. Set the `NOREBUILD` environment variable if you have already built the
70 simulator, and want the tests to run against that compiled binary.
71```sh
72 export NOREBUILD=1
73```
74
75 3. Set the `MAKE` variable if GNU Make is not `make` on your system.
76 ```sh
77 export MAKE=gmake
78 ```
79
80 4. Run the main script file with:
81```sh
82 ./ci
83```
84 5. Once the run completes, you can normalize the logs so they can be
85 (*visually*) compared against the known-good reference log file:
86```sh
87 make -f ci.makefile diff
88```
89
90 6. If this run looks good, (optionally) replace the `ci_full.log` with the
91 `ci_full.log.ref` to update the known-good reference log file.
92
93
94## FILES
95
96**NOTE**: ***This section is is out of date.***
97
98* `ci`
99 This is the launch script start automate starting the process. It mainly
100 invokes `make` to run the `ci.makefile`.
101
102* `ci_full.log.ref`
103 This is the reference log file that can be used to verify the output.
104
105* `ci.makefile`
106 This is a Makefile used to perform all the steps needed in the process.
107
108* `ci_t1.expect`
109 This is the main `expect` script. It starts the emulator with the init
110 script `yoyodyne_start.ini` that will cold boot a clean Multics 12.6f
111 system. After that it loads a card deck and the launches the `ci_t2.sh`
112 and `ci_t3.sh` `expect` scripts, in that order.
113
114* `ci_t2.expect`
115 This script does the following:
116 1. logs in to the "*Clayton*" account created during the cold boot process
117 2. tests with a tape "foo"
118 3. loads an MIT backup tape
119 4. runs a bunch of tests (`eis_tester`, `test_cpu`)
120 5. does an `instr_speed` and `check_cpu_speed`
121 6. creates simple test programs in: PL/1, Pascal, APL, Cobol, Lisp, Basic,
122 Fortran, C and, BCPL
123 7. creates a simple database with MRDS
124 8. uses FAST to create and run a Basic and Fortran program
125 9. uses `map355` to build the FNP code
126 10. prints most (if not all) of the meters
127 11. does some disk management and reporting commands
128
129* `ci_t3.expect` (called by `ci_t3.sh`)
130 This script does the following:
131 1. logs in to the "*Clayton*" account
132 2. invokes `isolts`
133
134* `init`
135 This script will download the Multics MR12.7 tapes and place them in the
136 tapes directory.
137
138* `tidy`
139 This is a shell script that attempts to remove some of the variation in the
140 log files to allow meld to only show significant changes. It does a fairly
141 good job but there are still some things it doesn't catch. Also, it can't
142 do anything about lines being out of order (which can happen quite a bit).
143
144
145## HISTORY
146
147 The initial version of the scripts did everything in a single script.
148 Since both the Multics console and a telnet session were used, it
149 required the `expect` script to deal with switching between the emulator
150 console and a `telnet` session. This had a side effect that, if the
151 timing was off slightly, the entire script execution could get "wedged"
152 and lock up.
153
154 An updated approach was implemented that uses multiple scripts and
155 separated the emulator console use from the telnet session. This proved to
156 be most effective in resolving the "wedging" issues and also removed some
157 intermixing of the logs.
158
159
160## ISSUES
161
162 It turns out that the original intent of automating a CI process with
163 these scripts does not work well. The main issue is that there is enough
164 variation in the log files that automated comparison is very difficult.
165
166 Most likely it will take a sophisticated program to do the comparison or
167 a different approach to automating this testing.
168
169 These scripts are still useful for performing manual testing runs so they
170 are being kept around for that purpose.
171