PiDP-8/I Software

inst
test

examples/*.fc
src/scp.*
src/sim_*.[ch]
src/sim_*.in

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

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

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

doc/simh/*.pdf
test/*

.agignore

# Creators and Major Contributors to the PiDP-8/I Project
# Creators of and Major Contributors to the PiDP-8/I Project

*   **Oscar Vermeulen <oscar.vermeulen@hotmail.com>**:
*   **[Oscar Vermeulen](mailto:oscar.vermeulen@hotmail.com)**:

    -   Creator of the project (both hardware and software)
    
    -   Author of the initial modifications to the SIMH PDP-8 simulator
        necessary to make it use the PiDP-8/I front panel hardware

    -   Curator of the default set of binary demo media

    -   Author of the simulator setup scripts

    -   Initiator of much else in the project

    -   Author of the bulk of the documentation

    -   Host and major contributor to the PiDP-8/I support forum on
        Google Groups

    -   Hardware kit assembler and distributor

*   **Robert M Supnik** Primary author of the SIMH PDP-8 simulator upon
    which this project is based.
*   **Robert M Supnik** is the primary author of the SIMH PDP-8
    simulator upon which this project is based.

*   **Mike Barnes** Ported Oscar Vermeulen's SIMH 3.9 based PiDP-8/I
*   **Mike Barnes** ported Oscar Vermeulen's SIMH 3.9 based PiDP-8/I
    simulator to the new SIMH 4.0 code base.  (September 2015.)

*   **Dylan McNamee** Ported the software to Buildroot for the official
    2015.12.15 binary OS images, and helped to merge the James L-W
*   **Dylan McNamee** ported the software to Buildroot for the official
    2015.12.15 binary OS images and helped to merge the James L-W
    "alt-serial" mode in.

*   **Mark G. Thomas** Creator of the installation scripts for the
    2015.12.15 release, which were folded into the `make install`
    handler within `Makefile.in`. Also wrote the version of the SysV
*   **Mark G. Thomas** wrote the installation scripts for the 2015.12.15
    release, which were folded into the `make install` handler within
    the current `Makefile.in`. He also wrote the version of the SysV
    init script that came with that release as `rc.pidp8`, shipped here
    as `pidp8i-init`.
    init script shipped here as `etc/pidp8i-init.in`.

*   **Ian Schofield <isysxp@gmail.com>** Modified the LED lamp driving
    code in the simulator to better simulate the incandescent lamps in
    the original PDP-8/I hardware.  (The bulk of his original code has
    since been rewritten, but the core idea remains, and it is doubtful
    whether the current method would exist without his instigation.)
*   **[Ian Schofield](mailto:isysxp@gmail.com)** modified the LED lamp
    driving code in the simulator to better simulate the incandescent lamps
    in the original PDP-8/I hardware.  (The bulk of his original code
    has since been rewritten, but the core idea remains, and it is
    doubtful whether the current method would exist without his
    instigation.)

*   **Henk Gooijen <henk.gooijen@boschrexroth.nl>** Pushed the PDP-8
    simulator's internal EAE step counter value down into the PiDP-8/I's
    LED manipulation code, without which the step counter LEDs remain
    dark even when using the EAE.
*   **[Henk Gooijen](mailto:henk.gooijen@boschrexroth.nl)** pushed the
    PDP-8 simulator's internal EAE step counter value down into the
    PiDP-8/I's LED manipulation code, without which the step counter
    LEDs remain dark even when using the EAE.

*   **Paul R. Bernard <prb@downspout.ca>** wrote `src/test.c` and the
    core of what now appears as `doc/pidp8i-test.md`. (The program builds
    and installs as `pidp8i-test`.)  He also provided a one-line fix
    that completes the work of Henk Gooijen's step counter patch.
*   **[Paul R. Bernard](mailto:prb@downspout.ca)** wrote `src/test.c`
    and the core of what now appears as `doc/pidp8i-test.md`. (The program
    builds and installs as `pidp8i-test`.)  He also provided a one-line
    fix that completes the work of Henk Gooijen's step counter patch.

*   **[Rick Murphy](mailto:k1mu.nospam@gmail.com)** is the current
    maintainer of [OS/8 Adventure][advent] which we've included in our
    OS/8 disk image. He's also provided several other files which have
    landed in the distribution such as the [VTEDIT][vtedit] feature. He
    also optimized the `pep001.pal` example so that it fits into a
    single page of PDP-8 core.

*   **[Tony Hill](mailto:hill.anthony@gmail.com)** merged all the
    upstream SIMH changes produced between late September 2015 and late
    December 2016 into the PiDP-8/I simulator. This is the basis for the
    current automatic upstream feature merge capability, which is why
    many releases since December 2016 include an update to the latest
    version of upstream SIMH. His contributions are made to the project
    [as `tony`][thcomm].

*   **Rick Murphy <k1mu.nospam@gmail.com>** optimized the `pep001.pal`
*   **[Jonathan Trites](mailto:tritesnikov@gmail.com)** wrote the
    example so that it fits into a single page of PDP-8 core, and
    provided several useful files in his OS/8 disk images that have
    initial version of the script now called `libexec/mkos8`, which
    builds the OS/8 disk images from source tapes.
    managed to land in this software distribution's OS/8 disk image.

*   **Tony Hill <hill.anthony@gmail.com>** Merged all the upstream SIMH
*   **[Bill Cattey](mailto:bill.cattey@gmail.com)** is the project lead
    changes produced between late September 2015 and late December 2016
    into the PiDP-8/I simulator.  (Since then, this merge process is
    automated as `tools/simh-update`.)
    and primary developer of the system that builds the OS/8 RK05 disk
    images from source tapes. He greatly extended the `mkos8` script,
    curated the tape collection 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 Cattey <bill.cattey@gmail.com>** (a.k.a. poetnerd) did the
*   **[Warren Young](mailto:tangentsoft@gmail.com)** Did everything
    bulk of the work on automatic generation of OS/8 system pack images
    from original source media, replacing the hand-assembled and -hacked
    `os8.rk05` image.
    listed in [the change log][cl] that is not attributed to anyone
    else.

*   **Jonathan Trites <tritesnikov@gmail.com>** wrote the original
    version of what has become `tools/mkos8s.in`, the script that
    generates `bin/os8v3d-*.rk05` from source tapes.
    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.

*   **Warren Young <tangentsoft@gmail.com>** Did everything listed in
    `ChangeLog.md` that is not attributed to anyone else.
[advent]: http://www.rickmurphy.net/advent/
[cl]:     https://tangentsoft.com/pidp8i/doc/trunk/ChangeLog.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

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


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

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


## PiDP-8/I Design Files
## <a id="hw"></a>PiDP-8/I Design Files

The PiDP-8/I design files in [`hardware/pidp8i`][hwp] were released
under the Creative Commons [Attribution-NonCommercial-ShareAlike 4.0
International][ccl] license [on the mailing list][pdp8il] by their
author, Oscar Vermeulen.

[ccl]: https://creativecommons.org/licenses/by-nc-sa/4.0/
[hwp]: https://tangentsoft.com/pidp8i/dir?name=hardware/pdp8i&ci=trunk
[pdp8il]: https://groups.google.com/d/msg/pidp-8/bcIH9uEB_kU/zg9uho7NDAAJ


## autosetup License
## <a id="autosetup"></a>autosetup License

The `configure` script and the contents of the `autosetup` directory are
released under the FreeBSD license given in [`autosetup/LICENSE`][as].

[as]: https://tangentsoft.com/pidp8i/doc/trunk/autosetup/LICENSE


## palbart License
## <a id="palbart"></a>palbart License

The `palbart` program and its manual page are released under the terms
of the license given in [`palbart/LICENSE.md`][pl].
of the license given in [`src/palbart/LICENSE.md`][pl].

[pl]: https://tangentsoft.com/pidp8i/doc/trunk/palbart/LICENSE.md
[pl]: https://tangentsoft.com/pidp8i/doc/trunk/src/palbart/LICENSE.md


## <a id="d8tape"></a>d8tape License

The `d8tape` program is distributed under the license given in
[`src/d8tape/LICENSE.md`][d8tl].

[d8tl]: https://tangentsoft.com/pidp8i/doc/trunk/src/d8tape/LICENSE.md


## <a id="cc8"></a>CC8 Compiler License

The license for the `src/cc8` subtree is messy as it comes to us from
multiple authors over many years.

There are two compilers here.

First we have the OS/8 "native" compiler in `src/cc8/os8`, which is
entirely Ian Schofield's work, released under the terms of the [GNU
General Public License version 3][gpl3].

Then we have the CC8 cross-compiler which is based on Ron Cain's
[Small-C][smc], originally published in [Dr.  Dobbs' Journal][ddj].
Wikipedia describes Small-C as "copyrighted but sharable," which I take
to mean that we cannot claim it as our exclusive property, but we can
modify it and distribute those modifications to others, which is what
we're doing here.

Ian Schofield then took the Small-C source base and added a SABR
back-end, `code8.c`, which is also distributed under the [GPLv3][gpl3].

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

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


## OS/8 License
## <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


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

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

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


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

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

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

# PiDP-8/I Changes

## Version 2017.12.eh? — The "Languages and Custom OS/8 Disk Packs" release

*   All prior versions were shipping `os8.rk05`, a "Field Service
    Diagnostic" OS/8 disk pack image with uncertain provenance,
    configuration, and modification history.  We have replaced that with
    a script run at build time that programmatically assembles a set of
    clean OS/8 RK05 disk images from curated, pristine, tested sources
    based on the user's chosen configuration options.

    This provides the following features and benefits as compared to the
    old `os8.rk05`:

    -   The PiDP-8/I software build process now builds up to three RK05
        disk images:

        -   `os8v3d-bin.rk05` is a bootable OS/8 V3D disk configured
            according to your chosen configuration options, which are
            described below and in [`README.md`][tlrm].  It is made from
            the pristine DECtape images shipped by DEC for OS/8 V3D plus
            several third-party tapes curated for and built by the
            project's maintainers.  See [the OS/8 media `README.md`
            file][os8rm] for more details.

        -   `os8v3d-patched.rk05` is a copy of the `bin` disk with
            [most][os8p] of the patches DEC published over the years for
            OS/8 V3D applied.  That set of patches was chosen and tested
            for applicability to our modern PiDP-8/I world and for
            mutual compatibility.

            This is the boot disk used for the IF=0 and IF=7 cases
            unless you give `--disable-os8-patches` to the `configure`
            script, in which case these boot options use the `bin` disk.

        -   `os8v3d-src.rk05` is a non-bootable disk containing the
            contents of the OS/8 V3D source code tapes plus the source
            code for the extensions to OS/8 V3D.  The *ten* TU56 tape
            images used as input to this process are also included among
            the PiDP-8/I software — see `media/os8/al-*-sa-*.tu56` — but
            we find it much more convenient to explore the sources on a
            single RK05 disk than to repeatedly attach and detach the
            TU56 tapes.

            You can suppress building this with `--disable-os8-src`.

        Default versions of these disk images are also now published on
        the project's home page for the benefit of those not running our
        PiDP-8/I software.  There are quite a few OS/8 RK05 disk images
        floating around on the Internet these days, and many of them
        have bugs and breakage in them that we've fixed.  It would
        completely fail to break our hearts if these images were used by
        many people outside the PiDP-8/I project.

    -   U/W FOCAL V4E is installed on SYS: by default. Start with our
        [U/W FOCAL Manual Supplement for the PiDP-8/I][uwfs], then
        follow links from there to further information.
        
        The primary linked source is the [U/W FOCAL Manual][uwfm] by Jim
        van Zee (creator of U/W FOCAL) converted from scanned and OCR'd
        PDF form to Markdown format, which Fossil renders nicely for us
        on the web.

        This is a fascinating programming language, well worth studying!

    -   Ian Schofield's CC8 OS/8 C compiler is installed on `SYS:` by
        default, and its examples and other files are on `DSK:`.  We
        have also merged in his `cc8` host-side cross-compiler.  See
        [the CC8 `README`][cc8rm] for details.
        
        This is a considerably improved compiler relative to what
        was distributed on the mailing list in August 2017.  Ian has
        been working within the PiDP-8/I project since that initial
        public release, which we are now distributing publicly for
        the first time.  We thank him for trusting us to host and
        distribute his project.

    -   The MACREL v2 macro assembler and its associated FUTIL V8B tool
        are installed by default.  Not only is this new functionality
        relative to prior releases of the PiDP-8/I software, it is a
        considerable upgrade over to the original MACREL and FUTIL V7
        that are more commonly found on the net.

    -   DCP disassembler is installed by default.

    -   John Comeau's CHECKMO-II chess program is installed by default.

    -   By default, SIMH no longer folds lowercase input and output to
        uppercase.  Instead, we apply patches to OS/8's command
        processor and its BASIC implementation to up-case input, since
        neither OS/8 nor BASIC can cope with lowercase input.

        All other programs are left to fend for themselves, which
        often works out fine.  U/W FOCAL, Adventure, and TECO all handle
        lowercase input to some extent, for example, and all three can
        emit lowercase text if given it.  With the prior SIMH setting,
        you could not use lowercase in these programs at all.

        This default can be overridden.  See the documentation for the
        new `--lowercase` configuration option in `README.md`.

    -   The `INIT.TX` message displayed by default on OS/8 boot is now
        more informative than the old `FIELD SERVICE PDP-8 DIAGNOSTIC
        SYSTEM` message.  It also now uses lowercase unless you built
        the simulator to force uppercase with `--lowercase=upper`.

        Those that do not want any boot message can disable it at
        configuration time with the `--disable-os8-init` flag.

        The message can be modified by editing `media/os8/init.tx.in`
        and saying `make`, which will rebuild the OS/8 media.

    -   All of the above features can be disabled if not wanted, as can
        several features present on the old `os8.rk05` disk: Adventure,
        FORTRAN IV, FORTRAN II, Kermit-12, and the BASIC game and demo
        programs.

        You can disable each feature above with a `--disable-os8-*`
        option to the `configure` script, or you can disable all of them
        collectively with the `--os8-minimal` option, which gets you a
        nearly bare-bones OS/8 installation with lots of spare disk
        space with which you can do what *you* want.

    -   Replaced the mismatched FORTRAN compiler and runtime with
        matched versions from the distribution DECtapes, and ensured that
        Adventure runs under this version of the FORTRAN Run Time System
        (FRTS). At various points in the past, either FORTRAN or
        Adventure has been broken.

    -   Repaired several broken BASIC programs on `RKB0:` by going back
        to primary sources.  Either the `os8.rk05` disk image was corrupted
        at some point or it is an image of a real RK05 disk pack that
        was corrupted, causing several of these BASIC programs to not
        run properly.

    -   The `*.MU` and music player files are left off of `RKB0:` by
        default, since they apparently do not cause sufficient RFI on
        the PiDP-8/I hardware to be picked up by normal AM radios.  This
        saves space for things that *do* work.

    -   No longer installing the `VTEDIT` macros for TECO by default.
        Although some may enjoy this alternative way of running TECO, it
        was decided that we should offer stock TECO by default for its
        historical value.  If you want VTEDIT back, it can be re-enabled
        with a `configure` script option.

    -   In the old `os8.rk05` disk image, both `SYS:` and `DSK:` were
        set to `RKA0:`, which meant that to address anything on `RKB0:`, you
        had to specify the device path explicitly or manually change the
        default in OS/8 with an `ASSIGN RKB0 DSK` command or similar.

        In the new disk pack, programs run with the OS/8 `R` command are
        installed on `RKA0:` which is the `SYS:` disk, and user data
        files, FOCAL and BASIC programs, etc. are on `RKB0:` which is
        assigned as `DSK:`. This means OS/8 and its programs are now far
        more likely to find files without an explicit device name,
        because files are installed where OS/8 looks for them by
        default.  Example:

            .R FRTS                   ⇠ loads FRTS from SYS: (RKA0:)
            *ADVENT                   ⇠ loads ADVENT.LD from DSK: (RKB0:)
            *[Esc]
            Welcome to Adventure!!

        Notice that no device names had to be specified.  OS/8 did the
        right thing by default here, even though the files involved are
        on two separate OS/8 devices.

        To a very rough approximation, `SYS:` on these new RK05 disk
        packs acts like the Unix `PATH` and `DSK:` acts like your user's
        home directory.

        The idea for this came from Ian Schofield's `cc8.rk05` disk
        image, which we are also shipping in this release.

    -   OS/8 has a limit on the number of devices it can support, and we
        made different choices than the creator of `os8.rk05`.

        Briefly, we replaced the second floppy (`RXA1:`) with a third
        RK05 disk, that being deemed a more useful configuration for
        this hard disk based OS/8 configuration.  A dual-floppy
        configuration implies that you are booting from floppy and need
        the second one for user files and such.  In our RK05 based
        configuration, users should need floppy disk support rarely, and
        then primarily to get data on and off of the attached hard
        disk(s).

        We chose to stick with the dual TU56 tape drive setup of the
        prior version as we found the ability to mount two tapes very
        helpful, particularly during the `mkos8` build process.

        The difference in the `RESORC` output between the versions is:

            Old: RKA0,RKB0,RKA1,RKB1,          RXA0,RXA1,DTA0,DTA1,TTY,LPT,PTP,PTR
            New: RKA0,RKB0,RKA1,RKB1,RKA2,RKB2,RXA0,     DTA0,DTA1,TTY,LPT,PTP,PTR

    This automatic OS/8 media build feature was suggested by Jonathan
    Trites who wrote the initial version of the script that is now
    called `libexec/mkos8`.  That script was then extended and factored
    into its current form by Bill Cattey and Warren Young.

    Warren thinks Bill did most of the hard work in the items above.

    The source media used by the `mkos8` script comes from many sources
    and was curated for the PiDP-8/I project by Bill Cattey.  See the
    [OS/8 media README][os8rm] for more details.

    See the [the top-level `README`][tlrm] for information on modifying
    the default OS/8 configuration.  Pretty much everything above can be
    disabled if it's enabled by default, and vice versa.

*   Added several new wiki articles covering the above:

    *   More Project Euler Problem #1 solutions in:

        *   [C][pe1c]
        *   [FORTRAN IV][pe1f4]
        *   [FORTRAN II][pe1f2]
        *   [U/W FOCAL][pe1u]

    *   [Demos in BASIC][dibas], deescribing `DSK:*.BA`

    *   [OS/8 Console TTY Setup][os8ct], describing how we have
        modified the stock behavior of OS/8 to behave appropriately
        with a glass terminal or SSH on its console, as opposed to
        its default behavior, which assumes a teletype.

    *   [OS/8 LCSYS.BI Disassembled][os8lc], a symbolic
        disassembly of the `LCSYS.BI` patch we distribute with the
        system, which is widely available online elsewhere. That script
        is a raw binary patch, which makes its operation a mystery
        unless you happen to be able to read PDP-8 machine code.

*   Added Bill Cattey's `txt2ptp` program which converts plain ASCII
    text files files to the paper tape format used by SIMH, which eases
    transfer of text data into the simulator.  That program is also
    linked to `ptp2txt`, which makes it perform the inverse function:
    given a SIMH paper tape image file, produce an ASCII text file on
    the host machine with its contents.

    This program was written to ease the movement of FOCAL program text
    between SIMH and its host OS, but they should prove useful for other
    similar tasks.

*   Integrated Robert Krten's `d8tape` PDP-8 host-side disassembler.
    This is distinct from the OS/8 DCP disassembler, which runs inside
    the simulator.  It is intended as a companion to `palbart`, which we
    integrated last year.

*   Added a new "blinkenlights" demo program called `bin/teco-pi-demo`
    which drives SIMH from the outside, running a TECO macro under OS/8
    to calculate *pi* to 248 digits at a very slow rate, producing a
    display that manages to land somewhere between the random default
    display of [Deeper Thought][dt2vk] and the clear, boring patterns of
    our preexisting IF=5 demo script.

    Why 248 digits?  Because at 249, TECO8 runs out of memory, aborting
    the demo early.  At the default execution rate, it would take over
    17 years to complete this demo, making it a good choice to run on
    PiDP-8/I units primarily being used as *objets d'art*.  The demo has
    a finite run time, but your Raspberry Pi is likely to die before it
    completes. `;)`

    This script is also included as a demonstration of how the end user
    can reuse the technology that we developed to automatically build
    the custom OS/8 disk images described above to achieve different
    ends.  Perhaps you have some other program you'd like to run within
    SIMH in an automated fashion?  This shows one way how, and
    demonstrates a pre-built and tested set of tools for achieving it.

    We have also written [a tutorial][csd] explaining how
    `bin/teco-pi-demo` works and how to reuse the components it is built
    atop for your own ends.

    This demo also has a benchmark mode (command line option `-b`) which
    has two purposes:

    1.  It lets you see how much faster your host system runs PDP-8 code
        than a Raspberry Pi Model B+ running the PiDP-8/I simulator.

    2.  Given that information, the benchmark overrides a hardcoded
        timing value in the source code as distributed which prevents
        programs like `teco-pi-demo` from spamming the OS/8 terminal
        input handler.  The default is for the slowest host we support
        this software on, that same Model B+ referred to above, but if
        we know you're running on a faster host, we can shorten this
        delay and remain reliable.
        
    If you run the demo in benchmark mode twice, you'll notice that the
    TECO script is input nearly instantaneously the second time, whereas
    you can see the demo "type" the script in very quickly the first
    time.  (Remove `lib/pidp8i/ips.py`, say `make reconfig` and run the
    demo again to see the difference.)

*   The `DF` + `SING_STEP` feature for automatically attaching binary
    media images to the simulator from files on USB sticks now looks
    at all directories under `/media`, not just `usb0` through `usb7`
    so that it works with several other common Linux USB automounting
    schemes, such as the one Raspbian Desktop uses.

*   Fixed the order of initialization in the GPIO setup code for the
    James L-W serial mod case.  Fix by Dylan McNamee.

*   The helper program that selects which boot script to run when the
    PiDP-8/I boots based on the IF switch settings broke at some point
    in the past, apparently because it was using its own idiosyncratic
    GPIO handling code, and thus did not track our evolving GPIO
    handling methods.  Now it shares the same code used by `pidp8i-sim`
    and `pidp8i-test`, so it works properly again.

*   The SysV init script that starts `pidp8i-sim` under GNU Screen on
    the PiDP-8/I now sets the working directory to `$prefix/share/media`
    on start, so relative paths given to SIMH commands (e.g. `ATTACH`)
    are more likely to do what you want.  In prior releases, you
    generally had to give absolute paths to attach media and such
    because CWD would be set somewhere unhelpful.

*   The Fetch LED is no longer lit when in STOP or single-step mode.  In
    real hardware, it can be either on or off in this mode, depending
    on various conditions, but it is most often off, so while it is not
    perfectly correct now, it is less wrong.  Most of the investigation
    into this issue is by Bill Cattey, with the current partial fix by
    me.  A more precise fix may come later.  (See ticket [347ae45403] if
    you care to know the details.)

*   The Pause LED state was over-counted in the LED sub-sampling scheme
    so that it would tend to be brighter than it should have been.
    Problem noticed by Ian Schofield.

*   The MB row's state was not showing the right thing.  The problem was
    noticed in comparison to real PDP-8/I hardware by Vincent Slyngstad
    and verified by William Cattey.  Ian Schofield suggested the current
    fix.

*   Updated SIMH to upstream checkin ID 27f9fc3c3, December 11, 2017.
    There have been no substantial changes to the PDP-8 simulator since
    the last update, 8 months ago, but there have been a lot of bug
    fixes to the SCP core program.

*   Updated for Raspbian Stretch, released in September 2017.  It should
    still run on Raspbian Jessie, however.

*   Assorted portability, build system, and documentation improvements.

*   **TODO**

    -   Create udev script replacement for usbmount so that `DF` +
        `SING_STEP` works on Stretch.

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


## 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
    last version, and we have no reason to believe our NLS code is
    sufficiently different to avoid the problem.

    percentage style throttle rates.  We now explicitly set the throttle
    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.


## Version 2017.04.01 The "I May Be a Fool, but I am *Your* Fool" Release
## Version 2017.04.01 — The "I May Be a Fool, but I am *Your* Fool" release

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

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

*   The simulator now reports the upstream Git commit ID it is based on
    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.)


## Version 2016.12.26 (The Boxing Day release)
## Version 2016.12.26 — The Boxing Day release

*   Tony Hill updated SIMH to the latest upstream version.

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

[p1saga]: https://tangentsoft.com/pidp8i/wiki?name=PEP001.PA


## Version 2016.11.28

*   Added an intelligent, powerful build system, replacing the
    bare-bones `Makefile` based build system in the upstream version.
    See [`README.md`][readme] for more info on this.
    See [`README.md`][tlrm] for more info on this.

*   The installation is now completely relocatable via `./configure
    --prefix=/some/other/place`. The upstream version would not work if
    installed somewhere other than `/opt/pidp8` due to many hard-coded
    absolute paths.  (This is enabled by the new build system, but
    fixing it was not simply a matter of swapping out the build system.)

    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!

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

You must use Fossil version 2.1 or higher with our repository, or you
will get an error.

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

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

    $ sudo apt install libssl-dev
    $ wget -O fossil-release.tar.gz \
    $ wget https://tangentsoft.com/pidp8i/uv/fossil-raspbian-9.1-stretch
      https://fossil-scm.org/index.html/tarball/fossil-release?uuid=release
    $ tar xvf fossil-release.tar.gz
    $ cd fossil-release
    $ sudo install -m 755 fossil-* /usr/local/bin/fossil
    $ ./configure
    $ make
    $ sudo make install

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


[fbin]:   http://fossil-scm.org/index.html/uv/download.html
[dvcs]:   http://en.wikipedia.org/wiki/Distributed_revision_control
[fbook]:  http://www.fossil-scm.org/schimpf-book/home
[fml]:    http://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/fossil-users
[fossil]: http://fossil-scm.org/
[fqsg]:   http://fossil-scm.org/index.html/doc/trunk/www/quickstart.wiki
[fbin]:   https://fossil-scm.org/index.html/uv/download.html
[dvcs]:   https://en.wikipedia.org/wiki/Distributed_revision_control
[fbook]:  https://www.fossil-scm.org/schimpf-book/home
[fml]:    https://mailinglists.sqlite.org/cgi-bin/mailman/listinfo/fossil-users
[fossil]: https://fossil-scm.org/
[fqsg]:   https://fossil-scm.org/index.html/doc/trunk/www/quickstart.wiki
[ggml]:   https://groups.google.com/forum/#!forum/pidp-8


Fossil Anonymous Access
----

To clone the code repository anonymously, say:

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

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


Working With Existing Tags and Branches
Working with Existing Tags and Branches
----

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

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

our scope here.  See the [Fossil Quick Start Guide][fqsg] and the
documents it links to for more details.)

This directory scheme shows an important difference between Fossil and
Git: with Git, the checkout and the clone are intermingled in the same
directory tree, but in Fossil, they are strictly separate.  Git can
emulate Fossil's normal working style through its [worktree][gitwt]
feature, but it's a kind of lash-up using symlinks and such, whereas
with Fossil, there is no confusion: the repository clone is a single
SQLite database file — here, `pidp8i.fossil` — and the checkouts are
made from the contents of that database.
feature, but it employs some trickery that causes some unwanted side
effects that don't affect Fossil by design: the repository clone is a
single SQLite database file — here, `pidp8i.fossil` — and the checkouts
are made from the contents of that database.

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

Fossil Developer Access
----

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

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

If you've already cloned anonymously, you don't have to clone again to
inform Fossil about your developer account.  Just do a manual sync,
changing the URL to include the user name:

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

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.
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, but you'll
be able to sync with the central repoisitory once you get back online.
If you're working offline, Fossil will still do the checkin locally, and
it will sync up with the central repoisitory 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
only when you are truly going to be offline and don't want Fossil
attempting to sync when you know it will fail.


Getting Developer Access
----

The administrator of this repository is Warren Young, whose email you

Manipulating the Build System Source Files
----

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

     auto.def
     autosetup/
     autosetup/*
     configure
     Makefile.in

Unlike with GNU Autoconf, which you may be familiar with, the
`configure` script is not output from some other tool.  It is just a
driver for the Tcl and C code under the `autosetup` directory.  If you
have to modify any of these files to get some needed effect, you should
try to get that change into the upstream project, then merge that change
down into the local copy when it lands upstream.
driver for the Tcl and C code under the `autosetup` directory.

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

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

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

The `Makefile.in` file is largely a standard [GNU `make`][gmake] file
excepting only that it has variables substituted into it by
[`autosetup`][asbs] 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 anticpate any need to support any other `make`
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 anticpate any need to support any other `make` flavors.
flavors.

(This, by the way, is why we're not using some heavy-weight build system
such as the GNU Autotools, CMake, etc.  The primary advantage of GNU
Autotools is that you can generate source packages that will configure
and build on weird and ancient flavors of Unix; we don't need that.
Cross-platform build systems such as CMake ease building the same
software on multiple disparate platforms straightforward, but the
PiDP-8/I software is built primarily on and for a single operating
system, Rasbpian Linux.  It also happens to build and run on other
modern Unix and Linux systems, 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/
[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, the top-level
    `README*.md` files, 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.  Say `fossil help set` at the command line for more on this.
    Such settings are intended to be correct for all users of the
    system; rather than expressing defaults, they express *policy*.

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

*   <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 run both in development and after
    installation.  Some files here are created directly by the project's
    developers, while others are outputs of the build system. The
    content of this directory is copied to `$prefix/bin` at installation
    time, which is added to the user's `PATH` by the installer.

*   <b>`boot`</b> - SIMH initialization scripts. The `*.script.in` files
    are written by the project developers but have build-time values
    substituted in by the `configure` script to produce a `*.script`
    version. Some of the remaining `*.script` files are hand-written and
    as such are checked into Fossil directly. The remainder are outputs
    of `tools/mkbootscript`, which produces them from `palbart` assembly
    listings.

    All of these `*.script` files are installed to `$prefix/share/boot`
    regardless of their origin.

*   <b>`doc`</b> - Documentation files not immediately important enough
    to a new user of the software that they do not have to be at the top
    level of the project tree.

    Fossil allows us to treat the contents of `doc` much like the wiki,
    so how do we decide whether to put a given document into `doc` or
    the wiki?  The rule is simple: is the document's history tied to the
    history of the PiDP-8/I project itself?  If so, it goes in `doc`,
    else it goes in the wiki.  When checking out older versions of the
    PiDP-8/I software, you expect to roll back to contemporaneous
    versions of the project documentation; such files go into `doc`.
    Documents which are independent of the PiDP-8/I project history go
    into the wiki.

    (The wiki does also have history, but rolling back to a prior
    version of the PiDP-8/I repository and then saying `fossil ui` will
    show you the current version of the wiki documents, not the versions
    as they existed at the time of the historical checkin you rolled
    back to.)

    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.

*   <b>`examples`</b> - Example programs for the end user's edification.
    Many of these are referenced by documentation files.

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

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

    *   <b>`mkos8`</b> - Run by the build system.
    
        <p>It is sometimes run by hand in development, but primarily
        only to further its development. Once it runs correctly after
        adding some feature, we let <code>make</code> run it for us.</p>

    *   <b>`scanswitch`</b> - Run by `etc/pidp8i`.
    
        <p>As with <code>mkos8</code>, it is generally run by hand only
        by developers modifying its behavior.</p>

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

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

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

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

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

*   <b>`src`</b> - Source code for the project's programs, especially
    those that cannot be used until they are built. The 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`.

    The top level of `src` is for the SIMH core, with the PDP-8
    simulator specific bits in the `PDP8` subdirectory.

    The subdirectories of `src` are for other programs' source code.

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


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

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

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

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

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


The PiDP-8/I Software Project Code Style Rules
----

# 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 of the latest version of the SIMH 4 project on GitHub 
# that has been merged into this source base.
SGCID=17903827bdb294f7e60d4c7f172bd6a1a71dfbd5
SGCID=27f9fc3c3e7ff105c6102dfffc6da7fb838d1e8f

# C build flags for src/*.c and PDP8/*.c, containing the SIMH core
# modules and the SIMH PDP-8 simulator, respectively.
TOP_CFLAGS := @CFLAGS@ @BUILDMODE@ \
CFLAGS = @CFLAGS@ -Wno-unused-result -Wno-parentheses @BUILDMODE@ \
	-DUSE_READER_THREAD -DHAVE_DLOPEN=so -DPIDP8I -DSIM_ASYNCH_IO \
	-DHAVE_REGEX_H -DHAVE_GLOB -DSIM_GIT_COMMIT_ID=$(SGCID) \
	-D_GNU_SOURCE -U__STRICT_ANSI__ \
	-Wno-unused-result -Wno-parentheses \
	-DUSE_READER_THREAD -DHAVE_DLOPEN=$(subst .,,@SH_SOEXT@) -DPIDP8I \
	-DSIM_ASYNCH_IO -DHAVE_REGEX_H -DHAVE_GLOB \
	-DSIM_GIT_COMMIT_ID=$(SGCID) -D_GNU_SOURCE \
	-U__STRICT_ANSI__ \
	-I @srcdir@/src -I @srcdir@/src/PDP8 -I src
PDP8_CFLAGS = $(TOP_CFLAGS)

# Greatly stripped-down build options for the cc8 cross-compiler
# primarily because it's K&R C.  Building under TOP_CFLAGS spews
# pages of warnings.  The only thing we share is whether to build
# a debug or optimized version, from BUILDMODE, set by auto.def.
CC8_CROSS_CFLAGS = -w @BUILDMODE@

# Krten's d8tape doesn't need much in the way of options.  It builds
# without warnings under the supported version of Raspbian.  On some
# other OS types, it complains about one of the printf() format
# specifiers, which we cannot fix portably, so we suppress that one.
D8TAPE_CFLAGS = -Wno-format @BUILDMODE@

# Ditto palbart.
PALBART_CFLAGS = @BUILDMODE@

SIM = bin/pidp8i-sim
BINS = $(SIM) @CC8_CROSS@ \
	bin/d8tape \
	bin/palbart \
	bin/pidp8i-test \
	bin/ptp2txt \
BINS = bin/palbart $(SIM) bin/pidp8i-test libexec/scanswitch
	libexec/scanswitch
BIN_SCRIPTS = \
	bin/pidp8i \
	@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 \
	$(PIDP8I_DIRS)

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

MKOS8         := @srcdir@/libexec/mkos8
MKOS8_LIB     := @srcdir@/lib/mkos8
MKOS8_PY      := \
	$(MKOS8_LIB)/__init__.py \
	$(MKOS8_LIB)/argparser.py \
	lib/mkos8/opts.py
MKOS8_PY_ALL  := $(GENNED_PY) $(MKOS8_PY) $(SIMH_PY_SRC)
MKOS8_SRCS    := $(MKOS8) $(MKOS8_PY_ALL) $(PIDP8I_DIN)

BUILDDIRS = bin libexec obj/PDP8
BUILDDIRS := bin libexec obj/cc8/cross obj/d8tape obj/palbart obj/PDP8

INSTDIRS = bin etc libexec share/boot share/media share/man/man1
INSTDIRS := bin etc lib/mkos8 lib/pidp8i libexec share/boot share/media share/include share/man/man1

OBJS = \
SIM_OBJS := \
	obj/gpio-common.o \
	obj/PDP8/pdp8_df.o \
	obj/PDP8/pdp8_cpu.o \
	obj/PDP8/pdp8_clk.o \
	obj/PDP8/pdp8_ct.o \
	obj/PDP8/pdp8_dt.o \
	obj/PDP8/pdp8_fpp.o \

	obj/sim_serial.o \
	obj/sim_sock.o \
	obj/sim_tape.o \
	obj/sim_timer.o \
	obj/sim_tmxr.o \
	obj/sim_video.o

CC8_OBJS := \
	obj/cc8/cross/code8.o \
	obj/cc8/cross/data.o \
	obj/cc8/cross/error.o \
	obj/cc8/cross/expr.o \
	obj/cc8/cross/function.o \
	obj/cc8/cross/gen.o \
	obj/cc8/cross/io.o \
	obj/cc8/cross/lex.o \
	obj/cc8/cross/main.o \
	obj/cc8/cross/preproc.o \
	obj/cc8/cross/primary.o \
	obj/cc8/cross/stmt.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

MISC_OBJS := \
	obj/ptp2txt.o \
	obj/scanswitch.o \
	obj/test.o

PALBART_OBJS := obj/palbart/palbart.o

ifeq (@BUILD_DEEPER_THOUGHT@, 1)
BINS += bin/deeper
endif

LIBS = -lm -ldl -lpthread

ASM_PTS     := $(wildcard @srcdir@/asm/*.pal)
ASM_PTS     := $(subst @srcdir@/asm,bin,$(ASM_PTS))
ASM_PTS     := $(ASM_PTS:.pal=.pt)
EX_PTS      := $(wildcard @srcdir@/examples/*.pal)
EX_PTS      := $(subst @srcdir@/examples,bin,$(EX_PTS))
EX_PTS      := $(EX_PTS:.pal=.pt)
LISTINGS    := $(ASM_PTS:.pt=.lst) $(EX_PTS:.pt=.lst)
ASM_PTS     := $(wildcard @srcdir@/src/asm/*.pal)
ASM_PTS     := $(subst @srcdir@/src/asm,bin,$(ASM_PTS))
ASM_PTS     := $(ASM_PTS:.pal=-pal.pt)
FC_EX_PTS   := $(wildcard @srcdir@/examples/*.fc)
FC_EX_PTS   := $(subst @srcdir@/examples,bin,$(FC_EX_PTS))
FC_EX_PTS   := $(FC_EX_PTS:.fc=-focal.pt)
PAL_EX_PTS  := $(wildcard @srcdir@/examples/*.pal)
PAL_EX_PTS  := $(subst @srcdir@/examples,bin,$(PAL_EX_PTS))
PAL_EX_PTS  := $(PAL_EX_PTS:.pal=-pal.pt)
LISTINGS    := $(ASM_PTS:-pal.pt=.lst) $(PAL_EX_PTS:-pal.pt=.lst)
LISTINGS    := $(subst bin/,obj/,$(LISTINGS))
BOOTSCRIPTS := $(LISTINGS:.lst=.script)
BOOTSCRIPTS := $(subst obj/,boot/,$(BOOTSCRIPTS)) \
	boot/1.script \
	boot/5.script

# List of *.in files from auto.def file, except for this present file
# (Makefile.in) which is handled separately.  This list should only
# change when the list of "make-template" calls in auto.def changes.
#
# If the first file listed below changes, change the AUTOREBUILD rule
# near the end of this file to match!
# 
# The MKOS8_INFILES set of files are those which, if changed, require
# rebuilding the OS/8 media.  Touching the combined set merely causes
# a reconfig and build.
#
# The PRECIOUS set are those whose outfiles we want make(1) to treat as
# "precious", meaning it won't delete files generated by a target if the
# rule being processed to create that target fails.
# 
# The rest have no special treatment.
MKOS8_INFILES = \
	@srcdir@/lib/pidp8i/__init__.py.in \
	@srcdir@/lib/pidp8i/ips.py.in \
	@srcdir@/media/os8/init.tx.in \
	@srcdir@/src/PDP8/pidp8i.c.in \
	$(PIDP8I_DIN)
PRECIOUS_INFILES = \
	@srcdir@/Makefile.in \
    @srcdir@/examples/Makefile.in \
    @srcdir@/src/Makefile.in \
    @srcdir@/src/cc8/Makefile.in \
    @srcdir@/src/PDP8/Makefile.in
INFILES = \
	@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@/etc/pidp8i-init.in \
	@srcdir@/etc/sudoers.in \
	@srcdir@/src/gpio-common.c.in \
	@srcdir@/src/PDP8/pidp8i.c.in \
	@srcdir@/tools/mkos8.in \
	@srcdir@/tools/simh-update.in
PRECIOUS_INFILES = \
	@srcdir@/tools/simh-update.in \
	$(MKOS8_INFILES)
	@srcdir@/Makefile.in \
	@srcdir@/examples/Makefile.in \
	@srcdir@/src/Makefile.in \
	@srcdir@/src/PDP8/Makefile.in
OUTFILES := $(subst @srcdir@/,,$(INFILES))
OUTFILES := $(subst .in,,$(OUTFILES))
MKOS8_OUTFILES := $(subst @srcdir@/,,$(MKOS8_INFILES))
MKOS8_OUTFILES := $(subst .in,,$(MKOS8_OUTFILES))
PRECIOUS_OUTFILES := $(subst @srcdir@/,,$(PRECIOUS_INFILES))
PRECIOUS_OUTFILES := $(subst .in,,$(PRECIOUS_OUTFILES))
OUTFILES := $(subst @srcdir@/,,$(INFILES))
OUTFILES := $(subst .in,,$(OUTFILES))

OS8_BIN_RK05 = bin/os8v3d-bin.rk05
OS8_SRC_RK05 = bin/os8v3d-src.rk05
OS8_SRC_RK05 = @OS8_SRC_RK05@
OS8_RK05S = $(OS8_BIN_RK05) $(OS8_SRC_RK05)

CLTXT = /boot/cmdline.txt

ADF := adrules.mk

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

all: $(OUTFILES) $(PRECIOUS_OUTFILES) $(BUILDDIRS) $(BINS) $(BOOTSCRIPTS) $(LISTINGS) $(ASM_PTS) $(EX_PTS) $(OS8_RK05S)
all: $(OUTFILES) $(PRECIOUS_OUTFILES) $(BUILDDIRS) $(BINS) $(BOOTSCRIPTS) $(LISTINGS) $(ASM_PTS) $(FC_EX_PTS) $(PAL_EX_PTS) $(OS8_RK05S)
	@chmod 755 bin/pidp8i

clean:
	@rm -f $(BINS) $(BOOTSCRIPTS) $(ASM_PTS) $(EX_PTS) $(LISTINGS) $(OBJS) $(OUTFILES) \
		tags \
		obj/*.d \
		obj/*.o \
	@rm -f $(BINS) $(BOOTSCRIPTS) $(ASM_PTS) $(PAL_EX_PTS) $(LISTINGS) \
		$(OUTFILES) $(ADF) \
		config.log cscope.out tags \
		bin/*.pt bin/*.rk05 bin/*.save bin/txt2ptp \
		lib/*.pyc lib/*/*.pyc lib/mkos8/opts.py \
		obj/*.log obj/*.pt obj/mkos8.opts \
		obj/PDP8/*.d \
		src/config.h \
		@srcdir@/examples/*.err
	@find obj \( -name \*.o -o -name \*.d \) -delete
	@-rmdir -p $(BUILDDIRS) 2> /dev/null || true

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

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

install: all
install: all instdirs
	@echo Installing to @prefix@...

	@# Create any missing install tree directories
	for d in $(INSTDIRS) ; do @INSTALL@ -m 755 -d @prefix@/$$d ; done

	@# Install files into those dirs and set their perms
	@for f in $(BINS) ; do \
		dest=@prefix@/bin/$$(basename $$f) ; \
		echo "Installing binary $$dest..." ; \
	for f in $(BINS) ; do @INSTALL@ -m 755 -D -s $$f @prefix@/$$f ; done
	@INSTALL@ -m 755 @srcdir@/bin/pidp8i @prefix@/bin
	-for f in @prefix@/bin/pidp8i-* ; do setcap 'cap_sys_nice=eip' $$f ; done || true
	test -e @MEDIADIR@/os8/os8.rk05 || $(MAKE) mediainstall
		@INSTALL@ -m 755 -D -s $$f $$dest ; \
	done
	@for f in $(BIN_SCRIPTS) ; do \
		dest=@prefix@/bin/$$(basename $$f) ; \
		echo "Installing script $$dest..." ; \
		@INSTALL@ -m 755 -D $$f $$dest ; \
	done
	@( cd @prefix@/bin ; \
	   echo "Installing txt2ptp symlink..." ; \
	   ln -f ptp2txt txt2ptp ; \
    )
	@(test -x /sbin/setcap && \
		for f in @prefix@/bin/pidp8i-* ; do \
			echo "Setting real-time priority capabilities on $$(basename $$f)..." ; \
			/sbin/setcap 'cap_sys_nice=eip' $$f ; \
		done \
	) || true
	@test -e @MEDIADIR@/os8/os8.rk05 || echo "Installing media..." && $(MAKE) mediainstall

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

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

	@# Install the init script if this system is systemd based.
	@INSTALL@ -m 755 @srcdir@/etc/pidp8i-init @prefix@/etc
	@@INSTALL@ -m 755 @srcdir@/etc/pidp8i-init @prefix@/etc
	@(  test -w /etc/init.d -a -x /bin/systemctl && \
		ln -sf @ABSPREFIX@/etc/pidp8i-init /etc/init.d/pidp8i && \
		/bin/systemctl enable pidp8i \
	) || 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

	done) || true

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

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

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

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

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

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

mediainstall:
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@ {} @ABSPREFIX@/share/{} \;
	@INSTALL@ -m 644 -o @INSTUSR@ -g @INSTGRP@ bin/os8v3d-*.rk05 @ABSPREFIX@/share/media/os8
	@INSTALL@ -m 664 -o @INSTUSR@ -g @INSTGRP@ boot/*.script @BOOTDIR@
	@@INSTALL@ -m 644 -o @INSTUSR@ -g @INSTGRP@ bin/os8v3d-*.rk05 @ABSPREFIX@/share/media/os8
	@@INSTALL@ -m 664 -o @INSTUSR@ -g @INSTGRP@ boot/*.script @BOOTDIR@

# No-dependencies versions of the bin/os8v3d-*.rk05 targets used by
# tools/test-mkos8, because there's no point rebuilding the simulator
# on each iteration.
os8-bin:
	$(MKOS8)@MKOS8_OPTS@ bin
os8-patched:
	$(MKOS8)@MKOS8_OPTS@ bin patch

reconfig:
	@AUTOREMAKE@

release: all
	@srcdir@/tools/mkrel

run: $(OS8_BIN_RK05) install
	$(SIM) @srcdir@/boot/0.script
run: $(SIM)
	$(SIM) boot/run.script

simh-update simh-update-f:
	@@srcdir@/tools/simh-update $(subst simh-update,,$@)

test-mkos8:
	tools/test-mkos8


# Build the OS/8 binary media needed by 0.script
OS8_BIN_SRCS = \
# Build the OS/8 binary media needed by 0.script.
#
# We use order-only prerequisites for the simulator here because we only
# care that it *exists*, not whether it is newer than the previously
# built RK05 media or not.
#
# Also notice that the init.tx file is not a prerequisite: we purposely
# do not rebiuld the RK05 media just because the configure script was
# re-run, which *always* regenerates the init.tx file because the
# timestamp always changes from one run to the next.  (Until computers
# get fast enough to do a complete re-configure in under a second,
# anyway!)  The thing is, we only want the RK05 bin media rebuilt when
# the configure --*-os8-* options change.  *That* is when we care about
# 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.
OS8_BIN_SRCS := $(MKOS8_SRCS) \
	@srcdir@/tools/mkos8.in \
	@srcdir@/media/os8/al-*-ba-*.tu56 \
	@srcdir@/media/os8/subsys/*.tu56
ifneq (@MKOS8_BIN_PATCHES@,)
	OS8_BIN_SRCS += @srcdir@/media/os8/patches/patch_list.txt
endif
$(OS8_BIN_RK05): $(SIM) $(OS8_BIN_SRCS)
	tools/mkos8@MK_OS8_RK05_OPTS@ bin
$(OS8_BIN_RK05): $(OS8_BIN_SRCS) | $(SIM) $(MKOS8_OUTFILES)
	$(MKOS8)@MKOS8_OPTS@ bin @MKOS8_BIN_PATCHES@

# 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 = \
OS8_SRC_SRCS = $(MKOS8_SRCS) \
	@srcdir@/tools/mkos8.in \
	@srcdir@/media/os8/al-*-sa-*.tu56
$(OS8_SRC_RK05): $(OS8_SRC_SRCS)
	tools/mkos8@MK_OS8_RK05_OPTS@ src
$(OS8_SRC_RK05): $(OS8_SRC_SRCS) | $(SIM) $(OS8_BIN_RK05)
	$(MKOS8)@MKOS8_OPTS@ src

# Rule for compiling *.c to *.o and autogenerating dependency info.
# Explained at http://scottmcpeak.com/autodepend/autodepend.html
#
# Reflect any changes here into near-duplicate below!
obj/%.o: @srcdir@/src/%.c
	$(CC)  -c $(CFLAGS) @srcdir@/src/$*.c -o obj/$*.o
	$(CC) -MM $(CFLAGS) @srcdir@/src/$*.c > obj/$*.d
	@mv -f obj/$*.d obj/$*.d.tmp
	@sed -e 's|.*:|obj/$*.o:|' < obj/$*.d.tmp > obj/$*.d
	@sed -e 's/.*://' -e 's/\\$$//' < obj/$*.d.tmp | fmt -1 | \
		sed -e 's/^ *//' -e 's/$$/:/' >> obj/$*.d
	@rm -f obj/$*.d.tmp

