Native Atari development environment and sources

Contents:

Introduction
Atari C-compilers
AHCC setup for Hatari emulator
- Notes
VBCC setup for Hatari emulator
MiNT notes
- VBCC under Aranym/MiNT

Introduction

Below is some information about C-compilers available for Atari and instructions on how to install two of them for plain TOS. First one (AHCC) provides an IDE GUI and second (VBCC) is used from command line.

These instructions are geared towards using them within the Hatari emulator. That's why they're run on plain TOS as Hatari can in that environment emulate host file system for the Atari programs and "autorun" an Atari program on Hatari startup.

Hatari is available for most Linux distributions directly from their own repositories. Windows binaries are available from Hatari download page and OSX binaries are provided by Hatari users.

Atari C-compilers

There are/were several C compilers available for Atari ST/STE/TT/Falcon, both commerical and free. Best known of the commercial ones are Pure-C (Atari ST version of Borland Turbo C) and Lattice-C. Both of them provided GUI development environment and (I think) supported ANSI-C. There were (earlier) also some other compilers like Mark Williams C, Laser-C and a C interpreter from HiSoft.

The free C compilers that I know of and have tested at some point are GCC, vbcc, c89, SozobonX and AHCC. Still relevant and updated ones are (from largest/slowest to smallest/fastest):

GCC, the GNU Compiler Collection. Its Atari port is maintained by Vincent Riviere. GCC supports widest number of platforms, languages and their versions and it typically optimizes the code best, but doing those optimizations takes time, the resulting binaries can be very large and latest versions require Unix-like environment. This makes it best suited for cross-compiling Atari binaries.
vbcc (compiler) / vasm (assembler) / vlink (linker) support several smaller operating system and CPU architectures. Vbcc understands ANSI-C and a subset of C99. The toolchain itself doesn't support POSIX APIs (e.g. unistd.h), but one can use GCC libraries with it as long as they don't use floating point and headers have VBCC compatible syntax. Vasm assembler understands Devpac assembly syntax.
AHCC compiler is based on SozonbonX sources and is binary compatible to Pure-C compiler and its libraries. It supports ANSI-C and a subset of C99. There are separate binary versions for 68000, 68030 and ColdFire. Produced ColdFire binaries use CPU instruction subset that is compatible with 68020+ processors. Unlike with other compilers, floating point operations require an FPU, i.e. plain 68000 version doesn't support floating point at all. While the only code optimizations AHCC does are at assembly level and its headers miss things, it's the only free compiler with an IDE, it does full function prototype checking and the produced binaries are small. This makes it best suited for native Atari compiling.

The differences between the GCC/VBCC and AHCC compilers which can be visible in the sources are the default int size (in AHCC it's 16-bit, in GCC 32-bit) and how their Atari specific include files and libraries are named (osbind.h vs. tos.h, gem.h vs. vdi.h + aes.h).

While AHCC and VBCC work fine with plain TOS, GCC usage would really need a unix-like directory hierarchy and command line environment. On Atari latter requires MiNT, the multitasking Unix-like extension to the Atari TOS which was shipped as kernel for the MultiTOS operating system for the newer Atari machines (Falcon etc).

AHCC setup for Hatari emulator

Below you will find a ready-made package containing:

AHCC v4.14 C-compiler toolchain which includes its IDE, command line tools, headers and libraries. There are 68000, 68020+ and ColdFire versions of the binaries, the headers and libraries are common for all of these CPU variants
Digger v8 disassembler/IDE
Corresponding AHCC and Digger documentation in hypertext format, and ST-Guide v1.5 viewer for that
EmuTOS v0.8.7 512k ROM image and Hatari configuration file

(AHCC, Digger and EmuTOS are GPL v2 and latest versions as of 2012-10-15, ST-Guide is ancient "fairware". Both AHCC and Digger are by Henk Robbers.)

AHCC IDE, Digger and EmuTOS ROM (2.9MB)

After you've installed Hatari and extracted above tar.gz file, run the hatari-gui.sh script included in it.

That will change to the AHCC develepment directory, run Hatari from there with the included hatari.cfg configuration file and EmuTOS ROM, and asks Hatari to start the AHCC IDE.

If you drag (or otherwise give) the script its directory name, Hatari will just mount that directory as C: drive without running any programs. In that case, Hatari (actually EmuTOS, according to emudesk.inf configuration file) will open a window from which you can start AHCC IDE version suitable for your selected Atari machine type.

Programs in Atari desktop can be started by double clicking on their icons. In Hatari, mouse middle-click emulates double click and that works even if you're running Hatari in fast-forward mode (toggled with AltGr+X shortcut).

The different AHCC IDE programs are:

ahcc.prg: IDE for building 68020+ (TT/Falcon/clone) binaries. Binaries using floating point should be compiled with "-2 -8" (020+FPU) options and they won't work with (unmodified ST, STE and Falcon) machines that don't have FPU
ahccst.prg: IDE for building 68000 binaries that work on all 680x0 machines (ST/STE/TT/Falcon). Binaries compiled with this should link to 'i' (integer) version of a library when such is available as this AHCC version doesn't have any floating point support
ahcccf.prog: IDE for building ColdFire (FireBee) binaries. Binaries compiled with this should be compiled with the "-7" option and link to 'cf' (ColdFire) or 'f' version of a library when such is available

If you've linked hatari-gui.sh on your desktop, you can just drag an Atari program to Hatari icon on your desktop, to run that program in Hatari with the included development environment settings. Or you can give the program as argument to Hatari on console to see any error etc. messages, like this:

	hatari-gui.sh ./ahcc.prg

After experimenting a bit with the AHCC IDE, building the included "Hello World" program and viewing the AHCC documentation with ST-Guide (under "Desk" menu), you can check my Atari programs page for binaries and source code to some free GEM/monochrome games which I've either developed myself or ported to ANSI-C and AHCC.

Notes

AHCC shortcomings:

Provides only couple of POSIX functions like stat()
It's headers are a bit of a mess, you can run into corner-case issues with them (e.g. HUGE_VAL doesn't seem to be correct in math.h)
32-bit ints aren't fully supported and sources from other platforms typically don't work properly with 16-bit ints. I'd recommend using AHCC only for Atari programs or things written from scratch
Doesn't optimize code much, so code is slower than with the other compilers. That is compensated by the small size of the produced binaries and fast compilation speed
Only partial support for C99, main shortcoming is probably lack of "inline" as that has been supported by mainline compilers for decades and is therefore widely used in sources

