Installing:

You will need a (cross-)GCC toolchain for TOS/MiNT.
Currently, the only supported one is Vincent Rivière's m68k-atari-mint tools:
http://vincent.riviere.free.fr/soft/m68k-atari-mint/
Other toolchains, such as the old one from SpareMiNT, may also work, too.
You will also need GNU make (tested with make 4.2.1).

Building EmuTOS
===============

To build, first do:

    make help

This will display the list of all possible targets.

To build the standard etos512k.img, do

    make 512

To build EmuTOS for a different default country (changes the language and the
keyboard), do

    make 512 COUNTRY=en
or
    make 512 COUNTRY=fr
or
    make 512 COUNTRY=de

NOTE: by specifying COUNTRY=xx, all countries are included in the binary,
but a flag in the TOS header will indicate country 'xx'. If, however, the
EmuTOS image is booted on an emulator featuring NVRAM emulation (such as
ARAnyM), the country number in the NVRAM will override that setting of the
country in the TOS header.

To build EmuTOS for a single country only, you must use UNIQUE instead of
COUNTRY. This is mainly useful for the 192 and 256 KB targets. Example:

    make 256 UNIQUE=fr

Many options are set via the configuration file include/config.h.  They can
be overridden most easily via #defines in a user-created file localconf.h.

A complete list of targets
==========================

EmuTOS binaries
---------------

192         etos192k.img, EmuTOS ROM padded to size 192 KB (starting at 0x00fc0000)
256         etos256k.img, EmuTOS ROM padded to size 256 KB (starting at 0x00e00000)
512         etos512k.img, EmuTOS ROM padded to size 512 KB (starting at 0x00e00000)
aranym      emutos-aranym.img, suitable for ARAnyM
firebee     emutosfb.s19, to be flashed on the FireBee
firebee-prg emutos.prg, a RAM tos for the FireBee
amiga       emutos-amiga.rom, EmuTOS ROM for Amiga hardware
amigakd     emutos-kickdisk.adf, EmuTOS as Amiga 1000 Kickstart disk
amigaflop   emutos.adf, EmuTOS RAM as Amiga boot floppy
amigaflopvampire emutos-vampire.adf, EmuTOS RAM as Amiga boot floppy optimized for Vampire V2
amigavampire     emutos-vampire.rom, EmuTOS ROM for Amiga optimized for Vampire V2
v4sa        emutos-vampire-v4sa.rom, EmuTOS ROM for Amiga Vampire V4 Standalone
m548x-dbug  emutos-m548x-dbug.s19, EmuTOS-RAM for dBUG on ColdFire Evaluation Boards
m548x-bas   emutos-m548x-bas.s19, EmuTOS-RAM for BaS_gcc on ColdFire Evaluation Boards
m548x-prg   emutos.prg, a RAM tos for ColdFire Evaluation Boards with BaS_gcc
prg         emutos.prg, a RAM tos
flop        emutos.st, a bootable floppy with RAM tos
cart        etoscart.img, EmuTOS as a diagnostic cartridge

Binary targets modifiers
------------------------

nothing     same as COUNTRY=us
COUNTRY=xx  all countries in the binary, country xx being the default
UNIQUE=xx   a smaller binary with only support for country xx
DEF='-DSOMEDEFINE=value'
            used to override the default settings from include/config.h.
            WARNING: do "make clean" first.

Utility targets
---------------

bugready    for translations: sets up files in preparation for 'bug update'

Debug targets
-------------

dsm         dsm.txt, an edited disassembly of emutos.img
*.dsm       disassembly of any .c or almost any .img file

Git-related targets
-------------------

depend      generates dependencies
clean       cleans all generated files
charset     check the charset of all the source files
crlf        convert all end-of-lines to LF
expand      expand tabs to spaces
gitready    ensure the files have a proper format for Git (same as 'make crlf expand')
checkindent try 'indent' without altering the files
indent      indent all files - never done yet :-(

Release-related targets
-------------------

all192      all 192 KB images
all256      all 256 KB images
allprg      all emutos*.prg
allflop     all emutos*.st
release     build the release archives into release-archives


STonX-specific notes
=======================

EmuTOS now no longer needs changes to STonX. It will run on a normal STonX.

But, if you want to see debugging output in STonX, you need to do two
things:

1. implement a write_native function in gemdos.c of STonX:

    /* Print string from emulated side */
    void write_native(char * addr)
    {
        char buf[1024];
        int n;

        for(n = 0 ; n < 1023 ; n++) {  /* Fill string char by char */
            if ( (buf[n]=LM_UB(MEM(addr++))) == 0) break;
        }
        buf[1023] = 0;
        fprintf(stderr,"%s", buf);
    }

    void call_native(UL as, UL func)
    {
    #if 0
        fprintf(stderr,"Calling native %d\n",func);
    #endif
        switch (func)
        {
        case 0: /* Get the address, where string begins*/
            write_native((char *)LM_UL(MEM(as)));
            break;
        case 1:
    ...

(STonX release 0.8.0 and later already has this function)

2. Switch on STonX debugging output by setting STONX_NATIVE_PRINT to 1
   before building EmuTOS. Do this by creating a file called localconf.h
   (in the same folder as the EmuTOS Makefile) with one line:
   #define STONX_NATIVE_PRINT 1


Good luck!

-- 
The EmuTOS development team
http://emutos.sourceforge.net/