Added note on the necessity of tab chars at the beginning of make command lines.

[cc65] / doc / intro.sgml

<!doctype linuxdoc system>

<article>

<title>cc65 Compiler Intro
<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">,
<and>CbmNut, <htmlurl url="mailto:cbmnut@hushmail.com" name="cbmnut@hushmail.com">,
<and><url name="Greg King" url="mailto:gngking@erols.com">
<date>2005-7-22

<abstract>
How to use the cc65 C language system -- an introduction.
</abstract>

<!-- Table of contents -->
<toc>

<!-- Begin the document -->

<sect>Overview<p>

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 <em/not/ contain a complete reference for
the tools used in the process. There are separate files describing those tools,
in detail (see <url url="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 <tt/CC65_INC/,
<tt/LD65_LIB/ and <tt/LD65_CFG/ as described below.

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


<sect1>Before we start<p>

You will find a copy of the sample modules, used in the next section, in the
"<tt>cc65/samples/tutorial</tt>" directory. If you encounter problems with
missing include files and/or libraries, please check the environment variables
<tt/CC65_INC/, <tt/LD65_LIB/ and <tt/LD65_CFG/. They should point to the
<tt/include/, <tt/lib/ and <tt/cfg/ subdirectories of the directory, where you
installed cc65.


<sect1>The sample modules<p>

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

hello.c:
<tscreen><code>
        #include <stdio.h>
        #include <stdlib.h>

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

        int main (void)
        {
            printf ("%s\n", text);
            return EXIT_SUCCESS;
        }
</code></tscreen>

text.s:
<tscreen><code>
        .export _text
        _text:  .asciiz "Hello world!"
</code></tscreen>


<sect1>Translation phases<p>

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

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

<tt/c64.o/ (the startup code) and <tt/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.



<sect>The compiler<p>

The compiler translates one C source into one assembly source, for each
invocation. It does <em/not/ create object files directly, and it is <em/not/
able to translate more than one file per run.

In the example above, we would use the following command line, to translate
<tt/hello.c/ into <tt/hello.s/:

<tscreen><verb>
        cc65 -O -t c64 hello.c
</verb></tscreen>

The <tt/-O/ switch tells the compiler to do an additional optimizer run, which
is usually a good idea, since it makes the code smaller. If you don't care
about the size, but want to have slightly faster code, use <tt/-Oi/ to inline
some runtime functions.

The <tt/-t/ switch is followed by the target system name.

If the compiler does not complain about errors in our "hello world" program, we
will have a file named "<tt/hello.s/", in our directory, that contains the
assembly source for the <bf/hello/ module.

For more information about the compiler, see <url url="cc65.html">.



<sect>The assembler<p>

The assembler translates one assembly source into an object file, for each
invocation. The assembler is <em/not/ able to translate more than one source
file per run.

Let's translate the "hello.s" and "text.s" files from our example:

<tscreen><verb>
        ca65 hello.s
        ca65 -t c64 text.s
</verb></tscreen>

The <tt/-t/ switch is needed when translating the <tt/text.s/ file, so the
text is converted from the input character-set (usually ISO-8859-1) into the
target character-set (PETSCII, in this example) by the assembler. The
compiler-generated file <tt/hello.s/ does not contain any character constants,
so specification of a target is not necessary (it wouldn't do any harm,
however).

If the assembler does not complain, we should now have two object files (named
<tt/hello.o/ and <tt/text.o/) in the current directory.

For more information about the assembler, see <url url="ca65.html">.



<sect>The linker<p>

The linker combines several object and library files into one output file.
<bf/ld65/ is very configurable, but fortunately has built-in configurations,
so we don't need to mess with configuration files, here.

The compiler uses small functions to do things that cannot be done inline
without a big impact on code size. Those runtime functions, together with the
C library, are in an object-file archive named after the system, in this case,
"<tt/c64.lib/". We have to specify that file on the command line, so that the
linker can resolve those functions.

Let's link our files to get the final executable:

<tscreen><verb>
        ld65 -t c64 -o hello hello.o text.o c64.lib
</verb></tscreen>

The argument after <tt/-o/ specifies the name of the output file, the argument
after <tt/-t/ gives the target system. The following arguments are object
files or libraries. Since the target library resolves imports in <tt/hello.o/
and <tt/text.o/, it must be specified <em/after/ those files.

After a successful linker run, we have a file named "<tt/hello/", ready for
our C64!

For more information about the linker, see <url url="ld65.html">.



<sect>The easy way (using the cl65 utility)<label id="using-cl65"><p>

The <bf/cl65/ utility is able to do all of the steps described above, in just
one command line, and it has defaults for some options that are very
well-suited for our example.

To compile both files into one executable, enter:

<tscreen><verb>
        cl65 -O hello.c text.s
</verb></tscreen>

The <bf/cl65/ utility knows how to translate C files into object files (it will
call the compiler, and then the assembler). It does know also how to create
object files from assembly files (it will call only the assembler, for that).
It knows how to build an executable (it will pass all object files to the
linker). And finally, it has the C64 as a default target, and will supply the
correct startup file and runtime library names to the linker, so you don't
have to care about that.

The one-liner above should give you a C64 executable named "<tt/hello/" in the
current directory.

For more information about the compile &amp; link utility, see <url
url="cl65.html">.



<sect>Running The Executable<p>

<em/Note: this section is incomplete!/

Depending on the target, cc65 chooses several methods of making a program
available for execution. Here, we list sample emulators and instructions for
running the program. Unless noted, similar instructions would also apply to a
real machine. One word of advice: we suggest you clear the screen at the
start, and wait for a keypress at the end of your program, as each target
varies in it's start and exit conditions.


<sect1>Apple

<sect2>AppleWin<p>
Available at <url
url="http://applewin.berlios.de/">:

Emulates Apple&nbsp;&rsqb;&lsqb;/enhanced&nbsp;Apple&nbsp;//e computers, with
sound, video, joysticks, serial port, and disk images. Includes monitor. Only
for Windows. The package comes with a DOS 3.3 disk (called "master.dsk") image;
however, you will need <bf/AppleCommander 1.3.5/ or later (available at <url
url="http://applecommander.sourceforge.net/">).

Compile the tutorial with

<tscreen><verb>
cl65 -O -t apple2 hello.c text.s
</verb></tscreen>
for the Apple&nbsp;&rsqb;&lsqb;, or:
<tscreen><verb>
cl65 -O -t apple2enh hello.c text.s
</verb></tscreen>
for the enhanced&nbsp;Apple&nbsp;//e.

Then, put the file onto an Apple disk image, for use with an emulator.  Copy
the <tt/master.dsk/ which comes with <bf/AppleWin/, and rename it to
<tt/cc65.dsk/, then use <bf/AppleCommander/:

<tscreen><verb>
java -jar ac.jar -cc65 cc65.dsk test B < hello
</verb></tscreen>

Note that a convention in the Apple world is that "hello" is the file which is
run automatically upon booting a DOS disk, sort of like the "autoexec.bat" of
the MSDOS/Windows world.  We've avoided that in the example, however.  Also,
the <tt/B/ parameter must be in caps., and "test" is the name of the program as
it will appear on the Apple disk.

Start the emulator, click on the <bf/Disk 1/ icon, and point to <bf/cc65.dsk/;
then, click the big Apple logo, to boot the system.  Then, type this on the
Apple:

<tscreen><verb>
BRUN TEST
</verb></tscreen>

You will see the "Hello, World!" appear on the same line.  Thanks to Oliver
Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de"> for his help
in completing this section.


<sect1>Atari

<sect2>Atari800Win Plus<p>
Available at <url
url="http://www.a800win.atari-area.prv.pl">:

Emulates Atari 400/800/65XE/130XE/800XL/1200XL/5200, with stereo sound, disk
images, scanline-exact NTSC/PAL video, joysticks, mouse, cartridges, and RAM
expansions. Includes monitor. Unfortunately, only for Windows. You will need
the emulator, "atarixl.rom" or "atariosb.rom"/"ataribas.rom", and "dos25.xfd"
files (not supplied).

Compile the tutorial with

<tscreen><verb>
cl65 -O -t atari hello.c text.s
</verb></tscreen>

Start the emulator, choose <bf/File&gt;Autoboot image/ or <bf/File&gt;Load
executable/, and point to the "<bf/hello/" executable.  It is customary to
rename executables of that type to "<bf/hello.xex/".  The file has a 7-byte
header meant to be loaded directly from Atari DOS 2/2.5 or compatibles.

On a real Atari, you would need a disk drive, and Atari DOS 2.5 or compatible.
Turn on the computer, type

<tscreen><verb>
DOS
</verb></tscreen>

at the BASIC prompt, then choose <bf/N. CREATE MEM.SAV/,
then choose <bf/L. BINARY LOAD/, and enter <tt/HELLO/.

The emulation, also, supports that method.  Look at <bf/Atari&gt;Settings/, and
check <bf/Enable H: Patch for Hard Disk Devices/, then <bf/Atari&gt;Hard
disks/, and set the path of <bf/H1:/ to your executables directory, then use
"<bf/H0:HELLO.XEX/" in the above procedure (after pressing <tt/L/), to access
your harddrive directly.

<bf/Note/: There is no delay after the program exits, as you are returned
to the DOS menu.  Your C program should wait for a keypress if you want to see
any output.


<sect1>Commodore

<sect2>VICE<p>
Available at <url
url="http://www.viceteam.org/">:

Emulates Commodore 64/128/VIC-20/PET/CBM II/Plus 4 computers. Supports
printers, serial port and adapters, stereo sound, disk drives and images, RAM
expansions, cartridges, ethernet connection, cycle-exact NTSC/PAL video, mice,
and joysticks. Includes monitor. Runs on MSDOS/PCDOS, Win9x/ME/NT/2000/XP, OS2,
BeOS x86, Acorn RISC OS, and most Unixes.

Compile the tutorial with
<tscreen><verb>
cl65 -O -t &lt;sys&gt; hello.c text.s
</verb></tscreen>
Substitute the name of a Commodore computer for that <tt/&lt;sys&gt;/:
<itemize>
<item><tt/c128/
<item><tt/c16/
<item><tt/c64/
<item><tt/cbm510/
<item><tt/cbm610/
<item><tt/pet/
<item><tt/plus4/
<item><tt/vic20/
</itemize>

Start the desired version of the emulator (CBM510 and CBM610 programs run on
the CBM II &lsqb;<tt/xcbm2/&rsqb; emulator).

In the Windows versions of VICE, choose <bf>File&gt;Autoboot disk/tape
image...</bf>, choose your executable, and click <bf/OK/.

In the Unix versions, hold down the mouse's first button. Move the pointer to
<bf>Smart-attach disk/tape...</bf>, and release the button. Choose your
executable, and click <bf/Autostart/.

The file has a 14-byte header which corresponds to a PRG-format BASIC program,
consisting of a single line, similar to this:

<tscreen><code>
1000 sys2061
</code></tscreen>

On a real Commodore with attached disk drive, you would type:

<tscreen><verb>
LOAD "0:HELLO",8
</verb></tscreen>

for VIC-20/C64, or:

<tscreen><verb>
DLOAD "HELLO"
</verb></tscreen>

on PET/CBM II/C128/C16/Plus 4; then, type

<tscreen><verb>
RUN
</verb></tscreen>

On a Commodore 128, you can combine those two commands:
<tscreen><verb>
RUN "HELLO"
</verb></tscreen>

The output will appear on a separate line, and you will be returned to a BASIC
prompt.


<sect1>GEOS<p>
Available at <it/Click Here Software's/ <url
url="http://cbmfiles.com/geos/index.html" name="GEOS download section">:

<it><bf/G/raphics <bf/E/nvironment <bf/O/perating <bf/S/ystem.</it>
It provides a WIMP GUI (Windows, Icons, and Mouse-Pointer Graphical User
Interface) for Commodore's computer models <bf/64/ and <bf/128/.  It can be
controlled by many different types of input devices:
<itemize>
<item>keyboard
<item>joysticks
<item>mice
<item>trackballs
<item>graphics drawing tablets
<item>light-pens
</itemize>

The tutorial files are different for GEOS.  You will find them "next door," in
"<tt>cc65/samples/geos</tt>"; they are called "<tt/hello1.c/" and
"<tt/apphello1.grc/".

Compile the tutorial with
<tscreen><verb>
cl65 -O -t geos hello1.c apphello1.grc
</verb></tscreen>
Copy the resulting file "<tt/hello1/" onto a (GEOS-format) disk.

Boot the GEOS master disk/image.

<quote>
When you want to run GEOS in an emulator, you must adjust that emulator so that
it does a "true drive" emulation. Each emulator has its own way of turning that
feature on.
</quote>

<quote>
VICE even has different ways that depend on which operating system is running
the emulator.
<itemize>
<item>In Windows, you must click on <bf/Options/ (in an always visible menu).
      Then, you must click on <bf/True drive emulation/.
<item>In Unix, you must <em/hold down/ the second button on your mouse.  Move
      the pointer down to <bf/Drive settings/.  Then, move the pointer over to
      <bf/Enable true drive emulation/.  (If there is a check-mark in front of
      those words, that feature already is turned on -- then, move the pointer
      off of that menu.) Release the mouse button.
</itemize>
</quote>

Find the <bf/CONVERT/ program on the boot disk &lsqb;tap the 6-key; then, you
should see it's icon in the fourth position on the <bf/deskTop/'s directory
notePad&rsqb;.  Move GEOS's pointer over to <bf/CONVERT/'s icon; double-click
it to run that program.  Click on the <bf/Disk/ icon; put the disk with
"<tt/hello1/" into the drive; and, click the <bf/OK/ icon.  Use the little
icons under the list of file-names to move through that list until you find
"<tt/hello1/".  Click on it; and then, click on the <bf/Convrt/ icon.
<bf/CONVERT/ will ask you to confirm that you choose the correct file; click
<bf/YES/ if you did (or, click <bf/NO/ if you made a mistake).  After the
program has converted "<tt/hello1/" from a CBM file into a GEOS file, it will
announce what it did -- click on <bf/OK/.  <bf/CONVERT/ will show the file list
again.  This time, click on <bf/Quit/.

(You might need to put the boot disk back into the drive, in order to reload
<bf/deskTop/.  Then, you must swap back to the disk with the tutorial program
on it, and click on its disk icon &lsqb;on the right side of the screen&rsqb;.)

Now, you must find <bf/hello1/.  Click on the lower left-hand corner of the
directory notePad.  Look at the eight file-positions on each page until you see
<bf/hello1/.  Double-click on its icon.

The output is shown in a GEOS dialog box; click <bf/OK/ when you have finished
reading it.


<sect1>Contributions wanted<p>

We need your help! Recommended emulators and instructions for other targets
are missing.  We suggest that you choose emulators with good compatibility.
Also, being able to run all computers in the target series is good for
target compatibility testing. A machine-language monitor is almost essential
for debugging, but a native debugger could be used, as well.

Finally, emulators which run on Unix or Windows would help to reach a wider
audience.

</article>