1. Overview

This is a short intro of how to use the compiler and the bin-utils. It contains a step-by-step example of how to build a complete application from one C and one assembly modules. This file does not contain a complete reference for the tools used in the process. There are separate files describing those tools, in detail (see index.html).

You are assumed to have downloaded and extracted the executables and the target-specific files. For example: for Windows users targeting C64, you need cc65-win32-2.10.1.zip and cc65-c64-2.10.1.zip (or, whatever the current cc65 version is) extracted to the same directory. If you received the files as a bzip2 archive (extension .bz2), you will need to get the bzip2 package to decompress it.

Note: There is a much simpler way to compile this example, by using the cl65 compile-and-link utility. However, it makes sense to understand how the separate steps work. How to do the example with the cl65 utility is described later.

1.1 Before we start

You will find a copy of the sample modules, used in the next section, in the "cc65/samples/tutorial" directory. Please make sure that the compiler and linker can find the include and library files, by setting the environment variables CC65_INC and CC65_LIB, respectively.

1.2 The sample modules

To explain the development flow, I will use the following example modules:

hello.c:

---

        #include <stdio.h>
        #include <stdlib.h>

        extern const char text[];       /* In text.s */

        int main (void)
        {
            printf ("%s\n", text);
            return EXIT_SUCCESS;
        }

---

text.s:

---

        .export _text
        _text:  .asciiz "Hello world!"

---

1.3 Translation phases

We assume that the target file should be named "hello", and the target system is the C64.

    +---------+
    | hello.c |
    +---------+
         |
        cc65
         \/
    +---------+       +---------+
    | hello.s |       | text.s  |
    +---------+       +---------+
         |                 |
        ca65              ca65
         \/                \/
    +---------+       +---------+       +----------+       +---------+
    | hello.o |       | text.o  |       |  c64.o   |       | c64.lib |
    +---------+       +---------+       +----------+       +---------+
         |                    \          /                      |
         |                     \        /                       |
         |                      \      /                        |
         +----------------------->ld65<-------------------------+
                                   \/
                                 hello

c64.o (the startup code) and c64.lib (the C64 version of the runtime and C library) are provided in binary form in the cc65 package.