mirror of
https://github.com/cc65/cc65.git
synced 2024-12-23 19:29:37 +00:00
502 lines
17 KiB
Plaintext
502 lines
17 KiB
Plaintext
<!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">).
|
|
|
|
You are assumed to have downloaded and extracted the executables and the
|
|
target-specific files. For example: for Windows users targeting C64, you need
|
|
<bf/cc65-win32-2.10.1.zip/ and <bf/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 <bf/.bz2/), you will need to get <url
|
|
url="http://sources.redhat.com/bzip2/#bzip2-latest" name="the bzip2 package">
|
|
to decompress it.
|
|
|
|
<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. Please make sure that the compiler
|
|
and linker can find the include and library files, by setting the environment
|
|
variables <tt/CC65_INC/ and <tt/CC65_LIB/, respectively.
|
|
|
|
|
|
<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.
|
|
|
|
|
|
|
|
<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 -I ../../include -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/-I/ switch gives a search path for the include files. You may also set
|
|
the environment variable <tt/CC65_INC/ to the search path.
|
|
|
|
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.
|
|
|
|
A second file (this time, an object file) needed is the startup code that
|
|
prepares the grounds for the C program to run. The startup file must be
|
|
executed first, so it must be the first file on the linker command line.
|
|
|
|
Let's link our files to get the final executable:
|
|
|
|
<tscreen><verb>
|
|
ld65 -t c64 -o hello c64.o 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. As discussed, the startup file must be
|
|
the first input file on the command line (you may have to add a path here, if
|
|
<tt/c64.o/ is not in your current directory). Since the 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 -I ../../include -L ../../lib hello.c text.s
|
|
</verb></tscreen>
|
|
|
|
(The <tt/-I/ option is not needed if you are working under a Unix-like system
|
|
with the include files in their default path, or if the <tt/CC65_INC/
|
|
environment variable is set correctly. The <tt/-L/ option is not needed if the
|
|
libraries are in their default path, or if the <tt/CC65_LIB/ environment
|
|
variable is set correctly. [Those two environment variables should be set to
|
|
absolute paths.])
|
|
|
|
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 & 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 ][/enhanced Apple //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 ][, or:
|
|
<tscreen><verb>
|
|
cl65 -O -t apple2enh hello.c text.s
|
|
</verb></tscreen>
|
|
for the enhanced Apple //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>Autoboot image/ or <bf/File>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>Settings/, and
|
|
check <bf/Enable H: Patch for Hard Disk Devices/, then <bf/Atari>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 <sys> hello.c text.s
|
|
</verb></tscreen>
|
|
Substitute the name of a Commodore computer for that <tt/<sys>/:
|
|
<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 [<tt/xcbm2/] emulator).
|
|
|
|
In the Windows versions of VICE, choose <bf>File>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 [tap the 6-key; then, you
|
|
should see it's icon in the fourth position on the <bf/deskTop/'s directory
|
|
notePad]. 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 [on the right side of the screen].)
|
|
|
|
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>
|