<!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
+<author>
+<url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">,<newline>
+<url url="mailto:cbmnut@hushmail.com" name="CbmNut">,<newline>
+<url url="mailto:greg.king5@verizon.net" name="Greg King">,<newline>
+<url url="mailto:stephan.muehlstrasser@web.de" name="Stephan Mühlstrasser">
<abstract>
How to use the cc65 C language system -- an introduction.
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
+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.
+
+<em/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.
+"<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>
|
cc65
\/
- +---------+ +---------+
- | hello.s | | text.s |
- +---------+ +---------+
- | |
- ca65 ca65
- \/ \/
- +---------+ +---------+ +----------+ +---------+
- | hello.o | | text.o | | c64.o | | c64.lib |
- +---------+ +---------+ +----------+ +---------+
- | \ / |
- | \ / |
- | \ / |
- +----------------------->ld65<-------------------------+
+ +---------+ +---------+ +---------+
+ | hello.s | | text.s | | crt0.o |
+ +---------+ +---------+ +---------+
+ | | |
+ ca65 ca65 ar65
+ \/ \/ \/
+ +---------+ +---------+ +---------+
+ | hello.o | | text.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.
+<tt/crt0.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.
<tt/hello.c/ into <tt/hello.s/:
<tscreen><verb>
- cc65 -O -I ../../include -t c64 hello.c
+ cc65 -O -t c64 hello.c
</verb></tscreen>
The <tt/-O/ switch tells the compiler to do an additional optimizer run, which
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
"<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
+ ld65 -o hello -t c64 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 <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!
To compile both files into one executable, enter:
<tscreen><verb>
- cl65 -O -I ../../include -L ../../lib hello.c text.s
+ cl65 -O 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
+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
<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.
+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 its start and exit conditions.
<sect1>Apple
<sect2>AppleWin<p>
Available at <url
-url="http://applewin.berlios.de/">:
+url="https://github.com/AppleWin/AppleWin">:
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/">).
+however, you will need <bf/AppleCommander 1.4.0/ or later (available at <url
+url="https://applecommander.github.io/">).
Compile the tutorial with
<tt/cc65.dsk/, then use <bf/AppleCommander/:
<tscreen><verb>
-java -jar ac.jar -cc65 cc65.dsk test B < hello
+java -jar ac.jar -as cc65.dsk test < 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.
+the MSDOS/Windows world. We've avoided that in the example, however by using
+"test" as 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
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
+You will see "Hello, World!" appear on the same line. Thanks to
+<url url="mailto:ol.sc@web.de" name="Oliver Schmidt"> for his help
in completing this section.
<sect1>Atari
-<sect2>Atari800Win P
lus<p>
+<sect2>Atari800Win P
Lus<p>
Available at <url
-url="http://www.a800win.atari-area.prv.pl">:
+url="http://www.atari.org.pl/PLus/index_us.htm">:
Emulates Atari 400/800/65XE/130XE/800XL/1200XL/5200, with stereo sound, disk
images, scanline-exact NTSC/PAL video, joysticks, mouse, cartridges, and RAM
"<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
+<em/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.
+<sect2>Stella<p>
+Available at <url
+url="http://stella.sourceforge.net">:
+
+Stella is a multi-platform Atari 2600 VCS emulator. The latest version
+is available on the emulator's website. It is also available through
+the package manager of most Linux distributions (Fedora, Ubuntu, ..).
+
+Compile the Atari 2600 sample with
+
+<tscreen><verb>
+make SYS=atari2600 samples
+</verb></tscreen>
+
+Then execute it with
+
+<tscreen><verb>
+stella samples/atari2600hello
+</verb></tscreen>
+
+<sect2>Harmony Cartridge<p>
+Available at <url
+url="http://harmony.atariage.com/Site/Harmony.html">:
+
+The Harmony Cartridge allows running any Atari 2600 binary on real
+hardware. The binary must be copied on an SD card, to be inserted in
+the Harmony Cartridge. It can then be inserted on an Atari 2600
+console, and run any binary on the SD card.
+
+
+<sect1>Atmos
+
+<sect2>Oricutron<p>
+Available at <url
+url="http://code.google.com/p/oriculator/">:
+
+Emulates Oric-1 and Atmos computers, with sound, disk images,
+scanline-exact NTSC/PAL video, and movie export. Includes a monitor.
+Fortunately, for all SDL platforms. You will need just the emulator; all
+ROMs are supplied.
+
+Compile the tutorial with
+
+<tscreen><verb>
+cl65 -O -t atmos hello.c text.s -o hello.tap
+</verb></tscreen>
+
+Start the emulator, choose <bf/F1/ and <bf/Insert tape.../, and point to
+the "<bf/hello.tap/" executable. After it has finished loading, type
+
+<tscreen><verb>
+RUN
+</verb></tscreen>
+
+On a real Atmos, you would need a tape drive.
+Turn on the computer, type
+
+<tscreen><verb>
+CLOAD""
+</verb></tscreen>
+
+at the BASIC prompt. After it has finished loading, type
+
+<tscreen><verb>
+RUN
+</verb></tscreen>
+
+The emulation, also, supports that method.
+
<sect1>Commodore
<sect2>VICE<p>
Available at <url
-url="http://www.viceteam.org/">:
+url="http://vice-emu.sourceforge.net/">:
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,
+printers, serial port and adapters, stereo sound, disk drives and images, RAM expansions,
+cartridges, ethernet connection, cycle-exact NTSC/PAL video, mice, graphics tablet,
+lightpens, 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
<item><tt/vic20/
</itemize>
-Start the desired version of the emulator (CBM510 and CBM610 programs run on
+Start the desired version of the emulator (CBM610 programs run on
the CBM II [<tt/xcbm2/] emulator).
In the Windows versions of VICE, choose <bf>File>Autoboot disk/tape
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/".
+"<tt/hello1res.grc/".
Compile the tutorial with
<tscreen><verb>
-cl65 -O -t geos hello1.c apphello1.grc
+cl65 -t geos-cbm -O -o hello1 hello1res.grc hello1.c
</verb></tscreen>
Copy the resulting file "<tt/hello1/" onto a (GEOS-format) disk.
</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
+should see its 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
reading it.
+<sect1>Ohio Scientific Challenger 1P<p>
+The <tt/osic1p/ runtime library returns to the boot prompt when the main()
+program exits. Therefore, the C file in the tutorial must be modified
+slightly, in order to see the results on the screen. Otherwise, the program
+would print the text string, and then jump to the boot prompt, making it
+impossible to see the results of running the tutorial program.
+
+In addition to that, the <tt/osic1p/ target does not yet have support for stdio
+functions. Only the functions from the conio library are available.
+
+Therefore, modify the "<tt/hello.c/" source file, as follows:
+
+<tscreen><code>
+#include <conio.h>
+#include <stdlib.h>
+
+extern const char text[]; /* In text.s */
+
+int main (void)
+{
+ clrscr ();
+ cprintf ("%s\r\nPress <RETURN>.\r\n", text);
+ cgetc ();
+ return EXIT_SUCCESS;
+}
+</code></tscreen>
+
+Compile the tutorial with
+
+<tscreen><verb>
+cl65 -O -t osic1p -u __BOOT__ -o hello.lod hello.c text.s
+</verb></tscreen>
+
+The program is configured for a Challenger 1P computer with, at least, 32 kB
+of RAM. See the <url url="osi.html"
+name="Ohio Scientifc-specific documentation"> for instructions about how to
+compile for other RAM sizes.
+
+Plug a cassette player into your C1P computer; or, connect an RS-232 cable
+between your C1P and a PC (set the PC's serial port to 300 Bits Per Second,
+8 data bits, No parity, and 2 stop bits). (Turn on the computers.)
+
+Tap the "<bf/BREAK/" key, to display the boot prompt; then, tap the "<tt/M/"
+key, to enter the 65V PROM monitor. Tap the "<tt/L/" key. Either start the
+cassette player (with a tape of the program), or start a transfer of the
+program file "<tt/hello.lod/" from the PC. After a while, you should see the
+following text on the screen:
+
+<tscreen><verb>
+Hello world!
+Press <RETURN>.
+</verb></tscreen>
+
+(Stop the cassette player.) After hitting the RETURN key, you should see the
+boot prompt again.
+
+<sect2>WinOSI<p>
+Available at <url
+url="http://osi.marks-lab.com/#Emulator">:
+
+Emulates the Ohio Scientific Challenger computers in different configurations.
+Configure it to emulate a C1P (model 600 board) with 32 kB of RAM.
+
+Compile the tutorial with the same command that is used to make the program
+for a real machine.
+
+Start the emulator. Tap the "<tt/M/" key, to enter the 65V PROM monitor; then,
+tap the "<tt/L/" key. If you had configured WinOSI to ask for a file when it
+starts to read data from the serial port, then you will see a file dialog box;
+otherwise, you must tap your host keyboard's F10 function key. Select the file
+"<tt/hello.lod/". After a moment, you should see the following text on the
+screen:
+
+<tscreen><verb>
+Hello world!
+Press <RETURN>.
+</verb></tscreen>
+
+After hitting the RETURN key, you should see the boot prompt again.
+
+<sect2>C1Pjs<p>
+Available at <url
+url="http://www.pcjs.org/docs/c1pjs/">:
+
+Emulates the Ohio Scientific Challenger 1P computer in different configurations.
+The 32 kB RAM machine that must be used with the default compiler settings is
+<url url="http://www.pcjs.org/devices/c1p/machine/32kb/" name="here">.
+
+In addition to cc65, the <bf/srec_cat/ program from <url
+url="http://srecord.sourceforge.net/" name="the SRecord tool collection">
+must be installed. Some Linux distributions also provide srecord directly as
+an installable package.
+
+Compile the tutorial with this command line:
+
+<tscreen><verb>
+cl65 -O -t osic1p hello.c text.s
+</verb></tscreen>
+
+Convert the binary file into a text file that can be loaded via
+the Ohio Scientific 65V PROM monitor, at start address 0x200:
+
+<tscreen><verb>
+srec_cat hello -binary -offset 0x200 -o hello.c1p -Ohio_Scientific -execution-start-address=0x200
+</verb></tscreen>
+
+Open the URL that points to the 32 kB machine; and, wait until the emulator
+has been loaded. Click on the "<bf/BREAK/" button to display the boot prompt;
+then, press the "<tt/M/" key to enter the 65V PROM monitor. Click the
+"<bf/Browse.../" button; and, select the file "<tt/hello.c1p/" that was
+created as the output of the above invocation of the "<tt/srec_cat/" command.
+Press the "<bf/Load/" button. You should see the following text on the screen:
+
+<tscreen><verb>
+Hello world!
+Press <RETURN>.
+</verb></tscreen>
+
+After hitting the RETURN key, you should see the boot prompt again.
+
+
<sect1>Contributions wanted<p>
We need your help! Recommended emulators and instructions for other targets
projects / cc65 / blobdiff