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

I do assume that you have downloaded and installed the compiler and target-specific files. Windows users should use the friendly .exe installer (named cc65-2.13.0-1.exe for version 2.13.0 of the package - adjust the version number if necessary). It does not only install the target files, but will also set up necessary environment variables for you.

If you're going for the .ZIP archives, please note that there is one file for the host platform (Windows, DOS or OS/2), one file for each target platform (C64 or whatever) and a separate file containing the docs (which include the file you're currently reading). So for most uses, you will need at least 3 files and unpack all three into one directory. In case of the .ZIP archives, you will also need to set the environment variables CC65_INC, LD65_LIB and LD65_CFG as described below.

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. If you encounter problems with missing include files and/or libraries, please check the environment variables CC65_INC, LD65_LIB and LD65_CFG. They should point to the include, lib and cfg subdirectories of the directory, where you installed cc65.

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. Actually, the startup code is contained in the library, so you won't need to care about it.