_____ ____  ____   __      _ _
   |  ___|___ \| ___| / /_    | | |_   ___ __ ___        _ __ ___   ___  ___
   | |_    __) |___ \| '_ \   | | \ \ / / '_ ` _ \ _____| '_ ` _ \ / _ \/ __|
   |  _|  / __/ ___) | (_) |  | | |\ V /| | | | | |_____| | | | | | (_) \__ \
   |_|   |_____|____/ \___/   |_|_| \_/ |_| |_| |_|     |_| |_| |_|\___/|___/

          Welcome to LLVM-MOS for the Foenix F256 family of computers!


REQUIREMENTS
============

The compiler toolchain and utilites will run on recent versions of Windows,
Linux, and Apple Silicon MacOS.  There is currently no support for Intel MacOS.

On Windows, you will need:

  * WinRAR (https://www.rarlab.com/) or 7-Zip (https://www.7zip.com/) installed.
  * Python 3.x (https://www.python.org/) installed and in your PATH.


INSTALLATION
============

Download the appropriate installation script:

  * 64 bit Intel Windows:   f256-install-windows.bat
  * 64 bit Intel Linux:     f256-install-linux.sh
  * 64 bit ARM MacOS:       f256-install-macos.sh

Create a new, empty directory, with no spaces in the name (or in the names of
the parent directories) and place this file into it.  From that folder, execute
the script.  It will download additional dependencies and install them.  Aside
from some Python modules needed by FoenixManager, everything will stay inside
this new folder.  Uninstalling is just a matter of deleting it.


CONFIGURATION
=============

You will need to modify foenixmgr.ini in the main installation folder.  The
only thing that should need updated is the COM port used to communicate with
your F256.  See:  https://github.com/pweingar/FoenixMgr


ASSUMPTIONS
===========

This package was designed to be easy to use for new programmers.  As such, some
liberties were taken that aren't entirely common practice.  There are no
project files, makefiles, or other build configuration systems.  The included
f256build and f256run scripts assume you have arranged your code in directories
like the example programs.  The main requirement is that each program have its
own parent directory named for that program and inside it, a "src" directory
where the actual code lives.  Example:

  C:\FOENIX\CODE\MYPROGRAM\SRC

This would be a project named "MYPROGRAM" located in a CODE folder under the
folder you installed the toolkit in.  (You do not have to locate your projects
under the toolkit folder.)  To build this, you would run f256build from the
C:\FOENIX folder as follows:

  f256build code\myprogram

UNIX folks, flip your slashes!


USAGE
=====

As shown above, f256build is used to build projects using the default linker
settings.  If you do not have linker settings in your project already, the
defaults will be added (in a file named f256.ld in your project directory).
Unless you need to use embedded binary data in your project, the defaults are
all you need.  Embedded data examples are included.  See SPRITES and TILEMAP in
the EXAMPLES folder.  More details can be found in the f256lib documentation.

When building your project f256build will create a ".builddir" folder in your
project directory.  In here you will find copies of your source code that have
been modified by the overlay tool (for creating programs larger than 64k),
"trampoline" headers (again, generated by the overlay tool), intermediate
binary files, symbol listings, assembler source listings, memory maps,
additional linker information, and more.  These can be safely ignored or used
to assist in debugging your application.

To run your program on the F256 using a USB debug cable, use f256run just as
you did f256build.  Example:

  f256run code\myprogram

If you do not have a debug cable, you can copy the PGZ for your program from
its project directory to the SD card used in your F256.


SUPPORT
=======

Drop by the Foenix Retro Systems Discord!  https://discord.gg/e32efF7FGy  I am
almost always online as "sduensin".

Additional information on the F256 family of computers can be found on the F256
wiki:  http://wiki.f256foenix.com/

As a last resort, you can email me, Scott Duensing, at scott@kangaroopunch.com
and I'll probably ask you to join the Discord.  :-)