<!doctype linuxdoc system>
<article>
-
-<title>cc65 compiler intro
-<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
-<date>19.07.2000
+<title>cc65 Compiler Intro
+<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 compiler - an introduction.
+How to use the cc65 C language system -- an introduction.
</abstract>
<!-- Table of contents -->
<sect>Overview<p>
-This is a short intro, how to use the compiler and the binutils. It contains a
-step-by-step example, how to build a complete application from one C and one
-assembler module. This file does <em/not/ contain a complete reference for the
-tools used in the process. There are separate files describing these tools in
-detail.
+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">).
+
+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">.
+
-<bf>Note</bf>: There is a much simpler way to compile this example using the
-cl65 compiler and link utility. However, it makes sense to understand how the
-separate steps work. How to do the example with the cl65 utility is described
-<ref id="using-cl65" name="below">.
+<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. 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>
To explain the development flow, I will use the following example modules:
hello.c:
-
<tscreen><code>
- #include <stdio.h>
- #include <stdlib.h>
+ #include <stdio.h>
+ #include <stdlib.h>
- extern const char text[]; /* In text.s */
+ extern const char text[]; /* In text.s */
- int main (void)
- {
- printf ("%s\n", text);
- return EXIT_SUCCESS;
- }
+ int main (void)
+ {
+ printf ("%s\n", text);
+ return EXIT_SUCCESS;
+ }
</code></tscreen>
text.s:
<tscreen><code>
- .export _text
- _text: .asciiz "Hello world!"
+ .export _text
+ _text: .asciiz "Hello world!"
</code></tscreen>
+---------+
| hello.c |
+---------+
- |
+ |
cc65
- \/
- +---------+ +---------+
- | hello.s | | text.s |
- +---------+ +---------+
- | |
- ca65 ca65
- \/ \/
- +---------+ +---------+ +----------+ +---------+
- | hello.o | | text.o | | c64.o | | c64.lib |
- +---------+ +---------+ +----------+ +---------+
- | \ / |
- | \ / |
- | \ / |
- +----------------------->ld65<-------------------------+
- \/
- hello
+ \/
+ +---------+ +---------+ +---------+
+ | 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.
<sect>The compiler<p>
-The compiler translates one C source into one assembler source for each
+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.
<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 CC65_INC to the search path.
-
-The <tt/-t/ switch is followed by the target system.
+The <tt/-t/ switch is followed by the target system name.
-If the compiler does not complain about errors in our hello world, we will
-have a file named "<tt/hello.s/" in our directory that contains the assembler
-source for the hello module.
+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 <htmlurl url="cc65.html"
-name="cc65.html">.
+For more information about the compiler, see <url url="cc65.html">.
<sect>The assembler<p>
-The assembler translates one assembler source into an object file for each
-invocation. The assembler is <tt/not/ able to translate more than one source
+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:
+Let's translate the "hello.s" and "text.s" files from our example:
<tscreen><verb>
- ca65 hello.s
- ca65 -t c64 text.s
+ 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) 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).
+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 <htmlurl url="ca65.html"
-name="ca65.html">.
+For more information about the assembler, see <url url="ca65.html">.
<sect>The linker<p>
-The linker combines several object and library file into one output file. ld65
-is very configurable, but fortunately has a builtin configuration for the C64,
-so we don't need to mess with configuration files here.
+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 big impact on code size. These 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 this file on the command line so that the
-linker can resolve these 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.
+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.
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 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/ these
-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!
-For more information about the linker see <htmlurl url="ld65.html"
-name="ld65.html">.
+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 cl65 utility is able to do all of the steps described above in just one
-call, and it has defaults for some options that are very well suited for our
-example.
+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
+To compile both files into one executable, enter:
<tscreen><verb>
- cl65 -O -I ../include hello.c test.s
+ cl65 -O hello.c text.s
</verb></tscreen>
-(The <tt/-I/ switch is not needed if you are working under Linux with the
-include files in the default path, or the <tt/CC65_INC/ environment variable
-is set correctly).
-
-The cl65 utility knows, how to translate C files into object files (it will
-call the compiler and then the assembler). It does also know how to create
-object files from assembler files (it will call the assember 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
+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 <htmlurl
-url="cl65.html" name="cl65.html">.
+For more information about the compile & link utility, see <url
+url="cl65.html">.
-</article>
+<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 its start and exit conditions.
+
+
+<sect1>Apple
+
+<sect2>AppleWin<p>
+Available at <url
+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.4.0/ or later (available at <url
+url="https://applecommander.github.io/">).
+
+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 -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 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
+Apple:
+
+<tscreen><verb>
+BRUN TEST
+</verb></tscreen>
+
+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>
+Available at <url
+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
+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.
+
+<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://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, 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
+<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 (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/hello1res.grc/".
+
+Compile the tutorial with
+<tscreen><verb>
+cl65 -t geos-cbm -O -o hello1 hello1res.grc hello1.c
+</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 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
+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>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
+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>
projects / cc65 / blobdiff