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 db6502 contains a simulator mode which is enabled by default. It mimics the 6502 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-6502-hello-world.git

Change to the newly cloned project directory:

$ cd calypsi-6502-hello-world

Build the project with:

$ make
cc6502 --core=6502 --debug --list-file=obj/main-debug.lst -o obj/main-debug.o src/main.c
ln6502 --debug -o hello.elf obj/main-debug.o linker.scm clib-6502.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:

$ db6502 hello.elf
Calypsi debugger for 6502
(db6502)

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

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

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

(db6502) 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:

$ db6502 hello.elf -e run --terminate-on-program-exit
Calypsi debugger for 6502
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. Commodore 64

This section shows how to build the “Hello World” application for a Commodore 64 and run it on an emulator like VICE or on actual Commodore 64 hardware.

To create an application suitable to run on the Commodore 64, the linker need output the application in the PRG 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-6502-hello-world.git

Change directory to the just cloned project:

$ cd calypsi-6502-hello-world

When you are standing in the project folder, you can build the application for the Commodore 64 using:

$ make hello.prg

This will result in a program file hello.prg. In order to run it on a real Commodore 64 you will need to put it on some suitable storage media for the Commodore 64. To run it on the VICE emulator it can be specified on the command line:

$ x64sc $(PWD)/hello.prg

This will put the application on a simulated drive and auto execute it from there. You can also load it as a program into memory with:

$ x64sc -autostartprgmode 1 $(PWD)/hello.prg

The $(PWD)/ prefix is needed with some versions of VICE on macOS. You can try without it and it may work depending on the version of VICE used:

$ x64sc -autostartprgmode 1 hello.prg

3.3. MEGA65

This section shows how to build the “Hello World” application for the MEGA65 and run it with the xemu emulator or actual MEGA65 hardware.

Note

You need to use ROM release version is 920395 and the 0.96 CORE (or later) for it to work.

To create an application suitable to run on the MEGA65, the linker need output the application in the PRG format. The provided Makefile is already configured to do this. You can clone the project in the following way:

$ git clone https://github.com/hth313/Calypsi-MEGA65-hello-world.git

Change directory to the just cloned project:

$ cd Calypsi-MEGA65-hello-world

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

$ make

This will result in application file named hello.prg. In order to run it on a real MEGA65 you will need to put it on some suitable storage media for the MEGA65. To run it on the x16emu emulator you can specify it on the command line:

$ xemu -prg hello.prg

This will start the emulator and auto load the application. Type run to run the application.

Note

The application is actually a BASIC application which has a single SYS command that gives control to the C application.