A Docker image with the tools to develop Atari ST software in a modern environment.
Welcome to the Atari ST cross compiling docker image! This image has been created to provide modern developers with an easy and convenient way to write code for the Atari ST, a popular home computer released in the 1980s.
It contains a range of cross compiling tools that allow you to write both assembler and C code for the Atari ST. With this image, you can easily set up a development environment on any modern machine, eliminating the need to track down and configure the tools yourself.
Whether you're an experienced Atari ST developer or new to the platform, this image has everything you need to get started writing code for this classic computer.
-
vasmm68k_motis an assembler for the Motorola 68000 microprocessor following the Motorola guidelines. It is customization ofvasm, a portable multi-CPU and retargetable assembler to create linkable objects in various formats or absolute code. It can be used to convert assembly code into machine code that can be run on the Atari ST. -
vlinkis a portable linker, written in ANSI-C, that can read and write a wide range of object- and executable file formats. It can be used to link a specific target format from several different input file formats, or for converting, stripping and manipulating files. It takes object files produced by an assembler or compiler and combines them into a single executable file that can be run on the Atari ST. -
libcminiis a minimal version of the C standard library. It provides functions that can be called from C code to perform common tasks such as input/output and memory allocation. libcmini aims to be a small-footprint C library for the m68k-atari-mint (cross) toolchain, similar to the C library Pure-C came with. Many GEM programs do not need full MiNT support and only a handful of C library functions. By default, gcc compiled programs on the Atari ST platform link to mintlib. Mintlib aims to implement all POSIX functionality to make porting Unix/Linux programs easier (which is a very good thing to have). For small GEM-based programs, this comes with a drawback, however: program size gets huge due to the underlying UNIX compatibility layer. -
m68k-atari-mint-gccis a cross compiler to generate C code usable in an Atari ST platform. It allows you to write C code on a modern machine and produce object files that can be run on the Atari ST. It is based on the GNU Compiler Collection (GCC) and has been specifically tailored for use with the Atari ST. -
[A]tari [G]ame [T]oolsare a set of tools and code for rapid prototyping of Atari STE games. This version embeds the necessary libraries to compile an AGT project. -
Pythonin case you want to write helper scripts to automate your development process. -
autoconf,automake,libtool,pkg-configfor projects that use the GNU autotools build system.
These tools are all included in the docker image and are ready to use out of the box, making it easy for you to get started writing code for the Atari ST. Hopefully, I will be expanding the range of tools and resources available to developers who use the image in the future. By adding more tools, a more comprehensive and complete development environment for developers who are interested in writing code for the Atari ST will come.
In order to run a container image, a user will need to have the following:
-
A host machine: This is the physical computer or virtual machine where the container will be run. The host machine must be running an operating system that supports the use of containers, such as Linux, MacOS or Windows.
-
Container runtime: This is software that is responsible for running and managing containers on the host machine. Popular container runtimes include Docker and containerd. You can learn how to install the Docker Desktop in its site.
-
A command line interface (CLI): This is a tool that allows the user to interact with the host machine and container runtime using text-based commands. The CLI is typically used to manage and control containers, including pulling images, running containers, and viewing container logs.
The installation process will start executing the following script:
For Linux, MacOS or RPi
curl -sL https://github.com/sidecartridge/atarist-toolkit-docker/releases/download/latest/install_atarist_toolkit_docker.sh | bash
or as sudo
sudo bash -c "$(curl -sL https://github.com/sidecartridge/atarist-toolkit-docker/releases/download/latest/install_atarist_toolkit_docker.sh)"
For Windows
Download and run the native installer:
https://github.com/sidecartridge/atarist-toolkit-docker/releases/download/latest/install_atarist_toolkit_docker.cmd
The developer can download manually the installation scripts from:
Once the script is downloaded, the developer can execute it in the terminal of the Operating System.
For Linux, MacOS, RPi
chmod +x install_atarist_toolkit_docker.sh
sudo bash -c ./install_atarist_toolkit_docker.sh
For Windows
Run install_atarist_toolkit_docker.cmd from a Command Prompt.
The script will perform two actions:
-
Download the latest version of the Atari ST development toolkit docker image for your ARCH from the Docker Hub and install it in the available list of images in your Docker runtime.
-
Install the script
stcmdin the PATH of your machine. To access the commands of the image the developer will only need to invoke thestcmd.
Open a terminal in your Operating System, and enter the following command:
stcmd
ST_WORKING_FOLDER is empty: using /current/path as absolute path to source code working folder.
If you see the message above, congratulations! You have successfully installed the Atari ST development toolkit docker image. The message means that the optional environment variable with the working folder of your project is missing. We will explain in the next chapter how to configure it.
STCMD_QUIET: Suppresses the informational message aboutST_WORKING_FOLDERso non-interactive scripts stay clean. Set it to1in your shell profile if you prefer silent startup.STCMD_NO_TTY: Removes the-itflags from the underlyingdocker runcall. Set to1when runningstcmdfrom automation that has no TTY available (CI pipelines, cron, AI agents, etc.).
You will need a docker environment, space and a decent processor. If you plan to publish or tag images under your own Docker Hub account, pass your account via DOCKER_ACCOUNT, otherwise the default logronoide account will be used.
git clone git@github.com:sidecartridge/atarist-toolkit-docker.git
cd atarist-toolkit-docker
make DOCKER_ACCOUNT=myaccount clean build release
And if successful you will find the installer scripts in target/release/install_atarist_toolkit_docker.sh and target/release/install_atarist_toolkit_docker.cmd, plus a docker image, for example:
docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
logronoide/atarist-toolkit-docker-arm64 0.0.3 650b5a8d8b13 2 hours ago 942MB
logronoide/atarist-toolkit-docker-arm64 0.0.3-2024-10-03 650b5a8d8b13 2 hours ago 942MB
logronoide/atarist-toolkit-docker-arm64 latest 650b5a8d8b13 2 hours ago 942MB
...
logronoide/atarist-toolkit-docker-x86_64 latest 7496991add79 6 minutes ago 1.07GB
Local builds tag the current version and latest. Date-suffixed tags are created by make tag-images or make publish.
so install this script
sudo bash -c target/release/install_atarist_toolkit_docker.sh
On Windows, run:
target/release/install_atarist_toolkit_docker.cmd
Extensions are x86_64 for builds targeting 64-bit AMD/Intel x86 platforms and arm64 for 64-bit ARM platforms, including M-series Macs and Raspberry Pi.
The Publish workflow builds and pushes both x86_64 and arm64 images.
By default, the latest version will be installed, but if you would like to install a specific version you can specify this as a parameter, for example to install version 1.2.3:
sudo bash -c ./install_atarist_toolkit_docker.sh 1.2.3
To install a custom build from your own Docker repository, you can use the following syntax, replacing myaccount with your own:
sudo DOCKER_ACCOUNT=myaccount bash -c ./install_atarist_toolkit_docker.sh
And you can of course combine both to install a specific version of your own Docker repository:
sudo DOCKER_ACCOUNT=myaccount bash -c ./install_atarist_toolkit_docker.sh 1.2.3
The Docker image guarantees that all the needed libraries and dependencies are in one place and managed by the container. The container has its own file system, and the files that are created in the container are not accessible from the host machine, so the Atari ST development toolkit docker image creates a folder on the host machine and mounts it in the container. This folder will be the working folder of your project.
When you run the command stcmd you will have full access to an Atari ST development environment running inside the container. stcmd passes your user and group id down to the docker container. This should ensure files created by the docker will be owned by you after the container exits.
By default, the Atari ST development toolkit docker image automatically sets the current folder as the working folder of your project whenever you run stcmd.
If you prefer, you can override the default behavior by setting the environment variable ST_WORKING_FOLDER to the absolute path of the folder where your source code is located. If this environment variable is set, the Atari ST development toolkit docker image will always use this folder as the working folder of your project, regardless of where you run the stcmd command from.
If you have a project in the folder /home/user/my-st-megademo, you can set the environment variable ST_WORKING_FOLDER to the value /home/user/my-st-megademo:
export ST_WORKING_FOLDER=/home/user/my-st-megademo
or
cd /home/user/my-st-megademo
export ST_WORKING_FOLDER=`pwd`
Let's create a project in the working folder /home/user/my-st-megademo that contains a simple C program that prints a message in the screen. To do this, we will use the command stcmd gcc:
Copy the following code into a file called hello.c in the working folder /home/user/my-st-megademo:
#include <stdio.h>
void main()
{
printf("Hello World!\n");
printf("Press Enter");
getchar();
}And now run the following command to compile the C code into an Atari ST executable:
stcmd gcc hello.c -o hello.tos
Now we have our first Atari ST executable in the working folder /home/user/my-st-megademo. To run it, we need to use an emulator or a real Atari ST machine. My testing platforms is Hatari emulator, but there are more options. By default, gcc is a shortcut to the infamous gcc-m68k-atari-mint.
Let's create a project in the working folder /home/user/my-st-megademo-asm that contains a simple M68K assembler program that prints a message in the screen. To do this, we will use the command stcmd vasm:
Copy the following code into a file called hello.asm in the working folder /home/user/my-st-megademo-asm (I have copied the code from the awesome article and tutorials from François-Xavier Robin!):
; ---------------------------------------------------
; Hello, Bitmap Brothers! en assembleur pour Atari ST
; (inspiré du HelloWorld de Vretrocomputing, 2019.)
; Date : 02/2021
; ---------------------------------------------------
; -- DEBUT ----------------------------------------------------------------------
; affichage du message
PEA MESSAGE ; 4 octets sur la pile (PEA = PUSH EFFECTIVE ADDRESS)
MOVE.W #9,-(sp) ; 2 octets sur la pile (9 = affiche chaine)s
TRAP #1
ADDQ.L #6,sp ; ajustement de la pile 6 octets
; attente d'une touche
MOVE.W #8,-(sp) ; 2 octets sur la pile (8 = attente clavier)
TRAP #1
ADDQ.L #2,sp ; ajustement de la pile de 2 octects
; fin du processus, retour au GEM
CLR.W -(sp) ; 1 octet sur la pile
TRAP #1 ; pas de besoin d'ajuster
; -- FIN ------------------------------------------------------------------------
; -- EQUATES ------------------------------------
CR EQU $0D ; ASCII Carriage Return
LF EQU $0A ; ASCII Line Feed
ES EQU $00 ; Fin de chaine
EA EQU $82 ; E accent aigue selon la table ASCII
; -- EQUATES ------------------------------------
; -- DATA -----------------------------------------------
MESSAGE:
DC.B "Hello Bitmap Brothers!",CR,LF
DC.B "----------------------",CR,LF
DC.B "- Compil",EA," avec vasm sur Linux",CR,LF
DC.B "- Link",EA," avec vlink sur Linux",CR,LF
DC.B "----------------------",CR,LF
DC.B "<APPUYER SUR UNE TOUCHE>",CR,LF,ES
; -- DATA -----------------------------------------------And now run the following command to compile the M68K code:
stcmd vasm hello.s -o hello.o -Felf
vasm 1.9a (c) in 2002-2022 Volker Barthelmann
vasm M68k/CPU32/ColdFire cpu backend 2.5f (c) 2002-2022 Frank Wille
vasm motorola syntax module 3.16 (c) 2002-2022 Frank Wille
vasm ELF output module 2.7a (c) 2002-2016,2020,2022 Frank Wille
CODE(acrx2): 184 bytes
And now link the object file into an Atari ST executable:
stcmd vlink hello.o -bataritos -o hello.tos
In the demo folder of the github repository you can find some examples of Atari ST development with the Atari ST development toolkit docker image. To run the examples, you need to clone the repository first:
git clone git@github.com:sidecartridge/atarist-toolkit-docker.git
Navigate to the different projects inside the demo folder and execute stcmd make to build; if you have previously set ST_WORKING_FOLDER, run unset ST_WORKING_FOLDER to ensure that stcmd uses the current directory.
Currently we have ASM, C, C_ASM and C_LIBCMINI demos.
pushd demo/ASM
stcmd make
vasm src/hello.s -o obj/hello.o -Felf
vasm 1.9f (c) in 2002-2023 Volker Barthelmann
vasm M68k/CPU32/ColdFire cpu backend 2.6c (c) 2002-2023 Frank Wille
vasm motorola syntax module 3.18 (c) 2002-2023 Frank Wille
vasm ELF output module 2.7a (c) 2002-2016,2020,2022 Frank Wille
CODE(acrx2): 184 bytes
vlink obj/hello.o -bataritos -o build/hello.tos
Resulting in:
file build/hello.tos
build/hello.tos: Atari ST M68K contiguous executable (txt=184, dat=0, bss=0, sym=84)
popd
pushd demo/C
stcmd make
rm -f obj/* *~ core /*~
m68k-atari-mint-gcc src/hello_bb.c -o obj/hello_bb.tos -Iinclude
m68k-atari-mint-gcc src/hello_ge.c -o obj/hello_ge.prg -Iinclude -lgem
resulting in
file obj/hello_bb.tos
obj/hello_bb.tos: Atari ST M68K contiguous executable (txt=111148, dat=1588, bss=4052, sym=17795)
popd
pushd demo/C_ASM/
stcmd make
Makefile:65: warning: overriding recipe for target 'clean'
Makefile:56: warning: ignoring old recipe for target 'clean'
rm -rf ./build
rm -rf ./dist
mkdir -p ./build
m68k-atari-mint-gcc -c -std=gnu99 -I/freemint/libcmini/include -g ./src/main.c -o ./build/main.o
vasm -Faout -quiet -x -m68000 -spaces -showopt ./src/asm_functions.s -o ./build/asm_functions.o
message 2050 in line 21 of "./src/asm_functions.s": operand optimized: label->(d16,PC)
> PEA MSG_PREFIX ; Stack : 4 bytes (PEA = PUSH EFFECTIVE ADDRESS)
message 2054 in line 22 of "./src/asm_functions.s": branch optimized into: b<cc>.b
> BSR print_string
message 2050 in line 24 of "./src/asm_functions.s": operand optimized: label->(d16,PC)
> PEA MESSAGE ; Stack : 4 bytes
message 2054 in line 25 of "./src/asm_functions.s": branch optimized into: b<cc>.b
> BSR print_string
message 2050 in line 35 of "./src/asm_functions.s": operand optimized: label->(d16,PC)
> PEA MSG_PREFIX ; Stack : 4 bytes
message 2054 in line 36 of "./src/asm_functions.s": branch optimized into: b<cc>.b
> BSR print_string
m68k-atari-mint-gcc -c -std=gnu99 -I/freemint/libcmini/include -g ./src/fx_screen.c -o ./build/fx_screen.o
m68k-atari-mint-gcc /freemint/libcmini/lib/crt0.o \
./build/asm_functions.o \
./build/fx_screen.o \
./build/main.o \
-o ./build/test.tos -nostdlib -s -L/freemint/libcmini/lib -lcmini -lgcc -Wl,--traditional-format;
mkdir -p ./dist
cp ./build/test.tos ./dist
resulting in
file dist/test.tos
dist/test.tos: Atari ST M68K contiguous executable (txt=12252, dat=156, bss=32, sym=0)
popd
pushd demo/C_LIBCMINI
stcmd make
rm -rf out/*.tos
mkdir -p out
m68k-atari-mint-gcc -std=gnu99 -I/freemint/libcmini/include -nostdlib /freemint/libcmini/lib/crt0.o src/main.c -o out/main.tos -s -L/freemint/libcmini/lib -lcmini -lgcc
resulting in
file out/main.tos
out/main.tos: Atari ST M68K contiguous executable (txt=11232, dat=164, bss=72, sym=0)
popd
The Silly Demo is a sample demo created with the Atari ST development toolkit docker image. You can learn more about it in the The Silly Demo repository.
If you want to create games for the Atari STe, you can use the [A]tari [G]ame [Tools] (AGT). The Atari ST development toolkit docker image includes the libraries for AGT to run. You can learn more about it in the AGT or in this thread in the Atari forum: AGT - Atari Game Tools.
If you want to build one of the sample AGT projects, you need to clone the AGT repository first. Since the AGT is not very Linux friendly and the Docker image is based on Linux, I have created a fork of the AGT repository that includes the changes needed to support Linux. You can clone the repository with the following command:
git clone git@bitbucket.org:logronoide/agtools.git
Hopefully the changes are really simple and they will be merged into the original repository soon.
Now navigate to the demo folder of the AGT repository choose one of the sample projects and execute make to build. My favourite is the horizontal scrolling shooter game called h-shmup:
cd agtools/demo/h-shmup
All the projects need to setup the environment variable AGTROOT with the value of the absolute path of the AGT repository, but you don't need to do it because the Atari ST development toolkit docker image already does it for you. So, you can just execute stcmd to access to the environment of the container and run make to build the project:
stcmd make
After a few minutes the project will create a disk1 folder with the auto executable file and resources needed to run the game.
- Atari ST development toolkit docker image
- Atari ST development toolkit docker image source code
- Atari ST samples of cross development (French)
- The Atari ST MC68000 Assembly Language Tutorials
Thank you for your interest in contributing to this repository! We welcome and appreciate contributions from the community. Here are a few ways you can contribute:
-
Report bugs: If you find a bug in the code, please let us know by opening an issue. Be sure to include details about the error, how to reproduce it, and any possible workarounds.
-
Suggest new features: Have an idea for a new feature or improvement? We'd love to hear about it. Open an issue to start a discussion.
-
Contribute code: If you're a developer and want to contribute code to this project, here are a few steps to get started:
- Fork the repository and clone it to your local machine.
- Create a new branch for your changes.
- Make your changes, including tests to cover your changes.
- Run the tests to ensure everything is working.
- Commit your changes and push them to your fork.
- Open a pull request to this repository.
-
Write documentation: If you're not a developer, you can still contribute by writing documentation, such as improved usage examples or tutorials.
-
Share feedback: Even if you don't have any specific changes in mind, we welcome your feedback and thoughts on the project. You can share your feedback by opening an issue or by joining the repository's community.
We appreciate any and all contributions, and we'll do our best to review and respond to your submissions in a timely manner. Please note that all contributors are expected to follow our code of conduct (one day we will have one!). Thank you for your support!
This project is licenses under the GNU General Public License v3.0. See the LICENSE file for details.