Hatari settings used by the included configuration file are suitable only for running text programs and resolution independent GEM programs, not games or demos because settings use a (larger) non-standard VDI graphics resolution. To run other kind of Atari programs, run Hatari directly without the script and the included hatari.cfg file.

While AHCC project files (which tell AHCC how to build the binaries from sources) are independent of any Hatari options, the AHCC specific Makefiles which I've included for automating AHCC building outside of Hatari expect:

files created within Hatari to be in lower case
hmake.sh script which forces this with the Hatari --gemdos-case lower option, but that needs newer Hatari version than v1.6.2
gulam.prg Atari program to be (linked into) the same directory where the hmake.sh script is

hmake.sh script uses Hatari and Gulam to do the building and will overwrite its gulam.g startup script for this purpose. Because of this, it's better if you don't mix AHCC setup with the VBCC setup below.

(I'd recommend you just to use the *.PRJ project files from AHCC IDE, instead of using AHCC from command line.)

VBCC setup for Hatari emulator

Below you will find a ready-made package containing:

VBCC toolchain TOS version with target files for building both m68k and ColdFire binaries
Corresponding VBCC documentation in PDF format (in doc-subdirectory)
GCC build of GEMlib library for m68k, needed for building GEM programs
Ancient GNU Make v3.58 which is buggy, but works with plain TOS (latest one would like to use pexecv() which is only available under MiNT)
Some tools for handling object archives and modifying binary settings (load flags, stack size etc) which are extracted from the mintbin RPM package at Sparemint
Gulam shell v1.03 (beta) which has crammed into a <100KB binary a fairly full featured shell with command line completion, small versions of most POSIX shell utils and a MicroEmacs text-editor
EmuTOS v0.8.7 512k ROM image and Hatari configuration file

(EmuTOS, GNU make, binutils and mintbin tools are GPL, but may link statically code that has other open source licenses, see MiNTlib license information for details. VBCC and Gulam are freeware for non-commercial use.)

VBCC toolchain, GNU Make, Gulam shell, tools and EmuTOS ROM (3.1MB)

After you've installed Hatari and extracted above tar.gz file, run the hatari-cli.sh script included in it.

That will change to the AHCC develepment directory, run Hatari from there with the included hatari.cfg configuration file and EmuTOS ROM, and asks Hatari to start the Gulam shell with which you can build your programs.

After you've added some source code, you can "cd" to its subdirectory and build it with "make" command, if source has a Makefile for that. Many of the programs on my Atari programs page contain Makefiles for several different compilers. In that case you need to specify "make" which one to use:

	make -f makefile.vbcc

If there's a single Makefile, it's VBCC support may be enabled with:

	make CC=vc

For more info on "make" and other tools included to the package's bin/-directory, see the manual pages on your Unix host for the corresponding tools, or call them with -h or --help option.

VBCC usage

VBCC has a frontend similar to "gcc", called "vc". You call "vc" and it calls the backend compiler, assembler and linker binaries with appropriate options, when needed, based on the given argument file name/type. Options for the binaries called by "vc" are set up in VBCC config files that reside in the vbcc/config/ directory.

To use a different compiler configuration, you don't specify options for the backend binaries, but give "vc" the name of the configuration file where these are set up, prefixed with "+". For example "+cf" for ColdFire compilation.

"vc" frontend supports similar basic options (-Ox, -v) as "gcc". For more on information, see the PDF documents in vbcc/doc/-directory.

Gulam usage

While Gulam is fairly similar to POSIX compatible shells on e.g. Linux, it's much earlier and has some gotchas. Its commands have only few options, keyboard layout is american and doesn't support numeric keyboard etc.

Gulam shell supports directory & filename TAB completion and command line editing. Some keyboard shortcuts (that work also in Linux shells):

Ctrl-A: go to beginning of line
Ctrl-E: to to end of line
Ctrl-D: delete char that is under cursor
Ctrl-K: remove text from cursor to end of line
Ctrl-W: remove word left of cursor
Ctrl-Y: paste ("yank") last removed text at cursor

Ctrl-A and Ctrl-E are useful because moving past line endpoints will in Gulam give you next/prev line in history ring buffer instead of stopping.

Although Gulam doesn't support multitasking, you can "suspend" the 'ue' editor with ^Z to go to shell and run other commands and then use 'fg' command to get back into editor.

For more information, see the gulam/gulamdoc/gulam.inf text document.

VBCC / Gulam shortcomings

VBCC shortcomings:

Its standard library doesn't provide any POSIX functionality; no unistd.h, no stat(), many functions don't set errno and their error return value may be any negative value, not just -1 like with POSIX... I.e. rely on "The C programming language" instead of Linux man pages when coding with this
Doesn't support ColdFire floating point instructions (subset)
Small data mode (enabled with '+tos16') doesn't work with the (MiNT tools compatible) a.out format
No support for GCC extensions. Before porting code working with GCC to VBCC, it's better to fix issues reported by GCC when using "-pedantic" option (e.g. empty array initializer produces internal VBCC compiler error)
Code generation has some bugs, especially with optimizations:
- Struct copies do unaligned accesses on 68000
- "regsused" assembly directive does mark given registers as something which contents are overwritten by the inline assembly, all registers besides a0/a1/do/d1 need to be explicitly stored/restore
- Passed double/longlong arguments aren't correctly marked as overwritten when one of the registers in the register pair used for passing 8 byte (double/longlong) argument is stated to be a scratch register with -scratch option in compiler options or configuration

Gulam shortcomings:

Not everything in the Makefiles included with my programs work under TOS And Gulam. For anything else than building the binaries, which is done by invoking "make" without giving Makefile target, I would suggest doing the same outside of Hatari or under MiNT setup. For example this:
```
make clean
```
Gulam works properly only with single TOS, it does some dirty tricks that don't work with MiNT. Use a normal Unix shell like Bash and GNU tools under MiNT.

MiNT notes

Later on I might consider make another package containing MiNT kernel, basic command line utilities, GCC toolchain, at least MiNT + GEM libraries and RPM package management, which one could convert into a harddisk image with Hatari atari-hd-image script. However, that would be a much larger package, even with no Perl and locale data remove it's nearly 80MB uncompressed (because MiNT doesn't support shared libraries).

