HOW TO BUILD A LINUX DEB PACKAGE FOR GENERAL RELEASE
====================================================

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 native compile it on the target machine.  Follow the
instructions in the appropriate atari800/DOC file:

    INSTALL      - see Building the Emulator on most platforms
    BUILD.RPI    - specific instructions for the Raspberry Pi

Confirm that the compilation completes without error.

UPDATE CONFIGURATION FILE FOR PACKAGING
=======================================
Temporarily rename or move the existing configuration file (.atari800.cfg in
the home directory), then run atari800 to generate a new default file, and
copy it to /debian/atari800.cfg (note there is no '.' preceeding
'atari800.cfg').

This copy will placed in the package for reference.

Reinstate the original copy of .atari800.cfg

UPDATE DEBIAN CHANGELOG
=======================
Update file 'atari800/debian/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

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-1ubuntu1) UNRELEASED; urgency=medium

      *

     -- Cliff <cliff@Inspiron>  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

    -- Antonin Kral <A.Kral@sh.cvut.cz>  Sat, 04 Jul 2020 10:06:18 +0100

The version number '4.2.0-1' will be used as part of the name of the package
you are going to build.

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.

You should replace your default user information with the name and email
address of the current package maintainer, as identified in
debian/README.debian.


ADJUST BUILD OPTIONS IN THE DEBIAN RULES FILE
=============================================

CONFIGURATION OPTIONS
---------------------
The debian rules file 'atari800/debian/rules' contains the following command
(split over two lines):

	./configure \
		 --with-video=sdl --with-sound=sdl

You don't need to change this if your are building the stock SDL version.
Otherwise edit the second line to specify configuration options for the target
machine.  For example, the command required for the older Raspberry
Pis (Zero, 2 and 3) is:

	./configure \
		 --target=rpi

DOCUMENTATION FILE OPTIONS
--------------------------
If you wish to package any special documentation relating to the target
machine, add commands under this existing comment:

    # Install docs in proper directory and gzip them

or if the files are small and don't need gzipping, put them under this comment:

    # These are too small to gzip

For example, you might add the following command to copy README.RPI into
Raspberry Pi packages: 

    cp DOC/README.RPI debian/tmp/usr/share/doc/$(P)/README.RPI
   
BUILD THE PACKAGE
=================

    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.

The above 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_amd64.buildinfo - Checksums and a list of dependencies
                                       in the .deb file.
    atari800_4.2.0-1_amd64.changes   - Changelog update and checksums for
                                       the .deb and .buildinfo files.
    atari800_4.2.0-1_amd64.deb       - The .deb package file for release.

'amd64' indicates the architecture of the machine that the build was done on.

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.1.0-1_amd64.deb

TEST
====
Check that the atari800 command runs the emulator successfully:

    atari800

The command should also work with options, for example:

    atari800 -v
    atari800 -help
    man atari800

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

    sudo dpkg --remove atari800

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

RENAME THE PACKAGE
==================
The default names of packages are sometimes not very informative, but you may
change them to anything you like.

For example, the name of the 4.2.0 Raspberry Pi 4 package was changed from

    atari800_4.2.0-2_armhf.deb

to

    atari800_4.2.0_rpi4_buster.deb

ISSUE A PULL REQUEST TO UPDATE THE DEBIAN CHANGELOG
===================================================
Enter the new lines you created in atari800/debian/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.

This is a shortcut method.  It is quicker than distribution via the Debian
Project.

When a new release is announced on the Atari800 mailing list, anyone in the
community can follow the procedure described in this document and make it
available to users without delay.

DISTRIBUTION VIA THE DEBIAN PROJECT
===================================
Formal distribution via the Debian Project can only be performed by the
package maintainer, a listed Debian member.  The procedure is rigourous in
order to ensure the quality of the software.  Depending on how much free
time the maintainer has it may take many months to complete.

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.