# Near-duplicate of above rule for those *.c files generated from *.c.in
# files in the srcdir.  Needed when building out-of-tree.
obj/%.o: src/%.c
	$(CC)  -c $(CFLAGS) src/$*.c -o obj/$*.o
	$(CC) -MM $(CFLAGS) src/$*.c > obj/$*.d
	@mv -f obj/$*.d obj/$*.d.tmp
	@sed -e 's|.*:|obj/$*.o:|' < obj/$*.d.tmp > obj/$*.d
	@sed -e 's/.*://' -e 's/\\$$//' < obj/$*.d.tmp | fmt -1 | \
		sed -e 's/^ *//' -e 's/$$/:/' >> obj/$*.d
	@rm -f obj/$*.d.tmp

# Rule for building PAL assembly language programs in asm/*.pal.
obj/%.lst bin/%.pt: @srcdir@/asm/%.pal bin/palbart
# 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@/asm/$*.lst obj
	mv @srcdir@/asm/$*.rim bin/$*.pt
	mv @srcdir@/src/asm/$*.lst obj
	mv @srcdir@/src/asm/$*.rim bin/$*-pal.pt

# Ditto for those in examples/*.pal.
obj/%.lst bin/%.pt: @srcdir@/examples/%.pal bin/palbart
obj/%.lst bin/%-pal.pt: @srcdir@/examples/%.pal bin/palbart
	bin/palbart -lr $< || cat obj/$*.err
	mv @srcdir@/examples/$*.lst obj
	mv @srcdir@/examples/$*.rim bin/$*.pt
	mv @srcdir@/examples/$*.rim bin/$*-pal.pt