In the meanwhile, please look into ARAnyM / AFROS or other readymade Aranym setups. Unfortunately those have mainly just MiNT and multitasking AES + corresponding Aranym setup, they're are missing the GCC toolchain and most of unix setup necessary for building software, but you can get those with above rpm2cpio trick.

For more information on MiNT today, see information on FreeMiNT (kernel) and SpareMiNT (distribution), and XaAES (multitasking AES).

VBCC under Aranym/MiNT

To use this same VBCC setup under MiNT, you just need to move or link the 'vbcc' directory under Aranym's directory mount and export VBCC variable pointing to 'vbcc' directory. VBCC variable you can set in mint.cnf with:
```
setenv VBCC c:\vbcc
```
or in (Bourne) shell with:
```
export VBCC="c:\vbcc"
```
Symlinking 'vc' to a directory in PATH makes its usage more convenient:
```
cd /usr/bin
ln -s /c/vbcc/bin/vc.ttp
```
Included TOS version of GNU Make is very buggy. If you need to do larger compilations, use the same VBCC setup under Aranym/MiNT with latest GNU Make MiNT version: http://sparemint.org/sparemint/html/packages/make.html
MiNT utilities like flags(.ttp) are from the binutils and mintbin RPM packages at Sparemint, extracted like this:
```
$ for pkg in binutils-2.20.1-1.m68kmint.rpm mintbin-0.3-4.m68kmint.rpm; do
  rpm2cpio $pkg | cpio -v -i -m -d --no-absolute-filenames --no-preserve-owner
  done
```
If those binaries are TOS compatible (unlike latest Make), you can make them runnable under TOS and Gulam just by renaming them:
```
$ cd usr/bin/
$ for bin in *; do mv $bin $bin.ttp; done
```

VBCC toolchain running under Aranym AFROS