

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

Change to the newly cloned project directory:

.. code-block:: sh

   $ cd Calypsi-m68k-hello-world

Build the project with:

.. code-block:: sh

   $ make
   cc68k --core=68000 --code-model=large --data-model=small --debug --list-file=obj/main-debug.lst -o obj/main-debug.o src/main.c
   ln68k --debug -o hello.elf obj/main-debug.o module/Calypsi-m68k-Foenix/linker-files/a2560u-simplified.scm clib-68000-lc-sd.a --list-file=hello-debug.lst --cross-reference --rtattr printf=reduced --semi-hosted --target=Foenix --stack-size=2000 --sstack-size=800

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

.. code-block:: sh

   $ db68k hello.elf
   Calypsi debugger for 68000
   (db68k)

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

.. code-block:: sh

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

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

.. code-block:: sh

   (db68k) 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

   $ db68k hello.elf -e run --terminate-on-program-exit
   Calypsi debugger for 68000
   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:: Amiga; example, example; Amiga

Amiga
=====

This section describes how to build a "Hello World" application for
the Amiga.

For the Amiga we need to generate Hunk output and the output can
either be executed on an emulator such as FS-UAE or WinUAE.

First you need to Git clone the Amiga Hello World example, you can do so using:

.. code-block:: sh

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

Change directory to the just cloned project and build the project:

.. code-block:: sh

   $ cd Calypsi-Amiga-hello-world
   $ make

This will generate an ``hello.hunk`` output file. You need to copy
this file to your emulator. Consult the documentation of the emulator
you are using. For the FS-UAE it will probably use a directory on the
host computer as the Amiga hard drive, copy ``hello.hunk`` to a
suitable location on it and start the emulator. You may want to rename
the file to be without ``.hunk`` while doing the copy.

Start the emulator, open a shell and run the program. It should print
"Hello World!" and then exit:

.. image:: ../../../../module/calypsi-pictures/screenshots/68000/HelloWorld-Amiga.png

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

A2560 Foenix
============

This section shows how to build the "Hello World" application for a
A2560 Foenix and run it on hardware.

This means you need to have access the actual hardware, but it is
possible to use an A2560 emulator as well, such as Morfe.

The the Calypsi C compiler tool chain generates ELF/DWARF by default, but you may prefer to use
the native PGZ format instead. It is also possible to load an
Intel-hex file over the debug port on the A2560.
The provided ``Makefile`` already has a target to build a PGZ executable.

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

.. code-block:: sh

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

Change directory to the just cloned project:

.. code-block:: sh

   $ cd Calypsi-m68k-hello-world

When you are standing in the project folder, you can build the
application for the A2560 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 A2560 Foenix.

Once you have the hardware or emulator set up you can load and run the
``hello.pgz`` by typing the filename at the prompt.

Downloading an executable to a real A2560 can also be done using the
USB debug port and the C256 Manager tool. In this case you will need to
generate an S-record output file.

The Morfe emulator
==================

It is also possible to download the program into Morfe, the
emulator. Currently this need to be done by a Intel-hex file which can
be generated using:

.. code-block:: sh

   $ make hello.hex

The Morfe emulator can be found at https://github.com/aniou/morfe and
need to be built according to instructions found there.
Morfe can be launched emulating the A2560 K:

.. code-block:: sh

   $ ./morfe-m68k conf/a2560k.ini

Once started, hit function key 9 to enter its TUI environment. Here
you can load the Intel-hex file using ``load hex hello.hex``. Then you
may need to set the ``PC`` register manually using ``set pc``. In this
case you may need to look up the address in the generated
``hello-Foenix.lst`` file and look for the address of
``__program_start`` in it.

Once entered, you can press ``quit`` to resume the emulator at the
start of the program. The result should be:

.. image:: ../../../../module/calypsi-pictures/screenshots/68000/HelloWorld-A2560-Foenix-K.png