# Rule for converting ASCII FOCAL examples in examples/*.fc to
# bin/*-focal.pt.
bin/%-focal.pt: @srcdir@/examples/%.fc bin/txt2ptp
	bin/txt2ptp < $< > bin/$*-focal.pt

# Rule for translating PAL assembly language program listings to SIMH
# boot scripts.
boot/%.script: obj/%.lst
	@srcdir@/tools/mkbootscript $<

# Rules for making aliases of named example programs translated to boot
# scripts as special numbered boot scripts
boot/1.script: boot/hs-rim-loader.script
	ln -f $< $@
boot/5.script: boot/ac-mq-blinker.script
	ln -f $< $@

bin/palbart: @srcdir@/palbart/palbart.c
	$(CC) -Wall -Wno-strict-prototypes @BUILDMODE@ $< -o $@
	$(CC) -MM $< -o obj/palbart.d

$(BUILDDIRS):
	mkdir -p $@

$(SIM): $(OBJS) obj/gpio-@LED_DRIVER_MODULE@ls.o
$(SIM): $(SIM_OBJS) obj/gpio-@LED_DRIVER_MODULE@ls.o
	$(CC) -o $@ $^ $(LIBS)

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

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

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

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

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

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

bin/deeper: obj/deeper.o obj/gpio-@LED_DRIVER_MODULE@ls.o obj/gpio-common.o
	$(CC) -o $@ $^ $(LIBS)

