_____ ____ ____ __ ____
| ___|___ \| ___| / /_ | _ \ _____ __
| |_ __) |___ \| '_ \ | | | |/ _ \ \ / /
| _| / __/ ___) | (_) | | |_| | __/\ 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.
MacOS and Linux:
* Ensure you have Python 3.x installed.
INSTALLATION
============
Download the appropriate installation script:
* 64 bit Intel Windows: f256-install.bat
* 64 bit Intel Linux: f256-install.sh
* 64 bit ARM MacOS: f256-install.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
UPGRADING
=========
Just re-run f256-install!
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!
f256build.sh code/myprogram
USAGE
=====
As shown above, f256build is used to build projects using the default linker
settings.
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.
TIPS
====
* Do NOT edit anything in the f256dev directory! It gets replaced on updates!
* Do NOT add anything under the f256dev directory! It gets nuked on updates!
* Create a "code" directory in the folder you copied f256-install into. Put
your F256 projects in directories under "code" for easy bulding!
* EMBED(); arguments must be literals. You cannot use #defines or variables.
* EMBED(); names (first argument) must begin with unique prefixes. For example,
"TILES" and "TILES_PALETTE" will cause an error due to "TILES" being a
complete substring of "TILES_PALETTE".
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. :-)
HISTORY
=======
* 19-JUN-2024 - PDF and AsciiDoc manual added to package.
* 25-MAY-2024 - Everything now installs into a single folder for safe updating.
Linker scripts not added to projects by default any longer.
* 09-MAY-2024 - Updated MacOS and Linux installation script to also search for
'pip3' as well as 'pip'.
* 01-MAY-2024 - Initial release for Linux, MacOS, and Windows.
