3. Tutorial

This chapter shows how to build and run a simple “Hello World” application on different targets.

The command line examples offer a clear understanding of the process. Tools can also be used with an IDE, but setup varies.

Beyond the Calypsi C compiler tool chain, you will need Make to control builds and Git to obtain projects. An internet connection is also required to download example projects.

3.1. Simulator

The db65816 contains a simulator mode which is enabled by default. It mimics the 65816 architecture and allows the application to run on your host machine.

From a terminal or command line, copy the example project from the internet using:

$ git clone https://github.com/hth313/Calypsi-65816-hello-world.git --recurse-submodules

Change to the newly cloned project directory:

$ cd Calypsi-65816-hello-world

Build the project with:

$ make
cc65816 --core=65816 --code-model=large --data-model=small --debug --list-file=obj/main-debug.lst -o obj/main-debug.o src/main.c
ln65816 --debug -o hello.elf obj/main-debug.o linker-large-small.scm clib-lc-sd.a --list-file=hello-debug.lst --cross-reference --rtattr printf=reduced --semi-hosted

This will create an output file hello.elf. To run the application you can load it into the debugger using:

$ db65816 hello.elf
Calypsi debugger for 65816
(db65816)

By default, the debugger enters interactive command mode. Run the application using the run command:

(db65816) run
running
Hello World!
program exited normally
(db65816)

When you are done with the debugger, you can leave it using the quit command:

(db65816) quit
$

You can also run the program directly from the command prompt, without entering interactive mode. You need to provide the debugger with additional command-line options to run and terminate automatically:

$ db65816 hello.elf -e run --terminate-on-program-exit
Calypsi debugger for 65816
run
running
Hello World!
program exited normally
$

This tells the debugger to execute the command run and that termination of the application also means termination of the debugger.

3.2. C256 Foenix U

This section shows how to build the “Hello World” application for a C256 Foenix U and run it on hardware.

This means you need to have access the actual hardware, but it may be possible to use a C256 emulator as well.

The the Calypsi C compiler tool chain generates ELF/DWARF by default, but this is not supported by the C256 Foenix kernel. To create an application suitable to run on the Foenix, the linker need output the application in the PGZ format. The provided Makefile is already configured to do this.

If you have not previously cloned the project, you can do so using:

$ git clone https://github.com/hth313/Calypsi-65816-hello-world.git --recurse-submodules

Change directory to the just cloned project:

$ cd Calypsi-65816-hello-world

When you are standing in the project folder, you can build the application for the C256 Foenix using:

$ make hello.pgz

This will result in a program file hello.pgz. In order to run it you need to put it on the removable SD card storage media you have with your C256 Foenix U. You can also run it in the Foenix emulator. In that case you need to select Tools>SD Card from its menu and direct it to the directory where the hello.pgz file is.

Once you have the hardware or emulator set up you can load and run the hello.pgz file with BRUN from the BASIC prompt: