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">,<newline>
10 <url url="mailto:stephan.muehlstrasser@web.de" name="Stephan Mühlstrasser">
14 How to use the cc65 C language system -- an introduction.
17 <!-- Table of contents -->
20 <!-- Begin the document -->
24 This is a short intro of how to use the compiler and the bin-utils. It contains
25 a step-by-step example of how to build a complete application from one C and
26 one assembly modules. This file does <em/not/ contain a complete reference for
27 the tools used in the process. There are separate files describing those tools,
28 in detail (see <url url="index.html">).
30 I do assume that you have downloaded and installed the compiler and
31 target-specific files. Windows users should use the friendly .exe installer
32 (named cc65-2.13.0-1.exe for version 2.13.0 of the package - adjust the
33 version number if necessary). It does not only install the target files, but
34 will also set up necessary environment variables for you.
36 If you're going for the .ZIP archives, please note that there is one file for
37 the host platform (Windows, DOS or OS/2), one file for each target platform
38 (C64 or whatever) and a separate file containing the docs (which include the
39 file you're currently reading). So for most uses, you will need at least 3
40 files and unpack all three into one directory. In case of the .ZIP archives,
41 you will also need to set the environment variables <tt/CC65_INC/,
42 <tt/LD65_LIB/ and <tt/LD65_CFG/ as described below.
44 <em/Note:/ There is a much simpler way to compile this example, by using the
45 <bf/cl65/ compile-and-link utility. However, it makes sense to understand how
46 the separate steps work. How to do the example with the <bf/cl65/ utility is
47 described <ref id="using-cl65" name="later">.
50 <sect1>Before we start<p>
52 You will find a copy of the sample modules, used in the next section, in the
53 "<tt>cc65/samples/tutorial</tt>" directory. If you encounter problems with
54 missing include files and/or libraries, please check the environment variables
55 <tt/CC65_INC/, <tt/LD65_LIB/ and <tt/LD65_CFG/. They should point to the
56 <tt/include/, <tt/lib/ and <tt/cfg/ subdirectories of the directory, where you
60 <sect1>The sample modules<p>
62 To explain the development flow, I will use the following example modules:
69 extern const char text[]; /* In text.s */
73 printf ("%s\n", text);
81 _text: .asciiz "Hello world!"
85 <sect1>Translation phases<p>
87 We assume that the target file should be named "hello", and the target system
97 +---------+ +---------+ +---------+
98 | hello.s | | text.s | | crt0.o |
99 +---------+ +---------+ +---------+
103 +---------+ +---------+ +---------+
104 | hello.o | | text.o | | c64.lib |
105 +---------+ +---------+ +---------+
109 +----------------------->ld65<
114 <tt/crt0.o/ (the startup code) and <tt/c64.lib/ (the C64 version of the runtime
115 and C library) are provided in binary form in the cc65 package. Actually, the
116 startup code is contained in the library, so you won't need to care about it.
120 <sect>The compiler<p>
122 The compiler translates one C source into one assembly source, for each
123 invocation. It does <em/not/ create object files directly, and it is <em/not/
124 able to translate more than one file per run.
126 In the example above, we would use the following command line, to translate
127 <tt/hello.c/ into <tt/hello.s/:
130 cc65 -O -t c64 hello.c
133 The <tt/-O/ switch tells the compiler to do an additional optimizer run, which
134 is usually a good idea, since it makes the code smaller. If you don't care
135 about the size, but want to have slightly faster code, use <tt/-Oi/ to inline
136 some runtime functions.
138 The <tt/-t/ switch is followed by the target system name.
140 If the compiler does not complain about errors in our "hello world" program, we
141 will have a file named "<tt/hello.s/", in our directory, that contains the
142 assembly source for the <bf/hello/ module.
144 For more information about the compiler, see <url url="cc65.html">.
148 <sect>The assembler<p>
150 The assembler translates one assembly source into an object file, for each
151 invocation. The assembler is <em/not/ able to translate more than one source
154 Let's translate the "hello.s" and "text.s" files from our example:
161 The <tt/-t/ switch is needed when translating the <tt/text.s/ file, so the
162 text is converted from the input character-set (usually ISO-8859-1) into the
163 target character-set (PETSCII, in this example) by the assembler. The
164 compiler-generated file <tt/hello.s/ does not contain any character constants,
165 so specification of a target is not necessary (it wouldn't do any harm,
168 If the assembler does not complain, we should now have two object files (named
169 <tt/hello.o/ and <tt/text.o/) in the current directory.
171 For more information about the assembler, see <url url="ca65.html">.
177 The linker combines several object and library files into one output file.
178 <bf/ld65/ is very configurable, but fortunately has built-in configurations,
179 so we don't need to mess with configuration files, here.
181 The compiler uses small functions to do things that cannot be done inline
182 without a big impact on code size. Those runtime functions, together with the
183 C library, are in an object-file archive named after the system, in this case,
184 "<tt/c64.lib/". We have to specify that file on the command line, so that the
185 linker can resolve those functions.
187 Let's link our files to get the final executable:
190 ld65 -o hello -t c64 hello.o text.o c64.lib
193 The argument after <tt/-o/ specifies the name of the output file, the argument
194 after <tt/-t/ gives the target system. The following arguments are object
195 files or libraries. Since the target library resolves imports in <tt/hello.o/
196 and <tt/text.o/, it must be specified <em/after/ those files.
198 After a successful linker run, we have a file named "<tt/hello/", ready for
201 For more information about the linker, see <url url="ld65.html">.
205 <sect>The easy way (using the cl65 utility)<label id="using-cl65"><p>
207 The <bf/cl65/ utility is able to do all of the steps described above, in just
208 one command line, and it has defaults for some options that are very
209 well-suited for our example.
211 To compile both files into one executable, enter:
214 cl65 -O hello.c text.s
217 The <bf/cl65/ utility knows how to translate C files into object files (it will
218 call the compiler, and then the assembler). It does know also how to create
219 object files from assembly files (it will call only the assembler, for that).
220 It knows how to build an executable (it will pass all object files to the
221 linker). And finally, it has the C64 as a default target, and will supply the
222 correct startup file and runtime library names to the linker, so you don't
223 have to care about that.
225 The one-liner above should give you a C64 executable named "<tt/hello/" in the
228 For more information about the compile & link utility, see <url
233 <sect>Running The Executable<p>
235 <em/Note: this section is incomplete!/
237 Depending on the target, cc65 chooses several methods of making a program
238 available for execution. Here, we list sample emulators and instructions for
239 running the program. Unless noted, similar instructions would also apply to a
240 real machine. One word of advice: we suggest you clear the screen at the
241 start, and wait for a keypress at the end of your program, as each target
242 varies in its start and exit conditions.
249 url="http://applewin.berlios.de/">:
251 Emulates Apple ][/enhanced Apple //e computers, with
252 sound, video, joysticks, serial port, and disk images. Includes monitor. Only
253 for Windows. The package comes with a DOS 3.3 disk (called "master.dsk") image;
254 however, you will need <bf/AppleCommander 1.3.5/ or later (available at <url
255 url="http://applecommander.sourceforge.net/">).
257 Compile the tutorial with
260 cl65 -O -t apple2 hello.c text.s
262 for the Apple ][, or:
264 cl65 -O -t apple2enh hello.c text.s
266 for the enhanced Apple //e.
268 Then, put the file onto an Apple disk image, for use with an emulator. Copy
269 the <tt/master.dsk/ which comes with <bf/AppleWin/, and rename it to
270 <tt/cc65.dsk/, then use <bf/AppleCommander/:
273 java -jar ac.jar -cc65 cc65.dsk test B < hello
276 Note that a convention in the Apple world is that "hello" is the file which is
277 run automatically upon booting a DOS disk, sort of like the "autoexec.bat" of
278 the MSDOS/Windows world. We've avoided that in the example, however. Also,
279 the <tt/B/ parameter must be in caps., and "test" is the name of the program as
280 it will appear on the Apple disk.
282 Start the emulator, click on the <bf/Disk 1/ icon, and point to <bf/cc65.dsk/;
283 then, click the big Apple logo, to boot the system. Then, type this on the
290 You will see "Hello, World!" appear on the same line. Thanks to
291 <url url="mailto:ol.sc@web.de" name="Oliver Schmidt"> for his help
292 in completing this section.
297 <sect2>Atari800Win PLus<p>
299 url="http://www.atari.org.pl/PLus/index_us.htm">:
301 Emulates Atari 400/800/65XE/130XE/800XL/1200XL/5200, with stereo sound, disk
302 images, scanline-exact NTSC/PAL video, joysticks, mouse, cartridges, and RAM
303 expansions. Includes monitor. Unfortunately, only for Windows. You will need
304 the emulator, "atarixl.rom" or "atariosb.rom"/"ataribas.rom", and "dos25.xfd"
305 files (not supplied).
307 Compile the tutorial with
310 cl65 -O -t atari hello.c text.s
313 Start the emulator, choose <bf/File>Autoboot image/ or <bf/File>Load
314 executable/, and point to the "<bf/hello/" executable. It is customary to
315 rename executables of that type to "<bf/hello.xex/". The file has a 7-byte
316 header meant to be loaded directly from Atari DOS 2/2.5 or compatibles.
318 On a real Atari, you would need a disk drive, and Atari DOS 2.5 or compatible.
319 Turn on the computer, type
325 at the BASIC prompt, then choose <bf/N. CREATE MEM.SAV/,
326 then choose <bf/L. BINARY LOAD/, and enter <tt/HELLO/.
328 The emulation, also, supports that method. Look at <bf/Atari>Settings/, and
329 check <bf/Enable H: Patch for Hard Disk Devices/, then <bf/Atari>Hard
330 disks/, and set the path of <bf/H1:/ to your executables directory, then use
331 "<bf/H0:HELLO.XEX/" in the above procedure (after pressing <tt/L/), to access
332 your harddrive directly.
334 <em/Note:/ There is no delay after the program exits, as you are returned
335 to the DOS menu. Your C program should wait for a keypress if you want to see
340 url="http://stella.sourceforge.net">:
342 Stella is a multi-platform Atari 2600 VCS emulator. The latest version
343 is available on the emulator's website. It is also available through
344 the package manager of most Linux distributions (Fedora, Ubuntu, ..).
346 Compile the Atari 2600 sample with
349 make SYS=atari2600 samples
355 stella samples/atari2600hello
358 <sect2>Harmony Cartridge<p>
360 url="http://harmony.atariage.com/Site/Harmony.html">:
362 The Harmony Cartridge allows running any Atari 2600 binary on real
363 hardware. The binary must be copied on an SD card, to be inserted in
364 the Harmony Cartridge. It can then be inserted on an Atari 2600
365 console, and run any binary on the SD card.
372 url="http://code.google.com/p/oriculator/">:
374 Emulates Oric-1 and Atmos computers, with sound, disk images,
375 scanline-exact NTSC/PAL video, and movie export. Includes a monitor.
376 Fortunately, for all SDL platforms. You will need just the emulator; all
379 Compile the tutorial with
382 cl65 -O -t atmos hello.c text.s -o hello.tap
385 Start the emulator, choose <bf/F1/ and <bf/Insert tape.../, and point to
386 the "<bf/hello.tap/" executable. After it has finished loading, type
392 On a real Atmos, you would need a tape drive.
393 Turn on the computer, type
399 at the BASIC prompt. After it has finished loading, type
405 The emulation, also, supports that method.
412 url="http://vice-emu.sourceforge.net/">:
414 Emulates Commodore 64/128/VIC-20/PET/CBM II/Plus 4 computers. Supports
415 printers, serial port and adapters, stereo sound, disk drives and images, RAM expansions,
416 cartridges, ethernet connection, cycle-exact NTSC/PAL video, mice, graphics tablet,
417 lightpens, and joysticks. Includes monitor. Runs on MSDOS/PCDOS, Win9x/ME/NT/2000/XP, OS2,
418 BeOS x86, Acorn RISC OS, and most Unixes.
420 Compile the tutorial with
422 cl65 -O -t <sys> hello.c text.s
424 Substitute the name of a Commodore computer for that <tt/<sys>/:
436 Start the desired version of the emulator (CBM610 programs run on
437 the CBM II [<tt/xcbm2/] emulator).
439 In the Windows versions of VICE, choose <bf>File>Autoboot disk/tape
440 image...</bf>, choose your executable, and click <bf/OK/.
442 In the Unix versions, hold down the mouse's first button. Move the pointer to
443 <bf>Smart-attach disk/tape...</bf>, and release the button. Choose your
444 executable, and click <bf/Autostart/.
446 The file has a 14-byte header which corresponds to a PRG-format BASIC program,
447 consisting of a single line, similar to this:
453 On a real Commodore with attached disk drive, you would type:
465 on PET/CBM II/C128/C16/Plus 4; then, type
471 On a Commodore 128, you can combine those two commands:
476 The output will appear on a separate line, and you will be returned to a BASIC
481 Available at <it/Click Here Software's/ <url
482 url="http://cbmfiles.com/geos/index.html" name="GEOS download section">:
484 <it><bf/G/raphics <bf/E/nvironment <bf/O/perating <bf/S/ystem.</it>
485 It provides a WIMP GUI (Windows, Icons, and Mouse-Pointer Graphical User
486 Interface) for Commodore's computer models <bf/64/ and <bf/128/. It can be
487 controlled by many different types of input devices:
493 <item>graphics drawing tablets
497 The tutorial files are different for GEOS. You will find them "next door," in
498 "<tt>cc65/samples/geos</tt>"; they are called "<tt/hello1.c/" and
499 "<tt/hello1res.grc/".
501 Compile the tutorial with
503 cl65 -t geos-cbm -O -o hello1 hello1res.grc hello1.c
505 Copy the resulting file "<tt/hello1/" onto a (GEOS-format) disk.
507 Boot the GEOS master disk/image.
510 When you want to run GEOS in an emulator, you must adjust that emulator so that
511 it does a "true drive" emulation. Each emulator has its own way of turning that
516 VICE even has different ways that depend on which operating system is running
519 <item>In Windows, you must click on <bf/Options/ (in an always visible menu).
520 Then, you must click on <bf/True drive emulation/.
521 <item>In Unix, you must <em/hold down/ the second button on your mouse. Move
522 the pointer down to <bf/Drive settings/. Then, move the pointer over to
523 <bf/Enable true drive emulation/. (If there is a check-mark in front of
524 those words, that feature already is turned on -- then, move the pointer
525 off of that menu.) Release the mouse button.
529 Find the <bf/CONVERT/ program on the boot disk [tap the 6-key; then, you
530 should see its icon in the fourth position on the <bf/deskTop/'s directory
531 notePad]. Move GEOS's pointer over to <bf/CONVERT/'s icon; double-click
532 it to run that program. Click on the <bf/Disk/ icon; put the disk with
533 "<tt/hello1/" into the drive; and, click the <bf/OK/ icon. Use the little
534 icons under the list of file-names to move through that list until you find
535 "<tt/hello1/". Click on it; and then, click on the <bf/Convrt/ icon.
536 <bf/CONVERT/ will ask you to confirm that you choose the correct file; click
537 <bf/YES/ if you did (or, click <bf/NO/ if you made a mistake). After the
538 program has converted "<tt/hello1/" from a CBM file into a GEOS file, it will
539 announce what it did -- click on <bf/OK/. <bf/CONVERT/ will show the file list
540 again. This time, click on <bf/Quit/.
542 (You might need to put the boot disk back into the drive, in order to reload
543 <bf/deskTop/. Then, you must swap back to the disk with the tutorial program
544 on it, and click on its disk icon [on the right side of the screen].)
546 Now, you must find <bf/hello1/. Click on the lower left-hand corner of the
547 directory notePad. Look at the eight file-positions on each page until you see
548 <bf/hello1/. Double-click on its icon.
550 The output is shown in a GEOS dialog box; click <bf/OK/ when you have finished
554 <sect1>Ohio Scientific Challenger 1P<p>
555 The <tt/osic1p/ runtime library returns to the boot prompt when the main()
556 program exits. Therefore, the C file in the tutorial must be modified
557 slightly, in order to see the results on the screen. Otherwise, the program
558 would print the text string, and then jump to the boot prompt, making it
559 impossible to see the results of running the tutorial program.
561 In addition to that, the <tt/osic1p/ target does not yet have support for stdio
562 functions. Only the functions from the conio library are available.
564 Therefore, modify the "<tt/hello.c/" source file, as follows:
570 extern const char text[]; /* In text.s */
575 cprintf ("%s\r\nPress <RETURN>.\r\n", text);
581 Compile the tutorial with
584 cl65 -O -t osic1p -u __BOOT__ -o hello.lod hello.c text.s
587 The program is configured for a Challenger 1P computer with, at least, 32 kB
588 of RAM. See the <url url="osi.html"
589 name="Ohio Scientifc-specific documentation"> for instructions about how to
590 compile for other RAM sizes.
592 Plug a cassette player into your C1P computer; or, connect an RS-232 cable
593 between your C1P and a PC (set the PC's serial port to 300 Bits Per Second,
594 8 data bits, No parity, and 2 stop bits). (Turn on the computers.)
596 Tap the "<bf/BREAK/" key, to display the boot prompt; then, tap the "<tt/M/"
597 key, to enter the 65V PROM monitor. Tap the "<tt/L/" key. Either start the
598 cassette player (with a tape of the program), or start a transfer of the
599 program file "<tt/hello.lod/" from the PC. After a while, you should see the
600 following text on the screen:
607 (Stop the cassette player.) After hitting the RETURN key, you should see the
612 url="http://osi.marks-lab.com/#Emulator">:
614 Emulates the Ohio Scientific Challenger computers in different configurations.
615 Configure it to emulate a C1P (model 600 board) with 32 kB of RAM.
617 Compile the tutorial with the same command that is used to make the program
620 Start the emulator. Tap the "<tt/M/" key, to enter the 65V PROM monitor; then,
621 tap the "<tt/L/" key. If you had configured WinOSI to ask for a file when it
622 starts to read data from the serial port, then you will see a file dialog box;
623 otherwise, you must tap your host keyboard's F10 function key. Select the file
624 "<tt/hello.lod/". After a moment, you should see the following text on the
632 After hitting the RETURN key, you should see the boot prompt again.
636 url="http://www.pcjs.org/docs/c1pjs/">:
638 Emulates the Ohio Scientific Challenger 1P computer in different configurations.
639 The 32 kB RAM machine that must be used with the default compiler settings is
640 <url url="http://www.pcjs.org/devices/c1p/machine/32kb/" name="here">.
642 In addition to cc65, the <bf/srec_cat/ program from <url
643 url="http://srecord.sourceforge.net/" name="the SRecord tool collection">
644 must be installed. Some Linux distributions also provide srecord directly as
645 an installable package.
647 Compile the tutorial with this command line:
650 cl65 -O -t osic1p hello.c text.s
653 Convert the binary file into a text file that can be loaded via
654 the Ohio Scientific 65V PROM monitor, at start address 0x200:
657 srec_cat hello -binary -offset 0x200 -o hello.c1p -Ohio_Scientific -execution-start-address=0x200
660 Open the URL that points to the 32 kB machine; and, wait until the emulator
661 has been loaded. Click on the "<bf/BREAK/" button to display the boot prompt;
662 then, press the "<tt/M/" key to enter the 65V PROM monitor. Click the
663 "<bf/Browse.../" button; and, select the file "<tt/hello.c1p/" that was
664 created as the output of the above invocation of the "<tt/srec_cat/" command.
665 Press the "<bf/Load/" button. You should see the following text on the screen:
672 After hitting the RETURN key, you should see the boot prompt again.
675 <sect1>Contributions wanted<p>
677 We need your help! Recommended emulators and instructions for other targets
678 are missing. We suggest that you choose emulators with good compatibility.
679 Also, being able to run all computers in the target series is good for
680 target compatibility testing. A machine-language monitor is almost essential
681 for debugging, but a native debugger could be used, as well.
683 Finally, emulators which run on Unix or Windows would help to reach a wider