# Major Differences Between the Distributions
This software began as a series of improvements I made to Oscar Vermeulen's 2015.12.15 software release. For the first several months of this software distribution's lifetime, it was considered an alternative to Oscar's stable version, but [as of May 2017][oann], Oscar now considers the current stable version to be whatever we've most recently [tagged as a stable release][relb].
You can consider the rest of this document to be a migration guide for users who are coming from Oscar's final stable release. It may also be of use while reading through older messages on the mailing list, since they often give instructions that don't work properly with this software but which can be adjusted to work.
This document ignores pure enhancements, bug fixes, and other things which do not change how the user interacts with the software from this site as compared with Oscar's prior stable version. If you want a detailed user-focused list of changes since that version, see [the ChangeLog](/doc/trunk/ChangeLog.md). For the low-level blow-by-blow, see [the project timeline](/timeline).
<a id="build" name="install"></a>
## Build and Installation
Unlike Oscar's final stable release, this software has a straightforward build system, typical of most Linux software. It can be as simple as:
$ ./configure && make && sudo make install
You no longer have to build `scanswitch` manually, you don't have to [build it in place](#multiple) within the installation directory, you don't have to edit the `Makefile` or source code to change build options, there is no separate installation script.
For more details on the build system options, see [the top-level `README.md` file](#options).
## Path Names
This software distribution builds and installs several files in different locations than the prior stable version. The mapping is:
Prior Name | What It Is | Current Name
`pdp.sh` | script to [re]enter the simulator from the command line | `pidp8i`
`pidp8` | modified SimH simulator for the PiDP-8/I panel | `pidp8i-sim`
`pidp8-test` | panel LED and switch test program by Paul R. Bernard, posted to mailing list | `pidp8i-test`
`/etc/init.d/pidp8` | init script used on boot to start the software | `~/.local/share/systemd/user/pidp8i.service`
`/opt/pidp8` | default installation location (a.k.a. $prefix) | `/opt/pidp8i`
`$prefix/bin/scanswitch` | helper program for the simulator startup script | `$prefix/libexec/scanswitch`
`$prefix/bootscripts` | scripts that tell the simulator how to start up given different IF switch combinations | `$prefix/share/boot`
`$prefix/imagefiles` | binary paper tape images, disk images, and such | `$prefix/share/media`
I added an `i` to some of these names for two reasons:
1. It was useful during the transition period so that [both versions of the software](#running-both) could be installed on the same system without conflicts.
2. I decided that it was unlikely that we will ever see a follow-on project for a different PDP-8 front panel, since it appears Oscar's got other projects stacked up for years. If he ever makes it back and does, say, a PiDP-8/**e**, we might have to revisit this decision. Meanwhile, the programs in this software distribution tend to be named after the only hardware they are known to work with, the PiDP-8/I.
The files now under the `share` subdirectory were moved to conform to the Linux Filesystem Hierarchy Standard, so that experienced Linux users would be more likely to guess their location.
The reason for the `scanswitch` relocation is that there is no reason for end users to run it directly, so it's better off out of the user's `PATH`. That is also why I haven't bothered to rename it to something like `pidp8i-scanswitch`. There is a [plan](/tktview?name=6c1f29ab59) to merge this program with `pidp8i-test`, which if done will mean `scanswitch` goes away.
## The PiDP-8/I Service
The way you start, stop, restart, and query the background simulator service has changed. See [the top-level `README.md` file](/doc/trunk/README.md#systemd) for details.
One detail that doc doesn't cover is that between this change and those documented in the prior section, it is possible to run both the current PiDP-8/I software from this web site alongside Oscar's last stable release. They can't run simultaneously, since they'd fight over the front panel GPIO pins, but you can swap between them at will.
To run Oscar's final stable version instead of this software distribution, say:
$ pidp8i stop
$ sudo systemctl start pidp8
And then to switch back to this version:
$ sudo systemctl stop pidp8
$ pidp8i start
## Multiple Installations
Oscar's final stable version was essentially fixed in place in the filesystem. Its source code had to be unpacked into `/opt/pidp8` and run from there to work correctly.
This current software can be unpacked anywhere in the filesystem you have sufficient access permission for, you can build it into a second directory separate from the source directory, and you can install it to yet a third directory. This affords considerable flexibility in how you build and install this software.
This software also doesn't overwrite your binary media on re-installation: whenever we ship a change to one of the paper tape images, DECtape images, RK05 disk images, etc., upgrading to that release only gets you a copy of the new media in the source tree; those new versions do not overwrite your local copies in the installation tree, since they may contain local changes. With the prior stable version, since the build and installation locations were the same, upgrading would always overwrite your local media images. See [Overwriting the Local Simulator Setup][olss] for more on this topic.
## Incandescent Lamp Simulator
When you build this software on a multi-core Pi, the default is to build the PiDP-8/I simulator with the [incandescent lamp simulator][wils] (ILS) enabled, as opposed to the original LED driving code which is more efficient but less period-accurate in appearance. On single-core Pis, we build the software to drive the LEDs in much the same way as the prior stable version does, because the ILS takes too much CPU to run both it and the PDP-8 simulator at the same time on a single 700 MHz ARM core. You can force a return to the old efficient method on a multi-core Pi by configuring the software with the `--no-lamp-simulator` option.
## Runs on More OSes
The PiDP-8/I software now builds and runs on more OS types than did Oscar's last release, which was pretty much tied to Raspbian and close relatives like pipaOS. Full details on this are covered [elsewhere][wosc].
## Front Panel Switch Combos
Several of the PiDP-8/I specific front-panel switch combos are different:
* `Sing_Step` + `Sing_Inst` + `Start` now reboots the host Pi, rather than power it down, because "Start" makes more sense as a mnemonic for "restart."
* `Sing_Step` + `Sing_Inst` + `Stop` now powers the host Pi down.
* `Sing_Step` + `Sing_Inst` + `Cont` used to reboot the host Pi, but is currently unassigned.
* `Sing_Step` + `Sing_Inst` + `Load_Add` used to mount the USB stick, but that is unnecessary, since the software now uses Raspbian's USB automounter.
* `Sing_Step` + `Sing_Inst` + `Dep` used to unmount the USB stick, but that is unnecessary in this instance since USB sticks are primarily used to emulate paper tapes, which are read-only media. You don't have to unmount the stick before unplugging it in order to avoid filesystem corruption in instances like this.
* `Sing_Step` + `DF=7` changed from looking for a `*.rl` file to mount as an RL01 disk pack image to expecting an `*.rk` file and mounting it on the second `RK05` disk drive. The RL series drives postdates the PDP-8/I by many years, and the stock OS/8 configuration ships as an RK05 image that mounts on the first drive, so this new meaning feels more appropriate on many axes. The other `DF` settings retain their [stock meanings](http://obsolescence.wixsite.com/obsolescence/how-to-use-the-pidp-8).
These are all combinations: the two or three switches involved all have to be closed at the same time for the action to occur. It doesn't matter which order you close those contacts: the software takes action when the last one closes. It's usually easiest to close the simple toggles first, then click the momentary `Sing_Step` and/or `Sing_Inst` once and release. You can then flip the other toggle back to its prior state, if you like.
Copyright © 2017-2019 by Warren Young. This document is licensed under the terms of [the SIMH license][sl].