X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fintro.sgml;h=bb8965c60c5b0f84483159ce0e045c035cc4d5d7;hb=cdca644c83c7d22b6b77e8e8deb599c974cd5ee5;hp=51c7f567afacdcdb5e28dc4844247fc6c085664f;hpb=8c7f6506218334eb5fcd406c7b7ce3fd2b463c06;p=cc65 diff --git a/doc/intro.sgml b/doc/intro.sgml index 51c7f567a..bb8965c60 100644 --- a/doc/intro.sgml +++ b/doc/intro.sgml @@ -2,12 +2,16 @@
-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"> -<date>07.13.2002 +<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"> +<date>2015-03-07 <abstract> -How to use the cc65 C compiler - an introduction. +How to use the cc65 C language system -- an introduction. </abstract> <!-- Table of contents --> @@ -17,32 +21,40 @@ How to use the cc65 C compiler - an introduction. <sect>Overview<p> -This is a short intro of how to use the compiler and the binutils. It contains a -step-by-step example of 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">). -You are assumed to have downloaded and extracted the executables and the -target specific files. For example, for Windows users targeting C64, you need -cc65-win32-2.8.0.zip and cc65-c64-2.8.0.zip (or whatever the current cc65 -version is) extracted to the same directory. If you received the files as a -bzip2 archive (extension *.bz2), you will need to get the <htmlurl -url="http://sources.redhat.com/bzip2/#bzip2-latest" name="bzip2 package"> to -decompress it. +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. -<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="later">. +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 -samples/tutorial directory. Windows users will also find a small batch file in -this directory named "cc65setup.bat". Be sure to examine and understand the -commands in this file, then adjust them for your setup, and execute the file. +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> @@ -50,24 +62,23 @@ commands in this file, then adjust them for your setup, and execute the file. 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> @@ -80,34 +91,35 @@ is the C64. +---------+ | 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. @@ -115,7 +127,7 @@ In the example above, we would use the following command line, to translate <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 @@ -123,173 +135,174 @@ is usually a good idea, since it makes the code smaller. If you don't care 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 name. -The <tt/-t/ switch is followed by the target system. +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. -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. - -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 text.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">. + + <sect>Running The Executable<p> -<bf>Note: this section is incomplete!</bf> +<em/Note: this section is incomplete!/ -Depending on the target, the compiler 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<p> -<bf>AppleWin 1.10.4</bf> (available at -<url url="http://www.jantzer-schmidt.de/applewin/">): Emulates Apple II+/IIe -computer, with sound, video, joysticks, serial port, and disk images. Roms and -dos disk included. Includes monitor. Only for Windows. The package comes with -roms and dos3.3 disk (called master.dsk), however you will need a2tools -(available at <url url="http://hotel04.ausys.se/pausch/apple2/#a2tools">). +<sect1>Apple + +<sect2>AppleWin<p> +Available at <url +url="http://applewin.berlios.de/">: + +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/">). 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 insert the file into an Apple disk image for use with an emulator. Copy -the master.dsk which comes with Applewin and rename it to cc65.dsk, then use -a2tools: +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> -a2tools in -r b cc65.dsk TEST hello +java -jar ac.jar -cc65 cc65.dsk test B < hello </verb></tscreen> -Note that a convention in the Apple world is that hello is the file which is -automatically run upon booting a DOS disk, sort of like the Autoexec.bat of -the PC world. We've avoided this in the example however. Also, the TEST -parameter must be in caps, and is the name of the program as it will appear on -the Apple disk. +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. -Start the emulator, click on the Disk 1 icon, and point to cc65.dsk, then -click the big Apple logo to boot the system. Then type this on the Apple: +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 the "Hello, World!" appear on the same line. Thanks to Oliver -Schmidt, <htmlurl url="mailto:oliver@jantzer-schmidt.de" -name="oliver@jantzer-schmidt.de"> for his help in completing this section. +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<p> -<bf>Atari800Win Plus 3.0</bf> (available at -<url url="http://www.a800win.atari-area.prv.pl">): 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). +<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 @@ -297,43 +310,141 @@ Compile the tutorial with cl65 -O -t atari hello.c text.s </verb></tscreen> -Start the emulator, choose File>Autoboot image or File>Load executable, and -point to the hello executable. It is customary to rename executables of this -type to hello.xex. The file has a 7 byte header meant to be loaded directly -from Atari DOS 2/2.5 or compatibles. +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. +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 N. CREATE MEM.SAV then choose L. BINARY LOAD -and enter HELLO. +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 this method. Look at Atari>Settings and check -Enable H: Patch for Hard Disk Devices, then Atari>Hard disks and set the path -of H1: to your executables directory, then use H0:HELLO.XEX in the above -proceedure (after pressing L) to access your hardrive directly. +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. -<bf>Note:</bf> 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. -<sect1>Commodore<p> +<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/">: -<bf>Vice 1.9</bf> (available at -<url url="ftp://ftp.funet.fi/pub/cbm/crossplatform/emulators/VICE/">): -Emulates Commodore 64/128/Vic 20/PET/CBM II computers. Missing is the Plus/4 -and Commodore 16. Supports printer, serial port, stereo sound, disk drives and -images, ram expansions, cartridges, cycle exact NTSC/PAL video, mice, -joysticks. Includes monitor. Runs on Win9x/NT/2000/XP/ME/OS2/MSDOS, Beos x86, -Acorn RISC OS, and many Unixes. +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. -Start the desired version of the emulator, choose File>Autoboot disk/tape -image, and choose your executable. The file has a 14 byte header which -corresponds to a PRG format BASIC program, consisting of a single line; +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 @@ -342,30 +453,234 @@ corresponds to a PRG format BASIC program, consisting of a single line; On a real Commodore with attached disk drive, you would type: <tscreen><verb> -LOAD "HELLO",8 +LOAD "0:HELLO",8 </verb></tscreen> -for Vic 20/C64, or +for VIC-20/C64, or: <tscreen><verb> -DLOAD "0:HELLO" +DLOAD "HELLO" </verb></tscreen> -on PET/CBM II/C128, then type +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 an emulator 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. +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/Windows would help reach a wider audience. +Finally, emulators which run on Unix or Windows would help to reach a wider +audience. </article>