

.. index:: Hello World; example, example; Hello World

********
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.

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:

.. code-block:: sh

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

Change to the newly cloned project directory:

.. code-block:: sh

   $ cd calypsi-6502-hello-world

Build the project with:

.. code-block:: sh

   $ 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:

.. code-block:: sh

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

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

.. code-block:: sh

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

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

.. code-block:: sh

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

.. code-block:: sh

   $ 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.

.. index:: Commodore 64; example, example; Commodore 64

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:

.. code-block:: sh

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

Change directory to the just cloned project:

.. code-block:: sh

   $ cd calypsi-6502-hello-world

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

.. code-block:: sh

   $ 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:

.. code-block:: sh

   $ 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:

.. code-block:: sh

   $ 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:

.. code-block:: sh

   $ x64sc -autostartprgmode 1 hello.prg

.. image:: ../../../../module/calypsi-pictures/screenshots/6502/HelloWorld-C64.png

.. index:: MEGA65; example, example; MEGA65

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:

.. code-block:: sh

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

Change directory to the just cloned project:

.. code-block:: sh

   $ cd Calypsi-MEGA65-hello-world

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

.. code-block:: sh

   $ 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:

.. code-block:: sh

   $ 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.

.. image:: ../../../../module/calypsi-pictures/screenshots/6502/HelloWorld-MEGA65.png
