<!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.
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
+<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">.
|
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
+<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.
<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 Plus<p>
+<sect2>Atari800Win PLus<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
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 monitor.
-Fortunately for all SDL platforms. You will just need the emulator, all
+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
</verb></tscreen>
Start the emulator, choose <bf/F1/ and <bf/Insert tape.../, and point to
-the "<bf/hello.tap/" executable. The file has an auto start header meant to
-be loaded directly from tape.
+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
CLOAD""
</verb></tscreen>
-at the BASIC prompt.
+at the BASIC prompt. After it has finished loading, type
+
+<tscreen><verb>
+RUN
+</verb></tscreen>
The emulation, also, supports that method.
<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
Compile the tutorial with
<tscreen><verb>
-cl65 -O -t geos-cbm hello1.c hello1res.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.
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