start.txt       14-Feb-2022

                             GETTING STARTED

This explains how to install and use the XPL0 language system on a
Raspberry Pi computer.

Begin by making a folder to hold the XPL0 files. From the graphical
desktop, click on the folder icon to start the File Manager. In the pi
folder, create a new folder called "myxpl" (or whatever you choose to
call it). To do this, near the upper-left corner, click on:

        File
        New Folder...
        type: myxpl
        click on OK

You should see the new folder appear in the window.

Download the xplrpi32.zip file. (It will appear in the pi/Downloads
folder.) Right-click on the zip file to Copy, and then Paste it into your
myxpl folder. In myxpl right-click on the zip file and select Extract
Here.

Click on the icon to start the Terminal program, then type "cd myxpl".
You should see a ~/myxpl $ prompt. Typing "dir" will verify that the
files are present.

To build and install executable versions of the compilers, type:

        chmod +x installxpl
        ./installxpl

(chmod changes the mode of the installxpl script so it can run.
installxpl compiles the compilers and copies them, along with their
required files, into the folders /usr/bin and /usr/include.)

At this point you have a working XPL0 compiler. Use it like this:

        x hello
        ./hello

You should see Hello, world! Don't run the other programs from the
graphical desktop, otherwise you might need to type "reboot" to regain
control of your display.


COMMAND LINE

XPL0 graphic programs must be run from a command-line prompt. The
Raspberry Pi operating system normally boots into a graphical desktop.
It's necessary to change this to boot to a command-line interface (CLI).
From the CLI you can always get back to the graphical desktop by typing:

        startx

From the graphical desktop, click on the raspberry icon and select
Preferences / Raspberry Pi Configuration. Change Boot: from Desktop to
CLI, then click OK. To get to the CLI, click on the raspberry icon and
select Shutdown, then click on Shutdown. Restart your computer by cycling
power.

If you're installing on a RPi 4, the legacy video driver might need to be
installed. The May 2020 version of the Buster OS comes with an
experimental driver that does not work with XPL0 graphics (nor with some
Linux commands). To install the legacy driver, from a command line (not
in X Windows) type: sudo raspi-config. Under Advanced Options select GL
Driver then select Legacy Original non-GL desktop driver. Reboot for the
change to take effect.


PROFILE

The commands below copy files that get executed each time the CLI is
started.

The Raspberry Pi OS does not come with .bash_profile, but if you've
already set one up, you might want to add some of the contents of this
.bash-profile to your existing file. It eliminates the need to type ./
each time you run a program from the CLI. It also enables extended ASCII
characters (128-255) like on the original IBM-PC. It also sets the
keyboard's auto-repeat rate to ten characters per second, like on the
original IBM-PC.

        cd myxpl
        cp .bash_profile /home/pi
        cp cp437-16.psf /home/pi
        reboot


TESTING

You can change the hello.xpl program using the nano editor like this:

        cd myxpl
        nano hello.xpl

Use the arrow keys to move the cursor to the word Hello and type Goodbye.
(When the Raspberry Pi OS starts, it can move the cursor to the left edge
of the screen when setting the date via an Internet connection.)

Press the Delete key five times to remove the word Hello, then type:

        Ctrl+X
        y<Enter>
        x hello
        hello

You should see Goodbye, world!

Try compiling and running some of the other programs, for instance:

        x mineswpr
        mineswpr

How fast can you clear the mine field without blowing yourself up?
Pressing any key exits the program.


OPTIMIZING COMPILER

The optimizing compiler generates programs that run up to four times
faster. It also enables tones for the Sound intrinsic. (If no sound then
sudo raspi-config Advanced Options can enable the 3.5mm jack.)

Use the xx script to compile programs to see how much faster they run
than with the x script, for example:

        xx xpong
        xpong


FEEDBACK

If you run into any problems or have any suggestions or comments, I'd be
very interested in hearing about them. Please contact me at:
loren.blaney@gmail.com

-Loren Blaney