PiDP-8/I SoftwareCheck-in [c3f1846968]
Not logged in

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Assorted improvements to the top-level README.md file.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: c3f1846968811fb93c50bdeabec7a3e8b48c0d8977f7a3b2e105b984debd8a21
User & Date: tangent 2019-08-11 03:37:54
Context
2019-08-13
04:58
Clarified the tarball unpacking command in the top-level README.md. check-in: 74ae8b2240 user: tangent tags: trunk
2019-08-11
03:37
Assorted improvements to the top-level README.md file. check-in: c3f1846968 user: tangent tags: trunk
2019-08-09
10:57
Added link to "Fossil Versus Git" article from our HACKERS.md, near where we are making similar (but less detailed) arguments. check-in: 1be7a95d8e user: tangent tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to README.md.

48
49
50
51
52
53
54

















55
56
57
58
59
60
61
...
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
...
156
157
158
159
160
161
162
163
164
165
166
167
168
169

170
171
172
173
174



175
176
177







178




179

180
181
182
183







184
185
186
187
188
189































































































190
191
192
193
194
195
196
...
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
...
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
        $ sudo apt update
        $ sudo apt install build-essential libraspberrypi-dev \
             libncurses-dev python-pip
        $ 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 may skip this section, because you have
already achieved its aim.
................................................................................
    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
................................................................................

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

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


    $ make reconfig

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




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














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

For the most part, this is covered in the documentation linked from the







