PiDP-8/I Software

inst
test

cc8/*.[ch]
cc8/*.pa
cc8/*.sb

examples/*.fc

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

.agignore

# Licenses

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


## <a id="simh"></a>SIMH License
## 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


## <a id="hw"></a>PiDP-8/I Design Files
## 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


## <a id="autosetup"></a>autosetup License
## 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


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

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

[pl]: https://tangentsoft.com/pidp8i/doc/trunk/src/palbart/LICENSE.md
[pl]: https://tangentsoft.com/pidp8i/doc/trunk/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


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

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

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


## <a id="dec"></a>Other DEC Software
## 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


## <a id="etos"></a>ETOS License
## 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
## Version 2017.10.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.
    clean OS/8 RK05 disk images from original DEC binary distribution
    DECtapes, other primary source media, and 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.
        
        default.  Also merged in his `cc8` cross-compiler and his
        hand-rolled OS/8 distribution, `media/os8/cc8.rk05`.  See [the
        CC8 `README`][cc8rm] for details.

        This is an improved version of the compiler relative to what was
        distributed on the mailing list in August 2017.  Ian has been
        working within the project since that initial public release,
        making improvements to his compiler within our project, so that
        there will be a single canonical version.  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
    -   MACREL macro assembler is installed by default.
        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.
        All other programs are left to fend for themselves, which often
        works out fine. U/W FOCAL, Adventure, TECO, etc. all handle
        lowercase input to some extent, and all can emit lowercase text
        if given it.  With the prior SIMH settting, you could not use
        lowercase at all.

        This default can be overridden.  See the documentation for the
        new `--lowercase` configuration option in `README.md`.
        This change has been slightly controversial, so we have two
        alternative modes that can be selected at `configure` time:

        -   No patches and no case-folding in SIMH.  Lowercase I/O is
            allowed, but neither SIMH nor OS/8 nor its programs will
            second-guess your input, even if that means some programs
            will fail when given lowercase input. If you need to engage
            CAPS LOCK to make the program do the right thing, you are
            expected to be aware enough to do this.
    -   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`.
            
            The argument in favor of this approach is that this is what
            a real PDP-8 system running this software would have done if
            sent lowercase input.

        -   Revert to the prior releases' behavior: no patches, and SIMH
            does automatic case-folding for you, so you only get
            uppercase, even when you type lowercase text.  Programs that
            emit lowercase text (e.g. Adventure) appear to be sending
            uppercase instead.

        Those that do not want any boot message can disable it at
        configuration time with the `--disable-os8-init` flag.
            This option is in fact historically accurate. Essentially,
            this configuration makes SIMH pretend that your terminal is
            only capable of uppercase text, which was very common in the
            PDP-8's day: the uppercase-only Teletype Model 33 ASR was
            the most common terminal type on PDP-8s.

        Our new default is historically inaccurate, but we think it the
        new behavior is the least likely to unpleasantly surprise end
        users.  Pick your poison.
        The message can be modified by editing `media/os8/init.tx.in`

        and saying `make`, which will rebuild the OS/8 media.
    -   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.  Those that do not want any boot message can
        disable it at configuration time.

    -   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-*`
        You can disable these features individually or you can disable
        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.
        all of them with the new `configure --os8-minimal` feature,
        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
    -   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.

    -   Added configure-time options to disable all of the above new
        features and most of the features that were present on the
        original `os8.rk05` disk as well.  You can create a completely
        stripped-down OS/8 disk image, one with all features enabled, or
        anything in between.

    -   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

        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

    -   TODO: Added the `os8` script to add and remove features from the
        built OS/8 binary disk image after it is initially built.  In a
        primitive sort of way, this is "[apt][apt] for OS/8."

    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 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
*   We now build an OS/8 RK05 source code disk image containing the
    contents of the OS/8 source distribution DECtapes for the
    convenience of those who would like to work with the OS/8 source
    code in a more convenient fashion than attaching and detaching the
    *ten* TU56 tape image files.
    the host machine with its contents.

    files between SIMH paper tape format and plain POSIX ASCII text
    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.
    files.  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.
*   Added a new "blinkenlights" demo program that drives SIMH from the
    outside, running a TECO macro under OS/8 which calculates *pi* to
    about 20 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.
    This script, called `bin/teco-pi-demo`, is also included as a
    demonstration of how an end-user program 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 for Raspbian Stretch, released in September 2017.  It should
*   Updated for Raspbian Squeeze, released in September 2017.  It should
    still run on Raspbian Jessie, however.

*   Assorted portability, build system, and documentation improvements.
*   Assorted portability improvements.

*   **TODO**

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

    -   Do a `simh-update` pass, document the diffs, test for breakage.

    -   Merge Steve Bennett's idea for combined autosetup/mkos8 option
        handling.
    *   Write `PEP001.FC` and wiki article explaining it
    *   Write `PEP001.F4` and wiki article explaining it
    *   Write `PEP001.F2` and wiki article explaining it
    *   Write `PEP001.C`  and wiki article explaining it
    *   Write a doc explaining how `teco-pi-demo` works, and by
        extension, how to use `class simh`.
    *   Fix all Immediate, High, and Medium priority [Bugs](/bugs)
    *   Implement all Immediate and High priority [Features](/features)

[apt]:   https://linux.die.net/man/8/apt
[cc8rm]: https://tangentsoft.com/pidp8i/doc/trunk/src/cc8/README.md
[cc8rm]: https://tangentsoft.com/pidp8i/doc/trunk/cc8/README.md
[csd]:   https://tangentsoft.com/pidp8i/doc/trunk/doc/class-simh.md
[dt2vk]: https://github.com/VentureKing/Deeper-Thought-2
[os8p]:  https://tangentsoft.com/pidp8i/doc/trunk/doc/os8-patching.md
[os8rm]: https://tangentsoft.com/pidp8i/doc/trunk/media/os8/README.md
[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

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

*   Fixed a bunch of bugs!

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

    $ 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]:   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
[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
[ggml]:   https://groups.google.com/forum/#!forum/pidp-8


Fossil Anonymous Access
----

To clone the code repository anonymously, say:

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 https://username@tangentsoft.com/pidp8i pidp8i.fossil
    $ fossil clone http://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

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
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.
account name for the checkin.

If you're working offline, Fossil will still do the checkin locally, and
it will sync up with the central 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

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

[osil]:  https://opensource.org/licenses
[repo]:  https://tangentsoft.com/pidp8i/
[repo]:  http://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
----

# 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

# 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@ \
	-Wno-unused-result -Wno-parentheses \
	-DUSE_READER_THREAD -DHAVE_DLOPEN=$(subst .,,@SH_SOEXT@) -DPIDP8I \
CFLAGS = @CFLAGS@ -Wno-unused-result -Wno-parentheses @BUILDMODE@ \
	-DUSE_READER_THREAD -DHAVE_DLOPEN=so -DPIDP8I -DSIM_ASYNCH_IO \
	-DSIM_ASYNCH_IO -DHAVE_REGEX_H -DHAVE_GLOB \
	-DSIM_GIT_COMMIT_ID=$(SGCID) -D_GNU_SOURCE \
	-U__STRICT_ANSI__ \
	-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 \
	libexec/scanswitch
BINS = bin/palbart $(SIM) bin/pidp8i-test bin/ptp2txt libexec/scanswitch @CC8_CROSS@
BIN_SCRIPTS = \
	bin/pidp8i \
	@srcdir@/bin/teco-pi-demo

# Some *.py files are generated by Autosetup, so they need different
# lib/pidp8i/dirs.py is generated by Autosetup, so it needs 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
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@/lib/simh.py
SIMH_PY_SRC := @srcdir@/$(SIMH_PY)

MKOS8         := @srcdir@/libexec/mkos8
MKOS8_LIB     := @srcdir@/lib/mkos8
MKOS8_PY      := \
MKOS8        = @srcdir@/libexec/mkos8
MKOS8_LIB    = lib/mkos8
MKOS8_PY     = \
	$(MKOS8_LIB)/__init__.py \
	$(MKOS8_LIB)/argparser.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)
MKOS8_PY_SRC = $(addprefix @srcdir@/,$(MKOS8_PY))
MKOS8_SRCS   = $(MKOS8) $(MKOS8_PY_SRC) $(PIDP8I_DIN) $(SIMH_PY_SRC)

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

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

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

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.
# 
# The MKOS8_INFILES set of files are those which, if changed, require
#
# If the first file listed below changes, change the AUTOREBUILD rule
# 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 \
# near the end of this file to match!
    @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/cc8.script.in \
	@srcdir@/boot/run.script.in \
	@srcdir@/etc/pidp8i-init.in \
	@srcdir@/etc/sudoers.in \
	@srcdir@/media/os8/init.tx.in \
	@srcdir@/src/gpio-common.c.in \
	@srcdir@/src/PDP8/pidp8i.c.in \
	@srcdir@/tools/simh-update.in \
	$(PIDP8I_DIN)
	$(MKOS8_INFILES)
MKOS8_OUTFILES := $(subst @srcdir@/,,$(MKOS8_INFILES))
MKOS8_OUTFILES := $(subst .in,,$(MKOS8_OUTFILES))
PRECIOUS_INFILES = \
	@srcdir@/Makefile.in \
	@srcdir@/cc8/Makefile.in \
	@srcdir@/examples/Makefile.in \
	@srcdir@/src/Makefile.in \
	@srcdir@/src/PDP8/Makefile.in
OUTFILES := $(subst @srcdir@/,,$(INFILES))
OUTFILES := $(subst .in,,$(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 = @OS8_SRC_RK05@
OS8_RK05S = $(OS8_BIN_RK05) $(OS8_SRC_RK05)

CLTXT = /boot/cmdline.txt

ADF := adrules.mk

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

all: $(OUTFILES) $(PRECIOUS_OUTFILES) $(BUILDDIRS) $(BINS) $(BOOTSCRIPTS) $(LISTINGS) $(ASM_PTS) $(FC_EX_PTS) $(PAL_EX_PTS) $(OS8_RK05S)

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

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

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

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

	@# Install files into those dirs and set their perms
	@for f in $(BINS) ; do \
		dest=@prefix@/bin/$$(basename $$f) ; \
		echo "Installing binary $$dest..." ; \
		@INSTALL@ -m 755 -D -s $$f $$dest ; \
	for f in $(BINS) ; do @INSTALL@ -m 755 -D -s $$f @prefix@/$$f ; done
	done
	@for f in $(BIN_SCRIPTS) ; do \
		dest=@prefix@/bin/$$(basename $$f) ; \
	( cd @prefix@/bin ; ln -f ptp2txt txt2ptp )
		echo "Installing script $$dest..." ; \
		@INSTALL@ -m 755 -D $$f $$dest ; \
	@INSTALL@ -m 755 @srcdir@/bin/pidp8i @prefix@/bin
	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
	test -e @MEDIADIR@/os8/os8.rk05 || $(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

	@(  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@" && \
	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@ -m 644 cc8/include/* @prefix@/share/include

	@# Install palbart stuff
	@@INSTALL@ -m 755 bin/palbart @prefix@/bin
	@@INSTALL@ -m 644 @srcdir@/src/palbart/palbart.1 @prefix@/share/man/man1
	@INSTALL@ -m 755 bin/palbart @prefix@/bin
	@INSTALL@ -m 644 @srcdir@/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 \
	@INSTALL@ -m 775 -g @INSTGRP@ $(MKOS8) @prefix@/libexec
	@( cd @srcdir@ ; \
	  for f in $(MKOS8_PY) ; 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 ; \
	    @INSTALL@ -m 644 -g @INSTGRP@ -D @srcdir@/$$f @prefix@/$$f ; \
	    @INSTALL@ -m 644 -g @INSTGRP@ -D @srcdir@/$${f}c @prefix@/$${f}c ; \
	  done \
	)
	@sed -e 's#^build =.*#build = "@ABSPREFIX@"#' \
	@sed -e 's#^build =.*$$#build = "@ABSPREFIX@"#' \
	     -e 's#^media =.*#media = os.path.join (build, "share/media/")#' \
	     -e 's#^os8mo =.*#os8mo = os8mi#' \
	     -e 's#^src   =.*$$#src   = "@ABSPREFIX@"#' \
		 < $(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
	for d in $(INSTDIRS) ; do @INSTALL@ -m 755 -d @prefix@/$$d ; done

mediainstall: instdirs
	@echo "[Re]installing OS and program media..."
	@cd @srcdir@ ; \
	find media \( \
		-name \*.bin  -o \
		-name \*.dsk  -o \
		-name \*.rk05 -o \
		-name \*.tu56 \
	\) -exec @INSTALL@ -D -m 664 -o @INSTUSR@ -g @INSTGRP@ {} @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: $(SIM)
run: $(OS8_BIN_RK05) $(SIM)
	$(SIM) boot/run.script

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

test-mkos8:
	tools/test-mkos8

# 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) \
OS8_BIN_SRCS = $(MKOS8_SRCS) \
	@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): $(OS8_BIN_SRCS) | $(SIM) $(MKOS8_OUTFILES)
	$(MKOS8)@MKOS8_OPTS@ bin @MKOS8_BIN_PATCHES@
$(OS8_BIN_RK05): $(OS8_BIN_SRCS) | $(SIM)
	$(MKOS8)@MKOS8_OPTS@ bin

# 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 = $(MKOS8_SRCS) \
	@srcdir@/media/os8/al-*-sa-*.tu56
$(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

# Another near-duplicate for the PDP-8 simulator.  First set above
# doesn't catch these.
obj/PDP8/%.o: @srcdir@/src/PDP8/%.c
	$(CC)  -c -w $(CFLAGS) @srcdir@/src/PDP8/$*.c -o obj/PDP8/$*.o
	$(CC) -MM -w $(CFLAGS) @srcdir@/src/PDP8/$*.c  > obj/PDP8/$*.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

# Another near-duplicate for CC8, since it's off in a different subdir
obj/%.o: @srcdir@/cc8/cross/%.c
	$(CC)  -c -w $(CFLAGS) @srcdir@/cc8/cross/$*.c -o obj/$*.o
	$(CC) -MM -w $(CFLAGS) @srcdir@/cc8/cross/$*.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/%-pal.pt: @srcdir@/asm/%.pal bin/palbart
	bin/palbart -lr $< || cat obj/$*.err
	mv @srcdir@/asm/$*.lst obj
	mv @srcdir@/asm/$*.rim bin/$*-pal.pt

# 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): $(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)),)
media/os8/init.tx: $(INFILES) $(PRECIOUS_INFILES) @AUTODEPS@
	@AUTOREMAKE@ && $(MAKE)

# Also do it if the autodep tool is newer than its output, suggesting
# that if re-run, it would generate different output.
$(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 \
	$(SIM_OBJS:.o=.d) \
	$(CC8_OBJS:.o=.d) \
-include $(SIM_OBJS:.o=.d) $(CC8_OBJS:.o=.d) obj/scanswitch.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 [a compatible OS][os].
*   An SD card containing Raspbian or something sufficiently close.
    This software is currently tested with the Jessie Lite distribution.

    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.

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

    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.

    Unlike with the [upstream 2015.12.15 release][upst], this present
    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.

    release of the software should *not* be unpacked into `/opt/pidp8`.
*   We require several tools and libraries that aren't always installed:

    I recommend that you unpack it into `$HOME/src`, `/usr/local/src` or
    *   A working C compiler and other standard Linux build tools,
        such as `make(1)`.

    similar, but it really doesn't matter where you put it, as long as
    *   Python's `pexpect` library

    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

    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:

*   A working C compiler and other standard Linux build tools, such as
        $ wget -O pidp8i.tar.gz https://goo.gl/JowPoC

    `make(1)`.  On Debian type systems — including Raspbian — you can
    That will get you a file called `pidp8i.tar.gz` in the current
    working directory.

    install such tools with `sudo apt install build-essential`
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 id="configuring"></a>
<a name="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`
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:

step fails, try redoing the `configure` step. Sometimes changes made to
    $ make reconfig

the source code invalidate prior `make` dependencies, which are
...and then continuing with the `make && sudo make install` steps before
reporting a build error.

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


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

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

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


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

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


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

Perhaps the most widely useful `configure` script option is `--prefix`,
which lets you override the default installation directory, `/opt/pidp8i`.
which lets you override the default installation directory,
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.

`/opt/pidp8i`.  You could make it install the software under your home
For example, you might prefer that the installer put the built software
under your home directory.  This will do that:
directory on the Pi with this command:

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

You might think that installing to a directory your user has complete
Although this is installing to a directory your user has write access
control over would remove the need for installing via `sudo`, but that
is not the case, since the installation script needs root privileges to
to, you still need to install via `sudo` because the installation
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.
process does other things that do require `root` access.


<a id="lowercase"></a>
<a name="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 id="nls"></a>
<a name="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 id="serial-mod"></a>
<a name="serial-mod"></a>
#### --serial-mod

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

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

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


<a id="alt-serial-mod"></a>
<a name="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.

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 id="disable-os8"></a>
<a name="disable-os8"></a>
#### --disable-os8-\*

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

*   **--disable-os8-advent** — Leave out the [Adventure][advent] game.
*   **--disable-os8-advent** — Leave out the Adventure 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][chess].
*   **--disable-os8-chess** — Leave out John Comeau's CHECKMO-II chess
    implementation.

*   **--disable-os8-cc8** - Leave out Ian Schofield's native OS/8 CC8
    compiler normally installed to `SYS:`.  This option is implicitly
    compiler normally installed to `RKA0:`
    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,
*   **--disable-os8-fortran-ii** - Leave the FORTRAN II compiler out.
    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
*   **--disable-os8-init** - Generate `SYS: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.
    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
*   **--disable-os8-macrel** - Leave the MACREL assembler out.
    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 id="enable-os8"></a>
<a name="enable-os8"></a>
#### --enable-os8-\*

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

*   **--enable-os8-music** — The `*.MU` music scores and Rich Wilson's
*   **--enable-os8-music** — The `*.MU` files and the player program for
    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".
    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-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][uvte] not normally recognized by TECO.
    commands](/wiki?name=Using+VTEDIT) not normally recognized by TEDO.

    This feature is disabled by default because the VTEDIT macro pack
    This feature is currently disabled because it is not yet fully
    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.
    tested by the person in charge of the OS/8 disk building process.

    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
    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
    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
    guilty if you choose to try this option.

    our mind on this.
[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.

#### --help

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


<a id="overwrite-setup"></a>
<a name="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

(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 the prior PDP-8 simulator configuration
1.  If you just want to reflect upstream 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 change is to the binary PDP-8 media image files — including
2.  If the upstream change is to the binary PDP-8 media image files and
    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.
    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.

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
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`.)
    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 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 someone 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 — see [the ChangeLog][cl] for details —
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 in the
new disk images, though the default configuration is not a strict
superset of the old disk image. In some cases, we have made some options
disabled by default, and in some cases, we have changed default
behaviors. 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.


### 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 id="testing"></a>
## Testing Your PiDP-8/I Hardware
<a name="testing"></a>
## Testing

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 id="using"></a>
<a name="using"></a>
## Using the Software

For the most part, this software distribution works like the [old stable
2015.12.15 distribution][osd]. Its [documentation][oprj] therefore
For the most part, this software distribution works like the upstream
[2015.12.15 distribution][usd].  Its [documentation][prj] 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 old stable
There are [other major differences][mdif] between the upstream
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].


[cprj]: https://tangentsoft.com/pidp8i/
[prj]:  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
[osd]:  http://obsolescence.wixsite.com/obsolescence/pidp-8-details
[usd]:  http://obsolescence.wixsite.com/obsolescence/pidp-8-details
[dt2]:  https://github.com/VentureKing/Deeper-Thought-2
[sdoc]: https://tangentsoft.com/pidp8i/uv/doc/simh/main.pdf
[oprj]: http://obsolescence.wixsite.com/obsolescence/pidp-8
[prj]:  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.


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

# 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      => "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-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       => "leave the CHECKMO-II game of chess off built OS/8 RK05 image"
    os8-dcp=1	      => "install DCP Disassembler executables to 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-init=1        => "suppress the OS/8 INIT message on boot: start with a bare . prompt"
    os8-k12=1         => "leave 12-bit Kermit off built OS/8 RK05 disk image"
    os8-macrel=1      => "leave MACREL assembler off the build OS/8 RK05 image"
    os8-minimal       => "disable all --enable-os8-* options, giving minimal OS/8 bin disk"
    os8-music         => "add *.MU files to built OS/8 RK05 disk 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-src=1         => "don't 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]} {

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

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 mkos8_opts " --disable-lcmod"
} elseif {$lv == "upper"} {
    append mkos8_opts " --disable-lcmod"
} else {
    user-error "Legal values for --lowercase are {auto,pass,upper}."
}
msg-result "Lowercase handling set to '$lv' mode."

set os8min [opt-bool os8-minimal]
if {$os8min || ![opt-bool os8-advent]} {
    msg-result "Will not add game of ADVENT to the OS/8 RK05 disk image."
    append mkos8_opts " --disable-advent"
}
if {$os8min || ![opt-bool os8-ba]} {
    msg-result "Will not add BASIC games and demos to the OS/8 RK05 disk image."
    append mkos8_opts " --disable-ba"
}
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 {$os8min || ![opt-bool os8-cc8]} {
    msg-result "Will not add CC8 to the OS/8 RK05 disk image."
    append mkos8_opts " --disable-cc8"
}
if {$os8min || ![opt-bool os8-chess]} {
    msg-result "Will not add game of CHESS to the OS/8 RK05 disk image."
    append mkos8_opts " --disable-chess"

# We've purposely held off exporting the mkos8 option set until now
# because some of the configuration options can affect the option set.
}
if {$os8min || ![opt-bool os8-crt]} {
    msg-result "Will not add BASIC games and demos to the OS/8 RK05 disk image."
    append mkos8_opts " --disable-crt"
}
if {$os8min || ![opt-bool os8-dcp]} {
    msg-result "Will not add DCP disassembler to the OS/8 RK05 disk image."
    append mkos8_opts " --disable-dcp"
}

if {$os8min || ![opt-bool os8-focal]} {
    msg-result "Will not add FOCAL 69 or U/W FOCAL to the OS/8 RK05 disk image."
    append mkos8_opts " --disable-focal"
} elseif {[opt-bool os8-focal69] && ![opt-bool os8-uwfocal]} {
    msg-result "Adding FOCAL 69 to the OS/8 RK05 disk image instead of U/W FOCAL."
    append mkos8_opts " --enable-focal69 --disable-uwfocal"
} elseif {[opt-bool os8-focal69] && [opt-bool os8-uwfocal]} {
    msg-result "Adding both FOCAL 69 and U/W FOCAL to the OS/8 RK05 disk image."
    append mkos8_opts " --enable-focal69"   ;# default --enable-uwfocal 
} else {
    msg-result "Adding U/W FOCAL to the OS/8 RK05 disk image instead of FOCAL 69."
}

if {$os8min || ![opt-bool os8-fortran-ii]} {
    msg-result "Will not add FORTRAN II compiler to the OS/8 RK05 disk image."
    append mkos8_opts " --disable-fortran-ii"
}
if {$os8min || ![opt-bool os8-fortran-iv]} {
    msg-result "Will not add FORTRAN IV compiler to the OS/8 RK05 disk image."
    append mkos8_opts " --disable-fortran-iv"
}
if {$os8min || ![opt-bool os8-k12]} {
    msg-result "Will not add Kermit-12 to the OS/8 RK05 disk image."
    append mkos8_opts " --disable-k12"
}
if {$os8min || ![opt-bool os8-macrel]} {
    msg-result "Will not add MACREL assembler to the OS/8 RK05 disk image."
    append mkos8_opts " --disable-macrel"
}
if {!$os8min && [opt-bool os8-music]} {
    msg-result "Will add music files to the OS/8 RK05 disk image."
    append mkos8_opts " --enable-music"
} else {
    msg-result "Will not add music files to the OS/8 RK05 disk image."
}
if {!$os8min && [opt-bool os8-vtedit]} {
    msg-result "Will add VTEDIT setup to the OS/8 RK05 disk image."
    append mkos8_opts " --enable-vtedit"
}

if {$os8min || ![opt-bool os8-init]} {
    msg-result "Suppressing the INIT message on OS/8 boot."
    append mkos8_opts " --disable-init"
}
if {[opt-bool os8-src]} {
    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 {}
}
define MKOS8_OPTS $mkos8_opts

# Force a rebuild of the OS/8 media if the option set changed.
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."

} else {
    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"} {

# 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 ".timeout 5000 ; select value from vvar where name=\"repository\""
    set sql "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 {

# 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/cc8.script.in
make-template boot/run.script.in
make-template cc8/Makefile.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/simh-update.in
exec chmod +x "$builddir/tools/simh-update"

	# 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
	set autosetup(optdefault) {}
	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

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

*.pt
*.rk05

.agignore

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

  # Start TECO in the simulator
  # Create the SIMH child instance and tell it where to send log output
  try:
    s = simh (dirs.build)
  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 ("att rk0 bin/os8v3d-bin.rk05")
  s.send_cmd ("boot rk0")

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

  # The macro comes from http://www.iwriteiam.nl/HaPi_TECO_macro.html
  # The macro we'll send: 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',
    'GZ0J\UNQN"E 40UN \' 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',
  ]

  # 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
  # Let macro run for a bit, then pop out to SIMH and throttle it down
  # to a rate suitable for a blinkenlights demo and let it go.
    # 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')
  time.sleep (0.1)
  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 ()
  s.send_cmd ('cont')
  s.spin ()                     # never exits


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/@OS8_BOOT_DISK@
att rk0 @MEDIADIR@/os8/os8v3d-bin.rk05
boot rk0

; This script initializes a populated OS/8 environment on an
; RK05 cartridge disk pack.  That's 10 whole megabytes, so big 
; the OS requires that you split it into two partitions in order
; to address the whole disk!  These are:
;
;     SYS: which conyains all of the OS/8 system files and CC8
;     DSK: which contains all of the user files
;
reset
echo Loading the CC8 OS/8 environment from the RK05 cartridge disk...
set tti 7b
set cpu 32k
set cpu noidle
@SET_THROTTLE@
att rk0 @MEDIADIR@/os8/cc8.rk05
boot rk0

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

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

########################################################################
# Makefile.in - Processed by autosetup's configure script to generate
#    an intermediate GNU make(1) file for building the PiDP-8/I software
#    from within its cc8/ subdirectory.
#
# The resulting Makefile will redirect simple "make" calls to the top
# level as well as the major top-level targets (e.g. "make clean") but
# purposefully will not redirect anything like an installation or "run
# the system" type target.  Its only purpose is to help out those who
# are working on CC8 from within this directory.  If you need to work
# on the wider system, do it from the project's top level.
#
# If you are seeing this at the top of a file called Makefile and you
# intend to make edits, do that in Makefile.in.  Saying "make" will then
# re-build Makefile from that modified Makefile.in before proceeding to
# do the "make" operation.
#
# Copyright © 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.
########################################################################

all clean ctags distclean tags reconfig:
	cd @builddir@; make $@

# A Minimal Implementation of C for the DEC PDP-8 Processor

## Introduction

The C language and its derivatives are now the industry standard for the
development of operating systems and utilities. The language has evolved
significantly since its initial specification in 1972. At this time, the
PDP-7 was used for the initial implementation and the compiler ported to
a number of other systems including the PDP-11. Also, the first
glimmerings of Unix appeared following a re-write of the assembly
language version in C and the rest is of course history. The PDP-8 was
introduced by DEC in 1965 at the same time as the PDP-7 with the
intention of being a small and cheap processor that could be used in a
variety of environments. From this simple machine, the modern desktop
device has evolved which I am using to type this document. Nonetheless,
far from fading into obscurity, there is a very active group of
enthusiasts who have looked to implementing the PDP-8 on modern hardware
and the thanks to Oscar Vermuelen and others, we can all have a PDP8/I
to play with. With this in mind, I thought it was time to have a modern
language compiler running on the PDP-8 which as far as I can tell, the
last native compiler developed for the PDP-8 was Pascal in 1979 by Heinz
Stegbauer. In more recent times, one cross-compiler has been developed
by Vince Slyngstad and updated by Paolo Maffei based on Ron Cain’s Small
C using a VM approach. [This code][sms] is most certainly worth
examining, and I am delighted to acknowledge this work as I have used
some of the C library code in this project.

[sms]: http://so-much-stuff.com/pdp8/C/C.php

Finally, I would refer the reader to Fabrice Bellard’s OTCC. It is this
bit of remarkable software that suggested that there may be a chance to
implement a native PDP-8 compiler.

Developing a native compiler for the PDP-8 is not an easy task as this
processor has a very limited address space and no hardware stack. And,
although the option exists to write the whole thing in assembly language
as has been the case for Pascal and Algol, this project has explored the
option of writing the compiler itself in C. To this end, 2 compilers
have been written. Firstly, a cross-compiler based again on Ron Cain’s
Small-C which is used to compile the native OS/8 compiler and library.
As yet, the native compiler has rather limited functionality and will
not compile itself. The cross-compiler will compile itself but produces
an enormous (28K) assembler file which cannot be run on the PDP-8.


# The Cross-Compiler

The code for this is in the `cross` subdirectory, and is built along
with the top-level PiDP-8/I software. As above, this is based upon Ron
Cain’s Small-C compiler, and the reader is directed to the extensive
documentation available on the web. The key file is the code generator
section in `code8.c`. This is used to generate SABR (Symbolic Assembler
for Binary Relocatable programmes) assembly output which is normally
used as the second pass of the OS/8 FORTRAN II system.

You use this cross-compiler to compile the 3 components of the OS/8 C
compiler:

1.  `n8.c` → `n8.s`: The parser/tokeniser section of the compiler

2.  `p8.c` → `p8.s`: The token to SABR code converter section.

3.  `libc.c` → `libc.s`: The C library used by both of the above
    via the `libc.h` include file.

When you build and run this cross-compiler on a POSIX type system such
as the Raspbian PiDP-8/I environment, the resulting `*.s` files will
have LF-only line endings. You may need to run these files through a
`unix2dos` type utility in order to produce the CRLF line endings that
OS/8's SABR assembler expects, depending on how you get those `*.s`
files into OS/8 as `*.SB`.

The `*.SB` files may be assembled under OS/8:

    .COMP N8.SB
    .COMP LIBC.SB
    .COMP P8.SB

This will create the `*.RL` files for the linking loader (`LOADER.SV`).

The cross-compiler has some non-standard features to enable the
interface between the main programme and the C library. This constitutes
a compile time linkage system to allow for standard and vararg functions
to be called in the library. The 3 SABR files generated from the source
files as above may then be separately downloaded, compiled, loaded and
linked under OS/8. Each of these SABR files generates just less than 4K
of relocatable code as `N8.RL`, `P8.RL` and `LIBC.RL`. These are linked
in pairs under OS/8 to create the 2 native OS/8 compiler phases:

Phase 1: Link `N8.RL` and `LIBC.RL` to be saved as `CC1.SV`

Phase 2: Link `P8.RL` and `LIBC.RL` to be saved as `CC2.SV`

The commands are as follows, with `$` being an Escape keypress:

    .R LOADER
    *N8,LIBC/I$
    .SAVE SYS CC1
    .R LOADER
    P8,LIBC/I/O$
    .SAVE SYS CC2

N8 (`CC1.SV`) terminates by chaining to `CC2.SV` to complete the process
of generating a final SABR file.

Several of the C programs in this distribution reference a PAL assembly
initialization routine `cc8/include/init.pa`, which is symlinked into
each directory that uses it. It defines some low-level subroutines,
initializes the environment for the programs, and calls into the LIBC
initialization code. If you are going to compile these programs with the
OS/8 native compiler, you will need to copy `init.pa` into the OS/8
environment as well.

The same goes for `cc8/include/libc.h`, which defines the mappings
between the familiar C library routine names and their underlying
implementation names.

The linking loader determines the core layout of each of the pairs of
`.RL` files as above. Typically this is as follows:

**Field 0:** FOTRAN library utility functions and OS/8 I/O system

**Field 1:** Reserved for the programme’s runtime stack/globals/literals.

**Field 2:** Usually the primary programme ... either N8 or P8.

**Field 3:** Usually the LIBC library.

In all, each phase of the native OS/8 compiler will use 16K of core.


## The Native Compiler

This compiler is built and linked as above. The final two files
generated are `CC1.SV` and `CC2.SV`. These should be on the OS/8 system
device. (`SYS:`) The compiler expects the source file in C to be in `CC.CC`
on the default user device. (`DSK:`) In addition, you will need to file
`HEADER.SB` on the default user device. This is used by `CC2.SV`. I suggest
you use the provided RK05 image as this has the `SYS:` and `DSK:` partitions
configured as required and include a linked copy of the compiler and
some example programs.

To try it out:

Boot OS/8 from the included RK05 image with:

     $ bin/pidp8i-sim boot/cc8.script

Note that this is a different version of OS/8 than the one currently
distributed in the IF=0, IF=3, and IF=7 positions in the PiDP-8/I boot
scheme. It is version V3Q (up from V3D) and it is configured to smash
lowercase input to uppercase only in the OS/8 command processor.
Lowercase input in the text editor will be saved as lowercase.

With this special CC8 OS/8 environment running, you can enter a C
programme in lower case via the editor.

Before getting into the text editor, try building a copy of one of the
example programs:

    .COPY CC.CC<PS.CC

Run with:

    .R CC1

Then:

    .COMP CC.SB

Then:

    .R LOADER
    *CC,LIBC/G

And hope for the best!!!!


## GOVERNMENT HEALTH WARNING

**You are hereby warned**: the native OS/8 compiler does not contain any
error checking whatsoever. If the source files contain an error, you
will either receive a compile time warning while compiling the CC.SB
file or a runtime crash. Any error will not give you any hint as to the
cause. It is worth noting that GCC uses some 100’s of K for error
checking. The app has only 3K to create a token list from CC.CC that
could run directly in a suitable VM. If your programme does not work,
check it carefully or test it with gcc in the sure knowledge that you
would need a roomful of magnetic core memory to do this!

The native OS/8 compiler implements a very limited version of C which is
nonetheless Turing complete. You could see it more as a simple scripting
system. It is actually typeless in that everything is a 12 bit integer
and any variable/array can interpreted as `int`, `char` or pointer.
However, all variables, functions and arrays must be declared `int`.

1.  There must be an `int main()` which appears as the last function.

2.  Arrays and variables may be local or global (implied static).

3.  Arrays may only be single indexed. See `PS.CC` for an example.

4.  Do not attempt to scope variables within a function. e.g. `for (int
    i=...`

5.  The only allowed digraphs are `++`, `--` (postfix only) and `==`.

6.  Comparison operators compare signed. Result is boolean true = -1.

7.  The `&`, &brvbar; and `!` operators are bitwise.

8.  See `libc.h` for allowed libc functions. There are 31.

9.  `atoi` is non-standard: `int atoi(char *,int *)`, returning
        the length of the numeric string.

10. `fopen` is implemented as `void fopen(char *filename, char *mode)`.
    The filename must be upper case. Mode is either "w" or "r".

    *   Only 1 input file and 1 output may be open at any one time

    *   `fclose()` only closes the output file.

    *   Call `fopen` to open a new input file. The current file does not
        need to be closed.

    *   `fprintf`, `fputc`, and `fputs` are as expected.

    *   `fgets` is implemented. It will read and retain CR/LF. It returns
        a null string on EOF.

    *   `fscanf` is not implemented. Read a line with `fgets()` and then
        call `sscanf` on it.

    *   `feof` is not implemented; `fgetc` and `fgets` will return a
        null on EOF.

11. `scanf` is not implemented; use `gets` then `sscanf`

12. `printf` is as expected. See `libc.c` for the allowed format
    specifiers: `%d`, `%s` etc. Length and width.precision formatting is
    supported.

13. Pointers are as expected. Do not try `*(<expr>)`. This does not
    work.

14. `struct` is not supported.

15. Double precision `int`, `float` etc. are not supported. If you need
    to do heavy duty maths, use Fortran.

16. The stack, which includes all globals and literals, is only 4k.
    Stack overflow is not detected.

17. Recursion is implemented. See `FIB.CC`.

18. Literals have to be included in the 4K limit programme area. These
    are copied into the stack at run time. This is due to the fact that
    ‘COMMON’ storage cannot be initialised.

19. There is no option for `#include` files. The available Libc
    functions are implicitly declared and listed in `libc.h` and `p8.c`.
    As a result, there is no arglist checking. Examine `libc.c` for
    details.


## OS/8 Specifics

1.  I strongly suggest you limit I/O to text files.

2.  Don’t forget to handle form feed.  See `c8.c`

3.  For some obscure reason, always open the input file first, then the
    output file. I suspect a fault in `libc.c`. Examine the code!!!!
    (Every trick in the book.)


## Preprocessor

The compiler distribution includes a pre-processor file (`c8.c` &rarr;
`CC0.SV`). This is a stub and merely asks for a filename and calls the
compiler chain. This file may be extended and used to process `#define`
`#include`, etc.

Compile using the cross-compiler to `c8.s`, copy to `C8.SB` under OS/8
on your PDP-8 target system, then:

    .COMP C8.SB
    .R LOADER
    *C8,LIBC/I/O$
    .SAVE SYS CC0
    .R CC0
    >                   enter filename and press Return
    .COMP CC.SB
    .R LOADER
    *CC,LIBC/G          if no file I/O; or...
    *CC,LIBC/I/O/G      ...if using file I/O

Try the examples in `*.CC` on `DSK:`. I personally like `PS.CC`,
Pascal’s triangle. This version does not require factorials, which are a
bit out of range for 12 bits!!

Try it with:

    .R CC0
    >PS.CC
    .COMP CC.SB
    .R LOADER
    *CC,LIBC/G


## Conclusion

This is a somewhat limited manual which attempts to give an outline of a
very simple compiler for which I apologise as the source code is obscure
and badly commented. However, the native OS/8 compiler/tokeniser
(`n8.c`) is only 600 lines which is a nothing in the scale of things
these days.  However, I hope this project gives some insight into
compiler design and code generation strategies to target a most
remarkable computer. I would also like to give credit to the builders of
OS/8 and in particular the FORTRAN II system which was never designed to
survive the onslaught of this kind of modern software.

Don’t expect too much! This compiler will not build this week’s bleeding
edge kernel. But, it may be used to build any number of useful utility
programs for OS/8.


## License

This document is under the [GNU GPLv3 License][gpl], copyright © May and
June 2017 by [Ian Schofield][ian], with minor updates by [Warren
Young][wy] in July 2017.

[gpl]: https://www.gnu.org/licenses/gpl.html
[ian]: mailto:Isysxp@gmail.com
[wy]:  https://tangentsoft.com/

This directory contains the sources for the CC8 cross-compiler, which is
based on Ron Cain's Small-C system.

It is built by the top-level build system as `bin/cc8` and is installed
to `$prefix/bin/cc8`.

Call it as:

    cc8 myfile.c

The compiler does not have any consequential command line options.

The output file is `myfile.s` which is in SABR assembly code, intended
to be assembled within the PiDP-8/I OS/8 environment. See the `test`
subdirectory and [the top-level README][/doc/trunk/cc8/README.md] for
further details.