HOW TO BUILD A TWO-BINARY RASPBERRY PI PACKAGE FOR GENERAL RELEASE
==================================================================
Atari800 packages may be built for the Raspberry Pi as described in
DOC/BUILD.linux_package.  However, it is not possible to build a single
package that will run on all the different models of Pi this way.

This document describes how to build a two-binary package that supports
the full range of Pis.  It installs two commands:
    atari800rpi - runs a special RPi version for the low power Zero, 2 and 3
    atari800stk - runs the stock Linux version for the Pi 4 and 400

All the scripts and data files required for the build are in atari800/raspbian.

NOT A DEBIAN BUILD
==================
The Debian standard requires all software to be hardware independent, but
the atari800rpi binary uses libraries brcmGLESv2 and brcmEGL which
are specific to Broadcom chips.  So although Debian tools are
used for the build, the resulting package does not comply with the
standard, and cannot therefore be distributed via the Debian Project.
It can however be distributed via the Raspbian Team and the GitHub
releases area.

INSTALL PACKAGE DEVELOPMENT TOOLS
=================================
Ensure that you have the necessary tools installed:

    sudo apt-get install build-essential
    sudo apt-get install fakeroot
    sudo apt-get install devscripts

OBTAIN SOURCE CODE
==================
Download the latest release of the source code from the Github Releases Area
(https://github.com/atari800/atari800/releases).  Look for a file with a name
like 'atari800-4.2.0-src.tgz'.

Unzip the source code.  The contents will go into a directory called
'atari800-4.2.0' or similar, which will be referred to in these notes as the
'atari800' directory.

Do not obtain the source code by cloning the current atari800 repository
because this may have been modified since the last release, and may contain
partially developed and untested code.

COMPILE WITHOUT ERROR
=====================
Unzip the code and compile two versions as described in DOC/BUILD.RPI, one
for the Pi Zero, 2 and 3; and another for the Pi 4 and 400.  You can use
any model of Pi for both compilations. 

Confirm that the compilations complete without error.

UPDATE THE CHANGELOG
====================
Update file 'atari800/raspbian/changelog'.  You can simply edit this manually,
but the system is fussy about the exact format, location of spaces etc., so it
is handy to use the debchange command as follows.

Open a terminal on the atari800 directory.

    debchange -c raspbian/changelog

Select an editor from the presented menu.  Debchange guesses a new version
number and other details and enters some new lines into the log for you.  The
top of the file should look something like this:

    atari800 (4.2.0-1) UNRELEASED; urgency=medium

      *

     -- Cliff <cliff@Iota4>  Sat, 04 Jul 2020 10:06:18 +0100

Edit these lines as appropriate.  For example:

    atari800 (4.2.0-1) unstable; urgency=low

      * New upstream version 4.2.0

    -- Cliff Hatch <hatchcw@btopenworld.com> 
        Sat, 04 Jul 2020 10:06:18 +0100

The version number '4.2.0-1' will be used to construct the name of the
package.

Label the release 'unstable'.  This does not mean it is actually unstable,
just that no tests have been performed at this stage to prove otherwise.

You may add additional comments if you wish, on lines beginning with two
spaces and a '*'.

Set urgency to 'low', or 'medium' for major updates.

Enter your name and contact details.  In Debian releases the name of an
accredited Debian member (the package manager) belongs here, but this is not
a Debian release, so these details are informal, but nevertheless
useful because they provide a build record and a contact for enquiries.
   
BUILD THE PACKAGE
=================
The system expects to find build information in a directory called "debian",
not "raspbian", so some temporary renaming is necessary:

    mv debian debian_save
    mv raspbian debian

then build:

    dpkg-buildpackage -B -uc
Even though you started with a version of the source code that compiles without
error, it is possible that warnings and errors may be reported at this stage.
Warnings can usually be ignored, but you will have to investigate and correct
any errors.

If the build reports any missing libraries, libreadline7 for example, you
will need to install them and build again:

    sudo apt-get install libreadline7

Finally, restore the original directory names:

    mv debian raspbian
    mv debian_save debian

The dpkg-buildpackage command creates three files and places them in the
parent of the atari800 directory.  They will have names like these:

    atari800_4.2.0-1_armhf.buildinfo - Checksums and a list of dependencies
                                       in the .deb file.
    atari800_4.2.0-1_armhf.changes   - Changelog update and checksums for
                                       the .deb and .buildinfo files.
    atari800_4.2.0-1_armhf.deb       - The .deb package file.

RENAME THE GENERATED FILES
==========================
'armhf' in the generated file names indicates the architecture of the machine
that the build was done on.  It is set automatically, but it is not correct
in this case, because the build is Raspberry Pi specific and will not run
on all armhf machines.  Rename the files, substituting 'rpi' for 'armhf':

    atari800_4.2.0-1_rpi.buildinfo
    atari800_4.2.0-1_rpi.changes
    atari800_4.2.0-1_rpi.deb

INSTALL
=======
<Double Left Click> on the .deb file to install it.

or

<Right Click> and select the appropriate menu item, <Package Install> or
<Open with GDebi Package Installer> etc..

or use the command:

    sudo dpkg -i atari800_4.2.0-1_rpi.deb

TEST
====
Check that the atari800 command works.  It should produce a message telling
you about the atari800rpi and atari800stk commands.

Check that the atari800rpi or atari800stk command (whichever is appropriate
for the machine you are using) runs the emulator successfully:

These commands should also work with options, for example:

    atari800rpi -v
    atari800rpi -help
    man atari800rpi

UNINSTALL
=========
You can unistall the package if desired with:

    sudo dpkg --remove atari800

This removes the command and documentation, but leaves configuration file
.atari.cfg in place.

ISSUE A PULL REQUEST TO UPDATE THE CHANGELOG
============================================
Enter the new lines you created in atari800/raspbian/changelog into the master
of this file on Git, to keep the record intact.

DISTRIBUTION VIA THE GITHUB RELEASES AREA
=========================================
Send the three files created (.buildinfo, .changes and .deb) to the owner of
the Git repository (https://github.com/atari800/atari800).

The owner will post the .deb file to the releases area
(https://github.com/atari800/atari800/releases) for download by users.


DISTRIBUTION VIA THE RASPBIAN TEAM
==================================
Send the three files (.buildinfo, .changes and .deb) to the Raspbian team
(https://www.raspbian.org/RaspbianTeam) for distribution via the Raspberry Pi
repositories.

Packages distributed in this manner become available in official repositories.
Users may download and install them using the apt-get command or a software
manager.








