PiDP-8/I Software

inst
test

*.mk

bin/*.pt
bin/*.rk05
bin/*.save
bin/*.tu56
bin/cc8
bin/d8tape
bin/os8-cp
bin/os8-run
bin/os8pkg
bin/palbart
bin/pdp8
bin/pidp8i
bin/pidp8i-sim
bin/pidp8i-test
bin/ptp2txt
bin/teco-pi-demo
bin/txt2ptp

boot/?.script
boot/ac-mq-blinker.script
boot/add.script
boot/asr33-rim-loader.script
boot/bit-rotate.script
boot/common.script
boot/hello.script
boot/hs-rim-loader.script
boot/pep001.script
boot/run-v3f.script
boot/run.script
boot/tss8.script

config.log

etc/*.service
etc/sudoers

lib/*.py
lib/*__pycache__/*.pyc

libexec/scanswitch

logfile.txt

Makefile
*/Makefile

media/os8/3finit.tx
media/os8/init.tx
media/os8/ock-init.tx

obj/*

src/config.h
src/os8/v3f/logfile.txt
src/pidp8i/gpio-common.c
src/pidp8i/main.c

tools/simh-update

examples/*.fc

hardware/pidp8i/*.cmp
hardware/pidp8i/*.dsn
hardware/pidp8i/*.kicad_pcb
hardware/pidp8i/*.lib
hardware/pidp8i/*.mod
hardware/pidp8i/*.pro
hardware/pidp8i/*.sch

src/*.[ch]
src/*.in

src/cc8/*/*.[ch]
src/cc8/include/*
src/cc8/os8/*.sb
src/cc8/os8/bldcc8.bi
src/cc8/os8/*.[ch]
src/cc8/os8/*.bi
src/cc8/os8/*.sb

src/PDP8/pdp8_*.[ch]
src/PDP8/pidp8i.c.in

autosetup/Makefile
doc/simh/*.pdf
test/*

name: ci
on: [push, pull_request]
jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest]
    steps:
    - uses: actions/checkout@v2
    - name: Dependency packages (ubuntu)
      run: sudo apt-get -y install build-essential python3-pexpect python3-yaml libncurses-dev
      if: ${{ matrix.os == 'ubuntu-latest' }}
    - name: Dependency packages (macos)
      run: |
        brew install coreutils ncurses
        pip3 install pexpect pyyaml
      if: ${{ matrix.os == 'macos-latest' }}
    - name: configure
      run: ./configure
    - name: make
      run: ./tools/mmake
    - name: make install-target
      run: make install-target DESTDIR=${GITHUB_WORKSPACE}/destdir
    - name: Build artifact tarball
      run: |
        mkdir -p ${GITHUB_WORKSPACE}/artifacts
        tar zcvf ${GITHUB_WORKSPACE}/artifacts/${{ github.job }}-${{ github.run_id }}.${{ github.run_number }}-${{ matrix.os }}.tar.gz -C ${GITHUB_WORKSPACE}/destdir .
    - name: Upload artifacts
      uses: actions/upload-artifact@v2
      with:
        name: ci-${{ github.job }}-${{ github.run_id }}.${{ github.run_number }}-${{ matrix.os }}
        path: artifacts/*.tar.gz

.agignore
inst
test

    and primary developer of the system that builds the OS/8 media
    images from source tapes. He first greatly extended the `mkos8`
    script then replaced it entirely as `os8-run`. He curated the tape
    collections we ship as `media/.../*.tu56`, created some of those
    tapes, and more. He has also contributed to other areas of the
    software project. His contributions are made to the project [as
    `poetnerd`][pncomm].

*   **[Bill Silver](mailto:bsilver@tidewater.net)** created E8, an
    Emacs-like editor for the PDP-8.  See [its `AUTHORS.md` file][e8au]
    for more info.

*   **[Warren Young](mailto:tangentsoft@gmail.com)** Did everything
    listed in [the change log][cl] that is not attributed to anyone
    else.

    His contributions are made to the project [as `tangent`][wycomm],
    though keep in mind that some of those are commits of external
    contributions made by people who do not have commit rights on our
    software repository. The changelog provides proper attribution for
    these where the checkin comments do not.

[advent]: http://www.rickmurphy.net/advent/
[cl]:     https://tangentsoft.com/pidp8i/doc/trunk/ChangeLog.md
[e8au]:   ./src/e8/AUTHORS.md
[pncomm]: https://tangentsoft.com/pidp8i/timeline?u=poetnerd
[thcomm]: https://tangentsoft.com/pidp8i/timeline?u=tony
[vtedit]: https://tangentsoft.com/pidp8i/wiki?name=Using+VTEDIT
[wycomm]: https://tangentsoft.com/pidp8i/timeline?u=tangent

# Contributing to the PiDP-8/I Project

If you wish to make any changes to [the project’s files][home], here are
some rules and hints to keep in mind while you work.

[home]: https://tangentsoft.com/pidp8i/


## <a id="gs-fossil"></a> Getting Started with Fossil

The PiDP-8/I software project is hosted using the Fossil
[distributed version control system][dvcs], which provides most of the
features of GitHub without [the complexities of Git][fvg].

Those new to Fossil should at least read its [Quick Start Guide][fqsg].
If you want to go deeper, [the Schimpf book][fbook] is somewhat
outdated, but it is still the best single coherent tutorial on Fossil.
Those coming from Git will benefit from the approach taken by the
“[Git to Fossil Translation Guide][gitusr].”

[The official Fossil docs][fdoc] are much more up to date, but they take
a piecemeal approach to topics, rather than the linear tutorial approach
of a book, so it is not my first recommendation for learning Fossil.
Those docs are better for polishing your skills and for reference after
you know Fossil reasonably well.

If you have questions about Fossil, ask on [the Fossil forum][ffor]
where I, your humble project maintainer, am active. I also work on the
Fossil docs quite a bit, so if your question really isn’t answered
somewhere in the above material, I might just solve it by extending the
Fossil docs.

Fossil is pre-installed on our [binary OS images][bosi] since April
2017.

When starting from Debian-based OSes released in June 2019 or newer,
this will work:

    $ sudo apt install fossil

Older Debian-based OSes will give you Fossil 1.*x*, which won’t work with
our repository, which requires Fossil 2.1 or higher. If you can’t
upgrade your host OS, you’ll have to [build Fossil from source][bffs].

Fossil is also available for all common desktop platforms. If your OS
package repository doesn’t include Fossil 2.1 or higher already, one of
the [precompiled binaries][fbin] may work on your system.


[bffs]:   https://fossil-scm.org/home/doc/trunk/www/build.wiki
[bosi]:   https://tangentsoft.com/pidp8i#bosi
[fbin]:   https://fossil-scm.org/index.html/uv/download.html
[fvg]:    https://fossil-scm.org/home/doc/trunk/www/fossil-v-git.wiki
[dvcs]:   https://en.wikipedia.org/wiki/Distributed_revision_control
[fbook]:  https://www.fossil-scm.org/schimpf-book/home
[fdoc]:   https://fossil-scm.org/home/doc/trunk/www/permutedindex.html
[ffor]:   https://fossil-scm.org/forum/
[fqsg]:   https://fossil-scm.org/home/doc/trunk/www/quickstart.wiki
[gitusr]: https://fossil-scm.org/home/doc/trunk/www/gitusers.md


## <a id="fossil-anon" name="anon"></a> Fossil Anonymous Access

There are three ways to clone the repository anonymously using Fossil.
Each of these methods gets you a file called `pidp8i.fossil` containing
the full history of the PiDP-8/I software project from the upstream
2015.12.15 release onward.

You only need to take one of these options, once per machine.
Thereafter, you will just be working with the cloned repository.


### One-Step Clone-and-Open <a id="one-step-open"></a>

The easiest way requires Fossil 2.14 or higher:

    $ fossil clone https://tangentsoft.com/pidp8i
    $ cd pidp8i

That gets you a clone of the `pidp8i.fossil` repository plus a check-out
of the current trunk in a `pidp8i/` directory alongside it. We recommend
that you do this in a directory like `~/src` so you don’t commingle
these files with other things in your current working directory.


### Open from URI <a id="open-uri"></a>

If you have Fossil 2.12 or 2.13, the next-easiest method is:

    $ mkdir -p ~/src/pidp8i
    $ cd ~/src/pidp8i
    $ fossil open https://tangentsoft.com/pidp8i

This opens the repository referenced by that URI into the current
directory as `pidp8i.fossil`, then opens that repo into that same
subdirectory.

You have to create the destination directory first with this method
because Fossil will refuse to spam a non-empty directory with the
check-out contents when opening the repo into a directory containing
other files unless you give it the `--force` flag.

Notice that the repo file ends up *inside* the check-out tree with this
method. This is because of a purposeful semantic difference in Fossil
between “open” and “clone.” It may seem strange to someone coming from
Git, but while we don’t want to get into the whys and wherefores here,
realize there is logic behind this choice.


### Separate Clone and Open <a id="sep-clone-open"></a>

The complicated method works with all versions of Fossil back to 2.1,
and it is the one we recommend to people who want to get involved with
the project, because it has [numerous advantages][cowf] over the easy
methods. We’ll explain those benefits in the context of the PiDP-8/I
project later, but for now, the method is:

    $ mkdir -p ~/museum ~/src/pidp8i/trunk
    $ fossil clone https://tangentsoft.com/pidp8i ~/museum/pidp8i.fossil
    $ cd ~/src/pidp8i/trunk
    $ fossil open ~/museum/pidp8i.fossil

[cowf]: https://fossil-scm.org/home/doc/trunk/www/ckout-workflows.md


## <a id="login"></a> Fossil Developer Access

If you have a developer account on the `tangentsoft.com/pidp8i` Fossil
instance, just add your username to the URL like so:

    $ fossil clone https://USERNAME@tangentsoft.com/pidp8i pidp8i.fossil

If you’ve already cloned anonymously, simply tell Fossil about the new
sync URL instead:

    $ cd ~/src/pidp8i/trunk
    $ fossil sync https://USERNAME@tangentsoft.com/pidp8i

Either way, Fossil will ask you for the password for `USERNAME` on the
remote Fossil instance, and it will offer to remember it for you. If
you let it remember the password, operation from then on is scarcely
different from working with an anonymous clone, except that on checkin,
your changes will be sync’d back to the repository on tangentsoft.com if
you’re online at the time, and you’ll get credit under your developer
account name for the checkin.

If you’re working offline, Fossil will still do the checkin locally, and
it will sync up with the central repository after you get back online.
It is best to work on a branch when unable to use Fossil’s autosync
feature, as you are less likely to have a sync conflict when attempting
to send a new branch to the central server than in attempting to merge
your changes to the tip of trunk into the current upstream trunk, which
may well have changed since you went offline.

You can purposely work offline by disabling autosync mode:

    $ fossil set autosync 0

Until you re-enable it (`autosync 1`) Fossil will stop trying to sync
your local changes back to the central repo. In this mode, Fossil works
more like Git’s default mode, buying you many of the same problems that
go along with that working style. I recommend disabling autosync mode
only when you are truly going to be offline and don’t want Fossil
attempting to sync when you know it will fail.


## <a id="gda"></a> Getting Developer Access

We’re pretty open about giving developer access to someone who’s
provided at least one good, substantial [patch](#patches) to the
software. If we’ve accepted one of your patches, just ask for a
developer account [on the forum][pfor].


## <a id="tags" name="branches"></a> Working with Existing Tags and Branches

The directory structure shown in the [separate clone and
open](#sep-clone-open) sequence above is more complicated than strictly
necessary, but it has a number of nice properties.

First, it collects software projects under a common top-level
directory. I’ve used `~/src` for this example, but you are free to use any scheme
you like.

Second, the level underneath the project directory (`~/src/pidp8i`) stores multiple separate
checkouts, one for each version the developer is actively working with at the moment,
so to add a few other checkouts, you could say:

    $ cd ~/src/pidp8i
    $ mkdir -p release          # another branch
    $ mkdir -p v20151215        # a tag this time, not a branch
    $ mkdir -p 2019-04-01       # the software as of a particular date
      ...etc...
    $ cd release
    $ fossil open ~/museum/pidp8i.fossil release
    $ cd ../v20151215
    $ fossil open ~/museum/pidp8i.fossil v20151215
    $ cd ../2019-04-01
    $ fossil open ~/museum/pidp8i.fossil 2019-04-01
      ...etc...

This gives you multiple independent checkouts, which allows you to
quickly switch between versions with “`cd`” commands. The alternative
(favored by Git and some other version control systems) is to use a
single working directory and switch among versions by updating that
single working directory in place. The problem is that this
invalidates all of the build artifacts tied to changed files, so you
have a longer rebuild time than simply switching among check-out
directories. Since disk space is cheap these days — even on a small
Raspberry Pi SD card – it’s better to have multiple working states and
just “`cd`” among them.

When you say `fossil update` in a check-out directory, you get the “tip”
state of that version’s branch. This means that if you created your
“`release`” check-out while version 2017.01.23 was current and you say
“`fossil update`” today, you’ll get the release version 2019.04.25 or
later. But, since the `v20151215` tag was made on trunk, saying
“`fossil update`” in that check-out directory will fast-forward you to the tip of
trunk; you won’t remain pinned to that old version. This is one of the
essential differences between tags and branches in Fossil, which are at
bottom otherwise nearly identical.

The PiDP-8/I project uses tags for [each released version][tags], and it
has [many working branches][brlist]. You can use any of those names in
“`fossil open`” and “`fossil update`” commands, and you can also use any
of [Fossil’s special check-in names][fscn].

[brlist]: https://tangentsoft.com/pidp8i/brlist
[fscn]:   https://fossil-scm.org/home/doc/trunk/www/checkin_names.wiki
[fvg]:    https://fossil-scm.org/home/doc/trunk/www/fossil-v-git.wiki
[gitwt]:  https://git-scm.com/docs/git-worktree
[tags]:   https://tangentsoft.com/pidp8i/taglist


## <a id="branching"></a> Creating Branches

Creating a branch in Fossil is scary-simple, to the point that those
coming from other version control systems may ask, “Is that really all
there is to it?” Yes, really, this is it:

    $ fossil ci --branch new-branch-name

That is to say, you make your changes as you normally would; then when
you go to check them in, you give the `--branch` option to the
`ci/checkin` command to put the changes on a new branch, rather than add
them to the same branch the changes were made against.

While developers with login rights to the PiDP-8/I Fossil instance are
allowed to check in on the trunk at any time, we recommend using
branches whenever you’re working on something experimental, or where you
can’t make the necessary changes in a single coherent checkin.

One of this project’s core principles is that `trunk` should always
build without error, and it should always function correctly. That’s an
ideal we have not always achieved, but we do always *try* to achieve it.

Contrast branches, which PiDP-8/I developers may use to isolate work
until it is ready to merge into the trunk. It is okay to check work in
on a branch that doesn’t work, or doesn’t even *build*, so long as the
goal is to get it to a point that it does build and work properly before
merging it into trunk.

Here again we have a difference with Git: because Fossil normally syncs
your work back to the central repository, this means we get to see the
branches you are still working on. This is a *good thing*. Do not fear
committing broken or otherwise bad code to a branch. [You are not your
code.][daff] We are software developers, too: we understand that
software development is an iterative process, that not all ideas
spring forth perfect and production-ready from the fingers of its
developers. These public branches let your collaborators see what
you’re up to; they may be able to lend advice, to help with the work, or
to at least be unsurprised when your change finally lands in trunk.

Fossil fosters close cooperation, whereas Git fosters wild tangents that
never come back home.

Jim McCarthy (author of [Dynamics of Software Development][dosd]) has a
presentation on YouTube that touches on this topic at a couple of
points:

*   [Don’t go dark](https://www.youtube.com/watch?v=9OJ9hplU8XA)
*   [Beware of a guy in a room](https://www.youtube.com/watch?v=oY6BCHqEbyc)

Fossil’s sync-by-default behavior fights these negative tendencies.

PiDP-8/I project developers are welcome to create branches at will. The
main rule is to follow the branch naming scheme: all lowercase with
hyphens separating words. See the [available branch list][brlist] for
examples to emulate.

If you have checkin rights on the repository, it is generally fine to
check things in on someone else’s feature branch, as long as you do so
in a way that cooperates with the purpose of that branch. The same is
true of `trunk`: you should not check something in directly on the trunk
that changes the nature of the software in a major way without
discussing the idea first. This is yet another use for branches: to
make a possibly-controversial change so that it can be discussed before
being merged into the trunk.

[daff]: http://www.hanselman.com/blog/YouAreNotYourCode.aspx
[dosd]: http://amzn.to/2iEVoBL


## <a id="special"></a> Special Branches

Most of the branches in the PiDP-8/I project are feature branches of the
sort described in the previous section: an isolated line of development
by one or more of the project’s developers to work towards some new
feature, with the goal of merging that feature into the `trunk` branch.

There are a few branches in the project that are special, which are
subject to different rules than other branches:

*   **<code>release</code>** — One of the steps in the
    [release process][relpr] is to merge the stabilized `trunk` into the
    `release` branch, from which the release tarballs and binary OS
    images are created. Only the project’s release manager — currently
    Warren Young — should make changes to this branch.

*   **<code>bogus</code>** or **<code>BOGUS</code>** — Because a branch
    is basically just a label for a specific checkin, Fossil allows the tip
    of one branch to be “moved” to another branch by applying a branch
    label to that checkin. We use this label when someone makes a
    checkin on the tip of a branch that should be “forgotten.” Fossil
    makes destroying project history very difficult, on purpose, so
    things moved to the “bogus” branch are not actually destroyed;
    instead, they are merely moved out of the way so that they do not
    interfere with that branch’s normal purpose.

    If you find yourself needing to prune the tip of a branch this way,
    the simplest way is to do it via the web UI, using the checkin
    description page’s “edit” link. You can instead do it from the
    command line with the `fossil amend` command.

[relpr]: https://tangentsoft.com/pidp8i/doc/trunk/doc/RELEASE-PROCESS.md


## <a id="forum"></a> Developer Discussion Forum

The “[Forum][pfor]” link at the top of the Fossil web interface is for
discussing the development of the PiDP-8/I software only. All other
traffic should go to [the end-user focused mailing list][ggml] instead. We’re not trying
to split the community by providing a second discussion forum; we just
think many development-related discussions are too low-level to be of
any interest to most of the people on the mailing list.

You can sign up for the forums without having a developer login, and you
can even post anonymously. If you have a login, you can [sign up for
email alerts][alert] if you like.

Keep in mind that posts to the Fossil forum are treated much the same
way as ticket submissions and wiki articles. They are permanently
archived with the project. The “edit” feature of Fossil forums just
creates a replacement record for a post, but the old post is still
available in the repository. Don’t post anything you wouldn’t want made
part of the permanent record of the project!

[ggml]: https://groups.google.com/forum/#!forum/pidp-8
[pfor]: https://tangentsoft.com/pidp8i/forum
[alert]: https://tangentsoft.com/pidp8i/alerts


## <a id="debug"></a> Debug Builds

By default, the build system creates a release build, but you can force
it to produce a binary without as much optimization and with debug
symbols included:

    $ ./configure --debug-mode
    $ make clean
    $ tools/mmake


## <a id="build-system"></a> Manipulating the Build System Source Files

The [autosetup build system][asbs] is composed of these files and
directories:

    auto.def
    autosetup/*
    configure
    Makefile.in

Unlike with GNU Autoconf, which you may be familiar with, the
`configure` script is not output from some other tool. It is just a
driver for the generic Tcl and C code under the `autosetup` directory,
which in turn runs the project-specific `auto.def` Tcl script to
configure the software. Some knowledge of [Tcl syntax][tcldoc] will
therefore be helpful in modifying `auto.def`.

If you have to modify any of the files in `autosetup/` to get some
needed effect, you should try to get that change into the upstream
[Autosetup][asbs] project, then merge that change down into the local
copy when it lands upstream.

If you do not have Tcl installed on your system, `configure` builds a
minimal Tcl interpreter called `jimsh0`, based on the [Jim Tcl][jim]
project. Developers working on the build system are encouraged to use
this stripped-down version of Tcl rather than “real” Tcl because Jim Tcl
is a mostly-pure subset of Tcl, and `jimsh0` is a subset of the complete
Jim Tcl distribution, so any changes you make that work with the
`jimsh0` interpreter should also work with “real” Tcl, but not vice
versa. If you have Tcl installed and don’t really need it, consider
uninstalling it to force Autosetup to build and use `jimsh0` to ensure
that your changes to `auto.def` work on both interpreters.

The `Makefile.in` file is largely a standard [GNU `make`][gmake] file
excepting only that it has variables substituted into it by Autosetup
using its `@VARIABLE@` syntax. At this time, we do not attempt to
achieve compatibility with other `make` programs, though in the future
we may need it to work with [BSD `make`][bmake] as well, so if you are
adding features, you might want to stick to the common subset of
features implemented by both the GNU and BSD flavors of `make`. We do
not anticipate any need to support any other `make` flavors.

This, by the way, is why we’re not using some heavy-weight build system
such as the GNU Autotools, CMake, etc.

The primary advantage of GNU Autotools is that you can generate
standalone source packages that will configure and build on weird and
ancient flavors of Unix. We don’t need that.

Cross-platform build systems such as CMake ease building the same
software on multiple disparate platforms, but the PiDP-8/I software is
built primarily on and for a single operating system, Raspberry Pi OS,
né Raspbian. It also happens to build and run on [several other
OSes][oscomp], for which we also do not need the full power of something
like CMake. Autosetup and GNU `make` suffice for our purposes here.

[asbs]:   http://msteveb.github.io/autosetup/
[bmake]:  https://www.freebsd.org/doc/en/books/developers-handbook/tools-make.html
[gmake]:  https://www.gnu.org/software/make/
[jim]:    http://jim.tcl.tk/
[oscomp]: https://tangentsoft.com/pidp8i/wiki?name=OS+Compatibility
[tcldoc]: http://wiki.tcl.tk/11485


## <a id="dirs"></a> Directory Structure

The directory structure of the PiDP-8/I project is as follows:

*   <b>`.`</b> — Top level, occupied only by the few files the end user
    of the source code needs immediately at hand on first unpacking the
    project: the top level build system files, key documentation, and
    licensing information. If a given file *can* be buried deeper, it
    *should* be buried to reduce clutter at this most precious level of
    the hierarchy.

*   <b>`.fossil-settings`</b> — Versioned settings for the Fossil build
    system which Fossil applies as defaults everywhere you check out a
    Fossil version. Settings made here are intended to be correct for
    all users of the system; think of these not as expressing defaults
    but as expressing *policy*. It is possible to override these
    settings, but we do not make settings here if we expect that some
    users may quibble with our choices here.

    Any setting whose value may vary between users of the Fossil
    repository should be done locally with a [`fossil setting` command][fscmd]
    rather than by creating or editing files in this subdirectory.

    See [the Fossil settings documentation][fset] for more on this.

*   <b>`autosetup`</b> — The bulk of the [Autosetup build system][asbs].
    These are generic files, not modified by the project itself. We
    occasionally run `tools/autosetup-update` to merge in upstream
    changes.

*   <b>`bin`</b> — Programs installed to `$prefix/bin`, which may also
    be run during development, if only to test changes to those
    programs. Some scripts stored here are written in place by the
    project’s developers, while other files in this directory are
    outputs of the build system.

    A subset of this directory’s content is copied to `$prefix/bin` at
    installation time, which is added to the user’s `PATH` by the
    `make install` script. We don’t copy the whole thing as-is because
    the build system places some files here that get installed to other
    locations or which don’t get installed at all.

*   <b>`boot`</b> — SIMH initialization scripts. The `*.script.in`
    files are written by the project developers but have local
    configuration values substituted in by the `configure` script to
    produce a `*.script` version. Scripts which need no config-time
    values substituted in are checked in directly as `*.script`. The
    `*.script` files in this directory which do not fall into either of
    those categories are outputs of `tools/mkbootscript`, which produces
    them from `palbart` assembly listings.

    All of these `*.script` files are copied to `$prefix/share/boot` by
    `make mediainstall` which runs automatically from `make install`
    when we detect that the binary media and SIMH boot scripts have
    never been installed at this site before. On subsequent installs,
    the user chooses whether to run `make mediainstall` by hand to
    overwrite all of this.

*   <b>`doc`</b> — Documentation files that can wait for new users to
    discover them, which do not need to be available immediately to the
    user on inspecting the tree for the first time.

    Fossil’s [embedded documentation][edoc] feature allows us to present
    the contents of `doc` to web site users all but indistinguishably
    from a wiki page.

    You may then ask, “Why are there two different ways to achieve the
    same end — embedded docs and the wiki — and how do we decide which
    mechanism to use?” Let us explore the differences before we answer
    the question.

    Fossil’s wiki feature behaves much like Wikipedia: it keeps change
    history for wiki documents, but it always presents the most recent
    version unless you go out of your way to manually dig up a
    historical version. This is true even if you’ve run `fossil ui` from
    a check-out directory where you’ve rolled back to a historical
    version. This doesn’t roll back the wiki to the same point in time;
    it continues showing the most recent version of each article.

    Embedded documentation — being files like any other committed to the
    repository — *are* rolled back to historical versions when you say
    something like `fossil update 2018-04-01` to see the software as of
    April Fool’s Day 2018. You see the embedded docs as of that date as
    well, unlike with the wiki.

    That leads us to the razor we use to decide where a given document
    lives.

    Use the wiki for evergreen content: material likely to remain
    correct for future versions of the software as well as the version
    contemporaneous with the initial version of the document. Also use
    the wiki for documention of conditions that change independently of
    the software’s version history, a good example being [our OS
    Compatibility wiki article][oscomp]. In either case, there is no tie
    between the software’s internal version history and changes out in
    the wider world, so the wiki’s always-current nature matches our
    needs well.

    The best case for using embedded documentation is when
    changes to the software are likely to require changes to the
    corresponding documentation, so that the commit changes both docs
    and code, keeping them in lock-step.

    When in doubt, use embedded documentation.

    The `doc/graphics` subdirectory holds JPEGs and SVGs displayed
    inline within wiki articles.

*   <b>`etc`</b> — Files which get copied to `/etc` or one of its
    subdirectories at installation time.

    There is an exception: `pidp8i.service.in` does not get installed to
    `/etc` at install time, but only because systemd’s [unit file load
    path scheme][uflp] is screwy: *some* unit files go in `/etc`, while
    others do not. The systemd docs claim we can put user units in
    `/etc/systemd/user` but this does not appear to work on a Raspberry
    Pi running Raspbian Stretch at least. We’ve fallen back to another
    directory that *does* work, which feels more right to us anyway, but
    which happens not to be in `/etc`. If systemd were designed sanely,
    we’d install such files to `$HOME/etc/systemd` but noooo…

    Since none of the above actually argues for creating another
    top-level repository directory to hold this one file, we’ve chosen
    to store it in `etc`.

*   <b>`examples`</b> — Example programs for the end user’s edification.
    Many of these are referenced by documentation files and therefore
    should not be renamed or moved, since there may be public web links
    referring to these examples.

*   <b>`hardware`</b> — Schematics and such for the PiDP-8/I board or
    associated hardware.

*   <b>`labels`</b> — Graphics intended to be printed out and used as
    labels for removable media.

*   <b>`lib`</b> — Library routines used by other programs, installed to
    `$prefix/lib`.

*   <b>`libexec`</b> — A logical extension of `lib`, these are
    standalone programs that nevertheless are intended to be run
    primarily by other programs. Whereas a file in `lib` might have its
    interface described by a programmer’s reference manual, the
    interface of a program in `libexec` is described by its usage
    message.

    Currently, there is only one such program, `scanswitch`, which si
    run primarily by `etc/pidp8i`. It is only run by hand when someone
    is trying to debug something, as in development.

    Programs in `libexec` are installed to `$prefix/libexec`, which is
    *not* put into the user’s `PATH`, on purpose. If a program should
    end up in the user’s `PATH`, it belongs in `bin`. Alternately, a
    wrapper may be put in `bin` which calls a `libexec` program as a
    helper.

*   <b>`media`</b> — Binary media images used either by SIMH directly or
    inputs consumed by tools like `os8-run` to *produce* media used by
    SIMH.

    The contents of this tree are installed to `$prefix/share/media`.

*   <b>`obj`</b> — Intermediate output directory used by the build
    system. It is safe to remove this directory at any time, as its
    contents may be recreated by `make`. No file checked into Fossil
    should be placed here.

    (Contrast `bin` which does have some files checked into Fossil; all
    of the *other* files that end up in `bin` can be recreated by
    `make`, but not these few hand-written programs.)

*   <b>`scripts`</b> — Scripts driving `os8-run`, most of which are
    invoked by the build system, though some are meant to be run by
    hand, such as the content of `scripts/test`.

*   <b>`src`</b> — Source code for the project’s programs, especially
    those that cannot be used until they are built. The great majority
    of these programs are written in C. The build system’s output
    directories are `bin`, `boot`, `libexec`, and `obj`.

    Programs that can be used without being “built,” example programs,
    and single-file scripts are placed elsewhere: `bin`, `examples`,
    `libexec`, `tools`, etc. Basically, we place such files where the
    build system *would* place them if they were built from something
    under `src`.

    This directory also contains PDP-8 source files of various sorts,
    mainly those used for building the SIMH media and the `os8pkg`
    packages. These are all “built” into other forms that then appear
    when running the simulator, rather than being used directly in this
    source code form.

    There are no program sources in the top level of `src`. The file
    `src/config.h` may appear to be an exception to that restriction,
    but it is *generated output* of the `configure` script, not “source
    code” *per se*.

    Multi-module programs each have their own subdirectory of `src`,
    each named after the program contained within.

    Single module programs live in `src/misc` or `src/asm`, depending on
    whether they are host-side C programs or PAL8 assembly programs.

*   <b>`test`</b> — Output directory used by `tools/test-*`.

*   <b>`tools`</b> — Programs run only during development and not
    installed.

    If a program is initially created here but we later decide that it
    should be installed for use by end users of the PiDP-8/I system, we
    move it to either `bin` or `libexec`, depending on whether it is run
    directly at the command line or run from some other program that is
    also installed, respectively.

[edoc]:  https://fossil-scm.org/home/doc/trunk/www/embeddeddoc.wiki
[fset]:  https://fossil-scm.org/home/doc/trunk/www/settings.wiki
[fscmd]: https://fossil-scm.org/home/help?cmd=setting
[uflp]:  https://freedesktop.org/software/systemd/man/systemd.unit.html#id-1.9


## <a id="patches"></a> Submitting Patches

If you do not have a developer login on the project repository, you can
still send changes to the project.

The simplest way is to say this after developing your change against
trunk:

    $ fossil diff > my-changes.patch

Then paste that into a [forum post][pfor] using a [fenced code
block][fcb]. We will also accept trivial patches not needing discussion
as text or attachments on [a Fossil ticket][tkt].

If you're making a patch against a PiDP-8/I distribution tarball, you can
generate a patch this way:

    $ diff -ruN pidp8i-olddir pidp8i-newdir > mychange.patch

The `diff` command is part of every Unix and Linux system, and should be
installed by default. If you're on a Windows machine, GNU diff is part
of [Cygwin](http://cygwin.com/) and [WSL]. Fossil is also available for
all of these systems. There are no excuses for not being able to make
unified diffs. :)

[fcb]: https://www.markdownguide.org/extended-syntax#fenced-code-blocks
[tkt]: https://tangentsoft.com/pidp8i/tktnew
[WSL]: https://docs.microsoft.com/en-us/windows/wsl/install-win10


#### Bundles Instead of Patches

If your change is more than a small patch, `fossil diff` might not
incorporate all of the changes you have made. The old unified `diff`
format can’t encode branch names, file renamings, file deletions, tags,
checkin comments, and other Fossil-specific information. For such
changes, it is better to send a [Fossil bundle][fb]:

    $ fossil set autosync 0                # disable autosync
    $ fossil checkin --branch my-changes
      ...followed by more checkins on that branch...
    $ fossil bundle export --branch my-changes my-changes.bundle

After that first `fossil checkin --branch ...` command, any subsequent
`fossil ci` commands will check your changes in on that branch without
needing a `--branch` option until you explicitly switch that checkout
directory to some other branch. This lets you build up a larger change
on a private branch until you’re ready to submit the whole thing as a
bundle.

Because you are working on a branch on your private copy of the
project’s Fossil repository, you are free to make as many checkins as
you like on the new branch before giving the `bundle export` command.

Once you are done with the bundle, upload it somewhere public and point
to it from a forum post or ticket.

[fb]: https://fossil-scm.org/home/help?cmd=bundle


#### Contribution Licensing

Submissions should include a declaration of the license you wish to
contribute your changes under. We suggest using the [SIMH license][simhl],
but any [non-viral][viral] [OSI-approved license][osil] should suffice.
We’re willing to tolerate viral licenses for standalone products; for
example, CC8 is under the GPL, but it’s fine because it isn’t statically
linked into any other part of the PiDP-8/I software system.

[osil]:  https://opensource.org/licenses
[simhl]: https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md
[viral]: https://en.wikipedia.org/wiki/Viral_license


#### <a id="ghm"></a> Can I Use GitHub Instead?

Although the PiDP-8/I project does have a [GitHub mirror][ghm], it is
intended as a read-only mirror for those heavily tied into Git-based
tooling. You’re welcome to send us a PR anyway, but realize that what’s
going to happen on the back end is that we’ll generate a patch, apply it
to the Fossil repo by hand, test it, and then commit it to the
repository under one of our existing Fossil developer accounts. Only
then do we update the mirror so that the change appears on GitHub; thus,
you don’t get GitHub credit for the PR. You avoid these problems by
simply asking for a developer account on the Fossil repo, so you can
commit there instead.

This is not simply because setting up bidirectional mirroring is
difficult, it is actually [impossible to achieve 100% fidelity][ghlim]
due to limitations of Git and/or GitHub. If you want a faithful clone of
the project repo, or if you wish to contribute to the project’s
development with full credit for your contributions, it’s best done via
Fossil, not via GitHub.

[ghlim]: https://fossil-scm.org/home/doc/trunk/www/mirrorlimitations.md
[ghm]:   https://github.com/tangentsoft/pidp8i/


## <a id="code-style"></a> The PiDP-8/I Software Project Code Style Rules

Every code base should have a common code style. Love it or
hate it, here are PiDP-8/I’s current code style rules:

**C Source Code**

File types: `*.c`, `*.h`, `*.c.in`

We follow the SIMH project’s pre-existing code style when modifying one
of its source files:

*   Spaces for indents, size 4; tabs are rendered size 8 in HTML output,
    since that’s how a PDP-8 terminal would likely interpret it!

*   DOS line endings. (Yes, even though this is a Linux-based project!
    All decent Linux text editors can cope with this.)

*   Function, structure, type, and variable names are all lowercase,
    with underscores separating words

*   Macro names are in `ALL_UPPERCASE_WITH_UNDERSCORES`

*   Whitespace in the SIMH C files is of a style I have never seen
    anywhere else in my decades of software development. This example
    shows the important features:

    ```C
    int some_function (char some_parameter)
    {
    int some_variable = 0;

    if (some_parameter != '\0') {
        int nbytes = sizeof (some_parameter);
        char *buffer = malloc (4 * nbytes);

        switch (some_parameter) {
            case 'a':
                do_something_with_buffer ((char *)buffer); 
            default:
                do_something_else ();
            }
        }
    else {
        some_other_function (with_a_large, "number of parameters",
            wraps_with_a_single, "indent level");
        printf (stderr, "Failed to allocate buffer.\n");
        }
    }
    ```

    It is vaguely like K&R C style except that:

    *   The top level of statements in a function are not indented

    *   The closing curly brace is indented to the same level as the
        statement(s) it contains

    *   There is a space before all opening parentheses, not just those
        used in `if`, `while`, and similar flow control statements.

        Nested open parentheses do not have extra spaces, however. Only
        the outer opening parenthesis has a space separating it from
        what went before.

    *   Multiple variables declared together don’t have their types and
        variable names aligned in columns.

    I find that this style is mostly sensible, but with two serious problems:
    I find the indented closing curly braces confusing, and I find that the
    loss of the first indent level for the statements inside a function makes
    functions all visually run together in a screenful of code. Therefore,
    when we have the luxury to be working on a file separate from SIMH,
    we use a variant of its style with these two changes, which you can
    produce with the `tools/restyle` command. See its internal comments for
    details.

    That gives the following, when applied to the above example:

    ```C
    int some_function (char some_parameter)
    {
        int some_variable = 0;

        if (some_parameter != '\0') {
            int nbytes = sizeof (some_parameter);
            char *buffer = malloc (4 * nbytes);

            switch (some_parameter) {
                case 'a':
                    do_something_with_buffer ((char *)buffer); 
                default:
                    do_something_else ();
            }
        }
        else {
            some_other_function (with_a_large, "number of parameters",
                wraps_with_a_single, "indent level");
            printf (stderr, "Failed to allocate buffer.\n");
        }
    }
    ```

    If that looks greatly different, realize that it is just two indenting
    level differences: add one indent at function level, except for the
    closing braces, which we leave at their previous position.

    SIMH occasionally exceeds 100-column lines. I recommend breaking
    long lines at 72 columns. Call me an 80-column traditionalist.

    When in doubt, mimic what you see in the current code. When still in
    doubt, ask on the [project forum][pfor].

[indent]: http://linux.die.net/man/1/indent


**Plain Text Files**

File types: `*.md`, `*.txt`

*   Spaces for indents, size 4.

*   Unix line endings. The only common text editor I’m aware of that
    has a problem with this is Notepad, and people looking at these
    files anywhere other than unpacked on a Raspberry Pi box are
    probably looking at them through the Fossil web interface on
    tangentsoft.com.

*   Markdown files must follow the syntax flavor understood by
    [Fossil’s Markdown interpreter][fmd].

[fmd]: https://tangentsoft.com/pidp8i/md_rules


## <a id="tickets"></a> Ticket Workflow

Normal end users of the Fossil ticket system are not expected to
understand it properly or to fill out tickets properly. Without certain
permissions, it is in fact not possible to completely fill out a ticket
properly. Project developers typically must triage, augment, and correct
submissions from the start.

Here’s the basic workflow for a “code defect” ticket, colloquially
called a bug report:

``` pikchr toggle indent
      fill = bisque
      linerad = 15px

      define diamond { \
        box wid 150% invis
        line from last.w to last.n to last.e to last.s close rad 0 $1
      }

      oval "SUBMIT TICKET" width 150%
      down
      arrow 50%
NEW:  file "New bug ticket" "marked \"Open\"" fit
      arrow same
      box "Triage," "augment &" "correct" fit
      arrow same
DC:   box "Developer comments" fit
      arrow same
FR:   box "Filer responds" fit
      arrow 100%
REJ:  diamond("Reject?")
      right
      arrow 100% "Yes" above
      box "Mark ticket" "\"Rejected\" &" "\"Resolved\"" fit with .w at previous.e
      arrow right 50%
REJF: file "Rejected" "ticket" fit
      arrow right 50%
REOP: diamond("Reopen?")
      down
REJA: arrow 75% from REJ.s "  No; fix it" ljust
CHNG: box "Developer changes code" with .n at last arrow.s fit
      arrow 50%
FIXD: diamond("Fixed?")
      right
FNO:  arrow "No" above
RES:  box "Optional:" "Update ticket resolution:" "\"Partial Fix\", etc." fit
      down
      arrow 75% "  Yes" ljust from FIXD.s
      box "Mark ticket" "\"Fixed\" & \"Closed\"" fit
      arrow 50%
RESF: file "Resolved ticket" fit
      arrow same
      oval "END"

      line from 0.3<FR.ne,FR.se> right even with 0.25 right of DC.e then \
          up even with DC.e then to DC.e ->

      line from NEW.w left 0.5 then down even with REJ.w then to REJ.w ->
      line invis from 2nd vertex of last line to 3rd vertex of last line \
          "fast reject path" above aligned

      line from RES.e right 0.3 then up even with CHNG.e then to CHNG.e ->

      line from REOP.s "No" aligned above down 0.4
      line from previous.s down to (previous.s, RESF.e) then to RESF.e ->

      line from REOP.n "Yes" aligned below up 0.3
      line from previous.n up even with 0.6<FR.ne,FR.se> then to 0.6<FR.ne,FR.se> ->
```

On noticing a new-filed ticket — such as because you are subscribed to
email notifications on ticket changes — someone with sufficient
privilege triages it, sets values for the fields not exposed to the
ticket’s filer, and fixes up any incorrect values given in the initial
submission.

The Status of a ticket initially starts out as Open; the filer cannot
change that default value, short-circuiting the process. If the person
triaging a ticket takes the time to check that the bug actually occurs
as the ticket filer claims, the Status should change to Verified.

If a developer implements a fix in response to a ticket, he
has two choices: change the ticket’s Status to “Review” if he wants
someone to check out the change before closing it, or go straight to
Closed status. Closing a ticket hides it from the [Wishes] and [Bugs] ticket
reports.

The process for software feature request and documentation improvement
request tickets is essentially the same, differing mainly in terminology
rather than process flow: instead of verifying the existence of a bug,
the one triaging the ticket verifies that the feature does in fact not
exist yet, and so on.

A common requrement in larger teams is that all ticket changes to go through Review
status before getting to Closed, but the PiDP-8/I project is too small
to require such ceremony: if we’ve given you a developer account on the
repository, you’re expected to resolve and close tickets in the same
step, most of the time. If you cannot confidently close a ticket when
resolving it, you should probably not be assigning a resolution yet
anyway. Do whatever you have to with tests and such to *become* certain
before you resolve a ticket.

There is a process interlock between the Resolution and Status settings
for a ticket: while Status is not Closed, Resolution should be Open.
When Resolution changes from Open, Status should change to either Review
or, preferentially, Closed. A resolution is an end state, not an
expression of changeable intent: no more ceremony than setting a
ticket’s Resolution state *away* from Open and its Status *to* Closed is
required.

If you do not intend to close a ticket but wish to advocate for a
particular resolution, just add a comment to the ticket and let someone
else choose whether to close the ticket or not. Don’t change the
Resolution value until the issue has been *resolved* for good.

For example, the resolution “Works as Designed” does not merely mean,
“Yes, we know it works that way,” it also implies “…and we have no
intention to change that behavior, ever.” If there is a chance that the
behavior described in the ticket could change, you should not assign any
resolution. Just leave it open until someone decides to do something
final with the ticket.

This is not to say that a ticket can never be re-opened once it’s had a
resolution assigned and been closed, but that this is a rare occurrence.
When a developer makes a decision about a ticket, it should be difficult
to re-open the issue. A rejected ticket probably shouldn’t be re-opened
with anything short of a working patch, for example:

> User A: I want feature X.

> Dev B: No, we’re not going to do that. Ticket closed and rejected.

> User C: Here’s a patch to implement feature X.

> Dev B: Well, that’s different, then. Thanks for the patch! Ticket
> marked Implemented, but still Closed.

[Bugs]:   https://tangentsoft.com/pidp8i/bugs
[Wishes]: https://tangentsoft.com/pidp8i/wishes


## License

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

[sl]: https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md

# Licenses

The PiDP-8/I software distribution is an agglomeration of software from
multiple sources.  Several different licenses apply to its parts.  This
file guides you to those individual licenses.


## <a id="simh"></a>SIMH License

Most of the files in this software distribution are released under the
terms of the SIMH license, a copy of which typically appears at the top
of each file it applies to. This includes not only SIMH proper but also
several files written by PiDP-8/I software project contributors who
chose to license their contributions under the same license.
chose to license their contributions under the same license, including
E8.

For a few files, textual inclusion of the license inside the file itself
was impractical, so this license is applied by reference to [a file
included with the distribution][sl].

[sl]: https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md

There is [another PDP-8 C compiler project][smsc] based on Small-C by
Vincent Slyngstad, which uses an entirely different approach for code
generation.  Ian Schofield took some of the library routines from this
implementation.

[ddj]:  https://en.wikipedia.org/wiki/Dr._Dobb%27s_Journal
[gpl3]: https://tangentsoft.com/pidp8i/doc/trunk/src/cc8/LICENSE.txt
[gpl3]: https://tangentsoft.com/pidp8i/doc/trunk/src/cc8/GPL3.txt
[smc]:  https://en.wikipedia.org/wiki/Small-C
[smsc]: http://so-much-stuff.com/pdp8/C/C.php


## <a id="os8"></a>OS/8 License

The OS/8 media images included with this software distribution are
released under the Digital License Agreement presented in
[`media/os8/LICENSE.md`][dla].

[dla]: https://tangentsoft.com/pidp8i/doc/trunk/media/os8/LICENSE.md


## <a id="dec"></a>Other DEC Software

The other files in the [`media`][md] and [`examples`][ed] directories
that originate from Digital Equipment Corporation are believed to fall
under the [public domain license][pdp8pd] DEC released all their PDP-8
under the [blanket public domain license][decpd] DEC released all their PDP-8
software under after it stopped being economically viable. Documented
releases for specific software (e.g. TSS/8) may be difficult to come by,
however.

[md]: https://tangentsoft.com/pidp8i/dir?ci=trunk&name=media
[ed]: https://tangentsoft.com/pidp8i/dir?ci=trunk&name=examples
[pdp8pd]: http://mailman.trailing-edge.com/pipermail/simh/2017-January/016164.html
[decpd]: http://mailman.trailing-edge.com/pipermail/simh/2017-January/016164.html


## <a id="etos"></a>ETOS License

ETOS was a commercial product produced outside of DEC. No public
documented declaration of license is known to be available for it, but
we have [a third-hand report][el] that its creators are fine with ETOS
being redistributed.

[el]: http://mailman.trailing-edge.com/pipermail/simh/2017-January/016169.html

# PiDP-8/I Changes

<a id="20210214"></a>
## Version 2021.02.14 — The Quarantine Release

*   Raspberry Pi 4 support.

*   Increased SD card requirement from 2 GB to 8 GB.  See
    [the OS images doc](doc/OS-images.md) for details.

*   Integrated Bill Silver’s E8 Emacs-like text editor for the PDP-8.

*   Updated Ian Schofield’s CC8 C compiler to V2.0:

    *   The OS/8 (“native”) compiler now has support for every K&R C
        1978 construct except for `struct`, `float`, and function
        pointers.  There are numerous compliance problems, but we’ve
        tried to document all of them in [`doc/cc8-manual.md`][cc8m].

        Most notably, this release adds support for `switch` and all of
        the remaining 2-character operators: `!=`, `>=`, `<=` and `?:`

    *   Added several more examples, including a Forth interpreter.

*   The software build now creates a [bootable RK05 disk image][OCK] of the
    [OS/8 Combined Kit (OCK)][kit] which is effectively the last
    official release of OS/8, with all patches. You can elect to use
    this for the IF=0 boot option instead of OS/8 V3D by configuring the
    software with the `--use-ock` flag.

    Bill Cattey did almost all of the work for this.

    Contrast the OS/8 V3F release, which wasn’t a formal release from
    DEC, but was rather V3D plus the Device Extensions Kit to support
    newer hardware that came out after V3D.

*   Added the [`os8pkg` package manager][os8pkg], allowing installation and
    uninstallation of packages on the installed RK05 OS/8 boot media,
    whether OCK or V3D. This is the new mechanism behind the existing
    `--with-os8-*` options, allowing you to get different feature sets
    on existing media without rebuilding it from scratch.  Bill Cattey
    did almost all of the work on this.

*   Many packages previously copied in as binary blobs have been shifted
    to the source tree to be built from source, or at the very least as
    individual binary files copied in from the source tree under code
    management.  This not only permits “clean” builds, it allows adding
    and removing packages from OS/8 media after installation, where
    previously you had to rebuild the entire medium after reconfiguring
    the source tree using `--enable-os8-*` type flags. Bill Cattey did
    this integration.

    The packages newly managed in this way are:

    *   [`advent`][adventrm]: The game of Adventure, built from
        [source][advsrc].

    *   [`basic-games`][gamesrm]: The collection of BASIC games and
        demos.  Although this is a [collection of ASCII text
        files][bgsrc], and OS/8 BASIC is an interpreter of those text
        program files, not a compiler, we still build this package of
        PDP-8 ASCII text files from POSIX ASCII text files.

        This not only permits later package add and remove options, it
        also allows fun things like editing the sources on the Pi side,
        rebuilding the package, and reinstalling, rather than editing
        the sources directly under OS/8.  Or, skip the middleman and use
        [`os8-cp`][os8cp] to copy the edited version to the boot media.

    *   [`cc8`][cc8m]: Ian Schofield's C compiler was always built from
        [source][cc8src], but now it’s built to an intermediate package
        rather than copied straight to the OS/8 boot media.

    *   [`chekmo`][chekmorm]: The Chekmo II chess playing program, built
        from [source][ckmsrc].

    *   [`dcp`][dcprm]: The OS/8 PDP-8 dissassembler, built from binary
        executables, since source has apparently been lost.

    *   [`e8`][e8man]: Bill Silver's E8 editor, built from
        [source][e8src].

    *   [`focal69`][focalrm]: The first DEC FOCAL interpreter, built
        from [source][f69src].

    *   [`kermit`][kermitrm]: The communication and text encode/decode
        suite, built from [source][krmsrc].

    *   [`lcmod`][lcsrc]: The batch scripts `UCSYS.BI`, `LCSYS.BI`,
        `UCBAS.BI` and `LCBAS.BI` are now under source control. Being
        patches to OS/8, the sources are scattered within our [OS/8
        source subtree][os8src].

    *   [`music`][musicrm]: The PDP-8 Music compiler is now built from
        [source][mussrc] with the scores under source control. Note that
        we still can't actually hear the output owing to lack of
        connection between the sound generation and SIMH.

    *   [`uwfocal`][uwfocalrm]: The U/W FOCAL interpreter. The main
        module is built from [source][uwfsrc], but other components are
        considered legacy and treated as binary blobs for now. This is
        documented in the `uwfocal.pspec` file.

    *   [`vtedit`][vteditdoc]: The VT screen editor extensions to TECO
        are now packaged separately, built from [source][vtesrc].

*   Added [`os8-progtest`][progtest] tool for testing software under OS/8. Tests
    in `pyyaml` format create state machines for starting programs
    engaging in run dialogs, and confirming success. Test harnesses
    exist for advent, cc8, chekmo, uwfocal, and basic-games. Bill Cattey
    did almost all the work on this.

*   The distribution now follows a [documented testing protocol][testing].

*   [Configurable screen manager][rmsm], allowing either tmux or "none"
    as an alternative to GNU screen.  Initial work on this feature done
    by Ryan Finnie.

*   Updated the PiDP-8/I KiCad hardware files to Oscar Vermeulen’s 2019
    kit version.

*   Integrated the octal comparison tool `ocomp` into the lower level
    `dist-v3d.rk05` and `dist-ocomp.rk05` images. Used for validation of
    packages installed by `os8pkg`. Integration by Bill Cattey.

*   Added udev rules to allow mounting media from disks on USB
    floppy drives.  (Thanks to Ryan Finnie for this feature.)

*   Updated SIMH to 2021-02-03 version, GitHub commit 2f66e74c50.  The
    primary user-visible changes from the perspective of a PiDP-8/I user
    are:

    *   The paper tape punch and LPT output devices now default to
        append mode for existing files, rather than overwriting them on
        `ATTACH`.  This not only follows the principle of least surprise
        for modern users, it also replicates the way actual hardware
        operated: reopening such devices and sending more data to them
        just advanced the tape thru the punch or the paper thru the
        teletypewriter.

    *   RF08: Fixed a bug that could cause loss of photo cell unit
        events.

    *   The simulator now does a precalibration pass to achieve a good
        initial guess at the host's IPS rate rather than drop sharply
        into a calibrated level some seconds past the simulator startup
        time, as in the prior release.

    *   Improvements to SCP, the command shell / script interpreter:

        *   Add the `RENAME/MOVE/MV`, `MKDIR`, and `RMDIR` commands.

        *   The `SAVE` command can now overwrite existing files.

        *   The unimplemented `DUMP` command now gives a helpful
            diagnostic message recommending use of `EXAMINE`.

        *   Several improvements to power-of-2 unit handling in command
            output and parameter input.

        *   Regular expressions in SIMH `EXPECT` commands now use
            PCRE syntax if available instead of the POSIX regex
            library.

    *   Many improvements to magnetic tape device handling.  (Nothing
        PDP-8 specific, just generic SIMH improvements.)

*   Fixed a bug in the `SING_STEP` + `IF` feature for switching between
    boot scripts (e.g. IF=2 for running TSS/8) that could cause the
    simulator to crash rather than execute the new script.

    In typical use, this may not even be noticed by the user because
    systemd will restart a crashed simulator, which will then choose its
    boot script based on the same `IF` switch setting.

    Likely the only people to notice this fix are those running the
    simulator attached to a terminal, such as in development.

*   The build system now detects the availability of Python 3 and
    prefers it if available. All documentation now assumes that you’re
    using Python 3. These changes mean we’re no longer testing regularly
    with Python 2, so there may be breakages going forward. These should
    be inadvertent, but we don’t rule out the possibility of a hard
    cut-over in the future that permanently breaks compatibility with
    Python 2. We believe we retain that compatibility in this release,
    but this may be the last such release of the PiDP-8/I software.

*   Considerable updates to the Python library classes we’ve built our
    tooling atop to support all of the above.  Some library behaviors
    and interfaces may have changed in ways that affect outside users.

*   Updated Autosetup to v0.7.0+, allowing builds under Tcl 8.7.

*   The previous release shipped with a broken version of the UCSYS.BI
    script on the v3d.rk05 boot image. The script is supposed to
    turn off forcing lower case characters to upper case in the OS/8
    keyboard monitor, and re-enable the linefeed key's command to
    re-echo the command line. (Cleaning up messy character echoing.)
    Instead linefeed would hang the keyboard monitor.  This is because
    the script for the v3f keyboard monitor was installed on the v3d
    packs.
    
*   Fixed a bug with the MB display in Sing Inst mode when poking around
    with Load Add and Exam.  This only affects some configurations, not
    all, but the fix appears benign on the non-affected ones.

*   The `os8script.py` class has been [documented][os8script] to explain
    the design and assist others in writing programs that can drive operation
    under OS/8 in SIMH using Python expect and all the layers developed
    above it.

*   Portability and documentation improvements.

[adventrm]:  https://tangentsoft.com/pidp8i/doc/release/src/advent/README.md
[advsrc]:    https://tangentsoft.com/pidp8i/dir?ci=release&name=src/advent
[bgsrc]:     https://tangentsoft.com/pidp8i/dir?ci=release&name=src/basic-games
[cc8src]:    https://tangentsoft.com/pidp8i/dir?ci=release&name=src/cc8/os8
[chekmorm]:  https://tangentsoft.com/pidp8i/doc/release/src/chekmo/README.md
[ckmsrc]:    https://tangentsoft.com/pidp8i/dir?ci=release&name=src/chekmo
[dcprm]:     https://tangentsoft.com/pidp8i/doc/release/src/dcp/README.md
[e8man]:     https://tangentsoft.com/pidp8i/doc/release/doc/e8-manual.md
[e8src]:     https://tangentsoft.com/pidp8i/dir?ci=release&name=src/e8
[f69src]:    https://tangentsoft.com/pidp8i/dir?ci=release&name=src/focal69
[focalrm]:   https://tangentsoft.com/pidp8i/doc/release/src/focal69/README.md
[gamesrm]:   https://tangentsoft.com/pidp8i/doc/release/src/basic-games/README.md
[kermitrm]:  https://tangentsoft.com/pidp8i/doc/release/src/kermit-12/README.md
[kit]:       https://tangentsoft.com/pidp8i/doc/release/doc/os8-combined-kit.md
[krmsrc]:    https://tangentsoft.com/pidp8i/dir?ci=release&name=src/kermit-12
[lcsrc]:     https://tangentsoft.com/pidp8i/dir?ci=release&name=src/os8/ock/SYSTEM
[musicrm]:   https://tangentsoft.com/pidp8i/doc/release/src/music/README.md
[mussrc]:    https://tangentsoft.com/pidp8i/dir?ci=release&name=src/music
[OCK]:       https://tangentsoft.com/pidp8i/doc/release/src/os8/ock/README.md
[ocomprm]:   https://tangentsoft.com/pidp8i/doc/release/src/os8/tools/ocomp/README.md
[os8cp]:     https://tangentsoft.com/pidp8i/doc/release/doc/os8-cp.md
[os8pkg]:    https://tangentsoft.com/pidp8i/doc/release/doc/os8pkg.md
[os8src]:    https://tangentsoft.com/pidp8i/dir?ci=release&name=src/os8
[progtest]:  https://tangentsoft.com/pidp8i/doc/release/doc/os8-progtest.md
[rmsm]:      https://tangentsoft.com/pidp8i/doc/release/README.md#rc-screen-manager
[testing]:   https://tangentsoft.com/pidp8i/doc/release/doc/testing.md
[uwfocalrm]: https://tangentsoft.com/pidp8i/doc/release/src/uwfocal/README.md
[uwfsrc]:    https://tangentsoft.com/pidp8i/dir?ci=release&name=src/uwfocal
[vtesrc]:    https://tangentsoft.com/pidp8i/dir?ci=release&name=src/vtedit
[os8script]: https://tangentsoft.com/pidp8i/doc/release/doc/class-os8script.md


<a id="20190425"></a>
## Version 2019.04.25 — The "OS/8 V3F and os8-run" release
## Version 2019.04.25 — The "OS/8 V3F and os8-run" Release

*   The banner feature in this release is that Bill Cattey transformed
    our `mkos8` tool into the `os8-run` script interpreter, giving us
    many new features and capabilities:

    *   The OS/8 V3D RK05 media build steps previously hard-coded in
        Python within `mkos8` are now in a series of scripts in the

        `examples/routines/prints.pal`.</p>

    Between these weaknesses and the `mkbootscript` bug fixed above,
    this example was entirely broken since being shipped.  Our thanks
    for the tests and diagnosis of these problems go to Greg Christie
    and Bill Cattey.

*   The `SING_STEP` + `IF` switch combo to restart the simulator with a
    new boot script (e.g. IF=2 for TSS/8) now does a full restart of the
    simulator rather than simply executing the script’s commands in the
    context of the current simulator instance.  This can make the
    relaunch more reliable by starting with the simulator with known
    register values, device states, etc.

*   Improved `examples/pep001.pal`:

    *   This program no longer gets stuck in the TSF loop on startup if
        you run it with the terminal unready for output.  The terminal
        would typically be ready when launching this program from within
        OS/8, but it could get stuck in other conditions, such as when
        running it under a freshly started simulator:

    allow building on other BSDs, but that is untested.

*   `scanswitch` now returns 127 on “no GPIO” rather than 255.

*   16 months of maintenance and polishing: better documentation, build
    system improvements, etc.

[cc8m]: https://tangentsoft.com/pidp8i/doc/trunk/doc/cc8-manual.md
[esco]: https://tangentsoft.com/pidp8i/doc/trunk/README.md#savestate
[pv]:   https://tangentsoft.com/pidp8i/doc/trunk/README.md#systemd
[cc8m]: https://tangentsoft.com/pidp8i/doc/release/doc/cc8-manual.md
[esco]: https://tangentsoft.com/pidp8i/doc/release/README.md#savestate
[pv]:   https://tangentsoft.com/pidp8i/doc/release/README.md#systemd
[sc85]: https://github.com/ncb85/SmallC-85
[tctd]: https://tangentsoft.com/pidp8i/wiki?name=TD8E+vs+TC08
[v3df]: https://tangentsoft.com/pidp8i/wiki?name=OS/8+V3D+vs+V3F


<a id="20171222"></a>
## Version 2017.12.22 — The "Languages and Custom OS/8 Disk Packs" release
## Version 2017.12.22 — The "Languages and Custom OS/8 Disk Packs" Release

*   All prior versions of the PiDP-8/I software distribution included
    `os8.rk05`, a "Field Service Diagnostic" OS/8 disk pack image with
    uncertain provenance, configuration, and modification history.  We
    have replaced that canned disk image with a script which is run at
    build time which programmatically assembles a set of clean OS/8 RK05
    disk images from curated, pristine, tested sources based on the

*   The binary OS images produced with this version automatically expand
    the root partition to fill your SD card.  (Prior versions required
    that you manually do this with `raspi-config`.)

*   Assorted portability, build system, and documentation improvements.

[apt]:   https://linux.die.net/man/8/apt
[cc8rm]: https://tangentsoft.com/pidp8i/doc/trunk/doc/cc8-manual.md
[csd]:   https://tangentsoft.com/pidp8i/doc/trunk/doc/class-simh.md
[cc8rm]: https://tangentsoft.com/pidp8i/doc/release/doc/cc8-manual.md
[csd]:   https://tangentsoft.com/pidp8i/doc/release/doc/class-simh.md
[dibas]: https://tangentsoft.com/pidp8i/wiki?name=Demos+in+BASIC
[dt2vk]: https://github.com/VentureKing/Deeper-Thought-2
[gh508]: https://github.com/simh/simh/issues/508
[mbua]:  https://serverfault.com/a/767079
[os8ct]: https://tangentsoft.com/pidp8i/wiki?name=OS/8+Console+TTY+Setup
[os8lc]: https://tangentsoft.com/pidp8i/wiki?name=OS/8+LCSYS.BI+Disassembled
[os8p]:  https://tangentsoft.com/pidp8i/doc/trunk/doc/os8-patching.md
[os8rm]: https://tangentsoft.com/pidp8i/doc/trunk/media/os8/README.md
[os8p]:  https://tangentsoft.com/pidp8i/doc/release/doc/os8-patching.md
[os8rm]: https://tangentsoft.com/pidp8i/doc/release/media/os8/README.md
[pe1c]:  https://tangentsoft.com/pidp8i/wiki?name=PEP001.C
[pe1f2]: https://tangentsoft.com/pidp8i/wiki?name=PEP001.FT#fortran-ii
[pe1f4]: https://tangentsoft.com/pidp8i/wiki?name=PEP001.FT#fortran-iv
[pe1u]:  https://tangentsoft.com/pidp8i/wiki?name=PEP001.FC
[uwfm]:  https://tangentsoft.com/pidp8i/doc/trunk/doc/uwfocal-manual.md
[uwfs]:  https://tangentsoft.com/pidp8i/doc/trunk/doc/uwfocal-manual-supp.md
[uwfm]:  https://tangentsoft.com/pidp8i/doc/release/doc/uwfocal-manual.md
[uwfs]:  https://tangentsoft.com/pidp8i/doc/release/doc/uwfocal-manual-supp.md


<a id="20170404"></a>
## Version 2017.04.04

*   Removed the PDP-8 CPU idle detection feature.  Oscar Vermeulen
    reports that it also interfered with NLS LED driving mode in his

    rate to "50%" which not only achieves an even higher throttle rate
    than in earlier releases, it's reliable in the face of varying
    background CPU usage.  See the single-core section of
    `README-throttle.md` for details.


<a id="20170401"></a>
## Version 2017.04.01 — The "I May Be a Fool, but I am *Your* Fool" release
## Version 2017.04.01 — The "I May Be a Fool, but I am *Your* Fool" Release

*   Added the `configure --alt-serial-mod` option to change the GPIO
    code to work with [James L-W's alternative serial mod][sm2].

*   Increased the stock CPU throttle from 0.67 MIPS to 0.85 MIPS on most
    Pi 1 class devices, except for the Pi Zero which is a bit faster and
    so is able to run at 1.25 MIPS.

    This release and prior ones do have important changes to some of
    these files, so if you do not wish to overwrite your local changes
    with a `make mediainstall` command, you might want to diff the two
    versions and decide which changes to copy over or merge into your
    local files.

[hltbug]:  https://tangentsoft.com/pidp8i/info/f961906a5c24f5de
[copying]: https://tangentsoft.com/pidp8i/doc/trunk/COPYING.md
[rmth]:    https://tangentsoft.com/pidp8i/doc/trunk/README-throttle.md
[copying]: https://tangentsoft.com/pidp8i/doc/release/COPYING.md
[rmth]:    https://tangentsoft.com/pidp8i/doc/release/README-throttle.md


<a id="20170105"></a>
## Version 2017.01.05

*   Automated the process for merging in new SIMH updates.  From within
    the PiDP-8/I software build directory, simply say `make simh-update`

    in its version string, so that if you report bugs upstream to the
    SIMH project, you can give them a version number that will be
    meaningful to them.  (They don't care about our vYYYYMMDD release
    numbers or our Fossil checkin IDs.)


<a id="20161226"></a>
## Version 2016.12.26 — The Boxing Day release
## Version 2016.12.26 — The Boxing Day Release

*   Tony Hill updated SIMH to the latest upstream version.

    This change represents about 15 months worth of work in the
    [upstream project][simh] — plus a fair bit of work by Tony to merge
    it all — so I will only summarize the improvements affecting the
    PDP-8 simulator here:

    In particular, the software now builds under Mac OS X, though it
    does not yet run properly.  (The modified SimH PDP-8 simulator
    currently misbehaves if the PiDP-8/I panel is not present.  Fixing
    this is on the radar.)

*   Fixed a bunch of bugs!

[tlrm]:    https://tangentsoft.com/pidp8i/doc/trunk/README.md
[tlrm]:    https://tangentsoft.com/pidp8i/doc/release/README.md
[dupatch]: https://groups.google.com/forum/#!topic/pidp-8/fmjt7AD1gIA
[dudis]:   https://tangentsoft.com/pidp8i/tktview?name=e06f8ae936
[wiki]:    https://tangentsoft.com/pidp8i/wcontent
[ex]:      https://tangentsoft.com/pidp8i/doc/trunk/examples/README.md
[ex]:      https://tangentsoft.com/pidp8i/doc/release/examples/README.md
[art]:     https://tangentsoft.com/pidp8i/dir?c=trunk&name=labels
[tix]:     https://tangentsoft.com/pidp8i/tickets


<a id="20151215"></a>
## Version 2015.12.15

*   The last release of the software made by Oscar Vermeulen, the
    creator of the PiDP-8/I project. This version of the software
    derives from it, but differs in many ways. (See above.)

    Since May of 2017, this version of the software is now considered
    the current stable version.

Hacking on the PiDP-8/I Software
====

If you are going to make any changes to the PiDP-8/I software, here are
some rules and hints to keep in mind while you work.


<a id="gs-fossil"></a>
Getting Started with Fossil
----

The PiDP-8/I software project is hosted using the [Fossil][fossil]
[distributed version control system][dvcs].  Fossil provides most of the
features of GitHub under a simpler operating model than Subversion
without tying you to a proprietary web service.

This guide will introduce you to some of the basics, but you should also
at least read the [Fossil Quick Start Guide][fqsg]. For a more thorough
introduction, I recommend [the Schimpf book][fbook]. If you have
questions about Fossil, you can ask on [the Fossil forum][ffor], where
I, your humble project maintainer, am active.

If you started with one of our PiDP-8/I binary OS images made in or
after April 2017, Fossil 2.x is already installed.

If you're starting from some other OS, you either won't have Fossil
installed at all, or you'll most likely be using an older version, since
the Debian project is still shipping version 1.37 and likely will
continue to do so until 2020 or so in accordance with their software
stability policy.  You could build Fossil from source, or you could just
go grab a pre-built binary we keep on the project site:

    $ wget https://tangentsoft.com/pidp8i/uv/fossil-2.8-raspbian-9.6-stretch
    $ sudo install -m 755 fossil-* /usr/local/bin/fossil

Fossil is also available for all common desktop platforms.  One of [the
official binaries][fbin] may work on your system.  If you're getting
binaries from a third party, be sure it is Fossil 2.1 or higher.


[fbin]:   https://fossil-scm.org/index.html/uv/download.html
[dvcs]:   https://en.wikipedia.org/wiki/Distributed_revision_control
[fbook]:  https://www.fossil-scm.org/schimpf-book/home
[ffor]:   https://fossil-scm.org/forum/
[fossil]: https://fossil-scm.org/
[fqsg]:   https://fossil-scm.org/index.html/doc/trunk/www/quickstart.wiki


<a id="fossil-anon"></a>
Fossil Anonymous Access
----

To clone the code repository anonymously, say:

    $ mkdir -p ~/museum ~/src/pidp8i/trunk
    $ fossil clone https://tangentsoft.com/pidp8i ~/museum/pidp8i.fossil
    $ cd ~/src/pidp8i/trunk
    $ fossil open ~/museum/pidp8i.fossil

The `clone` command gets you a file called `pidp8i.fossil` containing
the full history of the PiDP-8/I software project from the upstream
2015.12.15 release onward.  You can call that clone file anything you
like and put it in any directory you like.  Even the `.fossil` extension
is largely a convention, not a requirement.


<a id="tags" name="branches"></a>
Working with Existing Tags and Branches
----

The directory structure shown in the commands above is more complicated
than strictly necessary, but it has a number of nice properties.

First, it collects other software projects under a common top-level
directory, which I'm calling `~/src`, but you are free to use any scheme
you like.

Second, the top-level project directory stores multiple separate
checkouts, one for each branch or tag I'm actively working with at the
moment.  So, to add a few other checkouts, you could say:

    $ cd ~/src/pidp8i
    $ mkdir -p release          # another branch
    $ mkdir -p v20151215        # a tag this time, not a branch
      ...etc...
    $ cd release
    $ fossil open ~/museum/pidp8i.fossil release
    $ cd ../v20151215
    $ fossil open ~/museum/pidp8i.fossil v20151215
      ...etc...

This gives you multiple independent checkouts.  The branch checkouts
remain pinned to the tip of that branch, so that if someone else checks
changes in on that branch and you say `fossil update`, those changes
appear in your checkout of that branch.  The tag checkouts simply give
you the latest checkin with that tag; saying `fossil update` in a
checkout made from a tag will fast-forward you to the tip of the branch
that tag was made on.

(In Fossil, tags and branches are related, but the details are beyond
our scope here.  See the [Fossil Quick Start Guide][fqsg] and the
documents it links to for more details.)

This directory scheme shows an important difference between Fossil and
Git: with Git, the checkout and the clone are normally intermingled in
the same directory tree, but in Fossil, the clone and the checkout are
always strictly separate.  Git has a weak emulation of Fossil's normal
working style via its [worktree][gitwt] feature, but most Git users
aren't even aware of the feature, and those that are aware of it tend to
discourage its use because of the problems it can cause.  Fossil was
designed to work this way from the start, so it doesn't have the
problems associated with Git worktrees.

Another important difference relative to Git is that with Fossil, local
checkins attempt to automatically sync checked-in changes back to the
repository you cloned from.  (This only works if you have a login on the
remote repository, the subject of the [next section](#login).)  This
solves a number of problems with Git, all stemming from the fact that
Git almost actively tries to make sure every clone differs from every
other in some important way.

While Fossil does allow offline operation and local independent clones,
its default mode of operation is to try and keep the clones in sync as
much as possible.  Git works the way it does because it was designed to
meet the needs of the Linux kernel development project, which is
inherently federated, so Git tries to operate in a federated model as
well.  Fossil is better for smaller, more coherent teams, where there is
a single, clear goal for the project and a single source for its
official code.  Fossil helps remote developers cooperate, whereas Git
helps remote developers go off on their own tangents for extended
periods of time and optionally sync back up with each other
occasionally.

Fossil is a better match for the way the PiDP-8/I software project
works: we want you to cooperate closely with us, not go off on wild
tangents.

[gitwt]:  https://git-scm.com/docs/git-worktree


<a id="login"></a>
Fossil Developer Access
----

If you have a developer account on the `tangentsoft.com/pidp8i` Fossil
instance, just add your username to the URL like so:

    $ fossil clone https://username@tangentsoft.com/pidp8i pidp8i.fossil

If you've already cloned anonymously, you don't have to clone again to
inform Fossil about your developer account.  Just do a manual sync from
within a PiDP-8/I checkout directory, changing the URL to include the
user name:

    $ fossil sync https://username@tangentsoft.com/pidp8i

Either way, Fossil will ask you for the password for `username` on the
remote Fossil instance, and it will offer to remember it for you.  If
you let it remember the password, operation from then on is scarcely
different from working with an anonymous clone, except that on checkin,
your changes will be sync’d back to the repository on tangentsoft.com if
you're online at the time, and you'll get credit under your developer
account name for the checkin.

If you're working offline, Fossil will still do the checkin locally, and
it will sync up with the central repository after you get back online.
It is best to work on a branch when unable to use Fossil's autosync
feature, as you are less likely to have a sync conflict when attempting
to send a new branch to the central server than in attempting to merge
your changes to the tip of trunk into the current upstream trunk, which
may well have changed since you went offline.

You can purposely work offline by disabling autosync mode:

    $ fossil set autosync 0

Until you re-enable it (`autosync 1`) Fossil will stop trying to sync
your local changes back to the central repo.  In this mode, Fossil works
more like Git's default mode, buying you many of the same problems that
go along with that working style.  I recommend disabling autosync mode
only when you are truly going to be offline and don't want Fossil
attempting to sync when you know it will fail.


<a id="gda"></a>
Getting Developer Access
----

We are pretty open about giving developer access to someone who’s
provided at least one good, substantial [patch](#patches) to the
software. If we’ve accepted one of your patches, just ask for a
developer account [on the forum][pfor].


<a id="forum"></a>
Developer Discussion Forum
----

The "[Forum][pfor]" link at the top of the Fossil web interface is for
discussing the development of the PiDP-8/I software only. All other
traffic should go to [the mailing list][ggml] instead.  We're not trying
to split the community by providing a second discussion forum; we just
think many development-related discussions are too low-level to be of
any interest to most of the people on the mailing list.

We used to relegate such discussions to private email, but that was not
out of any wish to hide what we're doing. We just didn't have a good
place to do this work in public until recently.

You can sign up for the forums without having a developer login, and you
can even post anonymously. If you have a login, you can [sign up for
email alerts][alert] if you like.

Keep in mind that posts to the Fossil forum are treated much the same
way as ticket submissions and wiki articles. They are permanently
archived with the project. The "edit" feature of Fossil forums just
creates a replacement record for a post, but the old post is still
available in the repository. Don't post anything you wouldn't want made
part of the permanent record of the project!

[ggml]:  https://groups.google.com/forum/#!forum/pidp-8
[pfor]:  https://tangentsoft.com/pidp8i/forum
[alert]: https://tangentsoft.com/pidp8i/alerts


<a id="branching"></a>
Creating Branches
----

Creating a branch in Fossil is scary-simple, to the point that those
coming from other version control systems may ask, "Is that really all
there is to it?"  Yes, really, this is it:

    $ fossil ci --branch new-branch-name

That is to say, you make your changes as you normally would; then when
you go to check them in, you give the `--branch` option to the
`ci/checkin` command to put the changes on a new branch, rather than add
them to the same branch the changes were made against.

While developers with login rights to the PiDP-8/I Fossil instance are
allowed to check in on the trunk at any time, we recommend using
branches whenever you're working on something experimental, or where you
can't make the necessary changes in a single coherent checkin.

One of this project's core principles is that `trunk` should always
build without error, and it should always function correctly.  That's an
ideal we have not always achieved, but we do always *try* to achieve it.

Contrast branches, which PiDP-8/I developers may use to isolate work
until it is ready to merge into the trunk.  It is okay to check work in
on a branch that doesn't work, or doesn't even *build*, so long as the
goal is to get it to a point that it does build and work properly before
merging it into trunk.

Here again we have a difference with Git: because Fossil normally syncs
your work back to the central repository, this means we get to see the
branches you are still working on.  This is a *good thing*.  Do not fear
committing broken or otherwise bad code to a branch.  [You are not your
code.][daff]  We are software developers, too: we understand that
software development is an iterative process, and that not all ideas
spring forth perfect and production-ready from the fingers of its
developers.  These public branches let your collaborators see what
you're up to, and maybe lend advice or a hand in the work; mostly,
public branches let your collaborators see what you're up to, so they're
not surprised when the change finally lands in trunk.

This is part of what I mean about Fossil fostering close cooperation
rather than fostering wild tangents.

Jim McCarthy (author of [Dynamics of Software Development][dosd]) has a
presentation on YouTube that touches on this topic at a couple of
points:

* [Don't go dark](https://www.youtube.com/watch?v=9OJ9hplU8XA)
* [Beware of a guy in a room](https://www.youtube.com/watch?v=oY6BCHqEbyc)

Fossil's sync-by-default behavior fights these negative tendencies.

PiDP-8/I project developers are welcome to create branches at will. The
main rule is to follow the branch naming scheme: all lowercase with
hyphens separating words. See the [available branch list][brlist] for
examples to emulate.

If you have checkin rights on the repository, it is generally fine to
check things in on someone else's feature branch, as long as you do so
in a way that cooperates with the purpose of that branch.  The same is
true of `trunk`: you should not check something in directly on the trunk
that changes the nature of the software in a major way without
discussing the idea first.  This is yet another use for branches: to
make a possibly-controversial change so that it can be discussed before
being merged into the trunk.

[brlist]: https://tangentsoft.com/pidp8i/brlist
[daff]:   http://www.hanselman.com/blog/YouAreNotYourCode.aspx
[dosd]:   http://amzn.to/2iEVoBL


<a id="special"></a>
Special Branches
----

Most of the branches in the PiDP-8/I project are feature branches of the
sort described in the previous section: an isolated line of development
by one or more of the project's developers to work towards some new
feature, with the goal of merging that feature into the `trunk` branch.

There are a few branches in the project that are special, which are
subject to different rules than other branches:

*   **<code>release</code>** - One of the steps in the
    [release process][relpr] is to merge the stabilized `trunk` into the
    `release` branch, from which the release tarballs and binary OS
    images are created.  Only the project's release manager — currently
    Warren Young — should make changes to this branch.

*   **<code>bogus/BOGUS</code>** — Because a branch is basically just a
    label for a specific checkin, Fossil allows the tip of one branch to
    be "moved" to another branch by applying a branch label to that
    checkin.  We use this label when someone makes a checkin on the tip
    of a branch that should be "forgotten."  Fossil makes destroying
    project history very difficult, on purpose, so things moved to the
    "bogus" branch are not actually destroyed; instead, they are merely
    moved out of the way so that they do not interfere with that
    branch's normal purpose.

    If you find yourself needing to prune the tip of a branch this way,
    the simplest way is to do it via the web UI, using the checkin
    description page's "edit" link.  You can instead do it from the
    command line with the `fossil amend` command.

[relpr]:  https://tangentsoft.com/pidp8i/doc/trunk/doc/RELEASE-PROCESS.md


<a id="debug"></a>
Debug Builds
----

By default, the build system creates a release build, but you can force
it to produce a binary without as much optimization and with debug
symbols included:

     $ ./configure --debug-mode


<a id="build-system"></a>
Manipulating the Build System Source Files
----

The [autosetup build system][asbs] is composed of these files and
directories:

     auto.def
     autosetup/*
     configure
     Makefile.in

Unlike with GNU Autoconf, which you may be familiar with, the
`configure` script is not output from some other tool.  It is just a
driver for the Tcl and C code under the `autosetup` directory.

If you have to modify any of the files in `autosetup/` to get some
needed effect, you should try to get that change into the upstream
[Autosetup][asbs] project, then merge that change down into the local
copy when it lands upstream.

The bulk of the customization to the build system is in `auto.def`,
which is a Tcl script run by `autosetup` via the `configure` script.
Some knowledge of [Tcl syntax][tcldoc] will therefore be helpful in
modifying it.

If you do not have Tcl installed on your system, `configure` builds a
minimal Tcl interpreter called `jimsh0`, based on the [Jim Tcl][jim]
project.  Developers working on the build system are encouraged to use
this stripped-down version of Tcl rather than "real" Tcl because Jim Tcl
is more or less a strict subset of Tcl, so any changes you make that
work with the `jimsh0` interpreter should also work with "real" Tcl, but
not vice versa.  If you have Tcl installed and don't really need it,
consider uninstalling it to force Autosetup to build and use `jimsh0`.

The `Makefile.in` file is largely a standard [GNU `make`][gmake] file
excepting only that it has variables substituted into it by Autosetup
using its `@VARIABLE@` syntax.  At this time, we do not attempt to
achieve compatibility with other `make` programs, though in the future
we may need it to work with [BSD `make`][bmake] as well, so if you are
adding features, you might want to stick to the common subset of
features implemented by both the GNU and BSD flavors of `make`.  We do
not anticipate any need to support any other `make` flavors.

This, by the way, is why we're not using some heavy-weight build system
such as the GNU Autotools, CMake, etc.  The primary advantage of GNU
Autotools is that you can generate source packages that will configure
and build on weird and ancient flavors of Unix; we don't need that.
Cross-platform build systems such as CMake ease building the same
software on multiple disparate platforms straightforward, but the
PiDP-8/I software is built primarily on and for a single operating
system, Raspbian Linux.  It also happens to build and run on [several
other OSes][oscomp], for which we also do not need the full power of
something like CMake.  Autosetup and GNU `make` suffice for our purposes
here.

[asbs]:   http://msteveb.github.io/autosetup/
[bmake]:  https://www.freebsd.org/doc/en/books/developers-handbook/tools-make.html
[gmake]:  https://www.gnu.org/software/make/
[jim]:    http://jim.tcl.tk/
[oscomp]: https://tangentsoft.com/pidp8i/wiki?name=OS+Compatibility
[tcldoc]: http://wiki.tcl.tk/11485


<a id="dirs"></a>
Directory Structure
----

The directory structure of the PiDP-8/I project is as follows:

*   <b>`.`</b> - Top level, occupied only by the few files the end user
    of the source code needs immediately at hand on first unpacking the
    project: the top level build system files, key documentation, and
    licensing information. If a given file *can* be buried deeper, it
    *should* be buried to reduce clutter at this most precious level of
    the hierarchy.

*   <b>`.fossil-settings`</b> - Versioned settings for the Fossil build
    system which Fossil applies as defaults everywhere you check out a
    Fossil version.  Settings made here are intended to be correct for
    all users of the system; think of these not as expressing defaults
    but as expressing *policy*.  It is possible to override these
    settings, but we do not make settings here if we expect that some
    users may quibble with our choices here.

    Any setting whose value may vary between users of the Fossil
    repository should be done locally with a `fossil set` command.

    Say `fossil help set` at the command line for more on this.

*   <b>`autosetup`</b> - The bulk of the [Autosetup build system][asbs].
    These are generic files, not modified by the project itself. We
    occasionally run `tools/autosetup-update` to merge in upstream
    changes.

*   <b>`bin`</b> - Programs installed to `$prefix/bin`, which may also
    be run during development, if only to test changes to those
    programs.  Some scripts stored here are written in place by the
    project's developers, while other files in this directory are
    outputs of the build system.

    The content of this directory is copied to `$prefix/bin` at
    installation time, which is added to the user's `PATH` by the
    `make install` script.

*   <b>`boot`</b> - SIMH initialization scripts.  The `*.script.in`
    files are written by the project developers but have local
    configuration values substituted in by the `configure` script to
    produce a `*.script` version.  Scripts which need no config-time
    values substituted in are checked in directly as `*.script`.  The
    `*.script` files in this directory which do not fall into either of
    those categories are outputs of `tools/mkbootscript`, which produces
    them from `palbart` assembly listings.

    All of these `*.script` files are copied to `$prefix/share/boot` by
    `make mediainstall` which runs automatically from `make install`
    when we detect that the binary media and SIMH boot scripts have
    never been installed at this site before.  On subsequent installs,
    the user chooses whether to run `make mediainstall` by hand to
    overwrite all of this.

*   <b>`doc`</b> - Documentation files sufficiently unimportant to a new
    user of the software that they need not be at the top level of the
    project tree.  Such files can wait for new users to discover them.

    Fossil's [embedded documentation][edoc] feature allows us to present
    the contents of `doc` to web site users all but indistinguishably
    from a wiki page.  Why are there two different ways to achieve the
    same end, and how do we decide which mechanism to use?

    The rule is simple: if a given document's change history is tied to
    the history of the PiDP-8/I project itself, it goes in `doc`, else
    it goes in the wiki.  When checking out older versions of the
    PiDP-8/I software, you expect to roll back to contemporaneous
    versions of the project documentation, which is what happens to all
    files stored in the repository, including those in `doc`, but this
    does not happen to the wiki documents.  The wiki always presents the
    most current version, no matter what version you have locally
    checked out.

    (Fossil's wiki feature behaves much like Wikipedia: it keeps change
    history for wiki documents, but it always presents the most recent
    version unless you manually go poking around in the history to pull
    up old versions.  If you check out a historical version of the
    software and then say `fossil ui` within that checkout directory,
    the resulting web view still shows the most recent locally-available
    version of each wiki document, not versions of the wiki documents
    contemporaneous with the historical version of the Fossil tree you
    have checked out.)

    The `doc/graphics` subdirectory holds JPEGs and SVGs displayed
    inline within wiki articles.

*   <b>`etc`</b> - Files which get copied to `/etc` or one of its
    subdirectories at installation time.

    There is an exception: `pidp8i.service.in` does not get installed to
    `/etc` at install time, but only because systemd's [unit file load
    path scheme][uflp] is screwy: *some* unit files go in `/etc`, while
    others do not.  The systemd docs claim we can put user units in
    `/etc/systemd/user` but this does not appear to work on a Raspberry
    Pi running Raspbian Stretch at least.  We've fallen back to another
    directory that *does* work, which feels more right to us anyway, but
    which happens not to be in `/etc`.  If systemd were designed sanely,
    we'd install such files to `$HOME/etc/systemd` but noooo....

    Since none of the above actually argues for creating another
    top-level repository directory to hold this one file, we've chosen
    to store it in `etc`.

*   <b>`examples`</b> - Example programs for the end user's edification.
    Many of these are referenced by documentation files and therefore
    should not be renamed or moved, since there may be public web links
    referring to these examples.

*   <b>`hardware`</b> - Schematics and such for the PiDP-8/I board or
    associated hardware.

*   <b>`labels`</b> - Graphics intended to be printed out and used as
    labels for removable media.

*   <b>`lib`</b> - Library routines used by other programs, installed to
    `$prefix/lib`.

*   <b>`libexec`</b> - A logical extension of `lib`, these are
    standalone programs that nevertheless are intended to be run
    primarily by other programs.  Whereas a file in `lib` might have its
    interface described by a programmer's reference manual, the
    interface of a program in `libexec` is described by its usage
    message.  Example:

    *   <b>`scanswitch`</b> - Run by `etc/pidp8i`.
    
        <p>It is run by hand only by developers modifying its behavior.</p>

    Programs in `libexec` are installed to `$prefix/libexec`, which is
    *not* put into the user's `PATH`, on purpose.  If a program should
    end up in the user's `PATH`, it belongs in `bin`.  Alternately, a
    wrapper may be put in `bin` which calls a `libexec` program as a
    helper.

*   <b>`media`</b> - Binary media images used either by SIMH directly or
    by tools like `os8-run` to produce media used by SIMH.

    The contents of this tree are installed to `$prefix/share/media`.

*   <b>`obj`</b> - Intermediate output directory used by the build
    system.  It is safe to remove this directory at any time, as its
    contents may be recreated by `make`.  No file checked into Fossil
    should be placed here.

    (Contrast `bin` which does have some files checked into Fossil; all
    of the *other* files that end up in `bin` can be recreated by
    `make`, but not these few hand-written programs.)

*   <b>`src`</b> - Source code for the project's programs, especially
    those that cannot be used until they are built.  The great majority
    of these programs are written in C.  The build system's output
    directories are `bin`, `boot`, `libexec`, and `obj`.

    Programs that can be used without being "built," example programs,
    and single-file scripts are placed elsewhere: `bin`, `examples`,
    `libexec`, `tools`, etc.  Basically, we place such files where the
    build system *would* place them if they were built from something
    under `src`.

    There are no program sources in the top level of `src`.  The file
    `src/config.h` may appear to be an exception to that restriction,
    but it is *generated output* of the `configure` script, not "source
    code" *per se*.

    Multi-module programs each have their own subdirectory of `src`,
    each named after the program contained within.

    Single module programs live in `src/misc` or `src/asm`, depending on
    whether they are host-side C programs or PAL8 assembly programs.

*   <b>`test`</b> - Output directory used by `tools/test-*`.

*   <b>`tools`</b> - Programs run only during development and not
    installed.

    If a program is initially created here but we later decide that it
    should be installed for use by end users of the PiDP-8/I system, we
    move it to either `bin` or `libexec`, depending on whether it is run
    directly at the command line or run from some other program that is
    also installed, respectively.

[edoc]: https://www.fossil-scm.org/index.html/doc/trunk/www/embeddeddoc.wiki
[uflp]: https://www.freedesktop.org/software/systemd/man/systemd.unit.html#id-1.9


<a id="patches"></a>
Submitting Patches
----

If you do not have a developer login on the PiDP-8/I software
repository, you can still send changes to the project.

The simplest way is to say this after developing your change against the
trunk of PiDP-8/I:

    $ fossil diff > my-changes.patch

Then either upload that file somewhere (e.g. Pastebin) and point to it
from a [forum post][pfor] or attach the patch to a new [PiDP-8/I mailing
list][ggml] message. Either way, include a declaration of the license
you wish to contribute your changes under.  We suggest using the [SIMH
license][simhl], but any [non-viral][viral] [OSI-approved license][osil]
should suffice. We’re willing to tolerate viral licenses for standalone
products; for example, CC8 is under the GPL, but it’s fine because it
isn’t hard-linked into any other part of the PiDP-8/I software system.

If your change is more than a small patch, `fossil diff` might not
incorporate all of the changes you have made.  The old unified `diff`
format can't encode branch names, file renamings, file deletions, tags,
checkin comments, and other Fossil-specific information.  For such
changes, it is better to send a Fossil bundle:

    $ fossil set autosync 0                # disable autosync
    $ fossil checkin --branch my-changes
      ...followed by more checkins on that branch...
    $ fossil bundle export --branch my-changes my-changes.bundle

After that first `fossil checkin --branch ...` command, any subsequent
`fossil ci` commands will check your changes in on that branch without
needing a `--branch` option until you explicitly switch that checkout
directory to some other branch.  This lets you build up a larger change
on a private branch until you're ready to submit the whole thing as a
bundle.

Because you are working on a branch on your private copy of the
PiDP-8/I Fossil repository, you are free to make as many checkins as
you like on the new branch before giving the `bundle export` command.

Once you are done with the bundle, send it to the developers the same
way you should a patch file.

If you provide a quality patch, we are likely to offer you a developer
login on [the repository][repo] so you don't have to continue with the
patch or bundle methods.

Please make your patches or experimental branch bundles against the tip
of the current trunk.  PiDP-8/I often drifts enough during development
that a patch against a stable release may not apply to the trunk cleanly
otherwise.

[osil]:  https://opensource.org/licenses
[repo]:  https://tangentsoft.com/pidp8i/
[simhl]: https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md
[viral]: https://en.wikipedia.org/wiki/Viral_license


<a id="code-style"></a>
The PiDP-8/I Software Project Code Style Rules
----

Every code base should have a common code style.  Love it or
hate it, here are PiDP-8/I's current code style rules:

**C Source Code**

File types: `c`, `h`, `c.in`

We follow the SIMH project's pre-existing code style when modifying one
of its source files:

*   Spaces for indents, size 4

*   DOS line endings.  (Yes, even though this is a Linux-based project!
    All decent Linux text editors can cope with this.)

*   Function, structure, type, and variable names are all lowercase,
    with underscores separating words

*   Macro names are in `ALL_UPPERCASE_WITH_UNDERSCORES`

*   Whitespace in the SIMH C files is of a style I have never seen
    anywhere else in my decades of software development.  This example
    shows the important features:

        int some_function (char some_parameter)
        {
        int some_variable = 0;

        if (some_parameter != '\0') {
            int nbytes = sizeof (some_parameter);
            char *buffer = malloc (4 * nbytes);

            switch (some_parameter) {
                case 'a':
                    do_something_with_buffer ((char *)buffer); 
                default:
                    do_something_else ();
                }
            }
        else {
            some_other_function (with_a_large, "number of parameters",
                wraps_with_a_single, "indent level");
            printf (stderr, "Failed to allocate buffer.\n");
            }
        }
    
    It is vaguely like K&R C style except that:

    -   The top level of statements in a function are not indented

    -   The closing curly brace is indented to the same level as the
        statement(s) it contains

    -   There is a space before all opening parentheses, not just those
        used in `if`, `while`, and similar flow control statements.

        Nested open parentheses do not have extra spaces, however.  Only
        the outer opening parenthesis has a space separating it from
        what went before.

    -   Multiple variables declared together don't have their types and
        variable names aligned in columns.

I find that this style is mostly sensible, but with two serious problems:
I find the indented closing curly braces confusing, and I find that the
loss of the first indent level for the statements inside a function makes
functions all visually run together in a screenful of code.  Therefore,
when we have the luxury to be working on a file separate from SIMH,
we use a variant of its style with these two changes, which you can
produce with the `tools/restyle` command.  See its internal comments for
details.

That gives the following, when applied to the above example:

        int some_function (char some_parameter)
        {
            int some_variable = 0;

            if (some_parameter != '\0') {
                int nbytes = sizeof (some_parameter);
                char *buffer = malloc (4 * nbytes);

                switch (some_parameter) {
                    case 'a':
                        do_something_with_buffer ((char *)buffer); 
                    default:
                        do_something_else ();
                }
            }
            else {
                some_other_function (with_a_large, "number of parameters",
                    wraps_with_a_single, "indent level");
                printf (stderr, "Failed to allocate buffer.\n");
            }
        }
    
If that looks greatly different, realize that it is just two indenting
level differences: add one indent at function level, except for the
closing braces, which we leave at their previous position.

SIMH occasionally exceeds 100-column lines.  I recommend breaking
long lines at 72 columns.  Call me an 80-column traditionalist.

When in doubt, mimic what you see in the current code.  When still in
doubt, ask on the [project forum][pfor].

[indent]: http://linux.die.net/man/1/indent


**Plain Text Files**

File types: `md`, `txt`

*   Spaces for indents, size 4.

*   Unix line endings.  The only common text editor I'm aware of that
    has a problem with this is Notepad, and people looking at these
    files anywhere other than unpacked on a Raspberry Pi box are
    probably looking at them through the Fossil web interface on
    tangentsoft.com.

*   Markdown files must follow the syntax flavor understood by
    [Fossil's Markdown interpreter][fmd].

[fmd]: https://tangentsoft.com/pidp8i/md_rules


<a id="tickets"></a>
Ticket Processes
----
Normal end users of the Fossil ticket system are not expected to
understand it properly or to fill out tickets properly. Without certain
permissions, it is in fact not possible to completely fill out a ticket
properly.

Therefore, the first thing that should happen to a ticket is that
someone with sufficient privilege should triage it and fix up any
incorrect settings.

The Status of a ticket initially starts out as Open. If the person
triaging a ticket takes the time to check that the problem actually
occurs as the ticket filer claims or that the requested feature is in
fact missing, the Status should change to Verified.

If a developer implements a fix or feature in response to a ticket, he
has two choices: change the ticket’s Status to “Review” if he wants
someone to check out the change before closing it, or go straight to
Closed status. Closing a ticket hides it from the Wishes and Bugs ticket
reports.

Larger teams often require all ticket changes to go through Review
status before getting to Closed, but the PiDP-8/I project is too small
to require such ceremony: if we’ve given you a developer account on the
repository, you’re expected to resolve and close tickets in the same
step, most of the time. If you cannot confidently close a ticket when
resolving it, you should probably not be assigning a resolution yet
anyway. Do whatever you have to with tests and such to *become* certain
before you resolve a ticket.

There is a process interlock between the Resolution and Status settings
for a ticket: while Status is not Closed, Resolution should be Open.
When Resolution changes from Open, Status should change to either Review
or, preferentially, Closed.  A resolution is an end state, not an
expression of changeable intent: no more ceremony than setting a
ticket’s Resolution state *away* from Open and its Status *to* Closed is
required.

If you do not intend to close a ticket but wish to advocate for a
particular resolution, just add a comment to the ticket and let someone
else choose whether to close the ticket or not. Don’t change the
Resolution value until the issue has been *resolved* for good.

For example, the resolution "Works as Designed" does not merely mean,
“Yes, we know it works that way,” it also implies “...and we have no
intention to change that behavior, ever.”  If there is a chance that the
behavior described in the ticket could change, you should not assign any
resolution. Just leave it open until someone decides to do something
final with the ticket.

This is not to say that a ticket can never be re-opened once it’s had a
resolution assigned and been closed, but that this is a rare occurrence.
When a developer makes a decision about a ticket, it should be difficult
to re-open the issue. A rejected ticket probably shouldn’t be re-opened
with anything short of a working patch, for example:

> User A: I want feature X.

> Dev B: No, we’re not going to do that. Ticket closed and rejected.

> User C: Here’s a patch to implement feature X.

> Dev B: Well, that’s different, then. Thanks for the patch! Ticket
> marked Implemented, but still Closed.


## License

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

[sl]:   https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md

########################################################################
# Makefile.in - Processed by autosetup's configure script to generate
#    the GNU make(1) file for building the PiDP-8/I software.
#
# If you are seeing this at the top of a file called Makefile and you
# intend to make edits, do that in Makefile.in.  Saying "make" will then
# re-build Makefile from that modified Makefile.in before proceeding to
# do the "make" operation.
#
# Copyright © 2015 by Oscar Vermeulen, © 2016-2019 by Warren Young
# Copyright © 2015 by Oscar Vermeulen, © 2016-2021 by 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,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to

# shall not be used in advertising or otherwise to promote the sale,
# use or other dealings in this Software without prior written
# authorization from those authors.
########################################################################

# Git commit ID and time of the latest version of the SIMH 4 project on
# GitHub that has been merged into this source base.
SGCID=4e0450cff96830c5aced36928a4427adfc5314f8
SGCTM=2019-04-18T20:03:17-07:00
SGCID=ab48f31317f63943cf36995d2e29feb16d122b36
SGCTM=2021-04-20T18:37:32+02:00

# C build flags for the PDP-8 simulator and its PiDP-8/I extensions.
SIM_CFLAGS := @CFLAGS@ @BUILDMODE@ \
SIM_CFLAGS := @CFLAGS@ @PI_CFLAGS@ @BUILDMODE@ \
	-Wno-unused-result -Wno-parentheses \
	-DUSE_READER_THREAD -DHAVE_DLOPEN=$(subst .,,@SH_SOEXT@) -DPIDP8I \
	-DSIM_ASYNCH_IO -DHAVE_REGEX_H -DHAVE_GLOB \
	-DSIM_ASYNCH_IO -DHAVE_GLOB \
	-DSIM_GIT_COMMIT_ID=$(SGCID) -DSIM_GIT_COMMIT_TIME=$(SGCTM) \
	-DSIM_BUILD_TOOL='autosetup+gmake' \
	-D_GNU_SOURCE \
	-U__STRICT_ANSI__ \
	-I @srcdir@/src/SIMH -I @srcdir@/src/pidp8i -I src -I src/SIMH -I src/pidp8i
ifneq "@HAVE_PCRE_H@" "0"
SIM_CFLAGS += -DHAVE_PCRE_H
SIM_LFLAGS := -lpcre
endif
ifneq "@HAVE_PCREPOSIX_H@" "0"
SIM_CFLAGS += -DHAVE_PCREPOSIX_H
endif
PIDP8I_CFLAGS = $(SIM_CFLAGS)
SIMH_CFLAGS = $(SIM_CFLAGS)
SIMH_PDP8_CFLAGS = $(SIM_CFLAGS)

# Greatly stripped-down build options for the cc8 cross-compiler
# primarily because it's K&R C.  Building under SIM_CFLAGS spews
# pages of warnings.  The only thing we share is whether to build

BINS = $(PIDP8I_SIM) @CC8_CROSS@ \
	bin/d8tape \
	bin/palbart \
	bin/pidp8i-test \
	bin/ptp2txt \
	libexec/scanswitch
BIN_SCRIPTS = \
	bin/os8pkg \
	bin/pidp8i \
	bin/usb-mount \
	@srcdir@/bin/teco-pi-demo

# Some *.py files are generated by Autosetup, so they need different
# handling than the other libraries for the out-of-tree build case.
PIDP8I_DIRS := lib/pidp8i/dirs.py
PIDP8I_DIN  := @srcdir@/$(PIDP8I_DIRS).in
GENNED_PY   := \
	lib/pidp8i/__init__.py \
	lib/pidp8i/ips.py \
	lib/pidp8i/os8opts.py \
	$(PIDP8I_DIRS)

SIMH_PY     := lib/simh.py
SIMH_PY_SRC := @srcdir@/$(SIMH_PY)

# Any use of $(OS8RUN) must implicitly depend on $(OS8_TOOLTIME) disk image.
OS8RUN          = bin/os8-run

# Any use of $(OS8CP) must implicitly depend on $(OS8_TOOLTIME) disk image.
OS8CP          = bin/os8-cp

OS8SCRIPT      := lib/os8script.py
OS8RUN_PY_ALL  := $(GENNED_PY) $(OS8SCRIPT) $(SIMH_PY_SRC)
OS8RUN_SRCS    := $(OS8RUN) $(OS8RUN_PY_ALL) $(PIDP8I_DIN)

# If you edit this directory list, you should probably also edit
# the argument list to the mkadrules call in auto.def!
BUILDDIRS := \
	bin \
	libexec \
	obj/cc8/cross \
	obj/cc8/os8 \
	obj/d8tape \
	obj/misc \
	obj/palbart \
	obj/os8pkg \
	obj/pidp8i \
	obj/SIMH \
	obj/SIMH/PDP8

INSTDIRS := bin etc lib/pidp8i libexec \
	share/boot share/include share/man/man1 share/media/os8 share/save

	obj/cc8/cross/main.o \
	obj/cc8/cross/preproc.o \
	obj/cc8/cross/primary.o \
	obj/cc8/cross/stmt.o \
	obj/cc8/cross/struct.o \
	obj/cc8/cross/sym.o \
	obj/cc8/cross/while.o

CC_OS8_OBJS := \
	obj/cc8/os8/libc.sb \
	obj/cc8/os8/c8.sb \
	obj/cc8/os8/n8.sb \
	obj/cc8/os8/p8.sb

CC_OS8_SRCS := \
	@srcdir@/src/cc8/os8/header.sb

CC_OS8_DEMOS := \
	obj/cc8/os8/fib.c \
	obj/cc8/os8/calc.c \
	obj/cc8/os8/ps.c \


D8TAPE_OBJS := \
	obj/d8tape/dasm.o \
	obj/d8tape/flow.o \
	obj/d8tape/main.o \
	obj/d8tape/version.o

# 
# The rest have no special treatment.
OS8RUN_INFILES = \
	@srcdir@/lib/pidp8i/__init__.py.in \
	@srcdir@/lib/pidp8i/ips.py.in \
	@srcdir@/media/os8/init.tx.in \
	@srcdir@/media/os8/3finit.tx.in \
	@srcdir@/media/os8/ock-init.tx.in \
	@srcdir@/src/pidp8i/main.c.in \
	$(PIDP8I_DIN)
PRECIOUS_INFILES = \
	@srcdir@/Makefile.in \
    @srcdir@/examples/Makefile.in \
    @srcdir@/src/Makefile.in \
    @srcdir@/src/cc8/Makefile.in \
    @srcdir@/src/SIMH/Makefile.in \
    @srcdir@/src/SIMH/PDP8/Makefile.in
INFILES = \
	@srcdir@/tools/os8-progtest.in \
	@srcdir@/bin/os8pkg.in \
	@srcdir@/bin/os8-cp.in \
	@srcdir@/tools/os8-cmp.in \
	@srcdir@/bin/os8-run.in \
	@srcdir@/bin/teco-pi-demo.in \
	@srcdir@/bin/pidp8i.in \
	@srcdir@/boot/0.script.in \
	@srcdir@/boot/2.script.in \
	@srcdir@/boot/3.script.in \
	@srcdir@/boot/4.script.in \
	@srcdir@/boot/6.script.in \
	@srcdir@/boot/7.script.in \
	@srcdir@/boot/run.script.in \
	@srcdir@/boot/run-v3f.script.in \
	@srcdir@/boot/tss8.script.in \
	@srcdir@/etc/pidp8i.service.in \
	@srcdir@/etc/sudoers.in \
	@srcdir@/etc/usb-mount@.service.in \
	@srcdir@/lib/os8script.py.in \
	@srcdir@/lib/simh.py.in \
	@srcdir@/src/pidp8i/gpio-common.c.in \
	@srcdir@/tools/simh-bisect.in \
	@srcdir@/tools/simh-update.in \
	$(OS8RUN_INFILES)
OS8RUN_OUTFILES := $(subst @srcdir@/,,$(OS8RUN_INFILES))
OS8RUN_OUTFILES := $(subst .in,,$(OS8RUN_OUTFILES))
PRECIOUS_OUTFILES := $(subst @srcdir@/,,$(PRECIOUS_INFILES))
PRECIOUS_OUTFILES := $(subst .in,,$(PRECIOUS_OUTFILES))
OUTFILES := $(subst @srcdir@/,,$(INFILES))
OUTFILES := $(subst .in,,$(OUTFILES))

OS8_DIST_RK05 = bin/v3d-dist.rk05
OS8_SRC_RK05 = @OS8_SRC_RK05@
OS8_BOOT_DISK = bin/@OS8_BOOT_DISK@
OS8_RK05S = $(OS8_DIST_RK05) $(OS8_BOOT_DISK) $(OS8_SRC_RK05)
OS8_BASELINE = bin/@OS8_BASELINE@
OS8_TOOLTIME = bin/@OS8_TOOLTIME@

# auto.defs will select as OS8_RUNTIME either V3D_RUNTIME or OCK_RUNTIME disk image.
V3D_RUNTIME = bin/v3d.rk05
OCK_RUNTIME = bin/ock.rk05
OS8_RUNTIME = bin/@OS8_RUNTIME@

OS8_RK05S = \
	$(OS8_BASELINE) \
	$(V3D_RUNTIME) \
	$(OS8_SRC_RK05) \
	$(OS8_OCK_DIST_RK05) \
	$(OS8_OCK_PATCHED_RK05) \
	$(OCK_RUNTIME)



INC_SCRIPTS_DIR = @srcdir@/scripts/include
MISC_SCRIPTS_DIR = @srcdir@/scripts/misc
OS8_SCRIPTS_DIR = @srcdir@/media/os8/scripts
OS8_SCRIPTS_DIR = @srcdir@/scripts/os8

V3D_DIST_SCRIPT = $(OS8_SCRIPTS_DIR)/v3d-dist-rk05.os8
V3D_SRC_SCRIPT = $(OS8_SCRIPTS_DIR)/v3d-src-rk05.os8
V3D_RK05_SCRIPT = $(OS8_SCRIPTS_DIR)/v3d-rk05.os8
V3D_DIST_SCRIPT = $(OS8_SCRIPTS_DIR)/v3d/dist-rk05.os8
V3D_SRC_SCRIPT = $(OS8_SCRIPTS_DIR)/v3d/src-rk05.os8
V3D_PATCH_SCRIPT = $(OS8_SCRIPTS_DIR)/v3d/patch-rk05.os8
V3D_RK05_SCRIPT = $(OS8_SCRIPTS_DIR)/v3d/boot-rk05.os8

V3F_SRCDIR = @srcdir@/src/os8/v3f
V3F_BUILD_RK05 = obj/v3f-build.rk05
V3F_MANIFEST = actions.txt

V3F_MADE_RK05 = bin/v3f-made.rk05

V3F_MAKER = $(OS8_SCRIPTS_DIR)/v3f-control.os8
V3F_MAKER = $(OS8_SCRIPTS_DIR)/v3f/control.os8

# OS/8 Combined Kit. Build from Source.
# We build each object rk05 image in one large script
# Because otherwise mmake would have terrible race conditions.
# We cut the tree up into chunks to fit them on rk05 images:
# SYS: The System Head and device Handlers and key system CUSPS.
# CUSPS: The remaining Commonly Used System Programs (CUSPS)
# BF2: BASIC and FORTRAN II
# FIV: FORTRAN IV

OS8_OCK_SRCDIR = @srcdir@/src/os8/ock

OS8_OCK_SYS_SRC_RK05 = obj/ock-sys-src.rk05
OS8_OCK_SYS_OBJ_RK05 = bin/ock-sys-obj.rk05
OS8_OCK_SYS_MAKER = $(OS8_SCRIPTS_DIR)/ock/sys-build.os8

OS8_OCK_CUSPS_SRC_RK05 = obj/ock-cusps-src.rk05
OS8_OCK_CUSPS_OBJ_RK05 = bin/ock-cusps-obj.rk05
OS8_OCK_CUSPS_MAKER = $(OS8_SCRIPTS_DIR)/ock/cusps-build.os8

OS8_OCK_BF2_SRC_RK05 = obj/ock-bf2-src.rk05
OS8_OCK_BF2_OBJ_RK05 = bin/ock-bf2-obj.rk05
OS8_OCK_BF2_MAKER = $(OS8_SCRIPTS_DIR)/ock/bf2-build.os8

OS8_OCK_FIV_SRC_RK05 = obj/ock-fiv-src.rk05
OS8_OCK_FIV_OBJ_RK05 = bin/ock-fiv-obj.rk05
OS8_OCK_FIV_MAKER = $(OS8_SCRIPTS_DIR)/ock/fiv-build.os8

OS8_OCK_DIST_RK05 = bin/ock-dist.rk05
OS8_OCK_DIST_MAKER = $(OS8_SCRIPTS_DIR)/ock/dist-rk05.os8
OS8_OCK_PATCHED_RK05 = bin/ock-patched.rk05
OS8_OCK_PATCHED_MAKER = $(OS8_SCRIPTS_DIR)/ock/patch-rk05.os8
OS8_OCK_BOOT_MAKER = $(OS8_SCRIPTS_DIR)/ock/boot-rk05.os8

ALL_TU56_SCRIPT = $(OS8_SCRIPTS_DIR)/all-tu56.os8

CUSP_COPYIN_SCRIPT = $(OS8_SCRIPTS_DIR)/cusp-copyin.os8
CUSP_COPYIN_SCRIPT = $(INC_SCRIPTS_DIR)/cusp-copyin.os8

OS8_BOOT_TAPE = bin/@OS8_BOOT_TAPE@
V3D_TC08_TU56 = bin/v3d-tc08.tu56
V3D_TD12K_TU56 = bin/v3d-td12k.tu56
V3F_TC08_TU56 = bin/v3f-tc08.tu56
V3F_TD12K_TU56 = bin/v3f-td12k.tu56
V3F_BOOT_TAPE= bin/v3f-@OS8_TAPE_DEVICE@.tu56

CC8_TU56_SCRIPT = $(OS8_SCRIPTS_DIR)/cc8-tu56.os8

# Absolute version of --prefix passed to configure.
PREFIX = @ABSPREFIX@

# Normally unset.  Prepended to PREFIX to install files to a
# different tree than / (e.g. for distribution build/CI scripts).
# https://www.gnu.org/prep/standards/html_node/DESTDIR.html
DESTDIR = 

RCFILE := $(PREFIX)/etc/pidp8i.rc

CLTXT = /boot/cmdline.txt

ADF := adrules.mk

OS8_PKGS_SELECTED = @OS8_PKGS_SELECTED@
OS8_PKGS_SELECTED_NAMES = @OS8_PKGS_SELECTED_NAMES@
PKGS_INCLUDE = obj/os8pkg/pkgs.os8

#### TARGETS ###########################################################

.PHONY: all tags
.PRECIOUS: $(PRECIOUS_OUTFILES)

all: \
	$(OUTFILES) $(PRECIOUS_OUTFILES) \
	$(BUILDDIRS) $(BINS) $(BOOTSCRIPTS) $(LISTINGS) \
	$(ASM_PTS) $(FC_EX_PTS) $(PAL_EX_PTS) \
	$(OS8_TOOLTIME) pkg_all \
	$(OS8_RK05S) $(V3F_MADE_RK05) $(V3D_TC08_TU56) \
	$(V3D_TD12K_TU56) $(V3F_TC08_TU56) $(V3F_TD12K_TU56)

clean:
	@rm -f $(BINS) $(BOOTSCRIPTS) $(ASM_PTS) $(PAL_EX_PTS) $(LISTINGS) \
		$(OUTFILES) $(ADF) \
		$(OS8_RK05S) $(V3F_MADE_RK05) $(V3F_BUILD_RK05) $(V3D_TC08_TU56) \
		$(V3D_TD12K_TU56) $(V3F_TC08_TU56) $(V3F_TD12K_TU56) \
		config.log cscope.out tags \
		bin/*.pt  bin/*.save bin/txt2ptp \
		bin/*.pt bin/*.rk05 bin/*.save bin/*.tu56 bin/txt2ptp \
		lib/*.pyc lib/*/*.pyc lib/pidp8i/dirs.py lib/pidp8i/ips.py \
		obj/*.log obj/*.pt obj/os8.opts \
		src/config.h \
		obj/*.log obj/*.pt obj/os8.opts obj/os8pkg/* \
		src/config.h src/e8/e8defs.pa \
		@srcdir@/examples/*.err
	@find obj \( -name \*.o -o -name \*.d \) -delete
	@-rmdir -p $(BUILDDIRS) 2> /dev/null || true

distclean: clean
	@rm -f \
		$(PRECIOUS_OUTFILES) \
		config.log \
		autosetup/jimsh0 \
		src/config.h

ctags tags:
	ctags -R @srcdir@/src @srcdir@/lib
ifeq (@HAVE_PROG_CSCOPE@, 1)
	cscope -bR -s@srcdir@
endif

install: install-target install-system

install: all instdirs
	@echo Installing to @prefix@...
install-target: all instdirs
	@echo Installing to $(PREFIX)...

	@# Install most bin/* stuff and set their perms
	@for f in $(BINS) ; do \
		dest=@prefix@/$$f ; \
		dest=$(PREFIX)/$$f ; \
		echo "Installing binary $$dest..." ; \
		@INSTALL@ -m 755 -D -s $$f $$dest ; \
		@INSTALL@ -m 755 -D -s $$f $(DESTDIR)$$dest ; \
	done
	@for f in $(BIN_SCRIPTS) ; do \
		dest=@prefix@/bin/$$(basename $$f) ; \
		dest=$(PREFIX)/bin/$$(basename $$f) ; \
		echo "Installing script $$dest..." ; \
		@INSTALL@ -m 755 -D $$f $$dest ; \
		@INSTALL@ -m 755 -D $$f $(DESTDIR)$$dest ; \
	done
	@( cd @prefix@/bin ; \
	   echo "Installing txt2ptp symlink..." ; \
	   ln -f ptp2txt txt2ptp ; \
	@echo "Installing txt2ptp symlink..."
	@ln -f $(DESTDIR)$(PREFIX)/bin/ptp2txt $(DESTDIR)$(PREFIX)/bin/txt2ptp
	)
	@(test -x /sbin/setcap && \
		for f in @prefix@/bin/pidp8i-* ; do \
			echo "Setting real-time priority capabilities on $$(basename $$f)..." ; \
			/sbin/setcap 'cap_sys_nice=eip' $$f ; \
		done \
	) || true
	@(	test -e @MEDIADIR@/os8/os8.rk05 || \
		test -e @MEDIADIR@/os8/os8v3d-bin.rk05 || \
		test -e @MEDIADIR@/os8/v3d.rk05) && \
	@(	test -e $(DESTDIR)@MEDIADIR@/os8/os8.rk05 || \
		test -e $(DESTDIR)@MEDIADIR@/os8/os8v3d-bin.rk05 || \
		test -e $(DESTDIR)@MEDIADIR@/os8/v3d.rk05) && \
		echo "Skipping media image and SIMH boot script reinstall." || \
		$(MAKE) mediainstall
	@ln -f $(DESTDIR)$(PREFIX)/bin/pidp8i-sim $(DESTDIR)$(PREFIX)/bin/pdp8  # run w/o PiDP-8/I extensions
	@ln -f @prefix@/bin/pidp8i-sim @prefix@/bin/pdp8  # run w/o PiDP-8/I extensions

	@# Install CC8 stuff if built
	@test -n "@CC8_CROSS@" && \
		echo "Installing cc8 cross-compiler..." ; \
		@INSTALL@ -m 755 bin/cc8 $(DESTDIR)$(PREFIX)/bin && \
		@INSTALL@ -m 644 @srcdir@/src/cc8/include/* $(DESTDIR)$(PREFIX)/share/include

	@# Install palbart stuff
	@@INSTALL@ -m 755 bin/palbart $(DESTDIR)$(PREFIX)/bin
	@@INSTALL@ -m 644 @srcdir@/src/palbart/palbart.1 $(DESTDIR)$(PREFIX)/share/man/man1

	@# Install os8-run and its dependencies
	@echo "Installing os8-run..."
	@@INSTALL@ -m 775 -g @INSTGRP@ $(OS8RUN) $(DESTDIR)$(PREFIX)/bin
	@( for src in $(OS8RUN_PY_ALL) ; do \
		test -e $$src || src=@srcdir@/$$src ; \
		dest=$(PREFIX)/$$(echo $$src | sed -e 's_^@srcdir@/__') ; \
		echo "Installing $$src to $$dest..." ; \
	    @INSTALL@ -m 644 -g @INSTGRP@ -D $${src}  $(DESTDIR)$${dest}  ; \
	  done \
	)
	@sed -e 's#^build =.*#build = "$(PREFIX)"#' \
	     -e 's#^media =.*#media = os.path.join (build, "share/media/")#' \
	     -e 's#^os8mo =.*#os8mo = os8mi#' \
		 < $(PIDP8I_DIRS) > $(DESTDIR)$(PREFIX)/$(PIDP8I_DIRS)
	@chgrp @INSTGRP@ $(DESTDIR)$(PREFIX)/$(PIDP8I_DIRS)

	@# We need a directory for PIDs and such in some cases
	@@INSTALL@ -d -m 755 $(DESTDIR)$(PREFIX)/run

install-system: install-target
	@echo Installing system files and programs...

	@(test -x /sbin/setcap && \
		for f in $(PREFIX)/bin/pidp8i-* ; do \
			echo "Setting real-time priority capabilities on $$(basename $$f)..." ; \
			/sbin/setcap 'cap_sys_nice=eip' $(DESTDIR)$$f ; \
		done \
	) || true

	@# If this is a Debian-type system, install needed helper programs
	@test -x /usr/bin/apt-get -a ! -x /usr/bin/screen && apt-get -y install screen || true

	@# Remove usbmount: we've replaced that with bin/usb-mount and friends.
	@(test -x /usr/bin/apt-get -a -d /etc/usbmount && \
		apt-get -y remove usbmount > /dev/null 2>&1 \
	) || true

ifeq (@USB_AUTOMOUNT@, 1)
	@# Install the usb-mount systemd unit file and udev rules
	@(  test -d /etc/systemd && \
		@INSTALL@ -m 644 etc/usb-mount@.service /etc/systemd/system && \
		@INSTALL@ -m 644 @srcdir@/etc/udev.rules /etc/udev/rules.d/68-usb-mount.rules && \
		sed -i -e 's/MountFlags=slave/MountFlags=shared/' \
			/lib/systemd/system/systemd-udevd.service && \
		/bin/systemctl daemon-reload && \
		/sbin/udevadm control --reload-rules && \
		/sbin/udevadm trigger \
		udevadm control --reload-rules && \
		udevadm trigger \
	) || true
endif

	@# Disable competing services if this is a Raspberry Pi
	@(test -x /bin/systemctl && /bin/systemctl disable deeper pidp8 2> /dev/null || true)

	@# Get rid of the old SysV init file if upgrading an older system.
	@(test -e /etc/init.d/pidp8i -a -e /etc/rc5.d/S*pidp8i && \
		/bin/systemctl disable pidp8i && \
		rm -f /etc/init.d/pidp8i \
	) || true

	@# Install the systemd unit file if this system is systemd based.
	@(test -x /bin/systemctl && \
		sudo -i -u @INSTUSR@ @ABSPREFIX@/bin/pidp8i install && \
		sudo -i -u @INSTUSR@ $(DESTDIR)$(PREFIX)/bin/pidp8i install && \
		/bin/loginctl enable-linger @INSTUSR@ \
	) || true

	@# Give the install user permission to use GPIO if done on a Pi
	@grep -q '^gpio:' /etc/group && usermod -a -G gpio @INSTUSR@ || true

	@# Give the install user permission to shut down and reboot the Pi
	@# if this is a systemd/sudo based system.
	@(	test -d /etc/sudoers.d -a -w /etc/sudoers.d -a -x /bin/systemctl && \
		@INSTALL@ -m 440 -o root -g root @srcdir@/etc/sudoers \
		    /etc/sudoers.d/099_pidp8i \
	) || true

	@# Install runtime config file if there isn't one there already.
	@test -f $(DESTDIR)$(RCFILE) || @INSTALL@ -m 644 -o @INSTUSR@ @srcdir@/etc/pidp8i.rc $(DESTDIR)$(RCFILE)

	@# Add installation bin dir to the non-root user's PATH unless it's
	@# already in there or we aren't running under sudo.
	@(for p in .profile .bash_profile ; do \
		test -n "$$SUDO_USER" -a -w "/home/$$SUDO_USER/$$p" && \
			! grep -qF "@ABSPREFIX@/bin" "/home/$$SUDO_USER/$$p" && \
			echo "export PATH=\$$PATH:@ABSPREFIX@/bin" >> "/home/$$SUDO_USER/$$p" ; \
			! grep -qF "$(PREFIX)/bin" "/home/$$SUDO_USER/$$p" && \
			echo "export PATH=\$$PATH:$(PREFIX)/bin" >> "/home/$$SUDO_USER/$$p" ; \
	done) || true

	@# Ditto for MANPATH
	@(for p in .profile .bash_profile ; do \
		test -n "$$SUDO_USER" -a -w "/home/$$SUDO_USER/$$p" && \
			! grep -qF "@ABSPREFIX@/share/man" "/home/$$SUDO_USER/$$p" && \
			echo "export MANPATH=\$$MANPATH:@ABSPREFIX@/share/man" >> "/home/$$SUDO_USER/$$p" ; \
			! grep -qF "$(PREFIX)/share/man" "/home/$$SUDO_USER/$$p" && \
			echo "export MANPATH=\$$MANPATH:$(PREFIX)/share/man" >> "/home/$$SUDO_USER/$$p" ; \
		done \
	) || true

	@# If serial mod is disabled, turn off serial console and kgdb stuff
	@# in case they were enabled previously, else they will fight with
	@# our use of GPIO.
	@(  test -z "@PCB_SERIAL_MOD_ANY@" -a -r $(CLTXT) && ! -w $(CLTXT) && \
		cp -p $(CLTXT) "$(CLTXT)"_orig && \
		sed -e 's/console\=[a-zA-Z0-9]+,[0-9]+ //' \
		    -e  's/kgdboc\=[a-zA-Z0-9]+,[0-9]+ //' -i $(CLTXT) \
	) || true

	@# Install CC8 stuff if built
	@test -n "@CC8_CROSS@" && \
		echo "Installing cc8 cross-compiler..." ; \
		@INSTALL@ -m 755 bin/cc8 @prefix@/bin && \
		@INSTALL@ -m 644 @srcdir@/src/cc8/include/* @prefix@/share/include

	@# Install palbart stuff
	@@INSTALL@ -m 755 bin/palbart @prefix@/bin
	@@INSTALL@ -m 644 @srcdir@/src/palbart/palbart.1 @prefix@/share/man/man1

	@# Install os8-run and its dependencies
	@echo "Installing os8-run..."
	@@INSTALL@ -m 775 -g @INSTGRP@ $(OS8RUN) @prefix@/bin
	@( for src in $(OS8RUN_PY_ALL) ; do \
		test -e $$src || src=@srcdir@/$$src ; \
		dest=@prefix@/$$(echo $$src | sed -e 's_^@srcdir@/__') ; \
		echo "Installing $$src to $$dest..." ; \
	    @INSTALL@ -m 644 -g @INSTGRP@ -D $${src}  $${dest}  ; \
	    @INSTALL@ -m 644 -g @INSTGRP@ -D $${src}c $${dest}c ; \
	  done \
	)
	@sed -e 's#^build =.*#build = "@ABSPREFIX@"#' \
	     -e 's#^media =.*#media = os.path.join (build, "share/media/")#' \
	     -e 's#^os8mo =.*#os8mo = os8mi#' \
		 < $(PIDP8I_DIRS) > @prefix@/$(PIDP8I_DIRS)
	@chgrp @INSTGRP@ @prefix@/$(PIDP8I_DIRS)

instdirs:
	@echo "Creating installation directory tree..."
	@for d in $(INSTDIRS) ; do @INSTALL@ -m 755 -o @INSTUSR@ -g @INSTGRP@ -d @prefix@/$$d ; done
	@for d in $(INSTDIRS) ; do @INSTALL@ -m 755 -o @INSTUSR@ -g @INSTGRP@ -d $(DESTDIR)$(PREFIX)/$$d ; done

mediainstall: instdirs
	@echo "[Re]installing OS and program media..."
	@cd @srcdir@ ; \
	find media \( \
		-name \*.os8 -o \
		-name \*.bin  -o \
		-name \*.dsk  -o \
		-name \*.rk05 -o \
		-name \*.tu56 \
	\) -exec @INSTALL@ -D -m 664 -o @INSTUSR@ -g @INSTGRP@ {} @ABSPREFIX@/share/{} \;
	@@INSTALL@ -m 644 -o @INSTUSR@ -g @INSTGRP@ bin/*.rk05 @ABSPREFIX@/share/media/os8
	@@INSTALL@ -m 644 -o @INSTUSR@ -g @INSTGRP@ bin/*.tu56 @ABSPREFIX@/share/media/os8
	\) -exec @INSTALL@ -D -m 664 -o @INSTUSR@ -g @INSTGRP@ {} $(DESTDIR)$(PREFIX)/share/{} \;
	@@INSTALL@ -m 644 -o @INSTUSR@ -g @INSTGRP@ bin/*.rk05 $(DESTDIR)$(PREFIX)/share/media/os8
	@@INSTALL@ -m 644 -o @INSTUSR@ -g @INSTGRP@ bin/*.tu56 $(DESTDIR)$(PREFIX)/share/media/os8
	for f in boot/*.script ; do \
		sed -e 's#%HOME%/\.pidp8i-#@SHAREDIR@/save/#' < $$f > @SHAREDIR@/$$f ; \
		chown @INSTUSR@:@INSTGRP@ @SHAREDIR@/$$f ; \
		chmod 664 @SHAREDIR@/$$f ; \
		sed -e 's#%HOME%/\.pidp8i-#@SHAREDIR@/save/#' < $$f > $(DESTDIR)@SHAREDIR@/$$f ; \
		chown @INSTUSR@:@INSTGRP@ $(DESTDIR)@SHAREDIR@/$$f ; \
		chmod 664 $(DESTDIR)@SHAREDIR@/$$f ; \
	done

# Called by test-os8-run
# Minimizes dependencies to provoke minimal rebuilds.
# Builds cc8.tu56, copying in rather than rebuilding source and demo files.
os8-sys: test-tmp-tools
	$(OS8RUN)@OS8_OPTS@ $(V3D_DIST_SCRIPT)
	$(OS8RUN) $(CC8_TU56_SCRIPT)
	$(OS8RUN)@OS8_OPTS@ $(V3D_PATCH_SCRIPT)
	$(OS8RUN)@OS8_OPTS@ $(V3D_RK05_SCRIPT)

reconfig:
	find . -name \*.d -delete
	@AUTOREMAKE@

release: all
	@srcdir@/tools/mkrel

run: $(PIDP8I_SIM)
	@-libexec/scanswitch > /dev/null ; \

test-tmp-tools:
	@echo "Installing os8-run dependencies..."
	@( for src in $(OS8RUN_PY_ALL) ; do \
		test -e $$src || src=@srcdir@/$$src ; \
		dest=./$$(echo $$src | sed -e 's_^@srcdir@/__') ; \
		echo "Installing $$src to $$dest..." ; \
	    @INSTALL@ -m 644 -g @INSTGRP@ -D $${src}  $${dest}  ; \
	! test -e $${src}c || \
	    @INSTALL@ -m 644 -g @INSTGRP@ -D $${src}c $${dest}c ; \
	  done \
	)
	@( for src in $(TEST_TMP_BINS) ; do \
		test -e $$src || src=@srcdir@/$$src ; \
		dest=./$$(echo $$src | sed -e 's_^@srcdir@/__') ; \
		echo "Installing $$src to $$dest..." ; \

# the updated init.tx file, not before.  We needn't even make it an
# order-only prereq because configure and the INFILES rules above ensure
# that it always exists.
V3D_DIST_SRCS := \
	$(OS8RUN) $(PIDP8I_DIN) \
	lib/pidp8i/dirs.py \
	$(V3D_DIST_SCRIPT) \
	@srcdir@/src/os8/v3d/SYSTEM/LCSYS.BI \
	@srcdir@/src/os8/v3d/SYSTEM/UCSYS.BI \
	@srcdir@/src/os8/v3d/BASIC/LCBAS.BI \
	@srcdir@/src/os8/v3d/BASIC/UCBAS.BI \
	@srcdir@/media/os8/al-*-ba-*.tu56 \
	@srcdir@/media/os8/subsys/*.tu56

# Temporary: We depend on ALL the patches, but really we've picked them over.
V3D_PATCHES := \
	@srcdir@/media/os8/patches/*.patch8
	@srcdir@/patches/os8/v3d/*.patch8

# Dependency on the contents of the v3f source directory.
V3F_SOURCES := \
	@srcdir@/src/os8/v3f/*.PA \
	@srcdir@/src/os8/v3f/*.MA \
	@srcdir@/src/os8/v3f/*.BI

# Dependency on the contents of the ock source directory.
OS8_OCK_SYS_SOURCES := \
	@srcdir@/src/os8/ock/SYSTEM/*.PA \
	@srcdir@/src/os8/ock/SYSTEM/*.MA \
	@srcdir@/src/os8/ock/SYSTEM/*.BI \
	@srcdir@/src/os8/ock/HANDLERS/*.PA \
	@srcdir@/src/os8/ock/CUSPS/*.MA \
	@srcdir@/src/os8/ock/CUSPS/*.BI \
	@srcdir@/src/os8/ock/CUSPS/*.HL

OS8_OCK_CUSPS_SOURCES :=\
	@srcdir@/src/os8/ock/CUSPS/*.PA

OS8_OCK_BF2_SOURCES := \
	@srcdir@/src/os8/ock/LANGUAGE/BASIC/*.PA \
	@srcdir@/src/os8/ock/LANGUAGE/BASIC/*.BA \
	@srcdir@/src/os8/ock/LANGUAGE/BASIC/*.BI \
	@srcdir@/src/os8/ock/LANGUAGE/FORTRAN2/*.PA \
	@srcdir@/src/os8/ock/LANGUAGE/FORTRAN2/*.CO \
	@srcdir@/src/os8/ock/LANGUAGE/FORTRAN2/LIBRARY/*.SB

OS8_OCK_FIV_SOURCES := \
	@srcdir@/src/os8/ock/LANGUAGE/FORTRAN4/*.PA \
	@srcdir@/src/os8/ock/LANGUAGE/FORTRAN4/*.BI \
	@srcdir@/src/os8/ock/LANGUAGE/FORTRAN4/LIBRARY/*.RA

# We could make FIV conditional here.
OS8_OCK_DIST_SRCS := \
	$(OS8RUN) $(PIDP8I_DIN) \
	lib/pidp8i/dirs.py \
	$(OS8_OCK_DIST_MAKER) \
	@srcdir@/media/os8/al-*-ba-*.tu56 \
	@srcdir@/media/os8/subsys/*.tu56 \
	$(OS8_OCK_SYS_OBJ_RK05) $(OS8_OCK_CUSPS_OBJ_RK05) \
	$(OS8_OCK_BF2_OBJ_RK05) $(OS8_OCK_FIV_OBJ_RK05)

OCK_PATCHES := \
	@srcdir@/patches/os8/ock/*.patch8

$(OS8_DIST_RK05): $(V3D_DIST_SRCS) | $(PIDP8I_SIM) $(OS8RUN_OUTFILES)
$(OS8_BASELINE): $(V3D_DIST_SRCS) | $(PIDP8I_SIM) $(OS8RUN_OUTFILES)
	$(OS8RUN)@OS8_OPTS@ $(V3D_DIST_SCRIPT)

$(OS8_BOOT_DISK): $(V3D_RK05_SCRIPT) $(OS8_DIST_RK05) $(V3D_PATCHES) @CC8_TU56@ | $(PIDP8I_SIM) $(OS8RUN_OUTFILES)
	$(OS8RUN)@OS8_OPTS@ $(V3D_RK05_SCRIPT)
$(OS8_TOOLTIME): $(V3D_PATCH_SCRIPT) $(OS8_BASELINE) $(V3D_PATCHES) | $(PIDP8I_SIM) $(OS8RUN_OUTFILES)
	$(OS8RUN)@OS8_OPTS@ $(V3D_PATCH_SCRIPT)

-include obj/os8pkg/*.mk

# Extension of "all" rule to build all packages now that we've included
# the rules for doing so. If you move the autosetup variable below into
# the "all" target dependency list, it won't work because it references
# undefined variables.
pkg_all:@OS8_PKGS_ALL@

test: all
	tools/os8-progtest -x @OS8_PKGS_TESTING@

$(V3D_RUNTIME): $(V3D_RK05_SCRIPT) $(OS8_TOOLTIME) $(PKGS_INCLUDE) $(OS8_PKGS_SELECTED) | $(PIDP8I_SIM) $(OS8RUN_OUTFILES)
	$(OS8RUN) @OS8_OPTS@ $(V3D_RK05_SCRIPT)


$(OS8_OCK_PATCHED_RK05): $(OS8_OCK_PATCHED_MAKER) $(OS8_OCK_DIST_RK05) $(OCK_PATCHES) | $(PIDP8I_SIM) $(OS8RUN_OUTFILES)
	$(OS8RUN)@OS8_OPTS@ $(OS8_OCK_PATCHED_MAKER)

$(OCK_RUNTIME): $(OS8_OCK_BOOT_MAKER) $(OS8_OCK_PATCHED_RK05) $(PKGS_INCLUDE) $(OS8_PKGS_SELECTED) | $(PIDP8I_SIM) $(OS8RUN_OUTFILES)
	$(OS8RUN)@OS8_OPTS@ $(OS8_OCK_BOOT_MAKER)

# To build the magic includer, we should depend on all the created packages.
# Then a newly created one that we care about will drive creation of the include script.
$(PKGS_INCLUDE): $(OS8_PKGS_SELECTED)
	bin/os8pkg include $(OS8_PKGS_SELECTED_NAMES)


# Also build an OS/8 source disk, as a convenience to avoid the 
# need to mount up the 7 source tapes in succession.
#
# Using an order-only dependency for the simulator and the bin disk: we
# only need *a* version of each, they don't have to be recent!
OS8_SRC_SRCS = \
	$(OS8RUN) $(PIDP8I_DIN) \
	lib/pidp8i/dirs.py \
	$(V3D_SRC_SCRIPT) \
	@srcdir@/media/os8/al-*-sa-*.tu56

$(OS8_SRC_RK05): $(OS8_DIST_RK05) $(OS8_SRC_SRCS) | $(PIDP8I_SIM) $(OS8_BOOT_DISK)
$(OS8_SRC_RK05): $(OS8_BASELINE) $(OS8_SRC_SRCS) | $(PIDP8I_SIM) $(OS8_TOOLTIME)
	$(OS8RUN)@OS8_OPTS@ $(V3D_SRC_SCRIPT)

# Build the source disk for OS/8 V3F
$(V3F_BUILD_RK05): $(V3F_SRCDIR)/$(V3F_MANIFEST) $(V3F_SOURCES) | $(OS8_BOOT_DISK)
	cd $(V3F_SRCDIR); @builddir@/bin/os8-cp -v --action-file $(V3F_MANIFEST)
$(V3F_BUILD_RK05): $(V3F_SRCDIR)/$(V3F_MANIFEST) $(V3F_SOURCES) | $(OS8_TOOLTIME)
	rm -f $(V3F_BUILD_RK05)
	cd $(V3F_SRCDIR); @builddir@/$(OS8CP) -v --action-file $(V3F_MANIFEST)

# Make a disk with binaries assembled from the V3F source disk
$(V3F_MADE_RK05): $(V3F_BUILD_RK05) $(V3F_MAKER)
	$(OS8RUN) $(V3F_MAKER)

# Build the source disk for OS/8 OCK SYS Component.
$(OS8_OCK_SYS_SRC_RK05): $(OS8_OCK_SYS_SOURCES) | $(OS8_TOOLTIME)
	@builddir@/$(OS8CP) -v -rk1 $(OS8_OCK_SYS_SRC_RK05) -z -a $(OS8_OCK_SYS_SOURCES) RKA1:

# Make a disk with binaries assembled from the OS8_OCK SYS source disk
$(OS8_OCK_SYS_OBJ_RK05): $(OS8_OCK_SYS_SRC_RK05) $(OS8_OCK_SYS_MAKER)
	$(OS8RUN) $(OS8_OCK_SYS_MAKER)

# Build the source disk for OS/8 OCK CUSPS Component.
$(OS8_OCK_CUSPS_SRC_RK05): $(OS8_OCK_CUSPS_SOURCES) | $(OS8_TOOLTIME)
	@builddir@/$(OS8CP) -v -rk1 $(OS8_OCK_CUSPS_SRC_RK05) -z -a $(OS8_OCK_CUSPS_SOURCES) RKA1:

# Make a disk with binaries assembled from the OS8_OCK SYS source disk
$(OS8_OCK_CUSPS_OBJ_RK05): $(OS8_OCK_CUSPS_SRC_RK05) $(OS8_OCK_CUSPS_MAKER)
	$(OS8RUN) $(OS8_OCK_CUSPS_MAKER)

# Build the source disk for OS/8 OCK BASIC and FORTRAN II Component.
$(OS8_OCK_BF2_SRC_RK05): $(OS8_OCK_BF2_SOURCES) | $(OS8_TOOLTIME)
	@builddir@/$(OS8CP) -v -rk1 $(OS8_OCK_BF2_SRC_RK05) -z -a $(OS8_OCK_BF2_SOURCES) RKA1:

# Make a disk with binaries assembled from the OS8_OCK FIRTRAN II source disk
$(OS8_OCK_BF2_OBJ_RK05): $(OS8_OCK_BF2_SRC_RK05) $(OS8_OCK_BF2_MAKER)
	$(OS8RUN) $(OS8_OCK_BF2_MAKER)

# Build the source disk for OS/8 OCK FORTRAN IV Component.
$(OS8_OCK_FIV_SRC_RK05): $(OS8_OCK_FIV_SOURCES) | $(OS8_TOOLTIME)
	@builddir@/$(OS8CP) -v -rk1 $(OS8_OCK_FIV_SRC_RK05) -z -a $(OS8_OCK_FIV_SOURCES) RKA1:

# Make a disk with binaries assembled from the OS8_OCK FORTRAN IV source disk
$(OS8_OCK_FIV_OBJ_RK05): $(OS8_OCK_FIV_SRC_RK05) $(OS8_OCK_FIV_MAKER)
	$(OS8RUN) $(OS8_OCK_FIV_MAKER)

$(OS8_OCK_DIST_RK05): $(OS8_OCK_DIST_SRCS) | $(PIDP8I_SIM) $(OS8RUN_OUTFILES)
	$(OS8RUN)@OS8_OPTS@ $(OS8_OCK_DIST_MAKER)

# Make a bootable OS/8 v3f TCO8 DECtape image
$(V3F_TC08_TU56): $(V3F_MADE_RK05) $(ALL_TU56_SCRIPT) $(CUSP_COPYIN_SCRIPT)
	$(OS8RUN)@OS8_OPTS@ $(ALL_TU56_SCRIPT) --enable v3f

# Make a bootable OS/8 v3f TD8E 12K DECtape image
$(V3F_TD12K_TU56): $(V3F_MADE_RK05) $(ALL_TU56_SCRIPT) $(CUSP_COPYIN_SCRIPT)
	$(OS8RUN)@OS8_OPTS@ $(ALL_TU56_SCRIPT) --enable v3f --enable td12k

# Make a bootable OS/8 v3d TCO8 DECtape image
$(V3D_TC08_TU56): $(ALL_TU56_SCRIPT) $(CUSP_COPYIN_SCRIPT) | $(OS8_BOOT_DISK) 
$(V3D_TC08_TU56): $(ALL_TU56_SCRIPT) $(CUSP_COPYIN_SCRIPT) | $(OS8_TOOLTIME) 
	$(OS8RUN)@OS8_OPTS@ $(ALL_TU56_SCRIPT)

# Make a bootable OS/8 v3d TD8E 12K DECtape image
$(V3D_TD12K_TU56): $(ALL_TU56_SCRIPT) $(CUSP_COPYIN_SCRIPT) | $(OS8_BOOT_DISK) 
$(V3D_TD12K_TU56): $(ALL_TU56_SCRIPT) $(CUSP_COPYIN_SCRIPT) | $(OS8_TOOLTIME) 
	$(OS8RUN)@OS8_OPTS@ $(ALL_TU56_SCRIPT) --enable td12k

# Create the CC8 distribution DECtape image
bin/cc8.tu56: $(CC_OS8_OBJS) $(CC_OS8_SRCS) $(CC_OS8_DEMOS) $(CC8_TU56_SCRIPT) | $(OS8_DIST_RK05)
	$(OS8RUN) $(CC8_TU56_SCRIPT)

# Rule for building PAL assembly language programs in src/asm/*.pal.
obj/%.lst bin/%-pal.pt: @srcdir@/src/asm/%.pal bin/palbart
	bin/palbart -lr $< || cat obj/$*.err
	mv @srcdir@/src/asm/$*.lst obj
	mv @srcdir@/src/asm/$*.rim bin/$*-pal.pt

# Ditto for those in examples/*.pal.

obj/cc8/os8/%.c: @srcdir@/src/cc8/examples/%.c
	sed '/^#include/d' $< > $@

$(BUILDDIRS):
	mkdir -p $@

$(PIDP8I_SIM): $(SIM_OBJS) obj/pidp8i/gpio-@LED_DRIVER_MODULE@ls.o
	$(CC) -o $@ $^ $(LIBS)
	$(CC) -o $@ @PI_LFLAGS@ $^ $(LIBS) $(SIM_LFLAGS) @PI_LIBS@
	ln -f bin/pidp8i-sim bin/pdp8

bin/cc8: $(CC8_OBJS)
	$(CC) -o $@ $^ $(LIBS)
	$(CC) $(CC8_CROSS_CFLAGS) -o $@ $^ $(LIBS)

bin/d8tape: $(D8TAPE_OBJS)
	$(CC) -o $@ $^
	$(CC) $(D8TAPE_CFLAGS) -o $@ $^

bin/palbart: $(PALBART_OBJS)
	$(CC) -o $@ $^
	$(CC) $(PALBART_CFLAGS) -o $@ $^

bin/pidp8i-test: obj/misc/test.o obj/pidp8i/gpio-nls.o obj/pidp8i/gpio-common.o
	$(CC) -o $@ $^ $(LIBS) -lncurses
	$(CC) -o $@ $(CFLAGS) @PI_CFLAGS@ @PI_LFLAGS@ $^ $(LIBS) @PI_LIBS@ -lncurses

bin/ptp2txt: obj/misc/ptp2txt.o
	$(CC) -o $@ $^
	ln -f bin/ptp2txt bin/txt2ptp

bin/txt2ptp: bin/ptp2txt
	ln -f bin/ptp2txt bin/txt2ptp

bin/deeper: obj/misc/deeper.o obj/pidp8i/gpio-@LED_DRIVER_MODULE@ls.o obj/pidp8i/gpio-common.o
	$(CC) -o $@ $^ $(LIBS)
	$(CC) -o $@ $(CFLAGS) @PI_CFLAGS@ @PI_LFLAGS@ $^ $(LIBS) @PI_LIBS@

doc/e8-manual.pdf: doc/e8-manual.md
	tools/mkmanpdf doc/e8-manual

libexec/scanswitch: obj/misc/scanswitch.o obj/pidp8i/gpio-nls.o obj/pidp8i/gpio-common.o
	$(CC) -o $@ $^ $(LIBS)
	$(CC) -o $@ $(CFLAGS) @PI_CFLAGS@ @PI_LFLAGS@ $^ $(LIBS) @PI_LIBS@

# Reconfigure whenever one of the *.in or autosetup files changes unless
# this is "make clean".
# 
# We purposely list only one of the OUTFILES on the left hand side
# because to list them all is to invite Make to run N copies of the
# configure script in parallel up to the limit of -j or the number of

-include \
	$(SIM_OBJS:.o=.d) \
	$(CC8_OBJS:.o=.d) \
	$(D8TAPE_OBJS:.o=.d) \
	$(MISC_OBJS:.o=.d) \
	$(PALBART_OBJS:.o=.d)
-include $(ADF)

# Getting Started with the PiDP-8/I Software

## Orientation

You will be reading this file from one of several likely places:
You will be reading this either:

*   [Online][tlrm], within [the Fossil project repository][home].
*   …[online][tlrm], within [the Fossil project repository][home]; or

*   As a text file within the [source packages][src].
*   …as a text file within the [source packages][src]; or

*   In the read-only [GitHub mirror][ghm].
*   …in the read-only [GitHub mirror][ghm].

The source packages and the GitHub mirror are secondary outputs from the
The latter two are secondary outputs from the first, being the PiDP-8/I
Fossil repository, which is the primary home for the PiDP-8/I software
development project.
software development project’s home.

This is open source software: you are welcome to
[contribute to the project][ctrb].

[ctrb]: https://tangentsoft.com/pidp8i/doc/trunk/CONTRIBUTING.md
[ghm]:  https://github.com/tangentsoft/pidp8i
[home]: https://tangentsoft.com/pidp8i/
[src]:  https://tangentsoft.com/pidp8i/#src
[tlrm]: https://tangentsoft.com/pidp8i/doc/trunk/README.md


## Prerequisites

*   A Raspberry Pi with the 40-pin GPIO connector.  That rules out the
*   A Raspberry Pi with the 40-pin GPIO connector.
    first-generation Raspberry Pi model A and B boards which had a
    26-pin GPIO connector.

*   An SD card containing [a compatible OS][os].
*   An SD card imaged with Raspberry Pi OS, either [stock][rpios] or
    [modified by us][bosi].

*   This software distribution, unpacked somewhere convenient within the
    filesystem on the Raspberry Pi.  We recommend that you unpack it
    somewhere your user has read/write access like `$HOME/src/pidp8i`.
    filesystem on the Raspberry Pi. That’s already done on [our modified
    OS images][bosi], in `~/pidp8i`. When adding it to the stock OS, we
    recommend that you unpack it in your `HOME` directory or somewhere
    else your user has read/write access.

*   We require several tools and libraries that aren't always installed:

*   While those with no Linux and Raspberry Pi knowledge may be able to
    *   A working C compiler and other standard Linux build tools,
        such as `make(1)`.

    *   Python's `pexpect` library
    follow our instructions blindly, we recommend that such persons look
    at [the official Raspberry Pi documentation][rpfd], particularly
    their [Linux][rpfl] and [Raspberry Pi OS][rpfr] guides. The book
    "[Linux for Makers][lfm]" by Aaron Newcomb is also well-reviewed.

    *   The `ncurses` development libraries
*   Building the software requires several tools and libraries, some of
    which you may not already have.

    To install all of this on a Raspbian type OS, say:
    On Raspberry Pi OS, say:

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

    Under Homebrew, such as on macOS, say instead:

        $ brew install make perl python
        $ pip3 install --user pexpect pyyaml

    On [other compatible OSes][othos], you may need different commands.

[bosi]:  https://tangentsoft.com/pidp8i/#bosi
[lfm]:   https://www.makershed.com/products/make-linux-for-makers
[os]: https://tangentsoft.com/pidp8i/wiki?name=OS+Compatibility
[othos]: https://tangentsoft.com/pidp8i/wiki?name=OS+Compatibility
[rpfd]:  https://www.raspberrypi.org/documentation/
[rpfl]:  https://www.raspberrypi.org/documentation/linux/
[rpfr]:  https://www.raspberrypi.org/documentation/raspbian
[rpios]: https://www.raspberrypi.org/software/


<a id="unpacking"></a>
## Getting the Software onto Your Pi
## Enabling the SSH Server <a id="sshd"></a>

[That topic is covered elsewhere](./doc/OS-images.md#sshd).
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.
## Preparing Your Pi <a id="preparing"></a>

If you’ve just barely unpacked Raspberry Pi OS 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 incorrect for *your* location.
If you are reading this [online][this] and have not yet downloaded and
unpacked the software source code onto your Pi, this section will get
you going.

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


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

This section is for those reading this on [our project home site][home]
or via [its GitHub mirror][ghm]. If you are instead reading this as the
[this]: https://tangentsoft.com/pidp8i/doc/trunk/README.md
`README.md` file within an unpacked distribution of the PiDP-8/I
software, [skip to the next section](#configuring).


<a id="transferring"></a>
### Transferring the File to the Pi
### Transferring the Source Tarball to the Pi <a id="transferring"></a>

The first step is to get the tarball (`*.tar.gz` file) or Zip file onto
the Pi. There are many options:
There are many ways to get the `*.tar.gz` file onto your Pi:

1.  **Copy the file to the SD card** you're using to boot the Pi.
    When inserted into a Mac or Windows PC, typically only the `/boot`
    partition mounts as a drive your OS can see.  (There's a much
    larger partition on the SD card, but most PCs cannot see it.)
    There should be enough free space left in this small partition to
    copy the file over.  When you boot the Pi up with that SD card,
    you will find the tarball or Zip file in `/boot`.
    copy the tarball over.  When you boot the Pi up with that SD card,
    you will find it in `/boot`.

2.  **Pull the file down to the Pi** over the web, directly to the Pi:

        $ wget -O pidp8i.tar.gz https://goo.gl/JowPoC

    That will get you a file called `pidp8i.tar.gz` in the current
    working directory containing the latest *release* version.  (Use the
    "bleeding edge" links on the home page if you want the tip of trunk
    instead!)
    working directory containing the latest *stable release.* To get the
    bleeding edge tip-of-trunk version instead, say:

        $ wget -O pidp8i.tar.gz https://tangentsoft.com/pidp8i/tarball

3.  **SCP the file over** to a running Pi from another machine.
    If your Pi has OpenSSH installed and running, you can use
    If your Pi has [OpenSSH installed and running](#sshd), you can use
    [WinSCP][wscp], [Cyberduck][cd], [FileZilla][fz] or another SCP
    or SFTP-compatible file transfer program to copy the file to the
    Pi over the network.

[cd]:   https://cyberduck.io/
[fz]:   https://filezilla-project.org/
[wscp]: https://winscp.net/eng/

4.  **Clone the Fossil repository** using the instructions in the
    [`HACKERS.md` file][hack]. (Best for experts or those who wish to
    [`CONTRIBUTING.md` file][ctrb]. (Best for experts or those who wish to
    become experts.)

[hack]: https://tangentsoft.com/pidp8i/doc/trunk/HACKERS.md

5.  **Switch to the binary OS installation images** available from the
Alternatively, switch to [the binary OS installation images][bosi],
    [top-level project page][cprj].  These are default installations of
    Raspbian Lite with the PiDP-8/I software already downloaded, built,
which are a copy of Raspberry Pi OS as of our latest stable release,
with the PiDP-8/I software already downloaded, configured, and installed
    and installed.  These images were produced in part using option #4
    above, so you can use Fossil to update your software to the current
for you.
    version at any time, as long as the Pi is connected to the Internet.


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

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

If you grabbed the tarball:

    $ tar xf pidp8i.tar.gz
    $ 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
Pi Foundation.  In particular, we recommend their [Linux][rpfl] and
[Raspbian][rpfr] guides.  The book "[Make: Linux for Makers][lfm]"
by Aaron Newcomb is also supposed to be good.


[rpfd]: https://www.raspberrypi.org/documentation/
[rpfl]: https://www.raspberrypi.org/documentation/linux/
[rpfr]: https://www.raspberrypi.org/documentation/raspbian

[lfm]:  https://www.makershed.com/products/make-linux-for-makers


<a id="configuring"></a>
## Configuring, Building and Installing
## Configuring, Building and Installing <a id="configuring"></a>

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

    $ cd ~/pidp8i
    $ ./configure && make && sudo make install
    $ ./configure && tools/mmake && 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).
You may want to add options to the `configure` step, described
[below](#options).

After that initial configuration, the software normally auto-reconfigures
Subsequent software updates and rebuilds should not require that you
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
re-run the `configure` step manually, but if automatic re-configuration
fails, you can force it:
build error after updating to a new version of the software, try saying:

    $ make reconfig

The “`mmake`” 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.
...and then continuing with the `make && sudo make install` steps before
reporting a build error.

Only the `make install` step needs to be done via “`sudo`”. No other
step requires root privileges.

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

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

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

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, though there are [significant
differences][mdif].

Quick start:

1.  To start the simulator running in the background:
<a id="running"></a>
### Running the Software

        $ 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 your terminal to the running simulator, run the same
    script without an argument:

        $ pidp8i

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 command line:
For the most part, this is covered in the documentation linked from the
[Learning More](/#learning) section of the project home page.

        $ pidp8i stop

    That then lets you run something like [Incandescent Thought][ith]
    without conflict.

You might also find our [Learning More](/#learning) links helpful.

[ith]:     https://tangentsoft.com/pidp8i/wiki?name=Incandescent+Thought
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`.


## The Background Simulator Service <a id="systemd" name="unit"></a>

The PiDP-8/I software distribution uses [systemd] to run the background
PDP-8 simulator as user-level service, so you needn’t give `sudo` on any
command to interact with that service, as you did in older versions of
the software.

Although you can give verbose `systemctl` commands like this:

    $ systemctl --user start pidp8i

…we’ve provided a wrapper for such commands:
<a id="options"></a>
### Configure Script Options

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

*All* arguments are passed to `systemctl`, not just the first, so you
can pass any flags that `systemctl` accepts, as in the last example.

[systemd]: https://www.freedesktop.org/wiki/Software/systemd/



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

You can change many things about the way the software is built and
installed by giving options to the `configure` script:


<a id="prefix"></a>
### --prefix <a id="prefix"></a>
#### --prefix

Perhaps the most widely useful `configure` script option is `--prefix`,
which lets you override the default installation directory, `/opt/pidp8i`.
There are many good reasons to change where the software gets installed,
but the default is also a good one, so unless you know for a fact that
you want to change this default, leave it alone.

For example, you might prefer that the installer put the built software
under your home directory.  This will do that:

    $ ./configure --prefix=$HOME/pidp8i && sudo make install

You might think that installing to a directory your user has complete
control over would remove the need for installing via `sudo`, but that
is not the case, since the installation script needs root privileges to
mark a few of the executables as having permission to run at high priority
levels, which improves the quality of the display, particularly with the
[incandescent lamp simulator][ils] feature enabled.


<a id="lowercase"></a>
### --lowercase <a id="lowercase"></a>
#### --lowercase

The American Standards Association (predecessor to ANSI) delivered the
second major version of the ASCII character encoding standard the same
year the first PDP-8 came out, 1965. The big new addition? Lowercase.

That bit of history means that when the PDP-8 was new, lowercase was a
fancy new feature in the computing industry. That, plus the memory

    right thing." The simulator is configured to send lowercase input to
    the PDP-8 software running on it. Where we have the skill, will,
    need, and time for it, we have [patched][tty] some of the software
    we distribute that otherwise would not do the right thing with
    lowercase input to make it do so.

    This is *not* the option you want if you are a purist.

*   **pass** — This passes keyboard input through to the simulator
    unchanged, and no patches are applied to the PDP-8 software we
    distribute.

    This is the option for historical purists. If you run into trouble
    getting the software to work as you expect when built in this mode,
    try enabling CAPS LOCK.

*   **upper** — This option tells the PDP-8 simulator to turn lowercase
    input into upper case. This is the behavior we used for all versions
    of the PiDP-8/I software up through v2017.04.04.  Essentially, it
    tells the software that you want it to behave as through you've got
    it connected to a Teletype Model 33 ASR.
    it connected to an uppercase-only terminal like the Teletype Model 33 ASR.

    The advantage of this mode is that you will have no problems running
    PDP-8 software that does not understand lowercase ASCII text.

    The disadvantage is obvious: you won't be able to input lowercase
    ASCII text.

    ASCII text.  The SIMH option we enable in this mode is
    bidirectional, so that if you run a program that does emit lowercase
    ASCII text — such as Rick Murphy's version of Adventure — it will be
    uppercased, just like an ASR-33 would do.
    The SIMH option we enable in this mode is bidirectional, so that if
    you run a program that does emit lowercase ASCII text — such as Rick
    Murphy's version of Adventure — it will be uppercased, just like an
    ASR-33 would do.

    Another trap here is that the C programming language requires
    lowercase text, so you will get a warning if you leave the default
    option **--enable-os8-cc8** set. Pass **--disable-os8-cc8** when
    enabling **upper** mode.

*   **none** — This passes 7-bit ASCII text through to the software
    running on the simulator unchanged, and no patches are applied to
    the PDP-8 software we distribute.

    This is the option for historical purists. If you run into trouble
    getting the software to work as you expect when built in this mode,
    try enabling CAPS LOCK.

[sa]:  http://homepage.cs.uiowa.edu/~jones/pdp8/faqs/#charsets
[tty]: https://tangentsoft.com/pidp8i/wiki?name=OS/8+Console+TTY+Setup


<a id="nls"></a>
#### --no-lamp-simulator
### --no-lamp-simulator <a id="nls"></a>

If you build the software on a multi-core host, the PDP-8/I simulator is
normally built with the [incandescent lamp simulator][ils] feature,
which drives the LEDs in a way that mimics the incandescent lamps used
in the original PDP-8/I. (We call this the ILS for short.) This feature
currently takes too much CPU power to run on anything but a multi-core
Raspberry Pi, currently limited to the Pi 2 and Pi 3 series.
takes too much CPU power to run on anything but a multi-core
Raspberry Pi, being the Pi 2 and newer full-sized boards, excluding
the Zero series.

If you configure the software on a single-core Pi — models A+, B+, and
Zero — the simulator uses the original low-CPU-usage LED driving method
instead. (a.k.a. NLS for short, named after this configuration option.)

Those on a multi-core host who want this low-CPU-usage LED driving
method can give the `--no-lamp-simulator` option to `configure`.  This
method not only uses less CPU, which may be helpful if you're trying to
run a lot of background tasks on your Pi 2 or Pi 3, it can also be
helpful when the CPU is [heavily throttled][thro].


<a id="serial-mod"></a>
### --serial-mod <a id="serial-mod"></a>
#### --serial-mod

If you have done [Oscar's serial mod][sm1] to your PiDP-8/I PCB and the
Raspberry Pi you have connected to it, add `--serial-mod` to the
`configure` command above.

If you do not give this flag at `configure` time with these hardware
modifications in place, the front panel will not work correctly, and
trying to run the software may even crash the Pi.

If you give this flag and your PCBs are *not* modified, most of the
hardware will work correctly, but several lights and switches will not
work correctly.


<a id="alt-serial-mod"></a>
### --alt-serial-mod <a id="alt-serial-mod"></a>
#### --alt-serial-mod

This flag is for an [alternative serial mod by James L-W][sm2]. It
doesn't require mods to the Pi, and the mods to the PiDP-8/I board are
different from Oscar's.  This flag changes the GPIO code to work with
these modifications to the PiDP-8/I circuit design.

See the linked mailing list thread for details.

As with `--serial-mod`, you should only enable this flag if you have
actually done the mods as specified by James L-W.

This option is a pure alternative to [`--serial-mod`](#serial-mod): you
can leave both off, but you cannot pass both.


#### --throttle
### --throttle <a id="throttle"</a>

See [`README-throttle.md`][thro] for the values this option takes.  If
you don't give this option, the simulator runs as fast as possible, more
you don't give this option, the simulator runs as fast as possible.
or less.


<a id="savestate"></a>
### --enable-savestate <a id="savestate"></a>
#### --enable-savestate

By default, the PiDP-8/I starts up with the core state undefined and
runs the boot script you’ve selected either with the IF switches or by
passing it on the command line to `pidp8i-sim` or `pdp8`.  This brings
the simulator up in a known state, with no persistence between restarts
other than what was written to the simulated storage devices before the
last shutdown.

On a real PDP-8 with core memory, however, the values in memory will
persist for weeks without power; core memory on a PDP-8 is not zeroed on
power-up, unlike RAM on a modern computer.  Since the CPU doesn’t start
executing anything on power-up in a stock PDP-8 configuration, this
means the user can toggle in a program/OS restart address with the
switch register (SR), load it into the program counter (PC) with the
Load Addr switch, then START the CPU to restart their program without
having to reload it from tape or disk.

There were also several power fail and restart options designed and made
available for the PDP-8 series throughout its lifetime. One of these,
the KP8-I for the PDP-8/I would detect a power fail condition, then in
available for the PDP-8 series throughout its lifetime. One of these —
the KP8-I for the PDP-8/I — would detect a power fail condition, then in
the brief time window while the power supply’s reservoir capacitors kept
the computer running, this option card would raise an interrupt, giving
a user-written routine up to 1 millisecond to save important registers
to core so they would persist through the power outage. Then on
power-up, it would start executing at core location 00000, where another
user routine would load those registers back from core to restart the
system where it left off before the power failed.

Giving this option gives roughtly the same effect for all generated boot
scripts: any time the simulator is shut down gracefully, it saves all
key simulator state — registers, core, device assignments, etc. — to a
disk file. Then on restart, that script will reload that saved state if
it finds the saved state file.

This is not identical to a KP8-I, in that it doesn’t require any
This is not identical to a KP8-I in that it doesn’t require any
user-written PDP-8 code to run, which is why it’s optional: it’s
ahistoric with respect to the way the included OSes normally ran.

In absence of a hardware option like the KP8-I, a more accurate
simulation would only save the core memory state to a host-side disk
file and reload it on simulator re-start. You can get that behavior atop
the current mechanism by adding commands like the following to each

    DEP MQ 0
    DEP PC 0

That zeroes the key registers and prevents the CPU from running as it
normally would after giving the `RESTORE` command to SIMH.


#### --disable-usb-automount
### --disable-usb-automount <a id="dub"></a>

When you install the software on a [systemd][systemd]-based Linux
When you install the software on a [systemd]-based Linux
system, we normally configure the OS to automatically mount USB drives
when they are initially plugged in, which allows the `SING_STEP` + `DF`
media image auto-attach feature to work smoothly. That is, if you plug
in a USB memory stick holding a `*.pt` file containing a paper tape
image, you want the simulator to be able to find it if you have the DF
switches set to 1, telling the PiDP-8/I front panel code to look for
something to attach to the simulator's paper tape reader.

This feature may interfere with other uses of USB, such as when booting
your Pi from an external USB hard disk drive. Give this option to
disable the feature.

(Alternately, you could modify our `etc/udev.rules` and/or
`bin/usb-mount` scripts so that they work cooperatively with your local
USB setup rather than conflicting with it.)


#### --disable-cc8-cross
### --disable-cc8-cross <a id="dcc8"></a>

Give this option if you do not want to build Ian Schofield's `cc8` C
cross-compiler on the host.

Because the cross-compiler is needed to build the CC8 native OS/8
compiler, disabling the cross-compiler also causes the native compiler
to be left off the bootable OS/8 RK05 disk image, as if you’d passed the
`--disable-os8-cc8` configuration option.


### --use-ock <a id="ock"></a>
<a id="disable-os8"></a>
#### --disable-os8-\*

By default, the boot media used for the IF=0 and IF=7 cases is an
extended version of OS/8 V3D, as distributed by DEC, plus some patches
and third-party software additions, per the following sections.

For the late 2020 release, we have another more ambituous option, being
[the OS/8 Combined Kit][ock], which is the last complete release of OS/8
released by DEC. (See that link for details.)

Pass this option to boot OCK rather than OS/8 V3D.

[ock]: https://tangentsoft.com/pidp8i/dir?ci=tip&name=src/os8/ock



### --disable-os8-\* <a id="disable-os8"></a>

Several default components of the [OS/8 RK05 disk image](#os8di) used by
boot options IF=0 and IF=7 can be left out to save space and build time:

*   **--disable-os8-advent** — Leave out the [Adventure][advent] game.

*   **--disable-os8-ba** - Leave out the BASIC games and demos which
    come from DEC's book "101 BASIC Computer Games." These are normally
*   **--disable-os8-basic-games** - Leave out the BASIC games and demos which
    primarily come from DEC's book "101 BASIC Computer Games."
    installed to `RKB0:` as `*.BA`, thus the option's name.

    (We considered naming it `--disable-os8-basic-games-and-demos`, but
    that's too long, and it can't be `--disable-os8-basic` because that
    implies that it is the OS/8 BASIC subsystem that is being left out,
    which is not even currently an option.)

*   **--disable-os8-cc8** - Leave out Ian Schofield's native OS/8 CC8
    compiler and all of its ancillary files.

*   **--disable-os8-chess** — Leave out John Comeau's
*   **--disable-os8-chekmo** — Leave out John Comeau's
    [CHECKMO-II chess implementation][chess].

*   **--disable-os8-crt** — Suppress the [console rubout behavior][tty]
    enabled while building the OS/8 binary RK05 disk image. You
    probably only want to do this if you have attached a real teletype
    to your PiDP-8/I, and thus do not want video terminal style rubout
    processing.

*   **--disable-os8-dcp** — Leave out the DCP disassembler.

*   **--disable-os8-e8** — Leave out [Bill Silver’s E8][e8], an
    Emacs-like screen editor.

*   **--disable-os8-focal** - Do not install any version of FOCAL on the
    OS/8 system disk. This option sets `--disable-os8-uwfocal` and
    overrides `--enable-os8-focal69`, both discussed below.

*   **--disable-os8-fortran-ii** - Leaves out the FORTRAN II compiler,
    SABR, the linking loader (`LOADER`), the `LIBSET` tool, and the
    `*.RL` library files.  This option is ignored unless you also give
    `--disable-os8-cc8` because the OS/8 version of CC8 is built atop
    this subsystem.

*   **--disable-os8-fortran-iv** - Leave the FORTRAN IV compiler out.

*   **--disable-os8-init** - Do not install `RKB0:INIT.TX` or its “show
    on boot” script, `INIT.CM`.  Rather than disable the default on-boot
    init message, you may want to edit `media/os8/init.tx.in` to taste
    and rebuild.

*   **--disable-os8-k12** - Leave out the Kermit-12 implementation
*   **--disable-os8-kermit-12** - Leave out the Kermit-12 implementation
    normally installed to `RKA0:`

*   **--disable-os8-macrel** - Leave the MACREL v2 assembler and its
    associated FUTIL V8B tool out.

*   **--disable-os8-src** - Do not build the `v3d-src.rk05` disk
    image from the OS/8 source tapes.  This is not controlled by
    `--os8-minimal` because that only affects the bootable disk images.

*   **--disable-os8-uwfocal** - Leave out the U/W FOCAL V4E programming
    environment normally installed to `RKA0:`.
    
    Note that the default installation only installs `UWF16K.SV`, not
    the rest of the files on `media/os8/subsys/uwfocal*.tu56`. There is
    much more to explore here, but we cannot include it in the default
    installation set because that would overrun OS/8's limitation on the
    number of files on a volume.

You can later remove each of these after installation using
[our package manager][os8pkg].

[advent]: http://www.rickmurphy.net/advent
[chess]:  https://chessprogramming.wikispaces.com/CHEKMO-II
[e8]:     https://tangentsoft.com/e8/
[os8p]:   https://tangentsoft.com/pidp8i/doc/trunk/doc/os8-patching.md
[os8pat]: https://tangentsoft.com/pidp8i/doc/trunk/doc/os8-patching.md
[os8pkg]: https://tangentsoft.com/pidp8i/doc/trunk/doc/os8pkg.md


<a id="enable-os8"></a>
### --enable-os8-\* <a id="enable-os8"></a>
#### --enable-os8-\*

There are a few file sets not normally installed to the [OS/8 RK05 disk
image](#os8di) used by boot options IF=0 and IF=7. You can install them
with the following options:

*   **--enable-os8-music** — The `*.MU` music scores and Rich Wilson's
    associated compiler (`MUSIC.PA`) and player overlay (`PLAYOV.PA`)

    much older and had a much more wide-reaching impact in history, so
    we choose to provide unvarnished TECO by default.

    That having been said, people don't go to a ren fair and expect to
    experience the historical ubiquity of typhoid fever, so do not feel
    guilty if you choose to try this option.

[uvte]: https://tangentsoft.com/pidp8i/wiki?name=Using+VTEDIT

*   **--enable-os8-focal69** — Because the default installation includes
    U/W FOCAL, we have chosen to leave FOCAL 69 out by default to save
    space on the O/S 8 system disk. You can give this option to install
    this implementation alongside U/W FOCAL, or you can couple this
    option with `--disable-os8-uwfocal` to reverse our choice of which
    FOCAL implementation to install by default.
    U/W FOCAL, we have chosen to leave [FOCAL,1969][f69] out by default
    to save space on the O/S 8 system disk. You can give this option to
    install this implementation alongside U/W FOCAL, or you can couple
    this option with `--disable-os8-uwfocal` to reverse our choice of
    which FOCAL implementation to install by default.

    You should know that the reason we made this choice is that the
    version of FOCAL 69 we are currently shipping is fairly minimal: we
    believe we are shipping the original DEC version of FOCAL 69 plus a
    version of FOCAL,1969 we are currently shipping is fairly minimal: we
    believe we are shipping the original DEC version of FOCAL,1969 plus a
    few carefully-selected overlays. There are many more overlays and
    patches available on the Internet for FOCAL 69, but we have not had
    patches available on the Internet for FOCAL,1969, but we have not had
    time to sort through these and make choices of which ones to ship or
    how to manage which ones get installed. Thus our choice: we want to
    provide the most functional version of FOCAL by default, and within
    the limitations of the time we have chosen to spend on this, that is
    U/W FOCAL today.

    (See our [U/W FOCAL manual supplement][suppd] for a list of
    differences between these versions of FOCAL, which implicitly
    explains why we chose it.)

    It is possible that we will eventually add enough patches and
    overlays to FOCAL 69 that it will become more powerful than U/W
    overlays to FOCAL,1969 that it will become more powerful than U/W
    FOCAL, so we might then choose to switch the defaults, but that is
    just speculation at the time of this writing.

You can later add each of these after installation using
[our package manager][os8pkg].

[f69]:   https://tangentsoft.com/pidp8i/wiki?name=Running+FOCAL%2C1969
[suppd]: https://tangentsoft.com/pidp8i/doc/trunk/doc/uwfocal-manual-supp.md#diffs
[uvte]:  https://tangentsoft.com/pidp8i/wiki?name=Using+VTEDIT


#### --os8-minimal
### --os8-minimal <a id="os8-minimal"></a>

If you set this flag, it sets all `--enable-os8-*` flags to false and
all `--disable-os8-*` flags to true.  If you give this along with any
`--enable-os8-*` option, minimal mode overrides it.  Alas, the only way
to get "minimal plus one or two features" is to explicitly disable all
of the optional OS/8 features you don't want.
This sets all `--enable-os8-*` flags to false and all `--disable-os8-*`
flags to true. This mode overrides any `--enable-os8-*` flag, so if you
want a minimal install plus just one or two features, it’s simplest to
give this flag and then use [our package manager][os8pkg] to add in the
elements you want rather than pass a bunch of `--disable-os8-*` options.

This option may not do some things you think it should:

This flag's name is aspirational, rather than accurate: our current
"minimal" installation could still be stripped down some more.  We
1.  This flag's name is aspirational, not a promise of an ideal: our
    current "minimal" installation could be stripped down further. For
expect to add more `--disable-os8-*` flags later to reduce the delta
between the ideal "minimal OS/8" and our current offering.  These
options would then be included in `--os8-minimal`.  An example of this
is OS/8's BASIC interpreter, which currently cannot be left out.

    example, we currently have no way to leave out OS/8's BASIC
    interpreter, even though no core OS services depend on it.
This option does not control some things you might think it should:

1.  This option does not affect the `--lowercase` option because that
    affects only OS/8's command interpreter and OS/8's BASIC
2.  This option does not affect [the `--lowercase` option](#lowercase)
    because that affects only OS/8's command interpreter and OS/8's BASIC
    implementation, so we deem it to be orthogonal to the purpose of the
    `--os8-minimal` flag, which only affects the optional post-`BUILD`
    features.  If you want a *truly* pristime OS/8 disk, you should
    therefore also give `--lowercase=none`.
    features. You may therefore wish to give `--lowercase=none` along
    with `--os8-minimal`.

2.  This option does not affect `--disable-os8-src`, because it only
    suppresses optional features in the "bin" media.  If you want a
    minimal OS/8 bin disk and no src disk, give that option as well.
3.  This option does not affect `--disable-os8-src`, because it only
    suppresses optional features in the primary bootable OS/8 media.  If
    you want minimal OS/8 boot media without a separate source code
    data disk, give this option as well.

3.  Although it disables *display* of the `INIT.TX` file on boot, the
    file is still generated in case you later want to enable it, since
    the file acts as build documentation as well as a "welcome" message.
4.  Although this option disables *display* of the `INIT.TX` file on
    boot, the file is still generated, on purpose.  First, it acts as
    build documentation, recording what was built and when.  Second,
    you may wish to enable this welcome message later, and it’s rather
    painful to go back through the build process to generate it after
    the fact.


#### --help
### --help

Run `./configure --help` for more information on your options here.


## Runtime Configuration <a id="runtime"></a>

The `pidp8i` command sources a Bourne shell script called `pidp8i.rc` —
normally installed in `/opt/pidp8i/etc` — which you may edit to override
certain details of the way that script runs. The intended purpose is to
give you a place to define local overrides for default variables:


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

By default, the PiDP-8/I software distribution installs and uses [GNU
`screen(1)`][gscr] to allow the simulator to run in the background yet be
reattached from a later terminal session, then possibly later to be
backgrounded once again. Without the intermediation of something like
`screen`, the simulator would either forever be in the background — so
we’d have to export the console [another way][scons] — or we’d have to
give up on background startup, requiring that users fire the simulator
up interactively any time they wanted to use it. Using a screen manager
lets us have it both ways.

The `SCREEN_MANAGER` setting is for use by those that want to use
one of the alternatives to GNU `screen`:

*   **screen**: The default, per above.

*   [**tmux**][tmux]: A popular alternative to `screen`, especially on
    on BSD platforms. Note that the "attention" character for `tmux`
    is <kbd>Ctrl-B</kbd> by default, not <kbd>Ctrl-A</kbd> as with
    `screen`.

*   **none**: This mode is for interactive use, allowing you to
    run the installed simulator with the installed media without any
    screen manager at all.

    In this mode, the `pidp8i` and `pidp8i start` commands do the
    same thing: run the simulator directly attached to your current
    interactive terminal. The `pidp8i stop` command becomes a no-op,
    since stopping the simulator is then done in the standard SIMH way:
    <kbd>Ctrl-E, quit</kbd>.

Note that the alternative screen managers are not installed by default.
If you set `SCREEN_MANAGER=tmux`, you must then ensure that `tmux` is in
fact installed before the `pidp8i` script goes to try and use it. From
the Pi’s command line:

    $ sudo apt install tmux

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

[gscr]:  https://www.gnu.org/software/screen/
[scons]: /wiki?name=Serial+or+Telnet+PDP-8+Console
[tmux]:  https://tmux.github.io/


## Simplifying Boot and Login <a id="auto-login"></a>

The setup and installation instructions above assume you will be using
base the Raspberry Pi OS as a network server, offering SSH if nothing
else. Thus, we do not try to bypass any Linux security mechanisms, not
wanting to create an insecure island on your network.

However, if you want to run your system more as an appliance, you can
cast away some of this security to get auto-login and other convenient
behaviors:

*   [Serial or Telnet PDP-8 Console](https://tangentsoft.com/pidp8i/wiki?name=Serial+or+Telnet+PDP-8+Console)
*   [How to Run a Naked PiDP-8/i](https://tangentsoft.com/pidp8i/wiki?name=How+to+Run+a+Naked+PiDP-8/I)
*   [VNC for Remote GUI Access](https://www.raspberrypi.org/documentation/remote-access/vnc/)


## <a id="os8di"></a>The OS/8 RK05 Disk Image
## The OS/8 Disk Images <a id="os8di"></a>

For the first several years of the PiDP-8/I project, the OS/8 RK05 disk
image included with the PiDP-8/I software (called `os8.rk05`) was based
on an image of a real RK05 disk pack that someone allegedly found in a
salvaged PDP-8 system.  Parts of the image were corrupt, and not all of
the pieces of software on the disk worked properly with the other parts.
the pieces of software worked properly with the other parts.
It was also a reflection of the time it was created and used out in the
world, which was not always what we would wish to use today.

In late 2017 [several of us][aut] created the `mkos8` tool, which was
replaced during 2018 by Bill Cattey with the `os8-run` interpreter
and its stock scripts. The `--*-os8-*` options documented above get
Starting in late 2017, [several of us][aut] built a series of tools to
generate OS/8 media images from pristine source files in a repeatable,
[testable][pkgtst] way, culminating in [Bill Cattey’s `os8-run`][ori],
which backs other features like [the `--disable-os8-*` configuration
options](#disable-os8).
passed into `os8-run` during the PiDP-8/I software build process,
which controls how it generates the `v3d*.rk05` RK05 disk image files.

This set of disk images entirely replaces the old `os8.rk05` disk image,
in that all features of the old disk image are still available. In some
cases, features present on the old `os8.rk05` disk are now left out or
disabled by default, and in other cases we have changed the behavior of
features from the way they used to be on the old disk. Mostly, though,
the new disk images are simply more functional than the old ones.
The resulting set of media images entirely replace the old ones and go
well beyond each besides.  All prior features are still available,
though some features present on the old images are disabled by default,
requiring either [`--enable-os8-*` configure options](#enable-os8) or
[package manager commands][os8pkg] to add features back in. Mostly,
though, the new media images are more functional than the old ones.

If you wish to know the full details of how these disk images are
If you wish to know the full details of how these media images are
created, see the documentation for [`os8-run`][ori] and that for
[`class simh`][cs].

The remainder of this section describes some aspects of these disk
The remainder of this section describes some aspects of these media
images which are not clear from the descriptions of the `--*-os8-*`
configuration options above.

[aut]: https://tangentsoft.com/pidp8i/doc/trunk/AUTHORS.md
[ori]: https://tangentsoft.com/pidp8i/doc/trunk/doc/os8-run.md
[aut]:    https://tangentsoft.com/pidp8i/doc/trunk/AUTHORS.md
[ori]:    https://tangentsoft.com/pidp8i/doc/trunk/doc/os8-run.md
[pkgtst]: https://tangentsoft.com/pidp8i/doc/trunk/doc/testing.md


### Baseline

The baseline for the bootable OS/8 disk images comes from a set of
The baseline for the bootable OS/8 media images comes from a set of
DECtapes distributed by Digital Equipment Corporation which are now
included with the PiDP-8/I software; see the [`media/os8/*.tu56`
files][os8mf]. From these files and your configuration options, the
`os8-run` script creates the baseline `v3d-dist.rk05` disk image.
`os8-run` script creates the baseline bootable `v3d-dist.rk05` and
`ock-dist.rk05` disk images.

The default build creates a complete OS/8 V3D system including `BUILD`
support, FORTRAN IV, MACREL v2, and more.
support, FORTRAN IV, MACREL v2, and more, but you can switch to an
[OCK build at compile time](#ock) if you prefer.


### Subtractions

It turns out that it's pretty easy to run out of directory space on an
OS/8 RK05 disk due to a limitation in the number of files on an OS/8
filesystem.  For this reason, the archive of device drivers and TD8E
It's pretty easy to run out of space on an OS/8 RK05 disk, not just
because of its [2 × 0.8 MWord limit][rk05td], but also because of an
OS/8 limitation in the number of files on an OS/8 filesystem. We leave
the archive of device drivers and the TD8E subsystem off the system
system are left off the system packs.  They can be found in [OS/8
Binary Distribution DECtape #2][bdt2].
packs to avoid hitting this second limit. You can add them later from
[OS/8 Binary Distribution DECtape #2][bdt2], such as to create media
for a TD8E based PDP-8/e.

If you do fancy work with `BUILD`, you may need to attach that DECtape
image and copy files in from it.
[rk05td]: https://en.wikipedia.org/wiki/RK05#Technical_details


### Default Additions

The OS/8 RK05 disk image build process normally installs many software
and data file sets to the disk image.  See the option descriptions
above: the ["disable" option set](#disable-os8) effectively lists those