RASPBERRY PI SYSTEM REQUIREMENTS
================================
See README.RPI for system requirements.

PRELIMINARY
===========
Open a terminal on the directory containing your atari800 files.

CREATE THE CONFIGURE FILE
-------------------------
Ensure that you have autoconf installed:

    sudo apt-get install autoconf

Create the configure file:

    ./autogen.sh

See INSTALL for further details.


NATIVE COMPILE ON THE RASPBERRY PI
==================================
Ensure the SDL development files are installed:

    sudo apt-get install libsdl1.2-dev

Configure and make:

    ./configure --target=rpi
    make

Make generates the executable file src/atari800.


CROSS COMPILE FOR THE RASPBERRY PI
==================================

Cross compilation is only useful for major development projects involving
repeated compilation of large volumes of code.  For minor changes it is
much quicker and easier to native compile.

To cross compile you need the linaro-gnueabihf toolchain.  This can be
obtained from GitHub or from official software sources on some versions
of Linux.  Procedures for both are given below.

Wherever you obtain the toolchain there is no guarantee that it will be fully
compatible with the latest version of Raspbian.  You may have to copy some
missing files from the Pi into the toolchain.  The procedure is described
below.


COMPILE WITH THE LINARO TOOLCHAIN FROM GITHUB
=============================================

INSTALL
-------
The following command installs the toolchain in ~/RaspberryPi/Tools, but
you can alter the pathname to put it anywhere you like:

    git clone https://github.com/raspberrypi/tools ~/RaspberryPi/Tools


TOOLCHAIN BIN, INCLUDE AND LIB DIRECTORIES
------------------------------------------
Take note the location of the bin, include and lib directories for later
reference.  If you are using a 32 bit system they are in the following
directory:

    ~/RaspberryPi/Tools/arm-bcm2708/gcc-linaro-arm-gnueabihf-raspbian/
        arm-linux-gnueabihf

If you are using a 64 bit system they are in:

    ~/RaspberryPi/Tools/arm-bcm2708/gcc-linaro-arm-gnueabihf-raspbian-x64/
        arm-linux-gnueabihf

COPY THE SDL LIBRARY, INCLUDE AND CONFIG FILES INTO THE TOOLCHAIN
-----------------------------------------------------------------
See COPY SDL FILES below for details.

CONFIGURE AND COMPILE
---------------------
Place the following commands in a bash script called compile_rpi or
something similar, and place it in your atari800 directory .  You can then execute
the script with ./compile_rpi.  Note you will have to substitute your own
version of PATH (that is your normal PATH with the toolchain’s bin directory
tagged on the end), also your own version of RPI_SDK.  The exported symbols
apply only to the process executing the script and will not disrupt the
normal setup of your machine.

    export PATH=/home/cliff/bin:/home/cliff/.local/bin:/usr/local/sbin:
        /usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:
        /home/cliff/RaspberryPi/Tools/arm-bcm2708/
        gcc-linaro-arm-linux-gnueabihf-raspbian-x64/bin
    export RPI_SDK=/home/cliff/RaspberryPi/Tools/
        arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian-x64/
        arm-linux-gnueabihf
    ./configure --target=rpi --host=arm-linux -with-sdl-prefix=$RPI_SDK
    make

Make generates the executable file src/atari800.

Your system might not have all the required files in place at this stage, in which
case configure or make will fail and report any files that are missing.  Copy the
missing files from the Raspberry Pi into the toolchain (see MISSING FILES below
for guidance).  Rerun the script until it completes without error.

RUN
---
Copy the generated atari800 file to the Raspberry Pi, adjust its properties
to give execution permission to anyone and run it.


COMPILE WITH THE LINARO TOOLCHAIN FROM LINUX SOURCE
====================================================
These instructions relate to Ubuntu based Linux Mint v18.3.  The Linaro toolchain
is available as a cluster of applications from the official software source.

INSTALL
-------
    sudo apt-get install libc6-dev-armhf-armel-cross
    sudo apt-get install libc6-armhf-armel-cross
    sudo apt-get install build-essential
    sudo apt-get install g++-arm-linux-gnueabihf
    sudo apt-get install gdb-multiarch

TOOLCHAIN BIN, INCLUDE AND LIB DIRECTORIES
------------------------------------------
Take note of the location of the bin, include and lib directories for later
reference.  They are in:

    /usr/arm-linux-gnueabihf

In the next steps you need to copy files into this directory.  You will need
root access to do this.

COPY THE SDL LIBRARY, INCLUDE AND CONFIG FILES INTO THE TOOLCHAIN
-----------------------------------------------------------------
See COPY SDL FILES below for details.

CONFIGURE AND COMPILE
---------------------
Place the following commands in a bash script in your atari800 directory called
compile_rpi or something similar.  You can then execute the script with
./compile_rpi.  The exported symbol RPI_SDK applies only to the process
executing the script and will not be retained on your machine.

    export RPI_SDK=/usr/arm-linux-gnueabihf
    ./configure --target=rpi --host=arm-linux –with-sdl-prefix=$RPI_SDK
    make

Make generates the executable file src/atari800.

Your system might not have all the required files in place at this stage, in which
case configure or make will fail and report any files that are missing.  Copy the
missing files from the Raspberry Pi into the toolchain (see MISSING FILES
below for guidance).  Rerun the script until it completes without error.

RUN
---
Copy the generated atari800 file to the Raspberry Pi, adjust its properties
to give execution permission to anyone and run it.


COPY SDL FILES
==============
Copy the following from the rpi into the toolchain’s lib directory:
    file    /usr/lib/arm-linux-gnueabihf/libSDL-1.2.so.0.11.4  (or later version).

Create a symbolic link called libSDL.so to the copied file in the lib directory.

Copy the the following from the rpi into the toolchain’s include directory:
    directory   /usr/include/SDL

Copy the following from the rpi into the toolchain’s bin directory:
    file        /usr/bin/sdl-config

Ensure permissions are relaxed on sdl-config to allow it to be executed.


MISSING FILES
==================
The list of missing files will vary with different versions of Raspbian and
the toolchain.  These notes relate to Raspbian Stretch 7th Sep 2017 and the
Linaro Toolchains obtained from GitHub and the Linux Mint 18.3 repository in
July 2018.

Copy the following from the rpi into the toolchain’s lib directory:
    file        /opt/vc/lib/libbcm_host.so
    file        /opt/vc/lib/libbrcmEGL.so
    file        /opt/vc/lib/libbrcmGLESv2.so

Copy the following from the rpi into the toolchain’s include directory:
    file        /opt/vc/include/bcm_host.h
    directory   /opt/vc/include/EGL
    directory   /opt/vc/include/GLES2
    directory   /opt/vc/include/interface
    directory   /opt/vc/include/KHR
    directory   /opt/vc/include/vcinclude


