diff --git a/Setup.md b/Setup.md new file mode 100644 index 0000000..8b1f9ad --- /dev/null +++ b/Setup.md @@ -0,0 +1,72 @@ +# Setup the PiDP-10 + +## Setting up the Environment + +In order to run this program, you need a working PDP-10 simulator (or, if you +are a very lucky person,the real thing). You can either use the +[PiDP-10 kit](https://obsolescence.wixsite.com/obsolescence/pidp10), or a +Raspberry Pi 5 to run it on. The PiDP-10 can be run on any Raspberry 5 computer, +even without the front panel, but having the front panel is fancier. You can +also run [simh](https://opensimh.org/) on a PC, but that would only be half the +fun. + +The PiDP-10 should be booted into ITS, as this is the OS, this project is +running against. Now the only thing you need to do, is copy the source code +files into the file system of your PiDP-10. You can do this by using the `mlftp` +tool, installed on the machine your simulator runs on. You clone the repository +and run the following commands from the command line: + +```bash +/opt/pidp10/bin/mlftp -w ITS "SUDOKU 1 JALI;" ./src/sudoku.s +/opt/pidp10/bin/mlftp -w ITS "PUZZLE 1 JALI;" ./src/puzzle_1.sudoku +``` + +This will copy the source code file, and the example puzzle file onto the +PiDP-10. Remember to change the directory name in the ITS path form `JALI` to +the directory you want to copy to. + +You can now edit both files in EMACS on the PiDP-10. However, if you prefer to +edit your code in a somewhat more modern environment (your favourite IDE, for +example), consider installing the +[git-monitor](https://gitea.orca-central.de/jali/PiDP10Services) on your +PiDP-10's host system. The monitor is a service written in +[bash](https://www.gnu.org/software/bash/), that will clone your project +repositories and then monitor a given branch for new commits. On new commits it +pulls them, and runs the script `.git-monitor_after.sh`, which in turn, contains +the upload commands for ITS. This way, you can automatically update your source +code in ITS, even when you are working on a modern machine. + +## Building and running + +Log into ITS with your developers user name by typing `USERNAME$U` (where `$` is +the ESC-Key), If you are a *luser*: Type `:LOGIN USERNAME` and swap `USERNAME` +for your *actual* username. Confirm with `Enter`. + +Now you can build the sudoku solver by invoking MIDAS in DDT: + +``` +:MIDAS TS SUDOKU_SUDOKU +``` + +This will instruct MIDAS to create a relocatable binary (TS) from the latest +version of the `SUDOKU` file, and store it in a file named `TS SUDOKU` in the +current directory. If this succeded, listing the files with `:LISTF` (or +`CTRL+F`, if you're not a turist), should look something like this: + +``` +KA JALI +FREE BLOCKS #2=154 #3=169 #0=156 #1=171 + 1 PUZZL1 SUDOKU 1 ! 9/21/2025 22:02:04 + 3 SUDOKU 1 1 ! 9/21/2025 22:02:02 + 1 TS SUDOKU 1 ! 9/21/2025 23:25:09 +``` + +To invoke the solver run it with: + +``` +:SUDOKU PUZZLE 1 +``` + +This will pass the file `PUZZLE 1` to the program, and start solving it. + +The result will be printed on the screen (once the project is finished).