

.. 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 ``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:

.. code-block:: sh

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

Change to the newly cloned project directory:

.. code-block:: sh

   $ cd Calypsi-65816-hello-world

Build the project with:

.. code-block:: sh

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

.. code-block:: sh

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

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

.. code-block:: sh

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

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

.. code-block:: sh

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

.. code-block:: sh

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

.. index:: Foenix C256 U; example
.. index:: C256 Foenix U; example, example; C256 Foenix U

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:

.. code-block:: sh

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

Change directory to the just cloned project:

.. code-block:: sh

   $ cd Calypsi-65816-hello-world

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

.. code-block:: sh

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

.. image:: ../../../../module/calypsi-pictures/screenshots/65816/HelloWorld-C256-Foenix-U.png
