PiDP-8/I Software

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

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


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

The PiDP-8/I software project is hosted using the [Fossil][fossil]
[distributed version control system][dvcs].  Fossil provides most of the
features of GitHub without having to put up with all of the complexities
of Git. In a lot of ways, Fossil is even simpler to use than Subversion.
See [Fossil Versus Git][fvg] for a well-balanced comparison of the
user-facing differences.

This guide will introduce you to some of the basics, but you should also
at least read the [Fossil Quick Start Guide][fqsg]. For a more thorough
introduction, I recommend [the Schimpf book][fbook]. If you have







questions about Fossil, you can ask on [the Fossil forum][ffor], where
I, your humble project maintainer, am active.




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

If you're starting from some other OS, Fossil won’t be installed by
default, but if it’s Debian-based (e.g. Raspbian) you can easily install
Fossil with:

    $ sudo apt install fossil

That command assumes you’re running it on a derivative of Debian Buster,
released in June 2019, or newer. Older Debian-based OSes shipped Fossil
1.x, which is too old to work with our Fossil repository. (We need 2.1
or higher.) You could dig up an old version of this document to learn
our workaround for that problem, but it’s better to upgrade to an OS
that includes a compatible version of Fossil.

Fossil is also available for all common desktop platforms.  One of [the

official binaries][fbin] may work on your system.



[bosi]:   https://tangentsoft.com/pidp8i#bosi
[fbin]:   https://fossil-scm.org/index.html/uv/download.html
[fvg]:    https://fossil-scm.org/fossil/doc/trunk/www/fossil-v-git.wiki
[dvcs]:   https://en.wikipedia.org/wiki/Distributed_revision_control
[fbook]:  https://www.fossil-scm.org/schimpf-book/home

[ffor]:   https://fossil-scm.org/forum/
[fossil]: https://fossil-scm.org/
[fqsg]:   https://fossil-scm.org/index.html/doc/trunk/www/quickstart.wiki


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

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


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

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

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

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

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

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

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

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

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

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

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

For more on this topic, see [Fossil Versus Git][fvg] in the Fossil
documentation.

[fvg]:   https://fossil-scm.org/fossil/doc/trunk/www/fossil-v-git.wiki
[gitwt]: https://git-scm.com/docs/git-worktree


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

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

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

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


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

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

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


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

The "[Forum][pfor]" link at the top of the Fossil web interface is for
discussing the development of the PiDP-8/I software only. All other
traffic should go to [the mailing list][ggml] instead.  We're not trying
to split the community by providing a second discussion forum; we just


think many development-related discussions are too low-level to be of
any interest to most of the people on the mailing list.








We used to relegate such discussions to private email, but that was not






out of any wish to hide what we're doing. We just didn't have a good
place to do this work in public until recently.











You can sign up for the forums without having a developer login, and you
can even post anonymously. If you have a login, you can [sign up for

email alerts][alert] if you like.






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



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



[alert]: https://tangentsoft.com/pidp8i/alerts


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

Creating a branch in Fossil is scary-simple, to the point that those

in a way that cooperates with the purpose of that branch.  The same is
true of `trunk`: you should not check something in directly on the trunk
that changes the nature of the software in a major way without
discussing the idea first.  This is yet another use for branches: to
make a possibly-controversial change so that it can be discussed before
being merged into the trunk.

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


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

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

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

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

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

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

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





























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

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

     $ ./configure --debug-mode




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

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

     auto.def
     autosetup/*
     configure
     Makefile.in

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




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

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

If you do not have Tcl installed on your system, `configure` builds a
minimal Tcl interpreter called `jimsh0`, based on the [Jim Tcl][jim]
project.  Developers working on the build system are encouraged to use
this stripped-down version of Tcl rather than "real" Tcl because Jim Tcl

is more or less a strict subset of Tcl, so any changes you make that
work with the `jimsh0` interpreter should also work with "real" Tcl, but
not vice versa.  If you have Tcl installed and don't really need it,
consider uninstalling it to force Autosetup to build and use `jimsh0`.

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