PiDP-8/I Software

*.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/*.[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

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, 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/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 [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
[decpd]: http://mailman.trailing-edge.com/pipermail/simh/2017-January/016164.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

*   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/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

*   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/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/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/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

*   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/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

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

########################################################################
# 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-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=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@ @PI_CFLAGS@ @BUILDMODE@ \
	-Wno-unused-result -Wno-parentheses \
	-DUSE_READER_THREAD -DHAVE_DLOPEN=$(subst .,,@SH_SOEXT@) -DPIDP8I \
	-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
















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_SRC_RK05 = @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@/scripts/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

# 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 = $(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


# 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) \


		config.log cscope.out tags \
		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 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-target: all instdirs
	@echo Installing to $(PREFIX)...

	@# Install most bin/* stuff and set their perms
	@for f in $(BINS) ; do \
		dest=$(PREFIX)/$$f ; \
		echo "Installing binary $$dest..." ; \
		@INSTALL@ -m 755 -D -s $$f $(DESTDIR)$$dest ; \
	done
	@for f in $(BIN_SCRIPTS) ; do \
		dest=$(PREFIX)/bin/$$(basename $$f) ; \
		echo "Installing script $$dest..." ; \
		@INSTALL@ -m 755 -D $$f $(DESTDIR)$$dest ; \
	done

	@echo "Installing txt2ptp symlink..."
	@ln -f $(DESTDIR)$(PREFIX)/bin/ptp2txt $(DESTDIR)$(PREFIX)/bin/txt2ptp







	@(	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

	@# 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 && \
		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@ $(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 "$(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 "$(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




























instdirs:
	@echo "Creating installation directory tree..."
	@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 \*.bin  -o \
		-name \*.dsk  -o \
		-name \*.rk05 -o \
		-name \*.tu56 \
	\) -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 > $(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)@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@/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_BASELINE): $(V3D_DIST_SRCS) | $(PIDP8I_SIM) $(OS8RUN_OUTFILES)
	$(OS8RUN)@OS8_OPTS@ $(V3D_DIST_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_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_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_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_TOOLTIME) 
	$(OS8RUN)@OS8_OPTS@ $(ALL_TU56_SCRIPT) --enable td12k





# 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 $@ @PI_LFLAGS@ $^ $(LIBS) $(SIM_LFLAGS) @PI_LIBS@
	ln -f bin/pidp8i-sim bin/pdp8

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

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

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

bin/pidp8i-test: obj/misc/test.o obj/pidp8i/gpio-nls.o obj/pidp8i/gpio-common.o
	$(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 $@ $(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 $@ $(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 either:

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

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

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

The latter two are secondary outputs from the first, being the PiDP-8/I

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.



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


*   While those with no Linux and Raspberry Pi knowledge may be able to

    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.

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

    On Raspberry Pi OS, say:

        $ sudo apt update
        $ 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
[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/



## Enabling the SSH Server <a id="sshd"></a>

[That topic is covered elsewhere](./doc/OS-images.md#sshd).



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

[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
`README.md` file within an unpacked distribution of the PiDP-8/I
software, [skip to the next section](#configuring).



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


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 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 *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](#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
    [`CONTRIBUTING.md` file][ctrb]. (Best for experts or those who wish to
    become experts.)



Alternatively, switch to [the binary OS installation images][bosi],

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

for you.




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

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



    $ tar xf pidp8i.tar.gz






























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

For a stock build, say:


    $ cd ~/pidp8i
    $ ./configure && tools/mmake && sudo make install


You may want to add options to the `configure` step, described
[below](#options).

Subsequent software updates and rebuilds should not require that you

re-run the `configure` step manually, but if automatic re-configuration
fails, you can force it:


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

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


## 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:

        $ 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:

        $ 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 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:

    $ 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:


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


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.


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


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

    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.









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



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


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


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.


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


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



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


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
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
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 <a id="dub"></a>

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

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-basic-games** - Leave out the BASIC games and demos which
    primarily come from DEC's book "101 BASIC Computer Games."







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

*   **--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-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/
[os8pat]: https://tangentsoft.com/pidp8i/doc/trunk/doc/os8-patching.md
[os8pkg]: https://tangentsoft.com/pidp8i/doc/trunk/doc/os8pkg.md


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


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.



*   **--enable-os8-focal69** — Because the default installation includes
    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,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,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,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 <a id="os8-minimal"></a>

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:

1.  This flag's name is aspirational, not a promise of an ideal: our
    current "minimal" installation could be stripped down further. For



    example, we currently have no way to leave out OS/8's BASIC
    interpreter, even though no core OS services depend on it.


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. You may therefore wish to give `--lowercase=none` along
    with `--os8-minimal`.

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.

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

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/)


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

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



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 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 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
[pkgtst]: https://tangentsoft.com/pidp8i/doc/trunk/doc/testing.md


### Baseline

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 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, but you can switch to an
[OCK build at compile time](#ock) if you prefer.


### Subtractions

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

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.



[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

read-only master. A copy is made called `v3d.rk05`. This is the
default OS/8 rk05 image assigned to the IF=0 and IF=7 boot options.

In keeping with the standards of good systm management
this image incorporates all mandatory patches, as well as
optional patches appropriate to proper operation of the system.
For details on the available patches, the selection criteria,
and information about other optional patches see the [OS/8 system patches][os8pat]
document.

[bdt2]:  https://tangentsoft.com/pidp8i/file/media/os8/al-4712c-ba-os8-v3d-2.1978.tu56
[cl]:    https://tangentsoft.com/pidp8i/doc/trunk/ChangeLog.md
[cs]:    https://tangentsoft.com/pidp8i/doc/trunk/doc/class-simh.md
[os8mf]: https://tangentsoft.com/pidp8i/file/media/os8
[tlrm]:  https://tangentsoft.com/pidp8i/doc/trunk/README.md


## The OS/8 TU56 Tape Image <a id="os8ti"></a>

As with the [OS/8 disk image](#os8di), this distribution’s build system
can create custom TU56 tape images from pristine source media.  This
replaces the old `os8.tu56` binary image previously distributed with
this software.

The build system actually creates four such tape images according to a

    TD12K][os8td] for the reason you’re given a choice here.

[os8td]:  https://tangentsoft.com/pidp8i/wiki?name=TD8E+vs+TC08
[os8ver]: https://tangentsoft.com/pidp8i/wiki?name=OS/8+V3D+vs+V3F




## Overwriting the Local Simulator Setup <a id="overwrite-setup"></a>

When you run `sudo make install` step on a system that already has an
existing installation, it purposely does not overwrite two classes of
files:

1.  **The binary PDP-8 media files**, such as the RK05 disk image that
    holds the OS/8 image the simulator boots from by default. These media

    aren't precious, you can just copy the generated `boot/*.script`
    files from the build directory into the installation directory,
    `$prefix/share/boot`.  (See the `--prefix` option above for the
    meaning of `$prefix`.)

4.  If neither your previously installed simulator configuration files
    nor the binary media images are precious, you can force the
    installation script to overwrite them both with a
    `sudo make mediainstall` command after `sudo make install`.

    Beware that this is potentially destructive! If you've made changes
    to your PDP-8 operating systems or have saved files to your OS
    system disks, this option will overwrite those changes!



## Testing Your PiDP-8/I Hardware <a id="testing"></a>

You can test your PiDP-8/I LED and switch functions with these commands:

    $ pidp8i stop
    $ pidp8i-test

You may have to log out and back in before the second command will work,
since the installation script modifies your normal user's `PATH` the
first time you install onto a given system.

It is important to stop the PiDP-8/I simulator before running the test
program, since both programs need exclusive access to the LEDs and
switches on the front panel.  After you are done testing, you can start
the PiDP-8/I simulator back up with:

    $ pidp8i start

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





































































































































## License

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

<div id="this-space-intentionally-left-blank" style="min-height:50em"></div>


[cprj]:   https://tangentsoft.com/pidp8i/
[sm1]:    https://obsolescence.wixsite.com/obsolescence/pidp-8-details#i7g9qvpr
[sm2]:    https://groups.google.com/d/msg/pidp-8/-leCRMKqI1Q/Dy5RiELIFAAJ
[osd]:    http://obsolescence.wixsite.com/obsolescence/pidp-8-details
[dt2]:    https://github.com/VentureKing/Deeper-Thought-2
[sdoc]:   https://tangentsoft.com/pidp8i/uv/doc/simh/main.pdf
[oprj]:   http://obsolescence.wixsite.com/obsolescence/pidp-8
[pitest]: https://tangentsoft.com/pidp8i/doc/trunk/doc/pidp8i-test.md
[thro]:   https://tangentsoft.com/pidp8i/doc/trunk/README-throttle.md
[mdif]:   https://tangentsoft.com/pidp8i/wiki?name=Major+Differences
[sl]:     https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md
[ils]:    https://tangentsoft.com/pidp8i/wiki?name=Incandescent+Lamp+Simulator

Copyright © 2015-2020 by various authors

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

########################################################################
# auto.def - Configure file for the PiDP-8/I software build system,
#            based on autosetup.
#
# Copyright © 2016-2020 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

options-defaults {prefix /opt/pidp8i}

use cc
use cc-lib
use cc-shared

# Canonicalize some paths which may be relative and generate others from them
set abspfx    [file-normalize [get-define prefix]]
set abssrcdir [file-normalize [get-define srcdir]]
define ABSPREFIX $abspfx
define ABSSRCDIR $abssrcdir
define SHAREDIR "$abspfx/share"
define BOOTDIR  "$abspfx/share/boot"
define MEDIADIR "$abspfx/share/media"

# Define options the configure script shares with os8-run.  We insert a
# variant of each into the autosetup option list and also write a
# version to a Python library file that os8-run can read.  This avoids
# the need to define the options by hand in both places.
#
# Some of the --*-os8-* options are defined only for the configure
# script because they are either meta-options, affecting the definition
# of some of those we do define here, or they aren't passed as-is to the
# os8-run script, but instead must be translated.  (e.g. --disable-os8-src
# suppresses creation of the OS/8 src rk05 by the Makefile.)
set os8opts {
    advent      1  "Adventure"
    basic-games 1  "BASIC games and demos"
    cc8         1  "the native OS/8 CC8 compiler"
    chekmo      1  "the CHECKMO-II game of chess"
    crt         1  "CRT-style rubout processing"
    dcp         1  "the DCP disassembler"
    e8          1  "Emacs-like Editor"
    focal69     0  "FOCAL,1969"
    fortran-ii  1  "FORTRAN II"
    fortran-iv  1  "FORTRAN IV"
    init        1  "the OS/8 INIT message"
    kermit-12   1  "12-bit Kermit"
    macrel      1  "the MACREL assembler"
    music       0  "*.MU files"
    uwfocal     1  "U/W FOCAL (only)"
    vtedit      0  "the TECO VTEDIT setup"
}

set alloptions {}

foreach {opt def desc} $os8opts {
    if {$def} {
        set prefix "disable"
    } else {
        set prefix "enable"
    }
    append alloptions [list os8-$opt=$def => "$prefix $desc in the built OS/8 RK05 image"] \n
}

# Now define those command line options that belong only to us.
append alloptions {
    alt-serial-mod       => "use GPIO drive scheme suitable for James L-W's serial mod method"
    boot-tape-config:    => "boot tape configuration: tc08, or td12k"
    boot-tape-version:   => "OS/8 version for boot tape, either v3d or v3f"
    cc8-cross=1          => "do not build the cc8 cross-compiler on the host"
    debug-mode           => "create a debug build (default is release)"
    e8-screen-width:=80  => "set E8 terminal width"
    e8-screen-height:=24 => "set E8 terminal height"
    lowercase:           => "select how lowercase input is to be handled"
    no-lamp-simulator    => "use simple LED driver instead of incandescent lamp simulator"
    os8-focal=1          => "leave FOCAL,1969 and U/W FOCAL off the built OS/8 RK05 image"
    os8-minimal          => "set all --disable-os8-* options, giving minimal OS/8 bin disk"
    os8-src=1            => "do not build v3d-src.rk05 from OS/8 source tapes"
    savestate            => "save simulator state (regs, core, devices) on exit; restore on restart"
    serial-mod           => "use GPIO drive scheme suitable for Oscar Vermeulen's serial mod method"
    throttle:            => "override the throttle values in the boot scripts"
    usb-automount=1      => "do not automatically mount USB drives for SING_STEP + DF"
    use-ock              => "boot the OS/8 Combined Kit built from source instead of binary v3d."
}

options $alloptions

# use btc and btv to set defaults because I can't get the documented
# syntax of <name>:=<value> to work.

# Make our own array of os8 options so we can apply the meta options
foreach {opt def desc} $os8opts {
    set os8bool($opt) [opt-bool os8-$opt]
}
set os8bool(src) [opt-bool os8-src]

# Handle OS/8 meta-options
set os8min [opt-bool os8-minimal]
set os8src [opt-bool os8-src]
if {![opt-bool os8-focal]} {
    set os8bool(focal69) "0"
    set os8bool(uwfocal) "0"
}

# -- do not use opt-bool os8-* below this point
# -- use the os8bool() array

# Handle E8 related options
if {$os8bool(e8)} {
    define E8_TU56 bin/e8.tu56

    set w [opt-val e8-screen-width  80]
    set h [opt-val e8-screen-height 24]

    # Have to use Unix line endings for write-if-changed to work
    # properly.  We convert them to OS/8 CRLFs in the os8-run step.
    set    defs "DECIMAL\n"
    append defs "SCRWD=$w\n"
    append defs "SCRHT=$h\n"
    append defs "OCTAL"      ;# trailing \n added
    write-if-changed "src/e8/e8defs.pa" $defs
}

# Handle interdependent options
if {$os8bool(cc8) && !$os8bool(fortran-ii)} {
    set $os8bool(fortran-ii) 1
    msg-result "WARNING: Re-enabling OS/8 FORTRAN II: OS/8 CC8 requires it."
}
define CC8_TU56 {}

if {$os8src} {
    msg-result "Building v3d-src.rk05 from OS/8 source tapes."
    define OS8_SRC_RK05 bin/v3d-src.rk05
} else {
    msg-result "Will not build v3d-src.rk05 from OS/8 source tapes."
    define OS8_SRC_RK05 {}
}

# Define boot image used in various places.

# OS8_BASELINE is used at the lowest levels of building.
define OS8_BASELINE "v3d-dist.rk05"

# OS8_TOOLTIME is used by tools, it is the patched version of OS8_BASELINE.
# This enables tools and higher levels of building to work with the
# most up-to-date revisions of system and utilities.
define OS8_TOOLTIME "v3d-patched.rk05"

# OS8_RUNTIME is what the end user boots.  It contains the patched OS and utilies.
# It also contains all configured third party components.
# This boot disk is a choice between v3d, and ock.
# The ock image is built from source using OS8_BASELINE and OS8_TOOLTIME.
if {[opt-bool use-ock]} {
    define OS8_RUNTIME "ock.rk05"
} else {
    define OS8_RUNTIME "v3d.rk05"
}

# Compose our boot tape image name from boot-tape-config and boot-tape-version
# Pull defaults from $btc for boot-tape-config, and $btv for boot-tape-version.

set btn "$btv-$btc.tu56"

msg-result "Boot tape name: $btn"

    define LED_DRIVER_MODULE i
    define ILS_MODE 1
}

# Check for headers, functions, etc. whose absence we can work around
cc-check-decls __progname
cc-check-includes time.h
cc-check-includes pcre.h pcreposix.h
cc-check-function-in-lib clock_gettime rt
cc-check-functions clock_nanosleep nanosleep usleep
cc-check-functions sched_yield
cc-with {-includes signal.h} {
    cc-check-types sighandler_t sig_t
}

# Check for libraspberrypi-dev stuff
set old_LIBS [get-define LIBS]      ;# don't want LIBS modded directly
if {![file isdirectory "/opt/vc"]} {
    msg-result "WARNING: Not building on a Pi or libraspberrypi-dev not installed!"
    define PI_CFLAGS ""
    define PI_LFLAGS ""
    define PI_LIBS   ""
} elseif {![cc-with {-cflags "-L/opt/vc/lib"} {
             cc-check-function-in-lib bcm_host_get_peripheral_address bcm_host
           }]} {
    user-error "Found /opt/vc but cannot link to -lbcm_host!"
} elseif {![cc-with {-cflags "-I/opt/vc/include"} {
             cc-check-includes bcm_host.h
           }]} {
    user-error "Found /opt/vc but cannot #include bcm_host.h!"
} else {
    define PI_CFLAGS "-I/opt/vc/include"
    define PI_LFLAGS "-L/opt/vc/lib"
    define PI_LIBS   "-lbcm_host"
}
define LIBS $old_LIBS

# Ensure we have the libncurses development files installed here, else
# pidp8i-test won't build.
if {![cc-check-includes curses.h]} {
    user-error "Could not find curses.h.  Try installing libncurses-dev."
} elseif {![cc-check-function-in-lib initscr ncurses]} {
    user-error "Could not find initscr() in libncurses."

# Get host, user, and date info for use by media/os8/init.tx.
catch {exec hostname} host
set user $::env(USER)
define BUILDUSER "$user@$host"
define BUILDTS [clock format [clock seconds] -format "%Y.%m.%d at %T %Z"]

# The os8-run script requires Python 2 or 3 and some non-core modules.
set status [catch {exec python3 -c exit} result]
if {$status == 0} {
    set pyver 3
    set pycmd "python3"
} else {
    set status [catch {exec python2 -c exit} result]
    if {$status == 0} {
        set pyver 2
        set pycmd "python2"
    } else {
        set status [catch {exec python -c exit} result]
        if {$status == 0} {

            set status [catch {exec python --version | grep -q 'Version 2'} result]

            set pyver [expr $status == 0 ? 2 : 3]
            set pycmd "python"

        }
    }
}
if {$pyver == ""} {

    user-error "Python does not appear to be installed here.  It is required."
}
define PYCMD $pycmd
define PYVER $pyver
msg-result "Python $pyver is installed here as '$pycmd'."
foreach mfull {pexpect pkg_resources pyyaml} {
    set mshort [regsub "py" $mfull ""]
    set mapt [regsub "_" $mshort "-"]
    set test "import $mshort"
    set status [catch {exec $pycmd -c $test 2> /dev/null} result]
    if {$status != 0} {
        set msg "The Python $mfull module is not installed here.  Fix with\n\n"
        append msg "    sudo apt install $pycmd-pip$pyver\n"
        append msg "    pip$pyver install --user $mfull\n"

        append msg "\nOR on Debian type systems:\n\n"
        append msg "    sudo apt install $pycmd-$mapt\n"
        user-error $msg
    }
    msg-result "Found Python module $mfull."
}

# Check for Perl and that it can run the test corpus builder.  Not fatal
# if it can't, since only developers and deep testers need it.
#
# We generate os8-run early here because test-os8-run requires it.  We
# have a chicken-and-egg on initial configure in a clean tree otherwise.
make-template bin/os8-run.in
set status [catch {exec perl -e exit} result]
if {$status == 0} {
    set status [catch {exec perl -c "[get-define srcdir]/tools/test-os8-run" 2> /dev/null} result]
    if {$status == 0} {
        set status [catch {exec lz4 -h 2> /dev/null} result]
        if {$status == 0} {
            msg-result "All test-os8-run prereqs available here."

} result]
if {$status == 0} {
    msg-result $result
} else {
    user-error "Failed to generate autodependency rules: $result!"
}

# Create file symlinks.  Fossil can store these for us, but its
# allow-symlinks setting is off by default for belt-and-suspenders
# security reasons, so if we make use of it, we complicate the
# process for making checkouts on new machines and on existing one
# where this hasn't been set to "1" globally.  It's simpler to just
# re-create them at configure time, leaving Fossil to manage only the
# actual files.
proc mklink {subdir name} {
    set olddir [pwd]
    cd $subdir
    if {![file exists $name]} {
        set target "../include/$name"
        msg-result "Symlinking $name -> $target in $subdir..."
        exec ln -s $target $name
    }
    cd $olddir
}
set base "[get-define srcdir]/src/cc8"
mklink "$base/examples" "libc.h"
mklink "$base/examples" "init.h"
mklink "$base/os8"      "libc.h"
mklink "$base/os8"      "init.h"

# Write outputs.
#
# NOTE: If you change the list of files here, change INFILES in
# Makefile.in, too.
#
# We're listing the top-level Makefile.in last because the templates
# ahead of it may have @include directives which modify the @AUTODEPS@
# value substituted into the top-level Makefile.in's autoreconf target.
#
# The boot/common.script must precede the rest of boot/*, because they
# @include the output version.
make-config-header src/config.h \
    -auto {ENABLE_* HAVE_* PACKAGE_* SIZEOF_*} \
    -bare {ILS_MODE PCB_*}
make-template bin/pidp8i.in
make-template bin/os8-cp.in
make-template tools/os8-cmp.in
make-template bin/teco-pi-demo.in
make-template boot/common.script.in
make-template boot/0.script.in
make-template boot/2.script.in
make-template boot/3.script.in
make-template boot/4.script.in
make-template boot/6.script.in
make-template boot/7.script.in
make-template boot/run.script.in
make-template boot/run-v3f.script.in
make-template boot/tss8.script.in
make-template etc/pidp8i.service.in
make-template etc/sudoers.in
make-template etc/usb-mount@.service.in
make-template examples/Makefile.in
make-template lib/os8script.py.in
make-template lib/pidp8i/__init__.py.in
make-template lib/pidp8i/dirs.py.in
make-template lib/pidp8i/ips.py.in
make-template lib/simh.py.in
make-template bin/os8pkg.in
make-template tools/os8-progtest.in
make-template media/os8/init.tx.in
make-template media/os8/3finit.tx.in
make-template media/os8/ock-init.tx.in
make-template src/Makefile.in
make-template src/cc8/Makefile.in
make-template src/cc8/os8/Makefile.in
make-template src/pidp8i/gpio-common.c.in
make-template src/pidp8i/main.c.in
make-template src/SIMH/Makefile.in
make-template src/SIMH/PDP8/Makefile.in
make-template tools/simh-bisect.in
make-template tools/simh-update.in
foreach f [concat [glob "$builddir/bin/*"] [glob "$builddir/tools/*"]] {
    exec chmod +x $f
}

# Generate the dependencies for packages to build, the install scripts, and
# the list of packages selected to install.
# We need os8pkg and its prereqs first. So this code appears after those make-template lines.
# However, since we build Makefile.in from what is done here, THAT make-template must be later.
if {![file exists "obj/os8pkg"]} { file mkdir "obj/os8pkg" }
set os8pkgs_all ""
set os8pkgs_selected ""
set os8pkgs_selected_names ""
set os8pkgs_testing ""
foreach pspec [glob "$srcdir/pspec/*.pspec"] {
    set pkg_name [file rootname [file tail $pspec]]
    set obj_base "obj/os8pkg/$pkg_name"
    set dep_path "$obj_base.mk"
    set test_path "$srcdir/scripts/os8-progtest/${pkg_name}.yml"
    set script_path "$obj_base.os8"
    set uc_pkg_name [string toupper $pkg_name]
    set pkg_bin_var "\$(${uc_pkg_name}_PKG_BIN)"

    if {   ![file exists $dep_path] || \
            [file mtime $pspec]     > [file mtime $dep_path] || \
            [file mtime bin/os8pkg] > [file mtime $dep_path] } {
        exec bin/os8pkg deps $pspec
    }

    append os8pkgs_all " $pkg_bin_var"
    
    if {$os8bool($pkg_name)} {
        append os8pkgs_selected_names " $pkg_name"
        append os8pkgs_selected " $pkg_bin_var"
    }

    if {[file exists $test_path]} {
       append os8pkgs_testing " $pkg_name"
    }
}

msg-result "Packages selected for OS/8 RUNTIME packs: $os8pkgs_selected_names"
define OS8_PKGS_SELECTED_NAMES $os8pkgs_selected_names
define OS8_PKGS_SELECTED $os8pkgs_selected
define OS8_PKGS_ALL $os8pkgs_all
define OS8_PKGS_TESTING $os8pkgs_testing
msg-result "We can test: $os8pkgs_testing"

# Must be the last thing we do.
make-template Makefile.in

README.autosetup created by autosetup v0.7.0+

This is the autosetup directory for a local install of autosetup.
It contains autosetup, support files and loadable modules.

*.tcl files in this directory are optional modules which
can be loaded with the 'use' directive.

#!/bin/sh
# Copyright (c) 2006-2011 WorkWare Systems http://www.workware.net.au/
# All rights reserved
# vim:se syntax=tcl:
# \
dir=`dirname "$0"`; exec "`$dir/autosetup-find-tclsh`" "$0" "$@"

# Note that the version has a trailing + on unreleased versions
set autosetup(version) 0.7.0+

# Can be set to 1 to debug early-init problems
set autosetup(debug) [expr {"--debug" in $argv}]

##################################################################
#
# Main flow of control, option handling

	# At the is point we don't know what is a valid option
	# We simply parse anything that looks like an option
	set autosetup(getopt) [getopt argv]

	#"=Core Options:"
	options-add {
		help:=all       => "display help and options. Optional: module name, such as --help=system"
		licence license => "display the autosetup license"
		version         => "display the version of autosetup"
		ref:=text manual:=text
		reference:=text => "display the autosetup command reference. 'text', 'wiki', 'asciidoc' or 'markdown'"
		debug           => "display debugging output as autosetup runs"
		install:=.      => "install autosetup to the current or given directory"
	}
	if {$autosetup(installed)} {
		# hidden options so we can produce a nice error
		options-add {
			sysinstall:path
		}
	} else {

		} else {
			user-error "Unexpected parameter: $arg"
		}
	}

	autosetup_add_dep $autosetup(autodef)

	# Add $argv to CONFIGURE_OPTS, but ignore duplicates and quote if needed
	set configure_opts {}
	foreach arg $autosetup(argv) {
		set quoted [quote-if-needed $arg]
		# O(n^2), but n will be small
		if {$quoted ni $configure_opts} {
			lappend configure_opts $quoted
		}
	}
	define CONFIGURE_OPTS [join $configure_opts]
	define AUTOREMAKE [file-normalize $autosetup(exe)]
	define-append AUTOREMAKE [get-define CONFIGURE_OPTS]


	# Log how we were invoked
	configlog "Invoked as: [getenv WRAPPER $::argv0] [quote-argv $autosetup(argv)]"
	configlog "Tclsh: [info nameofexecutable]"

	# Load auto.def as module "auto.def"
	autosetup_load_module auto.def source $autosetup(autodef)

	# Could warn here if options {} was not specified

	show-notices

	if {$autosetup(debug)} {
		msg-result "Writing all defines to config.log"

			set result [lindex [dict get $::autosetup(optset) $opt] end]
		}
	}

	if {![info exists result]} {
		# No user-specified value. Has options-defaults been set?
		foreach opt $names {
			if {[dict exists $::autosetup(optdefault) $opt]} {
				set result [dict get $autosetup(optdefault) $opt]
			}
		}
	}

	if {[info exists result]} {
		set value $result
		if {$retopt} {

		}
	}
}

# Parse the option definition in $opts and update
# ::autosetup(setoptions) and ::autosetup(optionhelp) appropriately
#
proc options-add {opts} {
	global autosetup

	# First weed out comment lines
	set realopts {}
	foreach line [split $opts \n] {
		if {![string match "#*" [string trimleft $line]]} {
			append realopts $line \n
		}
	}
	set opts $realopts

	for {set i 0} {$i < [llength $opts]} {incr i} {
		set opt [lindex $opts $i]
		if {[string match =* $opt]} {
			# This is a special heading
			lappend autosetup(optionhelp) [list $opt $autosetup(module)]

			continue
		}
		unset -nocomplain defaultvalue equal value

		#puts "i=$i, opt=$opt"
		regexp {^([^:=]*)(:)?(=)?(.*)$} $opt -> name colon equal value
		if {$name in $autosetup(options)} {

				dict set autosetup(optset) $name $setvalue
				#puts "Found boolean option --$name=$setvalue"
			}
		} else {
			# String option.
			lappend autosetup(options) $name

			if {$equal ne "="} {
				# Was the option given as "name:value=default"?
				# If so, set $value to the display name and $defaultvalue to the default
				# (This is the preferred way to set a default value for a string option)
				if {[regexp {^([^=]+)=(.*)$} $value -> value defaultvalue]} {
					dict set autosetup(optdefault) $name $defaultvalue
				}
			}

			# Maybe override the default value
			if {[dict exists $autosetup(options-defaults) $name]} {
				# A default was specified with options-defaults, so use it
				set defaultvalue [dict get $autosetup(options-defaults) $name]
				dict set autosetup(optdefault) $name $defaultvalue
			} elseif {![info exists defaultvalue]} {
				# No default value was given by value=default or options-defaults
				# so use the value as the default when the plain option with no
				# value is given (.e.g. just --opt instead of --opt=value)
				set defaultvalue $value
			}

			if {$equal eq "="} {
				# String option with optional value
				set opthelp "--$name?=$value?"
			} else {

		# Now create the help for this option if appropriate
		if {[lindex $opts $i+1] eq "=>"} {
			set desc [lindex $opts $i+2]
			if {[info exists defaultvalue]} {
				set desc [string map [list @default@ $defaultvalue] $desc]
			}





			# A multi-line description
			lappend autosetup(optionhelp) [list $opthelp $autosetup(module) $desc]
			incr i 2
		}
	}
}

# @module-options optionlist
#
# Deprecated. Simply use 'options' from within a module.
proc module-options {opts} {




	options $opts








}

proc max {a b} {
	expr {$a > $b ? $a : $b}
}

proc options-wrap-desc {text length firstprefix nextprefix initial} {

		set space " "
	}
	if {$len} {
		puts ""
	}
}

# Display options (from $autosetup(optionhelp)) for modules that match
# glob pattern $what
proc options-show {what} {
	set local 0
	# Determine the max option width
	set max 0
	foreach help $::autosetup(optionhelp) {
		lassign $help opt module desc
		if {![string match $what $module]} {
			continue
		}
		if {[string match =* $opt] || [string match \n* $desc]} {
			continue
		}
		set max [max $max [string length $opt]]
	}
	set indent [string repeat " " [expr $max+4]]
	set cols [getenv COLUMNS 80]
	catch {
		lassign [exec stty size] rows cols
	}
	incr cols -1
	# Now output
	foreach help $::autosetup(optionhelp) {
		lassign $help opt module desc
		if {![string match $what $module]} {
			continue
		}
		if {$local == 0 && $module eq "auto.def"} {
			puts "Local Options:"
			incr local
		}
		if {[string match =* $opt]} {
			# Output a special heading line"
			puts [string range $opt 1 end]
			continue
		}
		puts -nonewline "  [format %-${max}s $opt]"
		if {[string match \n* $desc]} {
			# Output a pre-formatted help description as-is
			puts $desc
		} else {
			options-wrap-desc [string trim $desc] $cols "  " $indent [expr $max + 2]
		}
	}
}

#
## name[=0|1]  => "Description of this boolean option"
#
# The default is 'name=0', meaning that the option is disabled by default.
# If 'name=1' is used to make the option enabled by default, the description should reflect
# that with text like "Disable support for ...".
#
# An argument option (one which takes a parameter) is of one of the following forms:
#
## name:value         => "Description of this option"
## name:value=default => "Description of this option with a default value"
## name:=value        => "Description of this option with an optional value"
#
# If the 'name:value' form is used, the value must be provided with the option (as '--name=myvalue').
# If the 'name:value=default' form is used, the option has the given default value even if not
# specified by the user.
# If the 'name:=value' form is used, the value is optional and the given value is used
# if it is not provided.
#
# The description may contain '@default@', in which case it will be replaced with the default
# value for the option (taking into account defaults specified with 'options-defaults'.
#
# Undocumented options are also supported by omitting the '=> description'.
# These options are not displayed with '--help' and can be useful for internal options or as aliases.
#
# For example, '--disable-lfs' is an alias for '--disable=largefile':
#
## lfs=1 largefile=1 => "Disable large file support"
#
proc options {optlist} {
	global autosetup

	options-add $optlist

	if {$autosetup(showhelp)} {

		# If --help, stop now to show help
		return -code break
	}

	if {$autosetup(module) eq "auto.def"} {
		# Check for invalid options
		if {[opt-bool option-checking]} {
			foreach o [dict keys $::autosetup(getopt)] {
				if {$o ni $::autosetup(options)} {
					user-error "Unknown option --$o"
				}
			}
		}
	}
}

# @options-defaults dictionary
#

		lappend dirs $autosetup(srcdir)/autosetup
	}
	foreach m $args {
		if {[info exists libmodule($m)]} {
			continue
		}
		set libmodule($m) 1

		if {[info exists modsource(${m}.tcl)]} {
			autosetup_load_module $m eval $modsource(${m}.tcl)
		} else {
			set locs [list ${m}.tcl ${m}/init.tcl]
			set found 0
			foreach dir $dirs {
				foreach loc $locs {
					set source $dir/$loc
					if {[file exists $source]} {
						incr found
						break
					}
				}
				if {$found} {
					break
				}
			}
			if {$found} {
				# For the convenience of the "use" source, point to the directory
				# it is being loaded from
				set ::usedir [file dirname $source]
				autosetup_load_module $m source $source
				autosetup_add_dep $source
			} else {
				autosetup-error "use: No such module: $m"
			}
		}
	}
}

proc autosetup_load_auto_modules {} {
	global autosetup modsource
	# First load any embedded auto modules
	foreach mod [array names modsource *.auto] {
		autosetup_load_module $mod eval $modsource($mod)
	}
	# Now any external auto modules
	foreach file [glob -nocomplain $autosetup(libdir)/*.auto $autosetup(libdir)/*/*.auto] {
		autosetup_load_module [file tail $file] source $file
	}
}

