$ sudo apt update
        $ sudo apt install build-essential libraspberrypi-dev \
             libncurses-dev python-pip
        $ sudo pip install pexpect

[os]: https://tangentsoft.com/pidp8i/wiki?name=OS+Compatibility



















<a id="unpacking"></a>
## Getting the Software onto Your Pi

If you're reading this file within an unpacked distribution of the
PiDP-8/I software, you may skip this section, because you have
already achieved its aim.
................................................................................
    above, so you can use Fossil to update your software to the current
    version at any time, as long as the Pi is connected to the Internet.


<a id="unpacking"></a>
### Unpacking the Software on Your Pi

Having transferred the distribution file onto your Pi, you can unpack it
with one of the two following commands.

If you grabbed the tarball:

    $ tar xvf /path/to/pidp8i-VERSION.tar.gz

If you grabbed the Zip file instead:

    $ unzip /path/to/pidp8i-VERSION.zip

The file name will vary somewhat, depending on when and how you
transferred the file.  After unpacking it, you will have a new
directory beginning with `pidp8i`.  `cd` into that directory, then
proceed with the [configuration](#configuring) steps below.


<a id="help"></a>
### If You Need More Help

If the above material is not sufficient to get you started, you might
want to look at [the documentation][rpfd] provided by the Raspberry
................................................................................

This software distribution builds and installs in the same way as most
other Linux/Unix software these days.  The short-and-sweet is:

    $ ./configure && make && sudo make install

The `configure` step is generally needed only the first time you build
the software in a new directory.  You may want to add options after it,
as described [below](#options).

After that initial configuration, the software normally auto-reconfigures
itself on updates using the same options you gave before, but occasionally
we make some change that prevents this from happening.  If you get a
build error after updating to a new version of the software, try saying:


    $ make reconfig

...and then continuing with the `make && sudo make install` steps before
reporting a build error.




If `make reconfig` also fails, you can try running the `configure`
script again manually.














<a id="running"></a>
### Running the Software

For the most part, this is covered in the documentation linked from the







[Learning More](/#learning) section of the project home page.

The only tricky bit is that if this is the first time you have
configured, built and installed the software as above on a given system,
you will have to log out and back in before commands like `pidp8i` will
be in your user's `PATH`.

































































































<a id="options"></a>
### Configure Script Options

You can change many things about the way the software is built and
installed by giving options to the `configure` script:
................................................................................
switches on the front panel.  After you are done testing, you can start
the PiDP-8/I simulator back up with:

    $ pidp8i start

See [its documentation][test] for more details.


<a id="using"></a>
## Using the Software

For the most part, this software distribution works like the [old stable
2015.12.15 distribution][osd]. Its [documentation][oprj] therefore
describes this software too, for the most part.

The largest user-visible difference between the two software
distributions is that many of the shell commands are different:

1.  To start the simulator running in the background:

        $ pidp8i start

    This will happen automatically on reboot unless you disable the
    service, such as in order to run one of the various [forks of Deeper
    Thought][dt2].

2.  To attach the terminal you're working on to the simulator:

        $ pidp8i

    (Yes, it's the same base command as above.  The `pidp8i` script uses
    its first argument to determine what you want it to do.  Without
    arguments, this is what it does.)

3.  To detach from the simulator's terminal interface while leaving the
    PiDP-8/I simulator running, type <kbd>Ctrl-A d</kbd>.  You can
    re-attach to it later with a `pidp8i` command.

4.  To shut the simulator down while attached to its terminal interface,
    type <kbd>Ctrl-E</kbd> to pause the simulator, then at the `simh>`
    prompt type `quit`.  Type `help` at that prompt to get some idea of
    what else you can do with the simulator command language, or read
    the [SIMH Users' Guide][sdoc].

5.  To shut the simulator down from the Raspbian command line:

        $ pidp8i stop

There are [other major differences][mdif] between the old stable
distribution and this one.  See that linked wiki article for details.


<a id="sshd"></a>
## Enabling the SSH Server on the Binary OS Images

The OpenSSH server is enabled and running by default on the PiDP-8/I
binary OS images, but for security reasons, the build process we use
to create these OS images wipes out the SSH host keys generated here
................................................................................

You may be wondering why we don’t do this automatically, somehow. It’s
because, over time, we’ve removed all dependence on root access in our
software in the name of security, so that we no longer have permission
to make system-wide changes like this in our startup scripts.  We now
rely on you, the system’s administrator, to do it interactively with
`sudo` permissions.


<a id="systemd" name="unit"></a>
## The systemd Unit File

Older stable releases of the PiDP-8/I software used an [old-style System
V init script][svinit] to start the PiDP-8/I service. This includes
Oscar Vermeulen's final stable release.

Starting with release v2019.04.25, we have now switched to a
[systemd][systemd] unit file, since Raspbian has been systemd-based for
years. (It also supports SysV init scripts, but only as a second-class
mechanism intended for backwards compatibility only.)

One of the features systemd gives us is the ability to set the unit
to run as user-level service rather than as a system-wide service,
which means you no longer need the `sudo` prefix on commands to start,
stop, restart, and query the service. The only time you now need root
privileges is when installing the software. After that, the software
runs under your normal user account, as do all of the commands you
use to manipulate the background simulator service.

As a result of these changes, none of these commands work any longer:

    $ sudo /etc/init.d/pidp8i start
    $ sudo service pidp8i stop
    $ sudo systemctl restart pidp8i

The correct forms, respectively, are:

    $ systemctl --user start pidp8i
    $ systemctl --user stop pidp8i
    $ systemctl --user restart pidp8i

These commands are long, so we have extended the `pidp8i` command to
build and run `systemctl` commands for you when you pass it arguments:

    $ pidp8i start
    $ pidp8i stop
    $ pidp8i restart
    $ pidp8i status -l

If you run it without arguments, it attaches to the GNU screen(1)
session, just as before.

The last command above shows that *all* arguments are passed to
`systemctl`, not just the first, so you can pass flags and such.

The service is still set to start at boot, just as before.

To disable the service so you can run something else against the
PiDP-8/I front panel hardware instead, such as Deeper Thought 2:

    $ pidp8i stop
    $ pidp8i disable

If you install this release on a system that has the old SysV init
script on it, that service will be disabled and removed before we
install and enable the replacement systemd user service.

[svinit]:  https://en.wikipedia.org/wiki/Init#SysV-style
[systemd]: https://www.freedesktop.org/wiki/Software/systemd/



## License

Copyright © 2016-2019 by Warren Young. This document is licensed under
the terms of [the SIMH license][sl].

        $ sudo apt update
        $ sudo apt install build-essential libraspberrypi-dev \
             libncurses-dev python-pip
        $ sudo pip install pexpect

[os]: https://tangentsoft.com/pidp8i/wiki?name=OS+Compatibility


<a id="preparing"></a>
## Preparing Your Pi

If you have a working Raspberry Pi setup, you can probably just skip
ahead.

If you’ve just barely unpacked Raspbian onto an SD card and are now
trying to get the PiDP-8/I software distribution working on it, stop and
go through the [Rasbperry Pi documentation][rpd] first. At the absolute
minimum, run `raspi-config` and make sure the Localization settings are
correct. The defaults are for the United Kingdom, home of the Raspberry
Pi Foundation, so unless you live there, the defaults are probably not
correct out of the box.

[rpd]: https://www.raspberrypi.org/documentation/


<a id="unpacking"></a>
## Getting the Software onto Your Pi

If you're reading this file within an unpacked distribution of the
PiDP-8/I software, you may skip this section, because you have
already achieved its aim.
................................................................................
    above, so you can use Fossil to update your software to the current
    version at any time, as long as the Pi is connected to the Internet.


<a id="unpacking"></a>
### Unpacking the Software on Your Pi

Having transferred the distribution file onto your Pi, unpack it:




    $ tar xvf /path/to/pidp8i-VERSION.tar.gz





The file name will vary depending on what you downloaded and [how you
transferred it to the Pi](#transferring).  After unpacking it, you will
have a new directory beginning with `pidp8i`.  `cd` into that directory,
then proceed with the [configuration](#configuring) steps below.


<a id="help"></a>
### If You Need More Help

If the above material is not sufficient to get you started, you might
want to look at [the documentation][rpfd] provided by the Raspberry
................................................................................

This software distribution builds and installs in the same way as most
other Linux/Unix software these days.  The short-and-sweet is:

    $ ./configure && make && sudo make install

The `configure` step is generally needed only the first time you build
the software in a new directory.  You may want to add options, described
[below](#options).

Subsequent software updates and rebuilds should not require that you
re-run the `configure` step, even if you gave custom options. The build
system detects when the configuration is outdated and re-runs the
`configure` script with the same options. If for some reason that
automatic re-configuration fails, you can kick it off manually:

    $ make reconfig


The “`make`” step above will take quite a while to run, especially on
the slower Pi boards. The longest single step is building the OS/8 disk
packs from source media. Be patient; the build process almost certainly
isn’t frozen.



If you’re on a multi-core Pi, You can speed the build process up some by
running “`tools/mmake`” instead of directly calling “`make`”. It runs
Make in a mode that lets it do a lot of work in parallel, making better
use of your multiple CPU cores.  That OS/8 media rebuild step is choked
down to a single thread, though, so this won’t help with that.  (This is
a generic, portable script, so if you’re a software developer, feel free
to reuse `mmake` and `corecount` on your own systems.)

Only the `make install` step needs to be done via “`sudo`”.  For the
most part, we’ve tried very hard to minimize the places where you need
to use root privileges to get something done within the PiDP-8/I
software distribution.


<a id="using"></a>
## Using the Software


After running “`sudo make install`” the first time, you will have to log
out and back in to get the installation’s “bin” directory into your
`PATH`.

For the most part, this software distribution works like the [old stable
2015.12.15 distribution][osd]. Its [documentation][oprj] therefore
describes this software too, for the most part. Beyond that, you might
find our [Learning More](/#learning) links helpful.





The largest user-visible difference between the two software
distributions is that many of the shell commands are different:

1.  To start the simulator running in the background:

        $ pidp8i start

    This will happen automatically on reboot unless you disable the
    service, such as in order to run one of the various [forks of Deeper
    Thought][dt2].

2.  To attach the terminal you're working on to the simulator:

        $ pidp8i

    (Yes, it's the same base command as above.  The `pidp8i` script uses
    its first argument to determine what you want it to do.  Without
    arguments, this is what it does.)

3.  To detach from the simulator's terminal interface while leaving the
    PiDP-8/I simulator running, type <kbd>Ctrl-A d</kbd>.  You can
    re-attach to it later with a `pidp8i` command.

4.  To shut the simulator down while attached to its terminal interface,
    type <kbd>Ctrl-E</kbd> to pause the simulator, then at the `simh>`
    prompt type `quit`.  Type `help` at that prompt to get some idea of
    what else you can do with the simulator command language, or read
    the [SIMH Users' Guide][sdoc].

5.  To shut the simulator down from the Raspbian command line:

        $ pidp8i stop

There are [other significant differences][mdif] between the old stable
distribution and this one. You’ll want to be familiar with that
documentation’s content before reading Oscar Vermeulen’s documentation,
as it still refers to his last release in December 2015.


<a id="systemd" name="unit"></a>
## The systemd Unit File

Starting with release 2019.04.25, the PiDP-8/I software distribution is
based on [systemd][systemd], since Raspbian is now on its third
systemd-based release.

One of the features systemd gives us is the ability to set the unit to
run as user-level service rather than as a system-wide service, which
means you no longer need the `sudo` prefix on commands to start, stop,
restart, and query the service. The only time you now need root
privileges when working with the PiDP-8/I software is when installing
it. After that, the software runs under your normal user account, as do
all of the commands you use to manipulate the background simulator
service.

As a result of these changes, none of these commands work any longer:

    $ sudo /etc/init.d/pidp8i start
    $ sudo service pidp8i stop
    $ sudo systemctl restart pidp8i

The correct forms, respectively, are:

    $ systemctl --user start pidp8i
    $ systemctl --user stop pidp8i
    $ systemctl --user restart pidp8i

These commands are long, so we have extended the `pidp8i` command to
build and run `systemctl` commands for you when you pass it arguments:

    $ pidp8i start
    $ pidp8i stop
    $ pidp8i restart
    $ pidp8i status -l

If you run it without arguments, it attaches to the GNU screen(1)
session, just as it always has.

The last command above shows that *all* arguments are passed to
`systemctl`, not just the first, so you can pass any flags that
`systemctl` accepts.

Our systemd service starts at boot by default after you install the
software. To disable the service so you can run something else against
the PiDP-8/I front panel hardware instead, such as Deeper Thought 2:

    $ pidp8i stop
    $ pidp8i disable

If you install this release on a system that has the old SysV init
script on it, that service will be disabled and removed before we
install and enable the replacement systemd user service.

[svinit]:  https://en.wikipedia.org/wiki/Init#SysV-style
[systemd]: https://www.freedesktop.org/wiki/Software/systemd/


<a id="options"></a>
### Configure Script Options

You can change many things about the way the software is built and
installed by giving options to the `configure` script:
................................................................................
switches on the front panel.  After you are done testing, you can start
the PiDP-8/I simulator back up with:

    $ pidp8i start

See [its documentation][test] for more details.














































<a id="sshd"></a>
## Enabling the SSH Server on the Binary OS Images

The OpenSSH server is enabled and running by default on the PiDP-8/I
binary OS images, but for security reasons, the build process we use
to create these OS images wipes out the SSH host keys generated here
................................................................................

You may be wondering why we don’t do this automatically, somehow. It’s
because, over time, we’ve removed all dependence on root access in our
software in the name of security, so that we no longer have permission
to make system-wide changes like this in our startup scripts.  We now
rely on you, the system’s administrator, to do it interactively with
`sudo` permissions.

































































## License

Copyright © 2016-2019 by Warren Young. This document is licensed under
the terms of [the SIMH license][sl].