PiDP-8/I Software

        $ 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="runtime"></a>
## Runtime Configuration

The `pidp8i` command may be configured by the optional `pidp8i.rc` file,
located by default in `/opt/pidp8i/etc/`.  This is a Bourne shell script
which is sourced by `pidp8i` if it exists, and recognizes the following
variables:


<a id="rc-screen-manager"></a>
### SCREEN_MANAGER=screen

By default, pidp8i installs and uses [GNU screen(1)][gnuscreen] to
manage screen sessions.  However, if you prefer to use [tmux(1)][tmux]
as a screen manager for the pidp8i session, you may set
`SCREEN_MANAGER=tmux`.  Note that if you make this change, you are
responsible for installing tmux; on Raspbian, this is done by:

        $ sudo apt-get install tmux

Switching between configured screen managers must be done while pidp8i
is stopped.

[gnuscreen]: https://www.gnu.org/software/screen/
[tmux]:      https://tmux.github.io/


<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.

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 screen manager
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

#!/bin/bash
########################################################################
# pidp8i.in - Collection of scriptlets for dealing with the pidp8i
#   systemd user service and its associated screen manager session.
#
# Copyright © 2015-2019 Oscar Vermeulen and Warren Young
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,

bootdir="@BOOTDIR@"
prefix="@ABSPREFIX@"
sim="$prefix/bin/pidp8i-sim"
scanswitch="$prefix/libexec/scanswitch"
systemctl=$(uname -r | grep -qw Microsoft && echo /bin/nothing || echo /bin/systemctl)
ggrep=$(which ggrep grep 2> /dev/null | head -1)

if [ -e "$prefix/etc/pidp8i.rc" ]
then
    . "$prefix/etc/pidp8i.rc"
fi
[ -n "$SCREEN_MANAGER" ] || SCREEN_MANAGER=screen

is_running() {
    if [ "$SCREEN_MANAGER" = "tmux" ]
    then
        tmux has-session -t pidp8i 2>/dev/null
    else
        procs=`screen -list pidp8i | $ggrep -Pc '\d\.pidp8i'`
        test -n "$procs" && test $procs -gt 0 && return 0 || return 1
    fi
}

sim_child_pid() {
    if [ "$SCREEN_MANAGER" = "tmux" ]
    then
        tmux list-sessions -F '#{session_name} #{pid}' | awk '/^pidp8i / {print $2}'
    else
        screen -ls pidp8i | grep -Eo '[[:digit:]]+\.pidp8i' | grep -Eo '^[[:digit:]]+'
    fi
}

# Were we given a command line argument?
if [ -z "$1" ]
then
    # No, so just try to attach to the running simulator
    if is_running
    then
        echo Joining simulator session already in progress...
        if [ "$SCREEN_MANAGER" = "tmux" ]
        then
            exec tmux attach-session -d -t pidp8i
        else
            exec screen -r -S pidp8i
        fi
    else
        cat <<ERROR
Either the simulator isn't running, or it isn't running under a ${SCREEN_MANAGER}(1)
session owned by @INSTUSR@.  Did you start the simulator via systemd?

ERROR
		exit 1
    fi
fi

    fi

    # We want SIMH to have a sensible working directory: somewhere the
    # user can write files and which makes sense when giving SIMH
    # commands involving file paths.  This default is chosen because it
    # satisfies both criteria.
    # If you change the default here, change that script as well.
    set -e
    cd "$prefix/share/media"
    if [ "$SCREEN_MANAGER" = "tmux" ]
    then
        tmux new-session -s pidp8i -d "$sim" "$bscript"
    else
        screen -dm -S pidp8i "$sim" "$bscript"
    fi
    if [ -x $systemctl ]
    then
        systemd-notify --ready --pid=$(sim_child_pid)
    fi
    exit 0

elif [ "$verb" = "stop" ]
then
    # Someone (maybe the user via "pidp8i stop", maybe systemd via
    # "systemctl pidp8i stop") is telling us to stop the background
    # simulator.
    #
    # First figure out what the simulator is called and send it the
    # signal that shuts it down gracefully.
    for sim in pdp8 pidp8i-sim
    do
        if pkill -0 $sim
        then
            # Give it the signal to start shutting down gracefully: stop
            # GPIO thread, save simulator state if savestate enabled...
            # Give it time to complete, then kill it hard in case it
            # doesn't die on its own.
            echo -n "Stopping $sim simulator..."
            for sig in TERM KILL ; do pkill -$sig $sim ; sleep 1 ; done

            # The screen manager might still be running despite its
            # only child dying.  Nuke it hard if so.
            if is_running
            then
                if [ "$SCREEN_MANAGER" = "tmux" ]
                then
                    tmux kill-session -t pidp8i
                else
                    screen -S pidp8i -X quit
                fi
            fi

            exit 0
        fi
    done 

    exit 1
fi