libexec/scanswitch: obj/scanswitch.o obj/gpio-nls.o obj/gpio-common.o
	$(CC) -o $@ $^ $(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
# files in INFILES, whichever is lower.  Order-only prerequisites can't
# help here (|) as that only affects the right hand side.
ifeq ($(findstring clean,$(MAKECMDGOALS)),)
Makefile: @srcdir@/Makefile.in @srcdir@/auto.def $(INFILES) $(PRECIOUS_INFILES) @AUTODEPS@
media/os8/init.tx: $(INFILES) $(PRECIOUS_INFILES) @AUTODEPS@
	@AUTOREMAKE@ && $(MAKE)

# Rebuild simulator whenever one of its *.in files change.
#
# This is trickier than it appears.  If you simply make $(OUTFILES)
# Also do it if the autodep tool is newer than its output, suggesting
# depend on $(INFILES), make(1) thinks it can build all of $(OUTFILES)
# in parallel if given -jN, which causes ./configure --args to run N
# times in parallel, which blows the build system up right good and
# proper; bits everywhere.  We purposely list only the first file in
# $(INFILES) here to prevent that.  The other files in $(INFILES) will
# also be built, which confuses make(1) somewhat, but it figures things
# out on the subsequent $(MAKE) call.
#
# We also list files like tools/version which, when they change, trigger
# a rebuild of $(OUTFILES) because their change may affect what gets
# generated.  This happened when we moved from 8 to 10 character Fossil
# that if re-run, it would generate different output.
# artifact IDs in the version string to match Fossil timeline's default.
bin/pidp8i: @srcdir@/bin/pidp8i.in @srcdir@/tools/version
$(ADF): @srcdir@/tools/mkadrules
	@AUTOREMAKE@ && $(MAKE)
endif

# Rebuild simulator if the version string tool changes, since its output
# may have changed.
src/gpio-common.c: @srcdir@/tools/version

# Pull in *.d files generated by the autodependency mechanism.  See the
# header comment of tools/mkadrules.
-include $(OBJS:.o=.d) obj/scanswitch.d

-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

## Prerequisites

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

*   An SD card containing Raspbian or something sufficiently close.
    This software is currently tested with the Jessie Lite distribution.
*   An SD card containing [a compatible OS][os].

*   This software distribution, unpacked somewhere convenient within the
    filesystem on the Raspberry Pi.

    We recommend that you unpack it somewhere your user has read/write
    access like `$HOME/src/pidp8i`. Since it installs as a system
    service, you might prefer `/usr/local/src` or `/opt/src`, though
    you'll have to adjust permissions for that.
    Ideally, you will install a fresh OS image onto an unused SD card
    rather than use this software to modify an existing OS installation,
    but there is currently no known hard incompatibilty that prevents
    you from integrating this software into an existing OS.

    The [old stable 2015.12.15 release][osd] required that you unpack
    the software into `/opt/pidp8`, but we now neither require nor
    recommend that.

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

    *   A working C compiler and other standard Linux build tools,
        such as `make(1)`.

    *   Python's `pexpect` library
*   This software distribution, unpacked somewhere convenient within the
    Raspberry Pi filesystem.

    Unlike with the [upstream 2015.12.15 release][upst], this present
    release of the software should *not* be unpacked into `/opt/pidp8`.
    I recommend that you unpack it into `$HOME/src`, `/usr/local/src` or
    similar, but it really doesn't matter where you put it, as long as
    your user has full write access to that directory.

    *   The `usbmount` tool
    
        This is provides two things:
        
        *   USB stick auto-mounting on stripped-down OSes like Raspbian
            Lite so you can use the PiDP-8/I `SING_STEP` + `DF` feature
            without having to manually mount the USB stick first.
        
        *   A known directory structure that allows the PiDP-8/I
            software to find the media image files on those sticks.
            (`*.pt`, `*.dt`, `*.rk`, etc.)

        Full-blown GUI OSes tend to have USB auto-mounting set up
        already, though they won't meet the second criteria unless they
        use the same directory layout as `usbmount`: `/media/usbN`,
        where `N` is a number from 0 to 7, depending on the order
        you attached the USB stick.  Many Linuxes use `/media/LABEL`
        instead, for example, where `LABEL` is the partition's label;
        the PiDP-8/I software won't find the files on those USB sticks
        in that case.

    *   The `ncurses` development libraries
*   A working C compiler and other standard Linux build tools, such as
    `make(1)`.  On Debian type systems — including Raspbian — you can
    install such tools with `sudo apt install build-essential`

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

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

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


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

If you're reading this file within an unpacked distribution of the
PiDP-8/I software, you should skip this section, because you have
already achieved its aim.

If you are reading this [online][this] and have not yet downloaded and
unpacked the software source code onto your Pi, this section will get
you going.

[this]: https://tangentsoft.com/pidp8i/doc/trunk/README.md


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

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

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

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.

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

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

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

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

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


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

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

If you grabbed the tarball:

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

If you grabbed the Zip file instead:

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

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


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

If the above material is not sufficient to get you started, you might
want to look at [the documentation][rpfd] provided by the Raspberry
Pi Foundation.  In particular, we recommend their [Linux][rpfl] and
[Raspbian][rpfr] guides.  The book "[Make: Linux for Makers][lfm]"
by Aaron Newcomb is also supposed to be good.


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

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


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

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

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

The `configure` step is generally needed only the first time you build
the software in a new directory.  You may want to add options after it,
as described [below](#options).
If you've checked out a new version of the source code and the `make`
step fails, try redoing the `configure` step. Sometimes changes made to
the source code invalidate prior `make` dependencies, which are
implicitly repaired by the `configure` script.

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

    $ make reconfig

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

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


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

For the most part, this is covered in the documentation linked from the
[Learning More](/#learning) section of the project home page.

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


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

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


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

Perhaps the most widely useful `configure` script option is `--prefix`,
which lets you override the default installation directory,
`/opt/pidp8i`.  You could make it install the software under your home
directory on the Pi with this command:
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

Although this is installing to a directory your user has write access
to, you still need to install via `sudo` because the installation
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
process does other things that do require `root` access.
mark a few of the executables as having permission to run at high priority
levels, which improves the quality of the display, particularly with the
[incandescent lamp simulator][ils] feature enabled.


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

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

That bit of history means that when the PDP-8 was new, lowercase was a

    getting the software to work as you expect when built in this mode,
    try enabling CAPS LOCK.

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


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

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

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

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


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

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

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

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


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

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

See the linked mailing list thread for details.

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


#### --throttle

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


#### --disable-cc8-cross

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

Note that this is different from `--disable-os8-cc8`, which disables the
*native OS/8* C compiler. They are two different C compilers: one runs
outside the SIMH PDP-8 simulator and the other runs inside the simulator
under OS/8.


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

Several default components of the OS/8 RK05 disk image used by boot
options IF=0 and IF=7 can be left out to save space and build time:
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 game.
*   **--disable-os8-advent** — Leave out the [Adventure][advent] game.

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

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

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

*   **--disable-os8-cc8** - Leave out Ian Schofield's native OS/8 CC8
    compiler normally installed to `RKA0:`
    compiler normally installed to `SYS:`.  This option is implicitly
    given if you give `--disable-os8-fortran-ii` because the output of
    the OS/8 CC8 compiler is a SABR file, and SABR is part of the
    FORTRAN II subsystem.

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

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

*   **--disable-os8-init** - Generate `RKB0:INIT.TX` but do not display
    it on OS/8 boot.  Rather than disable the default on-boot init
    message, you may want to edit `media/os8/init.tx.in` to taste
    and rebuild.

    (We still build the file when you give this option in case you
    later decide you want to enable the boot message, or you need to
    call up configuration information stored in `INIT.TX`.)

*   **--disable-os8-k12** - 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-patches** - Do not apply any of the OS/8 V3D
    patches published by DEC.  See the [documentation][os8p] for this
    option for more information.

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

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

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


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

There are a few file sets not normally installed to the OS/8 RK05 disk
image used by boot options IF=0 and IF=7. You can install them with the
following options:
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` files and the player program for
    it are not normally installed to the built OS/8 binary RK05 disk
    image because the Raspberry Pi reportedly does not emit eufficient
    RFI at AM radio frequencies when running these programs to cause
    audible music on a typical AM radio, the very point of these demos.
    Until a way is found around this problem — what, low RFI is a
    *problem* now? — this option will default to "off".
*   **--enable-os8-music** — The `*.MU` music scores and Rich Wilson's
    associated compiler (`MUSIC.PA`) and player overlay (`PLAYOV.PA`)
    are not normally installed to the built OS/8 binary RK05 disk image
    because the Raspberry Pi reportedly does not emit eufficient RFI at
    AM radio frequencies when running these programs to cause audible
    music on a typical AM radio, the very point of these demos.  Until a
    way is found around this problem — what, low RFI is a *problem* now?
    — this option will default to "off".

*   **--enable-os8-vtedit** — This option installs a default-run macro
    pack called VTEDIT which causes the OS/8 version of TECO to run in
    full-screen mode and to react to [several special keyboard
    commands](/wiki?name=Using+VTEDIT) not normally recognized by TEDO.
    commands][uvte] not normally recognized by TECO.

    This feature is disabled by default because the VTEDIT macro pack
    changes the way TECO operates, and many people want TECO to behave
    like *TECO*. VTEDIT was first created during the PDP-8's commercial
    lifetime, so enabling this option is not an anachronism, but TECO is
    much older and had a much more wide-reaching impact in history, so
    we choose to provide unvarnished TECO by default.
    This feature is currently disabled because it is not yet fully
    tested by the person in charge of the OS/8 disk building process.

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

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

*   **--enable-os8-focal69** — Because the default installation includes
    U/W FOCAL, we have chosen to leave FOCAL 69 out by default to save
    space on the O/S 8 system disk. You can give this option to install
    this implementation alongside U/W FOCAL, or you can couple this
    option with `--disable-os8-uwfocal` to reverse our choice of which
    FOCAL implementation to install by default.
    It may remain disabled after that because it changes the behavior of
    the `TECO` command in OS/8, which violates the expectations of
    people expecting a historically accurate TECO experience. On the
    other hand, people don't go to a ren fair and expect to experience
    the historical ubiquity of typhoid fever either, so we might change
    our mind on this.

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

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

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

[suppd]: https://tangentsoft.com/pidp8i/doc/trunk/doc/uwfocal-manual-supp.md#diffs


#### --os8-minimal

If you set this flag, it sets all `--enable-os8-*` flags to false and
all `--disable-os8-*` flags to true. If you explicitly give any of these
flags to the `configure` script, this flag overrides them.

This flag only affects the optional installs made after the `BUILD`
step: it does not remove optional features of OS/8 itself, such as its
BASIC interpreter.

Giving this option therefore gets you an empty OS/8 `DSK:` device and
nothing in `SYS:` beyond what was left after the OS/8 `BUILD` step.

There are a few exceptions:

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

2.  This option does not affect `--disable-os8-src`, because it only
    suppresses optional features in the "bin" media.  If you want a
    minimal OS/8 bin disk and no src disk, give that option as well.


#### --help

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


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

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

In late 2017 [several of us][aut] created the `mkos8` tool, which takes
the `--*-os8-*` options documented above and generates the
`os8v3d-*.rk05` RK05 disk image files with your chosen configuration
options.

This set of disk images entirely replaces the old `os8.rk05` disk image,
in that all features of the old disk image are still available, though
not necessarily in the default configuration. In some cases, we have
disabled some features that were included in the stock `os8.rk05` disk
image, and in other cases we have changed the behavior of features.
Mostly, though, the new disk images are simply more functional than the
old ones.

If you wish to know the full details of how these disk images are
created, the best documentation so far is [the source code for the
`mkos8` script][mkos8] and the [documentation for `class simh`][cs].

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

[aut]: https://tangentsoft.com/pidp8i/doc/trunk/AUTHORS.md


### Baseline

The baseline for the bootable OS/8 disk 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
`mkos8` script creates the baseline `os8v3d-bin.rk05` disk image.

The default build creates a complete OS/8 system including `BUILD`
support, FORTRAN IV, MACREL v2, and more.


### Subtractions

It turns out that it's pretty easy to run out of directory space on an
OS/8 RK05 disk due to a limitation in the number of files on an OS/8
filesystem.  For this reason, the archive of device drivers and TD8E
system are left off the system packs.  They can be found in [OS/8
Binary Distribution DECtape #2][bdt2].

If you do fancy work with `BUILD`, you may need to attach that DECtape
image and copy files in from it.


### 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](#disable-os8): the "disable" option set effectively lists those
packages that `mkos8` installs by default, and the following set of
["enable" options](#enable-os8) lists those left out by default.


### Console Enhancements

The default build [enhances the console](/wiki?name=Console+TTY+Setup),
adding support for lower case terminals where:

1.  The SIMH PDP-8 simulator and a few select parts of OS/8 are adjusted
    to cope with lowercase input to [varying degrees](#lowercase).

2.  Rubout/backspace handling is set to assume a video terminal rather
    than a teletype by default.


### Patches

After the baseline disk image is created, `mkos8` makes a copy of it as
`os8v3d-patched.rk05` and applies a [carefully selected set of official
DEC patches][os8p] to it unless you give the `--disable-os8-patches`
configuration option.  The IF=0 and IF=7 boot options boot from the
patched disk unless you give that option.


[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
[mkos8]: https://tangentsoft.com/pidp8i/doc/trunk/libexec/mkos8
[os8mf]: https://tangentsoft.com/pidp8i/file/media/os8
[tlrm]:  https://tangentsoft.com/pidp8i/doc/trunk/README.md


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

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
    image files are considered "precious" because you may have modified
    the OS configuration or saved personal files to the disk the OS
    boots from, which in turn modifies this media image file out in the
    host operating environment.

    There is an important exception here: when upgrading from v20170404
    to v201712xx or newer, the old `os8.rk05` disk image will be left
    untouched per the above, but because `os8v3d-*.rk05` does not exist
    yet, those will be copied alongside `os8.rk05`. However, the next
    item still holds, so that the simulator will continue to use
    `os8.rk05` because it will be booted by the preexisting scripts.

2.  **The PDP-8 simulator configuration files**, installed as
    `$prefix/share/boot/*.script`, which may similarly have local
    changes, and thus be precious to you.

Sometimes this "protect the precious" behavior isn't what you want.
(Gollum!) One common reason this may be the case is that you've damaged
your local configuration and want to start over. Another common case is
that the newer software you're installing contains changes that you want
to reflect into your local configuration.

You have several options here:

1.  If you just want to reflect upstream PDP-8 simulator configuration
1.  If you just want to reflect the prior PDP-8 simulator configuration
    file changes into your local versions, you can hand-edit the
    installed simulator configuration scripts to match the changes in
    the newly-generated `boot/*.script` files under the build directory.

2.  If the upstream change is to the binary PDP-8 media image files and
    you're unwilling to overwrite them wholesale, you'll have to mount
    both versions of the media image files under the PDP-8 simulator and
    copy the changes over by hand.
2.  If the change is to the binary PDP-8 media image files — including
    the [generated OS/8 disk images](#os8di) — and you're unwilling to
    overwrite your existing ones wholesale, you'll have to mount both
    versions of the media image files under the PDP-8 simulator and copy
    the changes over by hand.

3.  If your previously installed binary OS media images — e.g. the OS/8
    RK05 disk image that the simulator boots from by default — are
    precious but the simulator configuration scripts 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`.)
3.  If your previously installed binary OS media images — e.g. the
    [OS/8 RK05 disk image](#os8di) that the simulator boots from by
    default — are precious but the simulator configuration scripts
    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!


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

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

    $ sudo systemctl stop pidp8i
    $ 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:

    $ sudo systemctl start pidp8i

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


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

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

The largest user-visible difference between the two software
distributions is that all of the shell commands affecting the software
were renamed to include `pidp8i` in their name:

1.  To start the simulator:

    what else you can do with the simulator command language, or read
    the [SIMH Users' Guide][sdoc].

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

        $ sudo systemctl stop pidp8i

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


## License

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


[prj]:  https://tangentsoft.com/pidp8i/
[cprj]: https://tangentsoft.com/pidp8i/
[upst]: http://obsolescence.wixsite.com/obsolescence/pidp-8
[sm1]:  http://obsolescence.wixsite.com/obsolescence/2016-pidp-8-building-instructions
[sm2]:  https://groups.google.com/d/msg/pidp-8/-leCRMKqI1Q/Dy5RiELIFAAJ
[usd]:  http://obsolescence.wixsite.com/obsolescence/pidp-8-details
[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
[prj]:  http://obsolescence.wixsite.com/obsolescence/pidp-8
[oprj]: http://obsolescence.wixsite.com/obsolescence/pidp-8
[test]: 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

# PiDP-8/I Software Release Process

This documents the process for producing release versions of the
software.


## Update ChangeLog.md

Trawl the Fossil timeline for user-visible changes since the last
release, and write them up in user-focused form into the `ChangeLog.md`
file.  If a regular user of the software cannot see a given change, it
shouldn't go in the `ChangeLog.md`; let it be documented via the
timeline only.


## Update the Release Branch

Run `make release` to check the `ChangeLog.md` file changes in, tagging
that checkin with a release version tag of the form vYYYYMMDD and merge
those changes into the `release` branch.

It runs entirely automatically unless an error occurs, in which case it
stops immediately, so check its output for errors before continuing.


## Update the Home Page Links

The zip and tarball links on the front page produce files named after
the date of the release. Those dates need to be updated immediately
after tagging the release, since they point at the "release" tag applied
by the previous step, so they begin shipping the new release immediately
after tagging it.


## Produce the Normal Binary OS Image

Start with the latest version of [Raspbian Lite][os] on a multi-core
Raspberry Pi.

1.  If the version of the base OS has changed since the last binary OS
    image was created, download the new one.

    While the OS is downloading, zero the SD card you're going to use
    for this, so the prior contents don't affect this process.
    
    Blast the base OS image onto the cleaned SD card.

2.  Boot it up on a multi-core Pi.

    Log in, then retreive and initialize BOSI:

        $ wget https://tangentsoft.com/bosi
        $ chmod +x bosi
        $ exec sudo ./bosi init

    The `exec` bit is required so that the `bosi` invocation is run as
    root without any processes running as `pi` in case the `init` step
    sees that user `pi` hasn't been changed to `pidp8i` here: the
    `usermod` command we give to make that change will refuse to do what
    we ask if there are any running processes owned by user `pi`.

    It will either reboot the system after completing its tasks
    successfully or exit early, giving the reason it failed.

3.  Clone the software repo and build the softare:

        $ ./bosi build

    On reboot, say `top -H` to make sure the software is running and
    that the CPU percentages are reasonable for the platform.

    You may also want to check that it is running properly with a
    `pidp8i` command.  Is the configuration line printed by the
    simulator correct?  Does OS/8 run?  Are there any complaints from
    SIMH, such as about insufficient CPU power?

4.  Do final inside-the-image steps:

        $ ./bosi prepare

5.  Move the SD card to a USB reader plugged into the Pi, boot the Pi
    from its prior SD card, and shrink the OS image:

        $ wget https://tangentsoft.com/bosi
        $ chmod +x bosi
        $ ./bosi shrink

6.  Move the USB reader to the Mac,¹ then say:

        $ bosi image [nls]

    For the ILS images, you can give "ils" as a parameter or leave it
    blank.

7.  The prior step rewrote the SD card with the image file it created.
    Boot it up and make sure it still works.  If you're happy with it,
    give this command *on the desktop PC*.

        $ bosi finish [nls]

    As above, the parameter can be "ils" or left off for the ILS images.

[os]: https://www.raspberrypi.org/downloads/raspbian/


## Produce the "No Lamp Simulator" Binary OS Image

Do the same series of steps above on a single-core Raspberry Pi, except
that you give "nls" parameters to the `image` and `finish` steps.


## Publicizing

While the NLS image uploads — the ILS image was already sent in step 7
in the first pass through the list above — compose the announcement
message, and modify the front page to point to the new images.  You
might also need to update the approximate image sizes reported on that
page.  Post the announcement message and new front page once that second
upload completes.


----------------------

### Footnotes

1.  The image production steps could just as well be done on a Linux box
    or on a Windows box via Cygwin or WSL, but the commands in that
    final stage change due to OS differences.  Since this document
    exists primarily for use by the one who uses it, there is little
    point in having alternatives for other desktop OSes above.  Should
    someone else take over maintainership, they can translate the above
    commands for their own desktop PC.


### License

Copyright © 2016-2017 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

/ asr33-rim-loader.pal
/
/ Load paper tapes in RIM format from a Teletype Model 33 ASR's paper
/ tape reader.  By contrast with the loader in hs-rim-loader.pal, this
/ is the low-speed paper tape RIM loader.
/
/ This is the RIM loader printed on the front panel of the PDP-8/I.  The
/ RIM loader in hs-rim-loader.pal (which is translated to boot/1.script
/ at build time) is similar to this one, but it works on the DEC high-
/ speed paper tape reader peripheral, which is where the PiDP-8/I's
/ automatic paper tape mounting feature attaches any tape images it
/ finds via USB.
/
/ Therefore, you cannot use this RIM loader if you want to use the
/ PiDP-8/I's automatic media attachment mechanism.  It is included
/ here mainly for documentation at the moment, but also in case
/ someone works out a way to build the simulator so that it can
/ conditionally load tapes from an emulated ASR-33.
/
/ Raw disassembly done from the octal values by Bernhard Baehr's PDP-8/E
/ Simulator.  Comments and labels by Warren Young.  Original copyright
/ by Digital Equipment Corporation: this program appeared in DEC manuals
/ and was printed on the front panel of every PDP-8/I.
/
/ SIMH: echo Installing the RIM loader for the ASR 33 paper tape reader...
/ SIMH: set df disabled

	*7755
	HLT		/ nonstandard: auto-halt on SIMH startup

	/ normal RIM loader entry point, 7756
NEXT,	KCC		/ clear PTR flag
RBYTE1,	KSF		/ loop until PTR is ready
	JMP RBYTE1
	KRB		/ read first byte in
	CLL RTL		/ shift it left by 2, clearing link as well
	RTL		/ and 2 more again
	SPA		/ if top bit of AC is set...
	JMP RBYTE1	/ ...AC contains the addr's value
	RTL		/ ...else rotate it another 2 positions
RBYTE2,	KSF		/ wait for next character
	JMP RBYTE2
	KRS		/ read second byte in
	SNL		/ if link is set...
	DCA I BYTE	/ ...it's the value's address
GOTVAL,	DCA BYTE	/ ...else it's the value at that addr
	JMP NEXT	/ go round again, getting next value from PTR
BYTE,	0
$

/ hs-rim-loader.pal
/
/ Load paper tapes in RIM format from the DEC high-speed PTR.
/
/ This routine differs from that printed in DEC's manuals in that it
/ starts with a HLT instruction so that when you [re]start SIMH with
/ IF=1, running this program, the processor auto-halts, giving the user
/ the opportunity to attach a paper tape via DF or ATTACH, then start
/ the processor at 7756 as normal.
/
/ The RIM loader code printed on the front panel of the PDP-8/I differs
/ because it is for the the paper tape reader built into a Teletype
/ Model 33 ASR.  See asr33-rim-loader.pal for that other implementation,
/ including more information about it.
/
/ Raw disassembly done from the octal values by Bernhard Baehr's PDP-8/E
/ Simulator.  Comments and labels by Warren Young.  Original copyright
/ by Digital Equipment Corporation: this program appeared in many DEC
/ manuals printed throughout the PDP-8 era variants of which were made
/ (and thus documented) from 1965 to 1979.
/
/ SIMH: echo Installing the RIM loader for the DEC high-speed tape reader...
/ SIMH: set df disabled
/ SIMH: set cpu noidle

	*7755
	HLT		/ nonstandard: auto-halt on SIMH startup

	/ normal RIM loader entry point, 7756
	RFC		/ clear PTR flag
RBYTE1,	RSF		/ loop until PTR is ready
	JMP RBYTE1
	RCC		/ read first byte in
	CLL RTL		/ shift it left by 2, clearing link as well
	RTL		/ and 2 more again
	SPA		/ if top bit of AC is set...
	JMP GOTVAL	/ ...AC contains the addr's value
	RTL		/ ...else rotate it another 2 positions
RBYTE2,	RSF		/ wait for next character
	JMP RBYTE2
	RCC		/ read second byte in
	SNL		/ if link is set...
	DCA I BYTE	/ ...it's the value's address
GOTVAL,	DCA BYTE	/ ...else it's the value at that addr
	JMP RBYTE1	/ go round again, getting next value from PTR
BYTE,	0
$

# authorization from those authors.
########################################################################

define defaultprefix /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]]
define ABSPREFIX $abspfx
define BOOTDIR  "$abspfx/share/boot"
define MEDIADIR "$abspfx/share/media"

# Define command line options
options {
    alt-serial-mod    => "use GPIO drive scheme suitable for James L-W's serial mod method"
    cc8-cross=1       => "do not build the cc8 cross-compiler on the host"
    debug-mode        => "create a debug build (default is release)"
    lowercase:        => "select how lowercase input is to be handled"
    no-lamp-simulator => "use simple LED driver instead of incandescent lamp simulator"
    os8-advent=1      => "add the game of ADVENT to built OS/8 RK05 image"
    os8-ba=1          => "leave *.BA BASIC games and demos off built OS/8 RK05 disk image"
    os8-cc8=1         => "leave the native OS/8 CC8 compiler off the built OS/8 RK05 disk image"
    os8-crt=1         => "set CRT-style rubout processing in built OS/8 KR05 image"
    os8-chess=1       => "add the game of CHESS to built OS/8 RK05 image"
    os8-k12=1         => "leave 12-bit Kermit off built OS/8 RK05 disk image"
    os8-music         => "add *.MU files to built OS/8 RK05 disk image"
    os8-advent=1      => "leave Adventure off the built OS/8 RK05 image"
    os8-ba=1          => "leave *.BA BASIC games and demos off the built OS/8 RK05 image"
    os8-cc8=1         => "leave the native OS/8 CC8 compiler off the built OS/8 RK05 image"
    os8-crt=1         => "suppress CRT-style rubout processing in the built OS/8 RK05 image"
    os8-chess=1       => "leave the CHECKMO-II game of chess off the built OS/8 RK05 image"
    os8-dcp=1         => "leave the DCP disassembler off the built OS/8 RK05 image"
    os8-focal=1       => "leave FOCAL 69 and U/W FOCAL off the built OS/8 RK05 image"
    os8-focal69       => "add FOCAL 69 to the built OS/8 RK05 image"
    os8-fortran-ii=1  => "leave FORTRAN II off the built OS/8 RK05 image"
    os8-fortran-iv=1  => "leave FORTRAN IV off the built OS/8 RK05 image"
    os8-init=1        => "do not show the OS/8 INIT message in the built OS/8 RK05 image"
    os8-k12=1         => "leave 12-bit Kermit off the built OS/8 RK05 image"
    os8-macrel=1      => "leave MACREL assembler off the built OS/8 RK05 image"
    os8-minimal       => "set all --disable-os8-* options, giving minimal OS/8 bin disk"
    os8-music         => "add *.MU files to the built OS/8 RK05 image"
    os8-patches=1     => "do not apply DEC patches to the built OS/8 RK05 bin image"
    os8-src=1         => "do not build os8v3d-src.rk05 from OS/8 source tapes"
    os8-uwfocal=1     => "leave U/W FOCAL (only) off the built OS/8 RK05 image"
    os8-vtedit        => "add the TECO VTEDIT setup to built OS/8 RK05 image"
    serial-mod        => "use GPIO drive scheme suitable for Oscar Vermeulen's serial mod method"
    throttle:         => "override the throttle values in the boot scripts"
}

# Handle meta-options first.
if {![opt-bool os8-focal]} {
    if {[opt-bool os8-focal69]} {
        dict set $::autosetup(optset) "os8-focal69" 0
    }
    if {[opt-bool os8-uwfocal]} {
        dict set $::autosetup(optset) "os8-uwfocal" 0
    }
}
set os8min [opt-bool os8-minimal]
set os8src [opt-bool os8-src]

# Translate the --*-os8-* options to mkos8 command line option format
# and build the Python option map it uses to interpret them.  This
# avoids the need to define the options by hand in both places.
set mkos8_opts ""
set os "# GENERATED BY auto.def; DO NOT MODIFY.\n\nopts = {\n"
foreach opt [lsort [dict keys $::autosetup(optdefault)]] {
    # Skip meta-options handled above and non --*-os8-* options.
    if {$opt in {os8-focal os8-minimal os8-src}} { continue }
    if {[string first "os8-" $opt] != 0} { continue }

    # Add next line to Python output
    set od [dict get $::autosetup(optdefault) $opt]
    set oh [dict get $::autosetup(opthelpline) $opt]
    set obn [string replace $opt 0 3]
    append os "\t\"" $obn "\": \[ $od, \"" $oh "\" \],\n"

    # Fix grammar for upcoming msg-result calls
    if {[string first "do not " $oh] == 0} {
        set oh [string replace $oh 0 6]
    } elseif {[string first "do " $oh] == 0} {
        set oh [string replace $oh 0 2]
    }

    # Choose option to pass to mkos8 corresponding to this configure
    # script option.  Also tell user what we're going to do; grammar
    # is inverted because the option help text says what happens when
    # you give the opposite of the option's default argument.
    set ov [opt-bool $opt]
    if {$ov == $od} {
        # Don't append a mkos8 option; the default is correct.
        msg-result "Will not $oh."
    } elseif {!$os8min && $ov} {
        append mkos8_opts " --enable-" $obn
    } else {
        append mkos8_opts " --disable-" $obn
    }
}
append os "}\n"
if {![file exists "lib/mkos8"]} { file mkdir "lib/mkos8" }
write-if-changed "lib/mkos8/opts.py" $os

# Handle the OS/8 options not passed to mkos8 generically by above.
if {$os8src} {
    msg-result "Building os8v3d-src.rk05 from OS/8 source tapes."
    define OS8_SRC_RK05 bin/os8v3d-src.rk05
} else {
    msg-result "Will not build os8v3d-src.rk05 from OS/8 source tapes."
    define OS8_SRC_RK05 {}
}
if {$os8min || ![opt-bool os8-patches]} {
    msg-result "Will not patch OS/8 on the RK05 bin disk."
    define OS8_BOOT_DISK "os8v3d-bin.rk05"
    define MKOS8_BIN_PATCHES {}
} else {
    msg-result "Will apply OS/8 V3D patches to the RK05 bin disk."
    define OS8_BOOT_DISK "os8v3d-patched.rk05"
    define MKOS8_BIN_PATCHES patch
}

# React to remaining chosen command line options
if {[opt-bool alt-serial-mod]} {
    msg-result "GPIO drive adjusted for James L-W's serial mods to the PiDP-8/I PCB."
    define PCB_SERIAL_MOD_JLW
    define PCB_SERIAL_MOD_ANY
}

if {[opt-bool serial-mod]} {
    msg-result "GPIO drive adjusted for O. Vermeulen's serial mods to the Pi & PiDP-8/I PCBs."
    define PCB_SERIAL_MOD_OV
    define PCB_SERIAL_MOD_ANY
}

if {[opt-bool cc8-cross]} {
    define CC8_CROSS bin/cc8
} else {
    define CC8_CROSS {}
    msg-result "Will not build the cc8 cross-compiler."
}

if {[opt-bool debug-mode]} {
    msg-result "Creating a debuggable build."
    define BUILDMODE {-O0 -g}
} else {
    msg-result "Creating a release build."
    define BUILDMODE {-O2}
}

set mk_os8_rk05s_options ""

set lv [opt-val lowercase]
if {$lv == ""} { set lv "auto" }
if {$lv == "auto"} {
    define SIMH_PASS_LOWERCASE
} elseif {$lv == "pass"} {
    define SIMH_PASS_LOWERCASE
    append mk_os8_rk05s_options " --without-lcmod"
    append mkos8_opts " --disable-lcmod"
} elseif {$lv == "upper"} {
    append mk_os8_rk05s_options " --without-lcmod"
    append mkos8_opts " --disable-lcmod"
} else {
    user-error "Legal values for --lowercase are {auto,pass,upper}."
}
msg-result "Lowercase handling set to '$lv' mode."

if {![opt-bool os8-advent]} {
    msg-result "Will not add game of ADVENT to the OS/8 RK05 disk image."
    append mk_os8_rk05s_options " --without-advent"
if {[opt-bool os8-cc8] && ![opt-bool os8-fortran-ii]} {
    msg-result "Must clear --disable-os8-fortran-ii when CC8 is enabled."
    regsub -- {--disable-os8-fortran-ii } $mkos8_opts {}
}
if {![opt-bool os8-ba]} {
    msg-result "Will not add BASIC games and demos to the OS/8 RK05 disk image."
    append mk_os8_rk05s_options " --without-ba"
}

if {![opt-bool os8-cc8]} {
    msg-result "Will not add CC8 to the OS/8 RK05 disk image."
    append mk_os8_rk05s_options " --without-cc8"
# We've purposely held off exporting the mkos8 option set until now
# because some of the configuration options can affect the option set.
}
if {![opt-bool os8-chess]} {
define MKOS8_OPTS $mkos8_opts
    msg-result "Will not add game of CHESS to the OS/8 RK05 disk image."
    append mk_os8_rk05s_options " --without-chess"
}

if {![opt-bool os8-crt]} {
    msg-result "Will not add BASIC games and demos to the OS/8 RK05 disk image."
# Force a rebuild of the OS/8 media if the option set changed.
    append mk_os8_rk05s_options " --without-crt"
}
if {![opt-bool os8-k12]} {
    msg-result "Will not add Kermit-12 to the OS/8 RK05 disk image."
if {![file exists "obj"]} { file mkdir "obj" }
write-if-changed "obj/mkos8.opts" $mkos8_opts {
    file delete -force bin/os8v3d-bin.rk05
    msg-result "mkos8 options changed; will rebuild OS/8 disk images."
    append mk_os8_rk05s_options " --without-k12"
}
if {[opt-bool os8-music]} {
    msg-result "Will add music files to the OS/8 RK05 disk image."
    append mk_os8_rk05s_options " --with-music"
} else {
    msg-result "Will not add music files to the OS/8 RK05 disk image."
}
if {[opt-bool os8-vtedit]} {
    msg-result "Will add VTEDIT setup to the OS/8 RK05 disk image."
    append mk_os8_rk05s_options " --with-vtedit"
}
define MK_OS8_RK05_OPTS $mk_os8_rk05s_options

# High-level definitions
set builddir [get-define builddir]
set srcdir [get-define srcdir]
set cores [exec $srcdir/tools/corecount]

# Translate --throttle value to a SIMH command

    user-error "No install(1) type program found; install GNU Coreutils."
}
msg-result "Found GNU install(1) program as [get-define INSTALL]."

# If we have cscope here, we'll use it in the "tags" target
define HAVE_PROG_CSCOPE [cc-check-progs cscope]

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

# Remember the name and primary group of the user who installed this, since
# we want to give that group write privileges to some files when they're
# installed, and we want them to own the screen(1) session.
set instgrp [exec id -grn]
set instusr [exec id -urn]
if {$instusr == "root"} {
    msg-result "Error: This software will not install and run as root."

# mask a real problem that needs to be diagnosed.
set tool "tools/version"
set cmd "$srcdir/$tool"
set status [catch {exec $cmd} version]
if {$status != 0} {
    # The most likely cause for tools/version to fail is that the repo
    # file has become disassociated from the local checkout directory.
    set sql "select value from vvar where name=\"repository\""
    set sql ".timeout 5000 ; select value from vvar where name=\"repository\""
    set cmd "fossil sql --no-repository $srcdir/.fslckout '$sql'"
    set status [catch {exec /bin/sh -c $cmd} path]
    if {$status != 0} {
        user-error "Fossil doesn't seem to work here.  Is it installed?\nCMD: $cmd"
    } elseif {[file exists $path]} {
        user-error "$tool failed to get checkout version from $path"
    } else {
        user-error "$tool failed: $path does not exist."
    }
}
define VERSION $version

# 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"]
# We need Python and pexpect installed here for mkos8 to run.

# The mkos8 script requires Python and some non-core modules.
set status [catch {exec python -c exit} result]
if {$status != 0} {
    user-error "Python does not appear to be installed here.  It is required."
}
msg-result "Python is installed here."
set status [catch {exec python -c "import pexpect" 2> /dev/null} result]
if {$status != 0} {
    set msg "The Python pexpect module is not installed here.  Fix with\n"
    append msg "\n    sudo pip install pexpect\n"
    append msg "\nOR:\n"
    append msg "\n    sudo easy_install pexpect\n"
    append msg "\nOR:\n"
    append msg "\n    sudo apt install python-pexpect\n"
    user-error $msg
}
msg-result "Python module pexpect is installed here."
set status [catch {exec python -c "import pkg_resources" 2> /dev/null} result]
if {$status != 0} {
    set msg "The Python pkg_resources module is not installed here.  Fix with\n"
    append msg "\n    sudo pip install pkg_resources\n"
    append msg "\nOR:\n"
    append msg "\n    sudo easy_install pkg_resources\n"
    append msg "\nOR:\n"
    append msg "\n    sudo apt install python-pkg-resources\n"
    user-error $msg
}
msg-result "Python module pkg_resources is installed here."

# Build Deeper Thought if we find it here
if {[file exists "[get-define srcdir]/src/deeper.c"]} {
    set ls [string toupper "[get-define LED_DRIVER_MODULE]ls"]
    msg-result "Found Deeper Thought; building it against $ls GPIO module"
    define BUILD_DEEPER_THOUGHT 1
}

# Generate autodependency Makefile rule sets.
#
# It is important to list "src" last, because GNU make takes the first
# one that matches, and the wildcards in the generated rules for "src"
# match all "src/*" subdirs.
set status [catch {
    exec $srcdir/tools/mkadrules $srcdir src/cc8/cross src/d8tape src/palbart src/PDP8 src
} result]
if {$status == 0} {
    msg-result $result
} else {
    user-error "Failed to generate autodependency rules: $result!"
}

# Write outputs.
#
# NOTE: If you change the list of files here, change INFILES in
# Makefile.in, too.
make-config-header src/config.h \
    -auto {ENABLE_* HAVE_* PACKAGE_* SIZEOF_*} \
    -bare {ILS_MODE PCB_*}
make-template Makefile.in
make-template bin/pidp8i.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 etc/pidp8i-init.in
make-template etc/sudoers.in
make-template examples/Makefile.in
make-template lib/pidp8i/__init__.py.in
make-template lib/pidp8i/dirs.py.in
make-template lib/pidp8i/ips.py.in
make-template media/os8/init.tx.in
make-template src/Makefile.in
make-template src/cc8/Makefile.in
make-template src/cc8/os8/Makefile.in
make-template src/gpio-common.c.in
make-template src/PDP8/Makefile.in
make-template src/PDP8/pidp8i.c.in
make-template tools/mkos8.in
make-template tools/simh-update.in
exec chmod +x "$builddir/tools/mkos8"
exec chmod +x "$builddir/tools/simh-update"

	set autosetup(argv) $argv
	set autosetup(cmdline) {}
	# options is a list of known options
	set autosetup(options) {}
	# optset is a dictionary of option values set by the user based on getopt
	set autosetup(optset) {}
	# optdefault is a dictionary of default values for options
	# optdefault is a dictionary of default values
	set autosetup(optdefault) {}
	# options-defaults is a dictionary of overrides for default values for options
	set autosetup(options-defaults) {}
	set autosetup(optionhelp) {}
	set autosetup(opthelpline) {}
	set autosetup(showhelp) 0

	# Parse options
	use getopt

	# 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:=local  => "display help and options. Optionally specify a 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"
		sysinstall:path  => "install standalone autosetup to the given directory (e.g.: /usr/local)"
		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 {
		options-add {
			sysinstall:path  => "install standalone autosetup to the given directory (e.g.: /usr/local)"
		}
	}
	options-add {
		force init:=help   => "create initial auto.def, etc.  Use --init=help for known types"
		# Undocumented options
		option-checking=1
		nopager
		quiet
		timing
		conf:
	}

	if {[opt-bool version]} {
		puts $autosetup(version)
		exit 0
	}

	# autosetup --conf=alternate-auto.def
	if {[opt-val conf] ne ""} {
		set autosetup(autodef) [lindex [opt-val conf] end]
	if {[opt-str conf o]} {
		set autosetup(autodef) $o
	}

	# Debugging output (set this early)
	incr autosetup(debug) [opt-bool debug]
	incr autosetup(force) [opt-bool force]
	incr autosetup(msg-quiet) [opt-bool quiet]
	incr autosetup(msg-timing) [opt-bool timing]

	# If the local module exists, source it now to allow for
	# project-local customisations
	if {[file exists $autosetup(libdir)/local.tcl]} {
		use local
	}

	# Now any auto-load modules
	autosetup_load_auto_modules

	if {[opt-val help] ne ""} {
	if {[opt-str help o]} {
		incr autosetup(showhelp)
		use help
		autosetup_help [lindex [opt-val help] end]
		autosetup_help $o
	}

	if {[opt-bool licence license]} {
		use help
		autosetup_show_license
		exit 0
	}

	if {[opt-val {manual ref reference}] ne ""} {
	if {[opt-str {manual ref reference} o]} {
		use help
		autosetup_reference [lindex [opt-val {manual ref reference}] end]
		autosetup_reference $o
	}

	# Allow combining --install and --init
	set earlyexit 0
	if {[opt-val install] ne ""} {
	if {[opt-str install o]} {
		use install
		autosetup_install [lindex [opt-val install] end]
		autosetup_install $o
		incr earlyexit
	}

	if {[opt-val init] ne ""} {
	if {[opt-str init o]} {
		use init
		autosetup_init [lindex [opt-val init] end]
		autosetup_init $o
		incr earlyexit
	}

	if {$earlyexit} {
		exit 0
	}
	if {[opt-val sysinstall] ne ""} {
	if {[opt-str sysinstall o]} {
		use install
		autosetup_install [lindex [opt-val sysinstall] end] 1
		autosetup_install $o 1
		exit 0
	}

	if {![file exists $autosetup(autodef)]} {
		# Check for invalid option first
		options {}
		user-error "No auto.def found in \"$autosetup(srcdir)\" (use [file tail $::autosetup(exe)] --init to create one)"

}

# @opt-val optionlist ?default=""?
#
# Returns a list containing all the values given for the non-boolean options in '$optionlist'.
# There will be one entry in the list for each option given by the user, including if the
# same option was used multiple times.
# If only a single value is required, use something like:
#
## lindex [opt-val $names] end
#
# If no options were set, '$default' is returned (exactly, not as a list).
#
# Note: For most use cases, 'opt-str' should be preferred.
#
proc opt-val {names {default ""}} {
	option-check-names {*}$names

	foreach opt $names {
		if {[dict exists $::autosetup(optset) $opt]} {
			lappend result {*}[dict get $::autosetup(optset) $opt]
		}
	}
	if {[info exists result]} {
		return $result
	}
	return $default
}

# @opt-str optionlist varname ?default?
#
# Sets '$varname' in the callers scope to the value for one of the given options.
#
# For the list of options given in '$optionlist', if any value is set for any option,
# the option value is taken to be the *last* value of the last option (in the order given).
#
# If no option was given, and a default was specified with 'options-defaults',
# that value is used.
#
# If no 'options-defaults' value was given and '$default' was given, it is used.
#
# If none of the above provided a value, no value is set.
#
# The return value depends on whether '$default' was specified.
# If it was, the option value is returned.
# If it was not, 1 is returns if a value was set, or 0 if not.
#
# Typical usage is as follows:
#
## if {[opt-str {myopt altname} o]} {
##     do something with $o
## }
#
# Or:
## define myname [opt-str {myopt altname} o "/usr/local"]
#
proc opt-str {names varname args} {
	global autosetup

	option-check-names {*}$names
	upvar $varname value

	if {[llength $args]} {
		# A default was given, so always return the string value of the option
		set default [lindex $args 0]
		set retopt 1
	} else {
		# No default, so return 0 or 1 to indicate if a value was found
		set retopt 0
	}

	foreach opt $names {
		if {[dict exists $::autosetup(optset) $opt]} {
			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(options-defaults) $opt]} {
				set result [dict get $autosetup(options-defaults) $opt]
			}
		}
	}

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

	if {$retopt} {
		set value $default
		return $value
	}

	return 0
}

proc option-check-names {args} {
	foreach o $args {
		if {$o ni $::autosetup(options)} {
			autosetup-error "Request for undeclared option --$o"
		}
	}

		set opt [lindex $opts $i]
		if {[string match =* $opt]} {
			# This is a special heading
			lappend autosetup(optionhelp) $opt ""
			set header {}
			continue
		}
		unset -nocomplain defaultvalue equal value

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

		#puts "$opt => $name $colon $equal $value"

		# Find the corresponding value in the user options
		# and set the default if necessary
		if {[string match "-*" $opt]} {
			# This is a documentation-only option, like "-C <dir>"
			set opthelp $opt
		} elseif {$colon eq ""} {
			# Boolean option
			lappend autosetup(options) $name

			# Check for override
			if {[dict exists $autosetup(options-defaults) $name]} {
				# A default was specified with options-defaults, so use it
				set value [dict get $autosetup(options-defaults) $name]
			}

			if {$value eq "1"} {
				set opthelp "--disable-$name"
			} else {
				set opthelp "--$name"
			}

			# Set the default
			if {$value eq ""} {
				set value 0
			}
			set defaultvalue $value
			dict set autosetup(optdefault) $name $value
			dict set autosetup(optdefault) $name $defaultvalue

			if {[dict exists $autosetup(getopt) $name]} {
				# The option was specified by the user. Look at the last value.
				lassign [lindex [dict get $autosetup(getopt) $name] end] type setvalue
				if {$type eq "str"} {
					# Can we convert the value to a boolean?
					if {$setvalue in {1 enabled yes}} {
						set setvalue 1
					} elseif {$setvalue in {0 disabled no}} {
						set setvalue 0
					} else {
						user-error "Boolean option $name given as --$name=$setvalue"
					}
				}
				dict set autosetup(optset) $name $setvalue
				#puts "Found boolean option --$name=$setvalue"
			}
		} else {
			# String option.
			lappend autosetup(options) $name

			if {$colon eq ":"} {
				# Was ":name=default" given?
				# 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]} {
				# For backward compatiblity, if ":name" was given, use name as both
				# the display text and the default value, but only if the user
				# specified the option without the value
				set defaultvalue $value
			}

			if {$equal eq "="} {
				# String option with optional value
				set opthelp "--$name?=$value?"
			} else {
				# String option with required value
				set opthelp "--$name=$value"
			}
			dict set autosetup(optdefault) $name $value

			# Get the values specified by the user
			if {[dict exists $autosetup(getopt) $name]} {
				set listvalue {}

				foreach pair [dict get $autosetup(getopt) $name] {
					lassign $pair type setvalue
					if {$type eq "bool" && $setvalue} {
						if {$equal ne "="} {
							user-error "Option --$name requires a value"
						}
						# If given as a boolean, use the default value
						set setvalue $value
						set setvalue $defaultvalue
					}
					lappend listvalue $setvalue
				}

				#puts "Found string option --$name=$listvalue"
				dict set autosetup(optset) $name $listvalue
			}
		}

		# 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]
			}
			#string match \n* $desc
			if {$header ne ""} {
				lappend autosetup(optionhelp) $header ""
				set header ""
			}
			# A multi-line description
			lappend autosetup(optionhelp) $opthelp $desc
			dict set autosetup(opthelpline) $name $desc
			incr i 2
		}
	}
}

# @module-options optionlist
#

		}
	}
}

# @options optionspec
#
# Specifies configuration-time options which may be selected by the user
# and checked with 'opt-val' and 'opt-bool'. '$optionspec' contains a series
# and checked with 'opt-str' and 'opt-bool'. '$optionspec' contains a series
# of options specifications separated by newlines, as follows:
#
# A boolean option is of the form:
#
## 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 the form:
#
## name:[=]value  => "Description of this option"
#
# If the 'name:value' form is used, the value must be provided with the option (as '--name=myvalue').
# If the 'name:=value' form is used, the value is optional and the given value is used as the default
# 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"

		foreach o [dict keys $::autosetup(getopt)] {
			if {$o ni $::autosetup(options)} {
				user-error "Unknown option --$o"
			}
		}
	}
}

# @options-defaults dictionary
#
# Specifies a dictionary of options and a new default value for each of those options.
# Use before any 'use' statements in 'auto.def' to change the defaults for
# subsequently included modules.
proc options-defaults {dict} {
	foreach {n v} $dict {
		dict set ::autosetup(options-defaults) $n $v
	}
}

proc config_guess {} {
	if {[file-isexec $::autosetup(dir)/autosetup-config.guess]} {
		if {[catch {exec-with-stderr sh $::autosetup(dir)/autosetup-config.guess} alias]} {
			user-error $alias
		}
		return $alias

# If the variable is not defined or empty, it is set to '$value'.
# Otherwise the value is appended, separated by a space.
# Any extra values are similarly appended.
# If any value is already contained in the variable (as a substring) it is omitted.
#
proc define-append {name args} {
	if {[get-define $name ""] ne ""} {
		# Make a token attempt to avoid duplicates
		# Avoid duplicates
		foreach arg $args {
			set found 0
			if {[string first $arg $::define($name)] == -1} {
			foreach str [split $::define($name) " "] {
				if {$str eq $arg} {
					incr found
				}
			}
			if {!$found} {
				append ::define($name) " " $arg
			}
		}
	} else {
		set ::define($name) [join $args]
	}
	#dputs "$name += [join $args] => $::define($name)"

# Module which can install autosetup

# autosetup(installed)=1 means that autosetup is not running from source
# autosetup(sysinstall)=1 means that autosetup is running from a sysinstall verion
# shared=1 means that we are trying to do a sysinstall. This is only possible from the development source.

proc autosetup_install {dir {shared 0}} {
	global autosetup
	if {$shared && $::autosetup(installed)} {
		user-error "Can only --sysinstall from development sources"
	}

	if {$::autosetup(sysinstall)} {
	if {$shared} {
		if {$autosetup(installed) || $autosetup(sysinstall)} {
			user-error "Can only --sysinstall from development sources"
		}
	} elseif {$autosetup(installed) && !$autosetup(sysinstall)} {
		user-error "Can't --install from project install"
	}

	if {$autosetup(sysinstall)} {
		# This is the sysinstall version, so install just uses references
		cd $dir

		puts "[autosetup_version] creating configure to use system-installed autosetup"
		autosetup_create_configure 1
		puts "Creating autosetup/README.autosetup"
		file mkdir autosetup

		file mkdir $targetdir

		set f [open $target w]

		set publicmodules {}

		# First the main script, but only up until "CUT HERE"
		set in [open $::autosetup(dir)/autosetup]
		set in [open $autosetup(dir)/autosetup]
		while {[gets $in buf] >= 0} {
			if {$buf ne "##-- CUT HERE --##"} {
				puts $f $buf
				continue
			}

			# Insert the static modules here
			# i.e. those which don't contain @synopsis:
			# All modules are inserted if $shared is set
			puts $f "set autosetup(installed) 1"
			puts $f "set autosetup(sysinstall) $shared"
			foreach file [lsort [glob $::autosetup(libdir)/*.{tcl,auto}]] {
			foreach file [lsort [glob $autosetup(libdir)/*.{tcl,auto}]] {
				set modname [file tail $file]
				set ext [file ext $modname]
				set buf [readfile $file]
				if {!$shared} {
					if {$ext eq ".auto" || [string match "*\n# @synopsis:*" $buf]} {
						lappend publicmodules $file
						continue
					}
				}
				dputs "install: importing lib/[file tail $file]"
				puts $f "# ----- @module $modname -----"
				puts $f "\nset modsource($modname) \{"
				puts $f $buf
				puts $f "\}\n"
			}
			if {$shared} {
				foreach {srcname destname} [list $::autosetup(libdir)/README.autosetup-lib README.autosetup \
						$::autosetup(srcdir)/LICENSE LICENSE] {
				foreach {srcname destname} [list $autosetup(libdir)/README.autosetup-lib README.autosetup \
						$autosetup(srcdir)/LICENSE LICENSE] {
					dputs "install: importing $srcname as $destname"
					puts $f "\nset modsource($destname) \\\n[list [readfile $srcname]\n]\n"
				}
			}
		}
		close $in
		close $f
		exec chmod 755 $target
		catch {exec chmod 755 $target}

		set installfiles {autosetup-config.guess autosetup-config.sub autosetup-test-tclsh}
		set removefiles {}

		if {!$shared} {
			autosetup_install_readme $targetdir/README.autosetup 0

		foreach fileinfo $installfiles {
			if {[llength $fileinfo] == 2} {
				lassign $fileinfo source dest
			} else {
				lassign $fileinfo source
				set dest $source
			}
			autosetup_install_file $::autosetup(dir)/$source $targetdir/$dest
			autosetup_install_file $autosetup(dir)/$source $targetdir/$dest
			exec chmod 755 $targetdir/$dest
		}

		# Remove obsolete files
		foreach file $removefiles {
			if {[file exists $targetdir/$file]} {
				file delete $targetdir/$file
			}

proc autosetup_install_file {source target} {
	dputs "install: $source => $target"
	if {![file exists $source]} {
		error "Missing installation file '$source'"
	}
	writefile $target [readfile $source]\n
	# If possible, copy the file mode
	file stat $source stat
	set mode [format %o [expr {$stat(mode) & 0x1ff}]]
	catch {exec chmod $mode $target}
}

proc autosetup_install_readme {target sysinstall} {
	set readme "README.autosetup created by [autosetup_version]\n\n"
	if {$sysinstall} {
		append readme \
{This is the autosetup directory for a system install of autosetup.

## CC_FOR_BUILD
## LD

use system

module-options {}

# Note that the return code is not meaningful
proc cc-check-something {name code} {
	uplevel 1 $code
}

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

# Checks for the existence of the given type by compiling

	cc-check-some-feature $args {
		cctest_type $each
	}
}

# @cc-check-defines define ...
#
# Checks that the given preprocessor symbol is defined.
# Checks that the given preprocessor symbols are defined.
proc cc-check-defines {args} {
	cc-check-some-feature $args {
		cctest_define $each
	}
}

# @cc-check-decls name ...

						incr found
						break
					}
				}
			}
		}
	}
	define-feature $function $found
	if {$found} {
	if {!$found} {
		define [feature-define-name $function]
	} else {
		msg-result "no"
	}
	return $found
}

# @cc-check-tools tool ...
#

		}
	} else {
		msg-result $version
		define PKG_CONFIG_VERSION $version

		set found 1

		if {[opt-val sysroot] ne ""} {
			define SYSROOT [file-normalize [lindex [opt-val sysroot] end]]
		if {[opt-str sysroot o]} {
			define SYSROOT [file-normalize $o]
			msg-result "Using specified sysroot [get-define SYSROOT]"
		} elseif {[get-define build] ne [get-define host]} {
			if {[catch {exec-with-stderr [get-define CC] -print-sysroot} result errinfo] == 0} {
				# Use the compiler sysroot, if there is one
				define SYSROOT $result
				msg-result "Found compiler sysroot $result"
			} else {

## infodir
## mandir
## includedir
#
# If '--prefix' is not supplied, it defaults to '/usr/local' unless 'defaultprefix' is defined *before*
# including the 'system' module.

if {[is-defined defaultprefix]} {
	user-notice "Note: defaultprefix is deprecated. Use options-defaults to set default options"
set defaultprefix [get-define defaultprefix /usr/local]
	options-defaults [list prefix [get-define defaultprefix]]
}

module-options [subst -noc -nob {
	host:host-alias =>		{a complete or partial cpu-vendor-opsys for the system where
							the application will run (defaults to the same value as --build)}
	build:build-alias =>	{a complete or partial cpu-vendor-opsys for the system
							where the application will be built (defaults to the
							result of running config.guess)}
	prefix:dir =>			{the target directory for the build (defaults to '$defaultprefix')}
	prefix:dir=/usr/local => {the target directory for the build (default: '@default@')}

	# These (hidden) options are supported for autoconf/automake compatibility
	exec-prefix:
	bindir:
	sbindir:
	includedir:
	mandir:
	infodir:
	libexecdir:
	datadir:
	libdir:
	sysconfdir:
	sharedstatedir:
	localstatedir:
	maintainer-mode=0
	dependency-tracking=0
	silent-rules=0
}]

# @check-feature name { script }
#
# defines feature '$name' to the return value of '$script',
# which should be 1 if found or 0 if not found.
#

		writefile $file $buf\n
		uplevel 1 $script
	}
}

# @make-template template ?outfile?
#
# Reads the input file '<srcdir>/$template' and writes the output file '$outfile'.
# Reads the input file '<srcdir>/$template' and writes the output file '$outfile'
# (unless unchanged).
# If '$outfile' is blank/omitted, '$template' should end with '.in' which
# is removed to create the output file name.
#
# Each pattern of the form '@define@' is replaced with the corresponding
# "define", if it exists, or left unchanged if not.
# 
# The special value '@srcdir@' is substituted with the relative

					set cond [expr {!$cond}]
				}
			}
			continue
		}
		lappend result $line
	}
	writefile $out [string map $mapping [join $result \n]]\n
	write-if-changed $out [string map $mapping [join $result \n]] {

	msg-result "Created [relative-path $out] from [relative-path $template]"
		msg-result "Created [relative-path $out] from [relative-path $template]"
	}
}

# build/host tuples and cross-compilation prefix
set build [lindex [opt-val build] end]
opt-str build build ""
define build_alias $build
if {$build eq ""} {
	define build [config_guess]
} else {
	define build [config_sub $build]
}

set host [lindex [opt-val host] end]
opt-str host host ""
define host_alias $host
if {$host eq ""} {
	define host [get-define build]
	set cross ""
} else {
	define host [config_sub $host]
	set cross $host-

		user-error "Invalid canonical $type: $v"
	}
	define ${type}_cpu $cpu
	define ${type}_vendor $vendor
	define ${type}_os $os
}

set prefix [lindex [opt-val prefix $defaultprefix] end]
opt-str prefix prefix /usr/local

# These are for compatibility with autoconf
define target [get-define host]
define prefix $prefix
define builddir $autosetup(builddir)
define srcdir $autosetup(srcdir)
define top_srcdir $autosetup(srcdir)
define abs_top_srcdir [file-normalize $autosetup(srcdir)]
define abs_top_builddir [file-normalize $autosetup(builddir)]

# autoconf supports all of these
set exec_prefix [lindex [opt-val exec-prefix $prefix] end]
define exec_prefix $exec_prefix
define exec_prefix [opt-str exec-prefix exec_prefix $prefix]
foreach {name defpath} {
	bindir /bin
	sbindir /sbin
	libexecdir /libexec
	libdir /lib
} {
	define $name [lindex [opt-val $name $exec_prefix$defpath] end]
	define $name [opt-str $name o $exec_prefix$defpath]
}
foreach {name defpath} {
	datadir /share
	sysconfdir /etc
	sharedstatedir /com
	localstatedir /var
	infodir /share/info
	mandir /share/man
	includedir /include
} {
	define $name [lindex [opt-val $name $prefix$defpath] end]
	define $name [opt-str $name o $prefix$defpath]
}
if {$prefix ne {/usr}} {
	opt-str sysconfdir sysconfdir $prefix/etc
} else {
	opt-str sysconfdir sysconfdir /etc

}
define sysconfdir $sysconfdir

define localstatedir [opt-str localstatedir o /var]

define SHELL [get-env SHELL [find-an-executable sh bash ksh]]

# These could be used to generate Makefiles following some automake conventions
define AM_SILENT_RULES [opt-bool silent-rules]
define AM_MAINTAINER_MODE [opt-bool maintainer-mode]
define AM_DEPENDENCY_TRACKING [opt-bool dependency-tracking]

# Windows vs. non-Windows
switch -glob -- [get-define host] {
	*-*-ming* - *-*-cygwin - *-*-msys {
		define-feature windows
		define EXEEXT .exe
	}

}

cc-check-tools ar ranlib

set objdir [get-env BUILDDIR objdir]

make-config-header $objdir/include/autoconf.h
make-tmake-settings $objdir/settings.conf {[A-Z]*}
make-tmake-settings $objdir/settings.conf {[A-Z]*} *dir lib_*
}

	autosetup_check_create project.spec \
{# Initial project.spec created by 'autosetup --init=tmake'

tmake-require-version 0.7.3

# vim:set syntax=tcl:
define? DESTDIR _install

# XXX If configure creates additional/different files than include/autoconf.h
#     that should be reflected here

# We use [set AUTOREMAKE] here to avoid rebuilding settings.conf
# if the AUTOREMAKE command changes
Depends {settings.conf include/autoconf.h} auto.def -msg {note Configuring...} -do {
	run [set AUTOREMAKE] >$build/config.out
} -onerror {puts [readfile $build/config.out]} -fatal
Clean config.out
DistClean --source config.log
DistClean settings.conf include/autoconf.h
Autosetup include/autoconf.h

# If not configured, configure with default options
# Note that it is expected that configure will normally be run
# separately. This is just a convenience for a host build
define? AUTOREMAKE configure TOPBUILDDIR=$TOPBUILDDIR --conf=auto.def

Load settings.conf

# e.g. for up autoconf.h
# e.g. for autoconf.h
IncludePaths include

ifconfig !CONFIGURED {
	# Not configured, so don't process subdirs
	AutoSubDirs off
	# And don't process this file any further
ifconfig CONFIGURED

	ifconfig false
}
# Hmmm, but should we turn off AutoSubDirs?
#AutoSubDirs off
}

	if {![file exists build.spec]} {
		puts "Note: I don't see build.spec. Try running: tmake --genie"
	}
}

*.pt
*.rk05

.agignore

#!/usr/bin/env perl
########################################################################
# cc8-to-os8 - Filter C code meant for the CC8 cross-compiler so that it
#   will work with the OS/8 version of CC8.
#
#   This is not meant to fix up 100% of the differences in the C
#   compilers, just the ones which prevent src/cc8/examples/*.c
#   from building under OS/8 CC8 as-is.
#
#   You can run it like a filter: 
#
#       $ cc8-to-os8 < foo.c | txt2ptp > foo.pt
#
#   Or you can just give it one or more file name(s), with output going
#   to stdout, which gives this way to hack around the lack of #include:
#
#       $ cc8-to-os8 myheader.h foo.c > OS8FOO.C
#
# Copyright © 2017 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
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS LISTED ABOVE BE LIABLE FOR ANY CLAIM,
# DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
# OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
# OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# Except as contained in this notice, the names of the authors above
# 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.
########################################################################

use strict;
use warnings;

my $nblines = 0;        # number of non-blank lines written out

while (<>) {
    if (m{^[a-zA-Z_][a-zA-Z0-9_]*\s*\(}) {
        # Looks like a function definition without a type; assume int.
        print "int $_";
        ++$nblines;
    }
    elsif (!m{^\#include } and length and $nblines) {
        # Pass it through unchanged.
        print;
    }
    else {
        # Unlike the CC8 cross-compiler, the OS/8 version of CC8 doesn't
        # process #includes, or in fact any C preprocessor directives,
        # not even #asm.  Strip just the #includes in the hope that it's
        # init.h or libc.h, the contents of which are hard-coded into
        # the OS/8 CC8 compiler.
    }
}

#!/usr/bin/python
# -*- coding: utf-8 -*-
########################################################################
# teco-pi-demo - Starts the simulator with the OS/8, sends one of the
#   famous TECO "calculate pi" program to it, and starts it running at
#   a very slow rate of speed to act as a blinkenlights demo.
#
# Copyright © 2017 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
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS LISTED ABOVE BE LIABLE FOR ANY CLAIM,
# DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
# OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
# OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# Except as contained in this notice, the names of the authors above
# 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.
########################################################################

# Bring in just the basics so we can bring in our local modules
import os
import sys
sys.path.insert (0, os.path.dirname (__file__) + '/../lib')
sys.path.insert (0, os.getcwd () + '/lib')

# Other core modules we need
from datetime import datetime
import time

# Our local modules
from pidp8i import *
from simh   import *


#### main ##############################################################

def main ():
  # Check for command line flags
  benchmark = len (sys.argv) > 1 and sys.argv[1] == '-b'

  # Create the SIMH child instance and tell it where to send log output
  try:
    s = simh (dirs.build)
  except (RuntimeError) as e:
    print "Could not start simulator: " + e.message + '!'
    exit (1)
  s.set_logfile (os.fdopen (sys.stdout.fileno (), 'w', 0))

  # Find and boot the built OS/8 bin disk
  rk = os.path.join (dirs.os8mo, 'os8v3d-bin.rk05')
  if not os.path.isfile (rk):
    print "Could not find " + rk + "; OS/8 media not yet built?"
    exit (1)
  print "Booting " + rk + "..."
  s.send_cmd ("att rk0 " + rk)
  s.send_cmd ("boot rk0")

  # Start TECO8 in the simulator under OS/8
  s.os8_send_cmd ('\\.', "R TECO")

  # The macro comes from http://www.iwriteiam.nl/HaPi_TECO_macro.html
  #
  # The 248 preceding "UN" in the first line of the macro is the number
  # of digits of pi to calculate.  That value was reached by experiment
  # as the largest value that runs without crashing TECO with a
  #
  #    ?MEM  STORAGE CAPACITY EXCEEDED
  #
  # error.  You can see that by increasing the value below, commenting
  # out the throttle setting below, and running the demo.  On a Pi 3, it
  # should take a bit over an hour to complete, if it doesn't error out.
  #
  # With the simulator throttled, generating 248 digits takes 17 years!
  #
  # That is based on generating 1 digit every ~16 seconds on a Pi 3 when
  # running unthrottled, roughly 8 MIPS.  When throttled to 59 IPS — or
  # 17ms per instruction, as below — you multiply the seconds by the
  # factor 8 MIPS / 59 IPS = ~136000, giving about 2.2 million seconds
  # per digit.  Multiplying that by 248 gives ~17 years.
  macro = [
    'GZ0J\UNQN"E 248UN \' BUH BUV HK',
    'QN< J BUQ QN*10/3UI',
    'QI< \+2*10+(QQ*QI)UA B L K QI*2-1UJ QA/QJUQ',
    'QA-(QQ*QJ)-2\ 10@I// -1%I >',
    'QQ/10UT QH+QT+48UW QW-58"E 48UW %V \' QV"N QV^T \' QWUV QQ-(QT*10)UH >',
    'QV^T @^A/',
    '/HKEX',
  ]

  # First and last lines are handled specially, so slice them off.
  first = macro.pop (0)
  last  = macro.pop ()

  # Send the first line of the macro; implicitly awaits 1st TECO prompt
  s.os8_send_cmd ('\*', first)

  # Blindly send core lines of the macro; TECO gives no prompts for 'em.
  for line in macro: 
    s.os8_send_line (line)

  # Send last line of macro sans CR, followed by two Esc characters to
  # start it running.
  s.os8_send_str (last)     # not os8_send_line!
  s.os8_send_ctrl ('[')
  s.os8_send_ctrl ('[')

  if benchmark:
    # Run demo long enough to get a good sense of the simulator's
    # execution rate while unthrottled on this host hardware.  If
    # you don't run it long enough, the IPS value is untrustworthy.
    try:
      s.spin (10)
    except pexpect.TIMEOUT:
      # Find out how many IPS was executing
      s.os8_send_ctrl ('e')
      s.send_cmd ('show clocks')
      line = s.read_tail ('Execution Rate:')
      curr_ips = int (line.strip().replace(',', '').split(' ')[0])
      pf = open ('lib/pidp8i/ips.py', 'a')
      pf.write ('current = ' + str (curr_ips) + '    # ' + \
            str (datetime.today ()) + '\n')
      pf.close ()
      s.send_cmd ('quit')
      pdp_ratio = float (curr_ips) / ips.pdp8i
      rpi_ratio = float (curr_ips) / ips.raspberry_pi_b_plus
      print "\nYour system is " + format (rpi_ratio, '.1f') + \
          " times faster than a Raspberry Pi Model B+"
      print "or " + format (pdp_ratio, '.1f') + \
          " times faster than a PDP-8/I.\n"
  else:
    # Normal mode.  Pop out to SIMH and throttle it down to a rate
    # suitable for a blinkenlights demo.  1/17 means SIMH runs one
    # instruction then waits for 17ms, yielding ~59 IPS.
    time.sleep (0.02)   # FIXME: simulator chokes on 'cont' without this
    s.os8_send_ctrl ('e')
    s.send_cmd ('set throttle 1/17')

    # You can't hit Ctrl-E while running this script in the foreground
    # since pexpect takes over stdio.  Therefore, if you want to be able
    # to send commands to the simulator while the demo is running,
    # uncomment the line below, which will let you send commands to the
    # simulator via telnet.  From another terminal or SSH session:
    #
    #     $ telnet localhost 3141
    #
    # or from a remote machine:
    #
    #     $ telnet 192.168.1.2 3141
    #
    # It's disabled by default because SIMH can't be made to listen only
    # on localhost, so doing this may be a security risk.  SIMH disables
    # obviously-unsafe commands like ! on the remote console, but it is
    # possible some mischief may be possible via this path anyway.  It
    # could be used to exfiltrate a sensitive file via ATTACH, for one
    # thing.  For another, it's a potential DoS vector.
    #s.send_cmd ('set remote telnet=3141')

    # Let it run.  Never exits.
    s.send_cmd ('cont')
    s.spin ()


if __name__ == "__main__":
    main()

#!/usr/bin/python
# -*- coding: utf-8 -*-
########################################################################
# Create a tu56 or rk05 image and fill it with ASCII files, i.e.  source code.
#
# It is intended to be be called manually when we have a POSIX
# directory full of ASCII files we want to bulk-copy into SIMH.
#
# The argument is taken both as the name of the image to create
# and the list of files to copy in.
#
# For now, it takes all input and produces all output in the
# current working directory.
#
# IMPORTANT:  Currently all input files are mindlessly passed through
# txt2ptp which transforms POSIX ASCII files to OS/8 ASCII files.
# It WILL mutilate non-ASCII files.
#
# This program is based on cc8-tu56-update.
#
# Copyright © 2017 by Warren Young and Bill Cattey
#
# 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
# the following conditions:
#
# The above copyright notice and this permission notice shall be
# included in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
# IN NO EVENT SHALL THE AUTHORS LISTED ABOVE BE LIABLE FOR ANY CLAIM,
# DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
# OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
# OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#
# Except as contained in this notice, the names of the authors above
# 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.
########################################################################

# Bring in just the basics so we can bring in our local modules
import os
import sys
import argparse

sys.path.insert (0, os.path.dirname (__file__) + '/../lib')
sys.path.insert (0, os.getcwd () + '/lib')

# Our local modules
from pidp8i import *
from simh   import *

# Other global Python modules
import glob
import subprocess


#### GLOBALS AND CONSTANTS #############################################

progmsg = True


#### main ##############################################################

def main ():
  global progmsg

  # Set up the arg parser and use it to parse the command line.
  parser = argparse.ArgumentParser()
  parser.add_argument("name",
                      help="Create an OS/8 image from a list of ASCII files.")
  group = parser.add_mutually_exclusive_group(required=True)
  group.add_argument("--tu56", "-t", action="store_true")
  group.add_argument("--rk05a", "-ra", action="store_true")
  group.add_argument("--rk05b", "-rb", action="store_true")

  args = parser.parse_args()
  
  print "Filename: " + args.name
  if args.tu56:
    sdev = "dt0"
    os8dev = "DTA0:"
    imagename = args.name + ".tu56"
    stat_str = "DECtape"

  if args.rk05a:
    sdev = "rk1"
    os8dev = "RKA1:"
    imagename = args.name + ".rk05"
    stat_str = "partition A of"
    
  if args.rk05b:
    sdev = "rk1"
    os8dev = "RKB1:"
    imagename = args.name + ".rk05"
    stat_str = "partition B of"
  
  listname = args.name + ".list"

  # Create the SIMH child instance and tell it where to send log output
  try:
    s = simh (dirs.build, True)
  except (RuntimeError) as e:
    print "Could not start simulator: " + e.message + '!'
    exit (1)
  s.set_logfile (os.fdopen (sys.stdout.fileno (), 'w', 0))

  # Attach a clean version of the image to the simulator
  if os.path.exists (imagename):
    print "Overwriting old " + stat_str + " image " + imagename

  s.send_cmd ("att " + sdev + " " + imagename)

  # Find and boot the bootable OS/8 disk.  Use the "patched" version
  # because that is what "make run" uses; we use that command to
  # inspect this script's work.
  rk = os.path.join (dirs.os8mo, 'os8v3d-patched.rk05')
  if not os.path.isfile (rk):
    print "Could not find " + rk + "; OS/8 media not yet built?"
    exit (1)
  print "Booting " + rk + "..."
  s.send_cmd ("att rk0 " + rk)
  s.send_cmd ("boot rk0")

  s.os8_send_cmd ('\\.', "ZERO " + os8dev)

  manifest = open (listname, "r")

  for line in manifest:
    src = line.strip()
    if src == "": continue
    if src[0] == '#': continue      # Allow commenting out files

    dest = src.upper ()
    s.os8_send_file (src, os8dev + dest)

  # Exit simulator nicely so that image detaches cleanly
  s.back_to_cmd ('\\.')
  s.send_cmd ("det " + sdev)
  s.send_cmd ('quit')


if __name__ == "__main__": main()

@else
; The software was configured with --lowercase=upper, meaning the user
; wants lowercase text to be forced to uppercase.  This is bidirectional,
; affecting both input to the simulated PDP-8 and output from it.
set tti ksr
@endif

att rk0 @MEDIADIR@/os8/os8v3d-bin.rk05
att rk0 @MEDIADIR@/os8/@OS8_BOOT_DISK@
boot rk0

; A stripped down version of 5.script with the throttle value set to a
; ratio between two values.  Used primarily to test our handling of this
; throttle type.  For example, we need to disable ILS at simulator
; start/continue time when this throttle type is used because it
; throws our timing logic way off.

set throttle 30/1
set df disabled
set cpu noidle
echo Running reeeealy slow version of the AC/MQ blinker...
dep 00000 2020
dep 00001 5000
dep 00002 7200
dep 00003 1021
dep 00004 7421
dep 00005 1021
dep 00006 7040
dep 00007 2021
dep 00010 7000
dep 00011 5000
dep 00020 0000
dep 00021 0000
go  00000

; Same as 0.script, only with RK0 attached to the *.rk05 file in the
; build directory, not the one in the installation directory.  Used
; by "make run" so you don't have to "make mediainstall" first.
;
reset
echo Loading OS/8 from the RK05 cartridge disk in the build directory...
set cpu 32k
set cpu noidle
set df disabled
@SET_THROTTLE@

@if SIMH_PASS_LOWERCASE
set tti 7b
@else
set tti ksr
@endif

att rk0 bin/@OS8_BOOT_DISK@
boot rk0

# PiDP-8/I Software Release Process

This documents the process for producing release versions of the
software.


## *Can* You Release Yet?

Before release, you must:

*   Fix all Immediate, High, and Medium priority [Bugs](/bugs)
*   Implement all Immediate and High priority [Features](/features)

Or reclassify them, of course.

Most of the bug levels simply aid scheduling: Immediate priority bugs
should be fixed before High, etc. Low priority bugs are "someone should
fix this someday" type of problems, so they can move from release to
release.

The Features levels may be read as:

*   **Immediate**: ASAP, or sooner. :)
*   **High**: Features for this release.
*   **Medium**: Features we'll look at lifting individually to High for
    the next release.
*   **Low**: "Wouldn't it be nice if..."


## Update SIMH

If `tools/simh-update` hasn't been run recently, you might want to do
that and re-test before publishing a new version.


## Publish OS/8 RK05s

Re-configure the software with default settings, remove `bin/*.rk05`,
rebuild, and run `tools/publish-os8` to send the "final" OS/8 disk
images for this version of the software up to tangentsoft.com as
unversioned assets.

Update the date stamp in the "OS/8 RK05 Media" section of the project
home page.


## Update ChangeLog.md

Trawl the Fossil timeline for user-visible changes since the last
release, and write them up in user-focused form into the `ChangeLog.md`
file.  If a regular user of the software cannot see a given change, it
shouldn't go in the `ChangeLog.md`; let it be documented via the
timeline only.


## Update the Release Branch

Run `make release` to check the `ChangeLog.md` file changes in, tagging
that checkin with a release version tag of the form vYYYYMMDD and merge
those changes into the `release` branch.

It runs entirely automatically unless an error occurs, in which case it
stops immediately, so check its output for errors before continuing.


## Update the Home Page Links

The zip and tarball links on the front page produce files named after
the date of the release. Those dates need to be updated immediately
after tagging the release, since they point at the "release" tag applied
by the previous step, so they begin shipping the new release immediately
after tagging it.


## Produce the Normal Binary OS Image

Start with the latest version of [Raspbian Lite][os] on a multi-core
Raspberry Pi.

1.  If the version of the base OS has changed since the last binary OS
    image was created, download the new one.

    While the OS is downloading, zero the SD card you're going to use
    for this, so the prior contents don't affect this process.
    
    Blast the base OS image onto the cleaned SD card.

2.  Boot it up on a multi-core Pi.

    Log in, then retreive and initialize BOSI:

        $ wget https://tangentsoft.com/bosi
        $ chmod +x bosi
        $ exec sudo ./bosi init

    The `exec` bit is required so that the `bosi` invocation is run as
    root without any processes running as `pi` in case the `init` step
    sees that user `pi` hasn't been changed to `pidp8i` here: the
    `usermod` command we give to make that change will refuse to do what
    we ask if there are any running processes owned by user `pi`.

    It will either reboot the system after completing its tasks
    successfully or exit early, giving the reason it failed.

3.  Clone the software repo and build the softare:

        $ ./bosi build

    On reboot, say `top -H` to make sure the software is running and
    that the CPU percentages are reasonable for the platform.

    You may also want to check that it is running properly with a
    `pidp8i` command.  Is the configuration line printed by the
    simulator correct?  Does OS/8 run?  Are there any complaints from
    SIMH, such as about insufficient CPU power?

4.  Do final inside-the-image steps:

        $ ./bosi prepare

5.  Move the SD card to a USB reader plugged into the Pi, boot the Pi
    from its prior SD card, and shrink the OS image:

        $ wget https://tangentsoft.com/bosi
        $ chmod +x bosi
        $ ./bosi shrink

6.  Move the USB reader to the Mac,¹ then say:

        $ bosi image [nls]

    For the ILS images, you can give "ils" as a parameter or leave it
    blank.

7.  The prior step rewrote the SD card with the image file it created.
    Boot it up and make sure it still works.  If you're happy with it,
    give this command *on the desktop PC*.

        $ bosi finish [nls]

    As above, the parameter can be "ils" or left off for the ILS images.

[os]: https://www.raspberrypi.org/downloads/raspbian/


## Produce the "No Lamp Simulator" Binary OS Image

Do the same series of steps above on a single-core Raspberry Pi, except
that you give "nls" parameters to the `image` and `finish` steps.


## Publicizing

While the NLS image uploads — the ILS image was already sent in step 7
in the first pass through the list above — compose the announcement
message, and modify the front page to point to the new images.  You
might also need to update the approximate image sizes reported on that
page.  Post the announcement message and new front page once that second
upload completes.


----------------------

### Footnotes

1.  The image production steps could just as well be done on a Linux box
    or on a Windows box via Cygwin or WSL, but the commands in that
    final stage change due to OS differences.  Since this document
    exists primarily for use by the one who uses it, there is little
    point in having alternatives for other desktop OSes above.  Should
    someone else take over maintainership, they can translate the above
    commands for their own desktop PC.


### License

Copyright © 2016-2017 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

# How to Control SIMH and OS/8 from Python

## Introduction

While we were building the `libexec/mkos8` tool, we built up a set of
functionality for driving SIMH and OS/8 running under SIMH from the
outside using [Python][py], a very powerful programming language well
suited to scripting tasks. It certainly beats writing PDP-8 code to
achieve the same ends!

When someone on the mailing list asked for a way to automatically drive
a demo script he'd found online, it was natural to generalize the core
functionality of `mkos8` as a reusable Python class, then write a script
to make use of it. I called resulting demo script `teco-pi-demo` and the
reusable bits `class simh`, which is now shared with `mkos8`.

This document describes how `teco-pi-demo` works, and through it, how
`class simh` works, with an eye toward teaching you how to reuse this
functionality for your own ends.

[py]: https://www.python.org/


## Invocation

Because we do not install these components in the system's Python
library path, you must modify that path to allow your script to find
these components. Simply copy this invocation block into the top of your
script:

    import os
    import sys
    sys.path.insert (0, os.path.dirname (__file__) + '/../lib')
    sys.path.insert (0, os.getcwd () + '/lib')

    from pidp8i import *
    from simh   import *

That adjusts the path, then imports all of the generic functionality
from the PiDP-8/I `lib` directory into the current namespace.

We do not pull the `mkos8` components into `teco-pi-demo` because they
are intended only to be used by `libexec/mkos8`. If you find something
in the `lib/mkos8` directory that you think is widely useful, make a
case for it on the mailing list, and we'll see about moving it to either
the `simh` or `pidp8i` namespace.

The `sys.path.insert` business assumes that your script is installed
into the PiDP-8/I's `bin` directory alongside `teco-pi-demo`. If you've
installed it somewhere else, you'll need to adjust these paths.


## Starting SIMH

The first thing we'lld do is start SIMH as a child process of our Python
script under control of an instance of `class simh`:

    s = simh (dirs.build)

We call that instance `s` for short, because we will be calling its
methods a lot in this script. 

We pass `dirs.build` to its constructor, which tells it how to find the
`pidp8i-sim` program, which is a version of the PDP-8 simulator from the
SIMH project, configured and modified for the needs of the PiDP-8/I
project. We call this the child program, which is what `class simh`
controls from the outside.

(Currently, we don't have a way to make it use other versions of the
SIMH `pdp8` simulator. Please send a patch if you do that.)

The next step is to tell the `s` object where to send its logging
output:

    s.set_logfile (os.fdopen (sys.stdout.fileno (), 'w', 0))

Contrast the corresponding line in `mkos8` which chooses whether to send
logging output to the console or to a log file:

    s.set_logfile (open (dirs.log + 'mkos8-' + first_act + '.log', 'w') \
        if progmsg else os.fdopen (sys.stdout.fileno (), 'w', 0))


## Finding and Booting the OS/8 Media

If your program will use our OS/8 boot disk, you can find it
programmatically by using the `dirs.os8mo` constant, which means "OS/8
media output directory", where "output" refers to the worldview of
`mkos8`.  Contrast `dirs.os8mi`, which points to the directory holding
the input media for `mkos8`.

This snippet shows how to use it:

    rk = os.path.join (dirs.os8mo, 'os8v3d-bin.rk05')
    if not os.path.isfile (rk):
        print "Could not find " + rk + "; OS/8 media not yet built?"
        exit (1)

Now we attach the RK05 disk image to the PiDP-8/I simulator found by the
`simh` object and boot from it:

    print "Booting " + rk + "..."
    s.send_cmd ("att rk0 " + rk)
    s.send_cmd ("boot rk0")

This shows one of the most-used methods in `class simh`, `send_cmd`,
which sends a line of text along with a carriage return to the spawned
child program, which again is `pidp8i-sim`.


## Driving SIMH and OS/8

After the simulator starts up, we want to wait for an OS/8 `.` prompt
and then send the first OS/8 command to start our demo. We use the
`simh.os8_send_cmd` method for that:

    s.os8_send_cmd ('\.', "R TECO")

This method differs from `send_cmd` in a couple of key ways.

First, it waits for a configurable prompt character — sent as the first
parameter — before sending the command.  This is critical when driving
OS/8 because OS/8 lacks a keyboard input buffer, so if you send text to
it too early, all or part of your input is likely to be lost, so your
command won't work.

Second, because OS/8 can only accept so many characters of input per
second, `os8_send_cmd` inserts a small delay between each input
character to prevent character losses.

(See the commentary for `simh._kbd_delay` if you want to know how that
delay value was calculated.)

The bulk of `teco-pi-demo` consists of more calls to `simh.os8_send_cmd`
and `simh.send_cmd`. Read the script if you want more examples.

Notice that we escape the OS/8 `.` command prompt in the first parameter
because `class simh` treats it as a [regular expression][re], and a `.`
in REs means "any character," which we definitely do *not* want to match
on!  If we did not escape this special RE character with a backslash,
`class simh` would send the command when the first character from the
running OS/8 instance came through, likely causing some or all of the
command to be lost by the time OS/8 is ready to accept input.

[re]: https://en.wikipedia.org/wiki/Regular_expression


## Escaping OS/8 to SIMH

Sometimes you need to escape from OS/8 back to SIMH with a
<kbd>Ctrl-E</kbd> keystroke so that you can send more SIMH commands
after OS/8 starts up. This accomplishes that:

    s.os8_send_ctrl ('e')

While out in the SIMH context, you *could* continue to call the
`simh.os8_*` methods, but since SIMH can accept input as fast as your
program can give it, it is best to use methods like `simh.send_cmd`
which don't insert artificial delays.  For many programs, this
difference won't matter, but it results in a major speed improvement in
a program like `mkos8` which sends many SIMH and OS/8 commands
back-to-back!


## Getting Back to OS/8 from SIMH

There are several ways to get back to the simulated OS/8 environment
from SIMH context, each with different tradeoffs.


### Rebooting

You saw the first one above: send a `boot rk0` command to SIMH. This
restarts OS/8 entirely. This is good if you need a clean environment.
If you need to save state between one run of OS/8 and the next, save it
to the RK05 disk pack or other SIMH media, then re-load it when OS/8
reboots.


### Continuing

The way `teco-pi-demo` does it is to send a `cont` command to SIMH.

The problem with this method is that it sometimes hangs the simulator.
The solution is to insert a small delay *before* escaping to the SIMH
context. I'm not sure why this is sometimes necessary. My best guess is
required to give OS/8 time to settle into an interruptible state before
escaping to SIMH, so that on "continue," we re-enter OS/8 in a sane
state.

You can usually avoid the need for that delay by waiting for an OS/8
command prompt before escaping to SIMH, since that is a reliable
indicator that OS/8 is in such an interruptible state.

You don't see these anomalies when using OS/8 interactively because
humans aren't fast enough to type commands at OS/8 fast enough to cause
the problem.  That is doubtless why there this bug still exists in OS/8
in 2017.


### Re-Entering

If your use of OS/8 is such that all required state is saved to disk
before re-entering OS/8, you can call the `simh.os8_restart` method to
avoid the need for a delay *or* a reboot.  It re-calls OS/8's entry
point from SIMH context, which we've found through much testing is
entirely reliable, as compared to sending a SIMH `cont` command without
having delayed before escaping to SIMH context.

`mkos8` uses this option extensively.


## Sending Escape Characters

Several OS/8 programs expect an <kbd>Escape</kbd> (a.k.a. `ALTMODE`)
keystroke to do things. Examples are `TECO` and `FRTS`. There isn't a
specific method to do this because we can do that in terms of one we've
just described:

    s.os8_send_ctrl ('[')

Yes, <kbd>Escape</kbd> is <kbd>Ctrl-\[</kbd>. Now you can be the life of
the party with that bit of trivia up your sleeve. Or maybe you go to
better parties than I do.


## But There's More!

The above introduced you to most of the functionality of `class simh`
used by `teco-pi-demo`, but there's more to the class than that,
primarily because the `mkos8` script's needs are broader.  Rather than
just recapitulate the class documentation here, please read through [the
class's source code][ssc], paying particular attention to the method
comments. It's a pretty simple class, making it a quick read.

Another useful module is [`pidp8i.dirs`][dsc] which contains paths to
many directories in the PiDP-8/I system, which you can reuse to avoid
having to hard-code their locations.  This not only makes your script
independent of the installation location, which is configurable at build
time via `./configure --prefix=/some/path`, but also allows it to run
correctly from the PiDP-8/I software's build directory, which has a
somewhat different directory structure from the installation tree.

[ssc]: https://tangentsoft.com/pidp8i/file/lib/simh.py
[dsc]: https://tangentsoft.com/pidp8i/file/lib/pidp8i/dirs.py


## <a id="license" name="credits"></a>Credits and License

Written by and copyright © 2017 by Warren Young. Licensed under the
terms of [the SIMH license][sl].

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