1 <!doctype linuxdoc system>
5 <title>cc65 Compiler Intro
7 <url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
8 <url url="mailto:cbmnut@hushmail.com" name="CbmNut">,<newline>
9 <url url="mailto:greg.king5@verizon.net" name="Greg King">
13 How to use the cc65 C language system -- an introduction.
16 <!-- Table of contents -->
19 <!-- Begin the document -->
23 This is a short intro of how to use the compiler and the bin-utils. It contains
24 a step-by-step example of how to build a complete application from one C and
25 one assembly modules. This file does <em/not/ contain a complete reference for
26 the tools used in the process. There are separate files describing those tools,
27 in detail (see <url url="index.html">).
29 I do assume that you have downloaded and installed the compiler and
30 target-specific files. Windows users should use the friendly .exe installer
31 (named cc65-2.13.0-1.exe for version 2.13.0 of the package - adjust the
32 version number if necessary). It does not only install the target files, but
33 will also set up necessary environment variables for you.
35 If you're going for the .ZIP archives, please note that there is one file for
36 the host platform (Windows, DOS or OS/2), one file for each target platform
37 (C64 or whatever) and a separate file containing the docs (which include the
38 file you're currently reading). So for most uses, you will need at least 3
39 files and unpack all three into one directory. In case of the .ZIP archives,
40 you will also need to set the environment variables <tt/CC65_INC/,
41 <tt/LD65_LIB/ and <tt/LD65_CFG/ as described below.
43 <em/Note:/ There is a much simpler way to compile this example, by using the
44 <bf/cl65/ compile-and-link utility. However, it makes sense to understand how
45 the separate steps work. How to do the example with the <bf/cl65/ utility is
46 described <ref id="using-cl65" name="later">.
49 <sect1>Before we start<p>
51 You will find a copy of the sample modules, used in the next section, in the
52 "<tt>cc65/samples/tutorial</tt>" directory. If you encounter problems with
53 missing include files and/or libraries, please check the environment variables
54 <tt/CC65_INC/, <tt/LD65_LIB/ and <tt/LD65_CFG/. They should point to the
55 <tt/include/, <tt/lib/ and <tt/cfg/ subdirectories of the directory, where you
59 <sect1>The sample modules<p>
61 To explain the development flow, I will use the following example modules:
68 extern const char text[]; /* In text.s */
72 printf ("%s\n", text);
80 _text: .asciiz "Hello world!"
84 <sect1>Translation phases<p>
86 We assume that the target file should be named "hello", and the target system
96 +---------+ +---------+ +---------+
97 | hello.s | | text.s | | crt0.o |
98 +---------+ +---------+ +---------+
102 +---------+ +---------+ +---------+
103 | hello.o | | text.o | | c64.lib |
104 +---------+ +---------+ +---------+
108 +----------------------->ld65<
113 <tt/crt0.o/ (the startup code) and <tt/c64.lib/ (the C64 version of the runtime
114 and C library) are provided in binary form in the cc65 package. Actually, the
115 startup code is contained in the library, so you won't need to care about it.
119 <sect>The compiler<p>
121 The compiler translates one C source into one assembly source, for each
122 invocation. It does <em/not/ create object files directly, and it is <em/not/
123 able to translate more than one file per run.
125 In the example above, we would use the following command line, to translate
126 <tt/hello.c/ into <tt/hello.s/:
129 cc65 -O -t c64 hello.c
132 The <tt/-O/ switch tells the compiler to do an additional optimizer run, which
133 is usually a good idea, since it makes the code smaller. If you don't care
134 about the size, but want to have slightly faster code, use <tt/-Oi/ to inline
135 some runtime functions.
137 The <tt/-t/ switch is followed by the target system name.
139 If the compiler does not complain about errors in our "hello world" program, we
140 will have a file named "<tt/hello.s/", in our directory, that contains the
141 assembly source for the <bf/hello/ module.
143 For more information about the compiler, see <url url="cc65.html">.
147 <sect>The assembler<p>
149 The assembler translates one assembly source into an object file, for each
150 invocation. The assembler is <em/not/ able to translate more than one source
153 Let's translate the "hello.s" and "text.s" files from our example:
160 The <tt/-t/ switch is needed when translating the <tt/text.s/ file, so the
161 text is converted from the input character-set (usually ISO-8859-1) into the
162 target character-set (PETSCII, in this example) by the assembler. The
163 compiler-generated file <tt/hello.s/ does not contain any character constants,
164 so specification of a target is not necessary (it wouldn't do any harm,
167 If the assembler does not complain, we should now have two object files (named
168 <tt/hello.o/ and <tt/text.o/) in the current directory.
170 For more information about the assembler, see <url url="ca65.html">.
176 The linker combines several object and library files into one output file.
177 <bf/ld65/ is very configurable, but fortunately has built-in configurations,
178 so we don't need to mess with configuration files, here.
180 The compiler uses small functions to do things that cannot be done inline
181 without a big impact on code size. Those runtime functions, together with the
182 C library, are in an object-file archive named after the system, in this case,
183 "<tt/c64.lib/". We have to specify that file on the command line, so that the
184 linker can resolve those functions.
186 Let's link our files to get the final executable:
189 ld65 -o hello -t c64 hello.o text.o c64.lib
192 The argument after <tt/-o/ specifies the name of the output file, the argument
193 after <tt/-t/ gives the target system. The following arguments are object
194 files or libraries. Since the target library resolves imports in <tt/hello.o/
195 and <tt/text.o/, it must be specified <em/after/ those files.
197 After a successful linker run, we have a file named "<tt/hello/", ready for
200 For more information about the linker, see <url url="ld65.html">.
204 <sect>The easy way (using the cl65 utility)<label id="using-cl65"><p>
206 The <bf/cl65/ utility is able to do all of the steps described above, in just
207 one command line, and it has defaults for some options that are very
208 well-suited for our example.
210 To compile both files into one executable, enter:
213 cl65 -O hello.c text.s
216 The <bf/cl65/ utility knows how to translate C files into object files (it will
217 call the compiler, and then the assembler). It does know also how to create
218 object files from assembly files (it will call only the assembler, for that).
219 It knows how to build an executable (it will pass all object files to the
220 linker). And finally, it has the C64 as a default target, and will supply the
221 correct startup file and runtime library names to the linker, so you don't
222 have to care about that.
224 The one-liner above should give you a C64 executable named "<tt/hello/" in the
227 For more information about the compile & link utility, see <url
232 <sect>Running The Executable<p>
234 <em/Note: this section is incomplete!/
236 Depending on the target, cc65 chooses several methods of making a program
237 available for execution. Here, we list sample emulators and instructions for
238 running the program. Unless noted, similar instructions would also apply to a
239 real machine. One word of advice: we suggest you clear the screen at the
240 start, and wait for a keypress at the end of your program, as each target
241 varies in its start and exit conditions.
248 url="http://applewin.berlios.de/">:
250 Emulates Apple ][/enhanced Apple //e computers, with
251 sound, video, joysticks, serial port, and disk images. Includes monitor. Only
252 for Windows. The package comes with a DOS 3.3 disk (called "master.dsk") image;
253 however, you will need <bf/AppleCommander 1.3.5/ or later (available at <url
254 url="http://applecommander.sourceforge.net/">).
256 Compile the tutorial with
259 cl65 -O -t apple2 hello.c text.s
261 for the Apple ][, or:
263 cl65 -O -t apple2enh hello.c text.s
265 for the enhanced Apple //e.
267 Then, put the file onto an Apple disk image, for use with an emulator. Copy
268 the <tt/master.dsk/ which comes with <bf/AppleWin/, and rename it to
269 <tt/cc65.dsk/, then use <bf/AppleCommander/:
272 java -jar ac.jar -cc65 cc65.dsk test B < hello
275 Note that a convention in the Apple world is that "hello" is the file which is
276 run automatically upon booting a DOS disk, sort of like the "autoexec.bat" of
277 the MSDOS/Windows world. We've avoided that in the example, however. Also,
278 the <tt/B/ parameter must be in caps., and "test" is the name of the program as
279 it will appear on the Apple disk.
281 Start the emulator, click on the <bf/Disk 1/ icon, and point to <bf/cc65.dsk/;
282 then, click the big Apple logo, to boot the system. Then, type this on the
289 You will see "Hello, World!" appear on the same line. Thanks to
290 <url url="mailto:ol.sc@web.de" name="Oliver Schmidt"> for his help
291 in completing this section.
296 <sect2>Atari800Win PLus<p>
298 url="http://www.atari.org.pl/PLus/index_us.htm">:
300 Emulates Atari 400/800/65XE/130XE/800XL/1200XL/5200, with stereo sound, disk
301 images, scanline-exact NTSC/PAL video, joysticks, mouse, cartridges, and RAM
302 expansions. Includes monitor. Unfortunately, only for Windows. You will need
303 the emulator, "atarixl.rom" or "atariosb.rom"/"ataribas.rom", and "dos25.xfd"
304 files (not supplied).
306 Compile the tutorial with
309 cl65 -O -t atari hello.c text.s
312 Start the emulator, choose <bf/File>Autoboot image/ or <bf/File>Load
313 executable/, and point to the "<bf/hello/" executable. It is customary to
314 rename executables of that type to "<bf/hello.xex/". The file has a 7-byte
315 header meant to be loaded directly from Atari DOS 2/2.5 or compatibles.
317 On a real Atari, you would need a disk drive, and Atari DOS 2.5 or compatible.
318 Turn on the computer, type
324 at the BASIC prompt, then choose <bf/N. CREATE MEM.SAV/,
325 then choose <bf/L. BINARY LOAD/, and enter <tt/HELLO/.
327 The emulation, also, supports that method. Look at <bf/Atari>Settings/, and
328 check <bf/Enable H: Patch for Hard Disk Devices/, then <bf/Atari>Hard
329 disks/, and set the path of <bf/H1:/ to your executables directory, then use
330 "<bf/H0:HELLO.XEX/" in the above procedure (after pressing <tt/L/), to access
331 your harddrive directly.
333 <em/Note:/ There is no delay after the program exits, as you are returned
334 to the DOS menu. Your C program should wait for a keypress if you want to see
342 url="http://code.google.com/p/oriculator/">:
344 Emulates Oric-1 and Atmos computers, with sound, disk images,
345 scanline-exact NTSC/PAL video, and movie export. Includes monitor.
346 Fortunately for all SDL platforms. You will just need the emulator, all
349 Compile the tutorial with
352 cl65 -O -t atmos hello.c text.s -o hello.tap
355 Start the emulator, choose <bf/F1/ and <bf/Insert tape.../, and point to
356 the "<bf/hello.tap/" executable. The file has an auto start header meant to
357 be loaded directly from tape.
359 On a real Atmos, you would need a tape drive.
360 Turn on the computer, type
368 The emulation, also, supports that method.
375 url="http://vice-emu.sourceforge.net/">:
377 Emulates Commodore 64/128/VIC-20/PET/CBM II/Plus 4 computers. Supports
378 printers, serial port and adapters, stereo sound, disk drives and images, RAM expansions,
379 cartridges, ethernet connection, cycle-exact NTSC/PAL video, mice, graphics tablet,
380 lightpens, and joysticks. Includes monitor. Runs on MSDOS/PCDOS, Win9x/ME/NT/2000/XP, OS2,
381 BeOS x86, Acorn RISC OS, and most Unixes.
383 Compile the tutorial with
385 cl65 -O -t <sys> hello.c text.s
387 Substitute the name of a Commodore computer for that <tt/<sys>/:
399 Start the desired version of the emulator (CBM610 programs run on
400 the CBM II [<tt/xcbm2/] emulator).
402 In the Windows versions of VICE, choose <bf>File>Autoboot disk/tape
403 image...</bf>, choose your executable, and click <bf/OK/.
405 In the Unix versions, hold down the mouse's first button. Move the pointer to
406 <bf>Smart-attach disk/tape...</bf>, and release the button. Choose your
407 executable, and click <bf/Autostart/.
409 The file has a 14-byte header which corresponds to a PRG-format BASIC program,
410 consisting of a single line, similar to this:
416 On a real Commodore with attached disk drive, you would type:
428 on PET/CBM II/C128/C16/Plus 4; then, type
434 On a Commodore 128, you can combine those two commands:
439 The output will appear on a separate line, and you will be returned to a BASIC
444 Available at <it/Click Here Software's/ <url
445 url="http://cbmfiles.com/geos/index.html" name="GEOS download section">:
447 <it><bf/G/raphics <bf/E/nvironment <bf/O/perating <bf/S/ystem.</it>
448 It provides a WIMP GUI (Windows, Icons, and Mouse-Pointer Graphical User
449 Interface) for Commodore's computer models <bf/64/ and <bf/128/. It can be
450 controlled by many different types of input devices:
456 <item>graphics drawing tablets
460 The tutorial files are different for GEOS. You will find them "next door," in
461 "<tt>cc65/samples/geos</tt>"; they are called "<tt/hello1.c/" and
462 "<tt/hello1res.grc/".
464 Compile the tutorial with
466 cl65 -t geos-cbm -O -o hello1 hello1res.grc hello1.c
468 Copy the resulting file "<tt/hello1/" onto a (GEOS-format) disk.
470 Boot the GEOS master disk/image.
473 When you want to run GEOS in an emulator, you must adjust that emulator so that
474 it does a "true drive" emulation. Each emulator has its own way of turning that
479 VICE even has different ways that depend on which operating system is running
482 <item>In Windows, you must click on <bf/Options/ (in an always visible menu).
483 Then, you must click on <bf/True drive emulation/.
484 <item>In Unix, you must <em/hold down/ the second button on your mouse. Move
485 the pointer down to <bf/Drive settings/. Then, move the pointer over to
486 <bf/Enable true drive emulation/. (If there is a check-mark in front of
487 those words, that feature already is turned on -- then, move the pointer
488 off of that menu.) Release the mouse button.
492 Find the <bf/CONVERT/ program on the boot disk [tap the 6-key; then, you
493 should see its icon in the fourth position on the <bf/deskTop/'s directory
494 notePad]. Move GEOS's pointer over to <bf/CONVERT/'s icon; double-click
495 it to run that program. Click on the <bf/Disk/ icon; put the disk with
496 "<tt/hello1/" into the drive; and, click the <bf/OK/ icon. Use the little
497 icons under the list of file-names to move through that list until you find
498 "<tt/hello1/". Click on it; and then, click on the <bf/Convrt/ icon.
499 <bf/CONVERT/ will ask you to confirm that you choose the correct file; click
500 <bf/YES/ if you did (or, click <bf/NO/ if you made a mistake). After the
501 program has converted "<tt/hello1/" from a CBM file into a GEOS file, it will
502 announce what it did -- click on <bf/OK/. <bf/CONVERT/ will show the file list
503 again. This time, click on <bf/Quit/.
505 (You might need to put the boot disk back into the drive, in order to reload
506 <bf/deskTop/. Then, you must swap back to the disk with the tutorial program
507 on it, and click on its disk icon [on the right side of the screen].)
509 Now, you must find <bf/hello1/. Click on the lower left-hand corner of the
510 directory notePad. Look at the eight file-positions on each page until you see
511 <bf/hello1/. Double-click on its icon.
513 The output is shown in a GEOS dialog box; click <bf/OK/ when you have finished
517 <sect1>Contributions wanted<p>
519 We need your help! Recommended emulators and instructions for other targets
520 are missing. We suggest that you choose emulators with good compatibility.
521 Also, being able to run all computers in the target series is good for
522 target compatibility testing. A machine-language monitor is almost essential
523 for debugging, but a native debugger could be used, as well.
525 Finally, emulators which run on Unix or Windows would help to reach a wider