[Learning More](/#learning) section of the project home page.

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

































































































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

You can change many things about the way the software is built and
installed by giving options to the `configure` script:
................................................................................
switches on the front panel.  After you are done testing, you can start
the PiDP-8/I simulator back up with:

    $ pidp8i start

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


<a id="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
describes this software too, for the most part.

The largest user-visible difference between the two software
distributions is that many of the shell commands are different:

1.  To start the simulator running in the background:

        $ pidp8i start

    This will happen automatically on reboot unless you disable the
    service, such as in order to run one of the various [forks of Deeper
    Thought][dt2].

2.  To attach the terminal you're working on to the simulator:

        $ pidp8i

    (Yes, it's the same base command as above.  The `pidp8i` script uses
    its first argument to determine what you want it to do.  Without
    arguments, this is what it does.)

3.  To detach from the simulator's terminal interface while leaving the
    PiDP-8/I simulator running, type <kbd>Ctrl-A d</kbd>.  You can
    re-attach to it later with a `pidp8i` command.

4.  To shut the simulator down while attached to its terminal interface,
    type <kbd>Ctrl-E</kbd> to pause the simulator, then at the `simh>`
    prompt type `quit`.  Type `help` at that prompt to get some idea of
    what else you can do with the simulator command language, or read
    the [SIMH Users' Guide][sdoc].

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

        $ pidp8i stop

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


<a id="sshd"></a>
## Enabling the SSH Server on the Binary OS Images

The OpenSSH server is enabled and running by default on the PiDP-8/I
binary OS images, but for security reasons, the build process we use
to create these OS images wipes out the SSH host keys generated here
................................................................................

You may be wondering why we don’t do this automatically, somehow. It’s
because, over time, we’ve removed all dependence on root access in our
software in the name of security, so that we no longer have permission
to make system-wide changes like this in our startup scripts.  We now
rely on you, the system’s administrator, to do it interactively with
`sudo` permissions.


<a id="systemd" name="unit"></a>
## The systemd Unit File

Older stable releases of the PiDP-8/I software used an [old-style System
V init script][svinit] to start the PiDP-8/I service. This includes
Oscar Vermeulen's final stable release.

Starting with release v2019.04.25, we have now switched to a
[systemd][systemd] unit file, since Raspbian has been systemd-based for
years. (It also supports SysV init scripts, but only as a second-class
mechanism intended for backwards compatibility only.)

One of the features systemd gives us is the ability to set the unit
to run as user-level service rather than as a system-wide service,
which means you no longer need the `sudo` prefix on commands to start,
stop, restart, and query the service. The only time you now need root
privileges is when installing the software. After that, the software
runs under your normal user account, as do all of the commands you
use to manipulate the background simulator service.

As a result of these changes, none of these commands work any longer:

    $ sudo /etc/init.d/pidp8i start
    $ sudo service pidp8i stop
    $ sudo systemctl restart pidp8i

The correct forms, respectively, are:

    $ systemctl --user start pidp8i
    $ systemctl --user stop pidp8i
    $ systemctl --user restart pidp8i

These commands are long, so we have extended the `pidp8i` command to
build and run `systemctl` commands for you when you pass it arguments:

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

If you run it without arguments, it attaches to the GNU screen(1)
session, just as before.

The last command above shows that *all* arguments are passed to
`systemctl`, not just the first, so you can pass flags and such.

The service is still set to start at boot, just as before.

To disable the service so you can run something else against the
PiDP-8/I front panel hardware instead, such as Deeper Thought 2:

    $ pidp8i stop
    $ pidp8i disable

If you install this release on a system that has the old SysV init
script on it, that service will be disabled and removed before we
install and enable the replacement systemd user service.

[svinit]:  https://en.wikipedia.org/wiki/Init#SysV-style
[systemd]: https://www.freedesktop.org/wiki/Software/systemd/



## License

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








>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







|
<
<
<



<
<
<
<
|
|
|
|







 







|
|

|
|
|
|
>



<
|
>
>
>

<
<
>
>
>
>
>
>
>

>
>
>
>

>
|
|

<
>
>
>
>
>
>
>
|

<
<
<
<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<







 







<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<







48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
...
130
131
132
133
134
135
136
137



138
139
140




141
142
143
144
145
146
147
148
149
150
151
...
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183

184
185
186
187
188


189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205

206
207
208
209
210
211
212
213
214




215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
...
929
930
931
932
933
934
935












































936
937
938
939
940
941
942
...
952
953
954
955
956
957
958































































959
960
961
962
963
964
965
        $ sudo apt update
        $ sudo apt install build-essential libraspberrypi-dev \
             libncurses-dev python-pip
        $ sudo pip install pexpect

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


<a id="preparing"></a>
## Preparing Your Pi

If you have a working Raspberry Pi setup, you can probably just skip
ahead.

If you’ve just barely unpacked Raspbian onto an SD card and are now
trying to get the PiDP-8/I software distribution working on it, stop and
go through the [Rasbperry Pi documentation][rpd] first. At the absolute
minimum, run `raspi-config` and make sure the Localization settings are
correct. The defaults are for the United Kingdom, home of the Raspberry
Pi Foundation, so unless you live there, the defaults are probably not
correct out of the box.

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


<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 may skip this section, because you have
already achieved its aim.
................................................................................
    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, unpack it:




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





The file name will vary depending on what you downloaded and [how you
transferred it to the Pi](#transferring).  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
................................................................................

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, described
[below](#options).

Subsequent software updates and rebuilds should not require that you
re-run the `configure` step, even if you gave custom options. The build
system detects when the configuration is outdated and re-runs the
`configure` script with the same options. If for some reason that
automatic re-configuration fails, you can kick it off manually:

    $ make reconfig


The “`make`” step above will take quite a while to run, especially on
the slower Pi boards. The longest single step is building the OS/8 disk
packs from source media. Be patient; the build process almost certainly
isn’t frozen.



If you’re on a multi-core Pi, You can speed the build process up some by
running “`tools/mmake`” instead of directly calling “`make`”. It runs
Make in a mode that lets it do a lot of work in parallel, making better
use of your multiple CPU cores.  That OS/8 media rebuild step is choked
down to a single thread, though, so this won’t help with that.  (This is
a generic, portable script, so if you’re a software developer, feel free
to reuse `mmake` and `corecount` on your own systems.)

Only the `make install` step needs to be done via “`sudo`”.  For the
most part, we’ve tried very hard to minimize the places where you need
to use root privileges to get something done within the PiDP-8/I
software distribution.


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


After running “`sudo make install`” the first time, you will have to log
out and back in to get the installation’s “bin” directory into your
`PATH`.

For the most part, this software distribution works like the [old stable
2015.12.15 distribution][osd]. Its [documentation][oprj] therefore
describes this software too, for the most part. Beyond that, you might
find our [Learning More](/#learning) links helpful.





The largest user-visible difference between the two software
distributions is that many of the shell commands are different:

1.  To start the simulator running in the background:

        $ pidp8i start

    This will happen automatically on reboot unless you disable the
    service, such as in order to run one of the various [forks of Deeper
    Thought][dt2].

2.  To attach the terminal you're working on to the simulator:

        $ pidp8i

    (Yes, it's the same base command as above.  The `pidp8i` script uses
    its first argument to determine what you want it to do.  Without
    arguments, this is what it does.)

3.  To detach from the simulator's terminal interface while leaving the
    PiDP-8/I simulator running, type <kbd>Ctrl-A d</kbd>.  You can
    re-attach to it later with a `pidp8i` command.

4.  To shut the simulator down while attached to its terminal interface,
    type <kbd>Ctrl-E</kbd> to pause the simulator, then at the `simh>`
    prompt type `quit`.  Type `help` at that prompt to get some idea of
    what else you can do with the simulator command language, or read
    the [SIMH Users' Guide][sdoc].

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

        $ pidp8i stop

There are [other significant differences][mdif] between the old stable
distribution and this one. You’ll want to be familiar with that
documentation’s content before reading Oscar Vermeulen’s documentation,
as it still refers to his last release in December 2015.


<a id="systemd" name="unit"></a>
## The systemd Unit File

Starting with release 2019.04.25, the PiDP-8/I software distribution is
based on [systemd][systemd], since Raspbian is now on its third
systemd-based release.

One of the features systemd gives us is the ability to set the unit to
run as user-level service rather than as a system-wide service, which
means you no longer need the `sudo` prefix on commands to start, stop,
restart, and query the service. The only time you now need root
privileges when working with the PiDP-8/I software is when installing
it. After that, the software runs under your normal user account, as do
all of the commands you use to manipulate the background simulator
service.

As a result of these changes, none of these commands work any longer:

    $ sudo /etc/init.d/pidp8i start
    $ sudo service pidp8i stop
    $ sudo systemctl restart pidp8i

The correct forms, respectively, are:

    $ systemctl --user start pidp8i
    $ systemctl --user stop pidp8i
    $ systemctl --user restart pidp8i

These commands are long, so we have extended the `pidp8i` command to
build and run `systemctl` commands for you when you pass it arguments:

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

If you run it without arguments, it attaches to the GNU screen(1)
session, just as it always has.

The last command above shows that *all* arguments are passed to
`systemctl`, not just the first, so you can pass any flags that
`systemctl` accepts.

Our systemd service starts at boot by default after you install the
software. To disable the service so you can run something else against
the PiDP-8/I front panel hardware instead, such as Deeper Thought 2:

    $ pidp8i stop
    $ pidp8i disable

If you install this release on a system that has the old SysV init
script on it, that service will be disabled and removed before we
install and enable the replacement systemd user service.

[svinit]:  https://en.wikipedia.org/wiki/Init#SysV-style
[systemd]: https://www.freedesktop.org/wiki/Software/systemd/


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

You can change many things about the way the software is built and
installed by giving options to the `configure` script:
................................................................................
switches on the front panel.  After you are done testing, you can start
the PiDP-8/I simulator back up with:

    $ pidp8i start

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














































<a id="sshd"></a>
## Enabling the SSH Server on the Binary OS Images

The OpenSSH server is enabled and running by default on the PiDP-8/I
binary OS images, but for security reasons, the build process we use
to create these OS images wipes out the SSH host keys generated here
................................................................................

You may be wondering why we don’t do this automatically, somehow. It’s
because, over time, we’ve removed all dependence on root access in our
software in the name of security, so that we no longer have permission
to make system-wide changes like this in our startup scripts.  We now
rely on you, the system’s administrator, to do it interactively with
`sudo` permissions.

































































## License

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