# Load module source in the global scope by executing the given command
proc autosetup_load_module {module args} {
	global autosetup
	set prev $autosetup(module)
	set autosetup(module) $module

	if {[catch [list uplevel #0 $args] msg opts] ni {0 2 3}} {
		autosetup-full-error [error-dump $msg $opts $::autosetup(debug)]
	}
	set autosetup(module) $prev
}

# Initial settings
set autosetup(exe) $::argv0
set autosetup(istcl) 1
set autosetup(start) [clock millis]
set autosetup(installed) 0
set autosetup(sysinstall) 0
set autosetup(msg-checking) 0
set autosetup(msg-quiet) 0
set autosetup(inittypes) {}
set autosetup(module) autosetup

# Embedded modules are inserted below here
set autosetup(installed) 1
set autosetup(sysinstall) 0
# ----- @module asciidoc-formatting.tcl -----

set modsource(asciidoc-formatting.tcl) {

proc autosetup_help {what} {
    use_pager

    puts "Usage: [file tail $::autosetup(exe)] \[options\] \[settings\]\n"
    puts "This is [autosetup_version], a build environment \"autoconfigurator\""
    puts "See the documentation online at http://msteveb.github.com/autosetup/\n"

    if {$what in {all local}} {
        # Need to load auto.def now
        if {[file exists $::autosetup(autodef)]} {
            # Load auto.def as module "auto.def"

            autosetup_load_module auto.def source $::autosetup(autodef)
        }
        if {$what eq "all"} {
            set what *
        } else {

            set what auto.def
        }
    } else {

        use $what


        puts "Options for module $what:"
    }

    options-show $what
    exit 0
}

proc autosetup_show_license {} {
    global modsource autosetup
    use_pager

#!/bin/sh
# Looks for a suitable tclsh or jimsh in the PATH
# If not found, builds a bootstrap jimsh in current dir from source
# Prefer $autosetup_tclsh if is set in the environment (unless ./jimsh0 works)
d="`dirname "$0"`"


for tclsh in ./jimsh0 $autosetup_tclsh jimsh tclsh tclsh8.5 tclsh8.6 tclsh8.7; do
	{ $tclsh "$d/autosetup-test-tclsh"; } 2>/dev/null && exit 0
done
echo 1>&2 "No installed jimsh or tclsh, building local bootstrap jimsh0"
for cc in ${CC_FOR_BUILD:-cc} gcc; do
	{ $cc -o jimsh0 "$d/jimsh0.c"; } 2>/dev/null || continue
	./jimsh0 "$d/autosetup-test-tclsh" && exit 0
done
echo 1>&2 "No working C compiler found. Tried ${CC_FOR_BUILD:-cc} and gcc."
echo false

# Copyright (c) 2011 WorkWare Systems http://www.workware.net.au/
# All rights reserved

# @synopsis:
#
# The 'cc-db' module provides a knowledge-base of system idiosyncrasies.
# In general, this module can always be included.

use cc

options {}

# openbsd needs sys/types.h to detect some system headers
cc-include-needs sys/socket.h sys/types.h
cc-include-needs netinet/in.h sys/types.h

# Copyright (c) 2011 WorkWare Systems http://www.workware.net.au/
# All rights reserved

# @synopsis:
#
# Provides a library of common tests on top of the 'cc' module.

use cc



# @cc-check-lfs
#
# The equivalent of the 'AC_SYS_LARGEFILE' macro.
#
# defines 'HAVE_LFS' if LFS is available,
# and defines '_FILE_OFFSET_BITS=64' if necessary
#

## SHOBJ_LDFLAGS     Flags to use linking a shared object, undefined symbols allowed
## SHOBJ_LDFLAGS_R   - as above, but all symbols must be resolved
## SH_LINKRPATH      Format for setting the rpath when linking an executable, %s = path
## SH_LINKFLAGS      Flags to use linking an executable which will load shared objects
## LD_LIBRARY_PATH   Environment variable which specifies path to shared libraries
## STRIPLIBFLAGS     Arguments to strip a dynamic library

options {}

# Defaults: gcc on unix
define SHOBJ_CFLAGS -fPIC
define SHOBJ_LDFLAGS -shared
define SH_CFLAGS -fPIC
define SH_LDFLAGS -shared
define SH_LINKFLAGS -rdynamic

## CPPFLAGS
## LINKFLAGS
## CC_FOR_BUILD
## LD

use system

options {}

# Checks for the existence of the given function by linking
#
proc cctest_function {function} {
	cctest -link 1 -declare "extern void $function\(void);" -code "$function\();"
}

if {[get-define CC] eq ""} {
	user-error "Could not find a C compiler. Tried: [join $try ", "]"
}

define CPP [get-env CPP "[get-define CC] -E"]

# XXX: Could avoid looking for a C++ compiler until requested
# If CXX isn't found, it is set to the empty string.
if {[env-is-set CXX]} {
	define CXX [find-an-executable -required [get-env CXX ""]]
} else {
	define CXX [find-an-executable [get-define cross]c++ [get-define cross]g++]
}

# CXXFLAGS default to CFLAGS if not specified
define CXXFLAGS [get-env CXXFLAGS [get-define CFLAGS]]

# May need a CC_FOR_BUILD, so look for one
define CC_FOR_BUILD [find-an-executable [get-env CC_FOR_BUILD ""] cc gcc false]

#define HAVE_MKSTEMP
#define HAVE_LINK
#define HAVE_SYS_TIME_H
#define HAVE_DIRENT_H
#define HAVE_UNISTD_H
#define HAVE_UMASK
#endif
#define JIM_VERSION 78
#ifndef JIM_WIN32COMPAT_H
#define JIM_WIN32COMPAT_H



#ifdef __cplusplus
extern "C" {

	char                *name;
} DIR;

DIR *opendir(const char *name);
int closedir(DIR *dir);
struct dirent *readdir(DIR *dir);






#endif

#endif

#ifdef __cplusplus
}
#endif

        void *ptr;

        struct {
            void *ptr1;
            void *ptr2;
        } twoPtrValue;

        struct {
            void *ptr;
            int int1;
            int int2;
        } ptrIntValue;

        struct {
            struct Jim_Var *varPtr;
            unsigned long callFrameId;
            int global;
        } varValue;

        struct {

            int lineNumber;
        } sourceValue;

        struct {
            struct Jim_Obj *varNameObjPtr;
            struct Jim_Obj *indexObjPtr;
        } dictSubstValue;





        struct {
            int line;
            int argc;
        } scriptLineValue;
    } internalRep;
    struct Jim_Obj *prevObjPtr;
    struct Jim_Obj *nextObjPtr;

    Jim_Obj *nullScriptObj;
    Jim_Obj *emptyObj;
    Jim_Obj *trueObj;
    Jim_Obj *falseObj;
    unsigned long referenceNextId;
    struct Jim_HashTable references;
    unsigned long lastCollectId; /* reference max Id of the last GC
                execution. It's set to ~0 while the collection
                is running as sentinel to avoid to recursive
                calls via the [collect] command inside
                finalizers. */
    time_t lastCollectTime;
    Jim_Obj *stackTrace;
    Jim_Obj *errorProc;
    Jim_Obj *unknown;

JIM_EXPORT void Jim_Free (void *ptr);
JIM_EXPORT char * Jim_StrDup (const char *s);
JIM_EXPORT char *Jim_StrDupLen(const char *s, int l);


JIM_EXPORT char **Jim_GetEnviron(void);
JIM_EXPORT void Jim_SetEnviron(char **env);
JIM_EXPORT int Jim_MakeTempFile(Jim_Interp *interp, const char *filename_template, int unlink_file);


JIM_EXPORT int Jim_Eval(Jim_Interp *interp, const char *script);


JIM_EXPORT int Jim_EvalSource(Jim_Interp *interp, const char *filename, int lineno, const char *script);

JIM_EXPORT int Jim_GetReturnCode (Jim_Interp *interp, Jim_Obj *objPtr,
        int *intPtr);


JIM_EXPORT int Jim_EvalExpression (Jim_Interp *interp,
        Jim_Obj *exprObjPtr);
JIM_EXPORT int Jim_GetBoolFromExpr (Jim_Interp *interp,
        Jim_Obj *exprObjPtr, int *boolPtr);


JIM_EXPORT int Jim_GetBoolean(Jim_Interp *interp, Jim_Obj *objPtr,
        int *booleanPtr);

JIM_EXPORT void Jim_MakeErrorMessage (Jim_Interp *interp);


JIM_EXPORT int Jim_InteractivePrompt (Jim_Interp *interp);
JIM_EXPORT void Jim_HistoryLoad(const char *filename);
JIM_EXPORT void Jim_HistorySave(const char *filename);
JIM_EXPORT char *Jim_HistoryGetline(Jim_Interp *interp, const char *prompt);
JIM_EXPORT void Jim_HistorySetCompletion(Jim_Interp *interp, Jim_Obj *commandObj);
JIM_EXPORT void Jim_HistoryAdd(const char *line);
JIM_EXPORT void Jim_HistoryShow(void);


JIM_EXPORT int Jim_InitStaticExtensions(Jim_Interp *interp);
JIM_EXPORT int Jim_StringToWide(const char *str, jim_wide *widePtr, int base);
JIM_EXPORT int Jim_IsBigEndian(void);

size_t regerror(int errcode, const regex_t *preg, char *errbuf,  size_t errbuf_size);
void regfree(regex_t *preg);

#ifdef __cplusplus
}
#endif

#endif
#ifndef JIM_SIGNAL_H
#define JIM_SIGNAL_H

#ifdef __cplusplus
extern "C" {
#endif

const char *Jim_SignalId(int sig);

#ifdef __cplusplus
}
#endif

#endif
#ifndef JIMIOCOMPAT_H
#define JIMIOCOMPAT_H


#include <stdio.h>
#include <errno.h>


void Jim_SetResultErrno(Jim_Interp *interp, const char *msg);

int Jim_OpenForWrite(const char *filename, int append);

int Jim_OpenForRead(const char *filename);

#if defined(__MINGW32__)
    #ifndef STRICT
    #define STRICT
    #endif
    #define WIN32_LEAN_AND_MEAN
    #include <windows.h>
    #include <fcntl.h>
    #include <io.h>
    #include <process.h>

    typedef HANDLE pidtype;
    #define JIM_BAD_PID INVALID_HANDLE_VALUE

    #define JIM_NO_PID INVALID_HANDLE_VALUE


    #define WIFEXITED(STATUS) (((STATUS) & 0xff00) == 0)
    #define WEXITSTATUS(STATUS) ((STATUS) & 0x00ff)
    #define WIFSIGNALED(STATUS) (((STATUS) & 0xff00) != 0)
    #define WTERMSIG(STATUS) (((STATUS) >> 8) & 0xff)
    #define WNOHANG 1

    int Jim_Errno(void);
    pidtype waitpid(pidtype pid, int *status, int nohang);

    #define HAVE_PIPE
    #define pipe(P) _pipe((P), 0, O_NOINHERIT)

#elif defined(HAVE_UNISTD_H)
    #include <unistd.h>
    #include <fcntl.h>
    #include <sys/wait.h>
    #include <sys/stat.h>

    typedef int pidtype;
    #define Jim_Errno() errno
    #define JIM_BAD_PID -1
    #define JIM_NO_PID 0

    #ifndef HAVE_EXECVPE
        #define execvpe(ARG0, ARGV, ENV) execvp(ARG0, ARGV)
    #endif
#endif

#endif
int Jim_bootstrapInit(Jim_Interp *interp)
{
	if (Jim_PackageProvide(interp, "bootstrap", "1.0", JIM_ERRMSG))
		return JIM_ERR;

	return Jim_EvalSource(interp, "bootstrap.tcl", 1,
"\n"
"\n"
"proc package {cmd pkg args} {\n"
"	if {$cmd eq \"require\"} {\n"
"		foreach path $::auto_path {\n"
"			set pkgpath $path/$pkg.tcl\n"
"			if {$path eq \".\"} {\n"
"				set pkgpath $pkg.tcl\n"
"			}\n"
"			if {[file exists $pkgpath]} {\n"
"				uplevel #0 [list source $pkgpath]\n"
"				return\n"
"			}\n"
"		}\n"
"	}\n"
"}\n"
);
}

{
	if (Jim_PackageProvide(interp, "stdlib", "1.0", JIM_ERRMSG))
		return JIM_ERR;

	return Jim_EvalSource(interp, "stdlib.tcl", 1,
"\n"
"\n"
"if {![exists -command ref]} {\n"
"\n"
"	proc ref {args} {{count 0}} {\n"
"		format %08x [incr count]\n"
"	}\n"
"}\n"
"\n"
"\n"
"proc lambda {arglist args} {\n"
"	tailcall proc [ref {} function lambda.finalizer] $arglist {*}$args\n"
"}\n"
"\n"
"proc lambda.finalizer {name val} {\n"
"	rename $name {}\n"

"		if {$line ne \"\"} {\n"
"			lappend lines $line\n"
"		}\n"
"	}\n"
"	join $lines \\n\n"
"}\n"
"\n"
"\n"
"\n"
"proc defer {script} {\n"
"	upvar jim::defer v\n"
"	lappend v $script\n"
"}\n"
"\n"
"\n"
"\n"
"proc errorInfo {msg {stacktrace \"\"}} {\n"
"	if {$stacktrace eq \"\"} {\n"
"\n"
"		set stacktrace [info stacktrace]\n"
"\n"

"		catch {$in close}\n"
"	}\n"
"}\n"
"\n"
"\n"
"\n"
"proc popen {cmd {mode r}} {\n"
"	lassign [pipe] r w\n"
"	try {\n"
"		if {[string match \"w*\" $mode]} {\n"
"			lappend cmd <@$r &\n"
"			set pids [exec {*}$cmd]\n"
"			$r close\n"
"			set f $w\n"
"		} else {\n"
"			lappend cmd >@$w &\n"
"			set pids [exec {*}$cmd]\n"
"			$w close\n"
"			set f $r\n"
"		}\n"
"		lambda {cmd args} {f pids} {\n"
"			if {$cmd eq \"pid\"} {\n"
"				return $pids\n"
"			}\n"
"			if {$cmd eq \"getfd\"} {\n"
"				$f getfd\n"
"			}\n"
"			if {$cmd eq \"close\"} {\n"
"				$f close\n"
"\n"
"				set retopts {}\n"
"				foreach p $pids {\n"
"					lassign [wait $p] status - rc\n"
"					if {$status eq \"CHILDSTATUS\"} {\n"
"						if {$rc == 0} {\n"
"							continue\n"
"						}\n"
"						set msg \"child process exited abnormally\"\n"
"					} else {\n"
"						set msg \"child killed: received signal\"\n"
"					}\n"
"					set retopts [list -code error -errorcode [list $status $p $rc] $msg]\n"
"				}\n"
"				return {*}$retopts\n"
"			}\n"
"			tailcall $f $cmd {*}$args\n"
"		}\n"
"	} on error {error opts} {\n"
"		$r close\n"
"		$w close\n"
"		error $error\n"

"		return -code error \"can not find channel named \\\"$channelId\\\"\"\n"
"	}\n"
"	if {[catch {$channelId pid} pids]} {\n"
"		return \"\"\n"
"	}\n"
"	return $pids\n"
"}\n"
"\n"
"\n"
"\n"
"\n"
"\n"
"\n"
"\n"
"\n"

#include <sys/stat.h>
#endif


#if defined(HAVE_SYS_SOCKET_H) && defined(HAVE_SELECT) && defined(HAVE_NETINET_IN_H) && defined(HAVE_NETDB_H) && defined(HAVE_ARPA_INET_H)
#include <sys/socket.h>
#include <netinet/in.h>
#include <netinet/tcp.h>
#include <arpa/inet.h>
#include <netdb.h>
#ifdef HAVE_SYS_UN_H
#include <sys/un.h>
#endif
#define HAVE_SOCKETS
#elif defined (__MINGW32__)

#else
#define JIM_ANSIC
#endif

#if defined(JIM_SSL)
#include <openssl/ssl.h>
#include <openssl/err.h>

#else
#define IPV6 0
#ifndef PF_INET6
#define PF_INET6 0
#endif
#endif

#ifdef JIM_ANSIC

#undef HAVE_PIPE
#undef HAVE_SOCKETPAIR
#endif


struct AioFile;

typedef struct {
    int (*writer)(struct AioFile *af, const char *buf, int len);
    int (*reader)(struct AioFile *af, char *buf, int len);

    if (name) {
        Jim_SetResultFormatted(interp, "%#s: %s", name, JimAioErrorString(af));
    }
    else {
        Jim_SetResultString(interp, JimAioErrorString(af), -1);
    }
}

static int JimCheckStreamError(Jim_Interp *interp, AioFile *af)
{
	int ret = af->fops->error(af);
	if (ret) {
		JimAioSetError(interp, af->filename);
	}
	return ret;
}

static void JimAioDelProc(Jim_Interp *interp, void *privData)
{
    AioFile *af = privData;

    JIM_NOTUSED(interp);

    af = Jim_AioFile(interp, command);
    if (af == NULL) {
        return NULL;
    }

    return af->fp;
}

static int aio_cmd_getfd(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
{
    AioFile *af = Jim_CmdPrivData(interp);

    fflush(af->fp);
    Jim_SetResultInt(interp, fileno(af->fp));

    return JIM_OK;
}

static int aio_cmd_copy(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
{
    AioFile *af = Jim_CmdPrivData(interp);
    jim_wide count = 0;
    jim_wide maxlen = JIM_WIDE_MAX;
    AioFile *outf = Jim_AioFile(interp, argv[0]);

    Jim_SetResultInt(interp, feof(af->fp));
    return JIM_OK;
}

static int aio_cmd_close(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
{
    if (argc == 3) {
#if defined(HAVE_SOCKETS) && defined(HAVE_SHUTDOWN)
        static const char * const options[] = { "r", "w", NULL };
        enum { OPT_R, OPT_W, };
        int option;
        AioFile *af = Jim_CmdPrivData(interp);

        if (Jim_GetEnum(interp, argv[2], options, &option, NULL, JIM_ERRMSG) != JIM_OK) {
            return JIM_ERR;

        }
        (void)fcntl(af->fd, F_SETFL, fmode);
    }
    Jim_SetResultInt(interp, (fmode & O_NONBLOCK) ? 1 : 0);
    return JIM_OK;
}
#endif


#ifdef HAVE_FSYNC
static int aio_cmd_sync(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
{
    AioFile *af = Jim_CmdPrivData(interp);

    fflush(af->fp);