-
Notifications
You must be signed in to change notification settings - Fork 16
Expand file tree
/
Copy pathintro.html
More file actions
896 lines (783 loc) · 30.5 KB
/
intro.html
File metadata and controls
896 lines (783 loc) · 30.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<LINK REL="stylesheet" TYPE="text/css" HREF="doc.css">
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.83">
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<TITLE>cc65 Compiler Intro</TITLE>
</HEAD>
<BODY>
<H1>cc65 Compiler Intro</H1>
<H2>
<A HREF="mailto:uz@cc65.org">Ullrich von Bassewitz</A>,<BR>
<A HREF="mailto:cbmnut@hushmail.com">CbmNut</A>,<BR>
<A HREF="mailto:greg.king5@verizon.net">Greg King</A>,<BR>
<A HREF="mailto:groepaz@gmx.net">Groepaz</A>,<BR>
<A HREF="mailto:stephan.muehlstrasser@web.de">Stephan Mühlstrasser</A></H2>
<HR>
<EM>How to use the cc65 C language system -- an introduction.</EM>
<HR>
<P>
<H2><A NAME="toc1">1.</A> <A HREF="intro.html#s1">Overview</A></H2>
<UL>
<LI><A NAME="toc1.1">1.1</A> <A HREF="intro.html#ss1.1">Before we start</A>
<LI><A NAME="toc1.2">1.2</A> <A HREF="intro.html#ss1.2">The sample modules</A>
<LI><A NAME="toc1.3">1.3</A> <A HREF="intro.html#ss1.3">Translation phases</A>
</UL>
<P>
<H2><A NAME="toc2">2.</A> <A HREF="intro.html#s2">The compiler</A></H2>
<P>
<H2><A NAME="toc3">3.</A> <A HREF="intro.html#s3">The assembler</A></H2>
<P>
<H2><A NAME="toc4">4.</A> <A HREF="intro.html#s4">The linker</A></H2>
<P>
<H2><A NAME="toc5">5.</A> <A HREF="intro.html#s5">The easy way (using the cl65 utility)</A></H2>
<P>
<H2><A NAME="toc6">6.</A> <A HREF="intro.html#s6">Running The Executable</A></H2>
<UL>
<LI><A NAME="toc6.1">6.1</A> <A HREF="intro.html#ss6.1">Apple</A>
<LI><A NAME="toc6.2">6.2</A> <A HREF="intro.html#ss6.2">Atari</A>
<LI><A NAME="toc6.3">6.3</A> <A HREF="intro.html#ss6.3">Atmos</A>
<LI><A NAME="toc6.4">6.4</A> <A HREF="intro.html#ss6.4">Commander X16</A>
<LI><A NAME="toc6.5">6.5</A> <A HREF="intro.html#ss6.5">Commodore</A>
<LI><A NAME="toc6.6">6.6</A> <A HREF="intro.html#ss6.6">Gamate</A>
<LI><A NAME="toc6.7">6.7</A> <A HREF="intro.html#ss6.7">GEOS</A>
<LI><A NAME="toc6.8">6.8</A> <A HREF="intro.html#ss6.8">Nintendo Entertainment System</A>
<LI><A NAME="toc6.9">6.9</A> <A HREF="intro.html#ss6.9">Ohio Scientific Challenger 1P</A>
<LI><A NAME="toc6.10">6.10</A> <A HREF="intro.html#ss6.10">PC Engine/TurboGrafx 16</A>
<LI><A NAME="toc6.11">6.11</A> <A HREF="intro.html#ss6.11">Contributions wanted</A>
</UL>
<HR>
<H2><A NAME="s1">1.</A> <A HREF="#toc1">Overview</A></H2>
<P>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</EM> contain a complete reference for
the tools used in the process. There are separate files describing those tools,
in detail (see
<A HREF="index.html">index.html</A>).</P>
<P>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.</P>
<P>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 <CODE>CC65_INC</CODE>,
<CODE>LD65_LIB</CODE> and <CODE>LD65_CFG</CODE> as described below.</P>
<P><EM>Note:</EM> There is a much simpler way to compile this example, by using the
<B>cl65</B> compile-and-link utility. However, it makes sense to understand how
the separate steps work. How to do the example with the <B>cl65</B> utility is
described
<A HREF="#using-cl65">later</A>.</P>
<H2><A NAME="ss1.1">1.1</A> <A HREF="#toc1.1">Before we start</A>
</H2>
<P>You will find a copy of the sample modules, used in the next section, in the
"<CODE>cc65/samples/tutorial</CODE>" directory. If you encounter problems with
missing include files and/or libraries, please check the environment variables
<CODE>CC65_INC</CODE>, <CODE>LD65_LIB</CODE> and <CODE>LD65_CFG</CODE>. They should point to the
<CODE>include</CODE>, <CODE>lib</CODE> and <CODE>cfg</CODE> subdirectories of the directory, where you
installed cc65.</P>
<H2><A NAME="ss1.2">1.2</A> <A HREF="#toc1.2">The sample modules</A>
</H2>
<P>To explain the development flow, I will use the following example modules:</P>
<P>hello.c:
<BLOCKQUOTE><CODE>
<HR>
<PRE>
#include <stdio.h>
#include <stdlib.h>
extern const char text[]; /* In text.s */
int main (void)
{
printf ("%s\n", text);
return EXIT_SUCCESS;
}
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<P>text.s:
<BLOCKQUOTE><CODE>
<HR>
<PRE>
.export _text
_text: .asciiz "Hello world!"
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<H2><A NAME="ss1.3">1.3</A> <A HREF="#toc1.3">Translation phases</A>
</H2>
<P>We assume that the target file should be named "hello", and the target system
is the C64.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
+---------+
| hello.c |
+---------+
|
cc65
\/
+---------+ +---------+ +---------+
| hello.s | | text.s | | crt0.o |
+---------+ +---------+ +---------+
| | |
ca65 ca65 ar65
\/ \/ \/
+---------+ +---------+ +---------+
| hello.o | | text.o | | c64.lib |
+---------+ +---------+ +---------+
| \ /
| \ /
| \ /
+----------------------->ld65<
\/
hello
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P><CODE>crt0.o</CODE> (the startup code) and <CODE>c64.lib</CODE> (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.</P>
<H2><A NAME="s2">2.</A> <A HREF="#toc2">The compiler</A></H2>
<P>The compiler translates one C source into one assembly source, for each
invocation. It does <EM>not</EM> create object files directly, and it is <EM>not</EM>
able to translate more than one file per run.</P>
<P>In the example above, we would use the following command line, to translate
<CODE>hello.c</CODE> into <CODE>hello.s</CODE>:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
cc65 -O -t c64 hello.c
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>The <CODE>-O</CODE> switch tells the compiler to do an additional optimizer run, which
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 <CODE>-Oi</CODE> to inline
some runtime functions.</P>
<P>The <CODE>-t</CODE> switch is followed by the target system name.</P>
<P>If the compiler does not complain about errors in our "hello world" program, we
will have a file named "<CODE>hello.s</CODE>", in our directory, that contains the
assembly source for the <B>hello</B> module.</P>
<P>For more information about the compiler, see
<A HREF="cc65.html">cc65.html</A>.</P>
<H2><A NAME="s3">3.</A> <A HREF="#toc3">The assembler</A></H2>
<P>The assembler translates one assembly source into an object file, for each
invocation. The assembler is <EM>not</EM> able to translate more than one source
file per run.</P>
<P>Let's translate the "hello.s" and "text.s" files from our example:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
ca65 hello.s
ca65 -t c64 text.s
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>The <CODE>-t</CODE> switch is needed when translating the <CODE>text.s</CODE> file, so the
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 <CODE>hello.s</CODE> does not contain any character constants,
so specification of a target is not necessary (it wouldn't do any harm,
however).</P>
<P>If the assembler does not complain, we should now have two object files (named
<CODE>hello.o</CODE> and <CODE>text.o</CODE>) in the current directory.</P>
<P>For more information about the assembler, see
<A HREF="ca65.html">ca65.html</A>.</P>
<H2><A NAME="s4">4.</A> <A HREF="#toc4">The linker</A></H2>
<P>The linker combines several object and library files into one output file.
<B>ld65</B> is very configurable, but fortunately has built-in configurations,
so we don't need to mess with configuration files, here.</P>
<P>The compiler uses small functions to do things that cannot be done inline
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,
"<CODE>c64.lib</CODE>". We have to specify that file on the command line, so that the
linker can resolve those functions.</P>
<P>Let's link our files to get the final executable:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
ld65 -o hello -t c64 hello.o text.o c64.lib
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>The argument after <CODE>-o</CODE> specifies the name of the output file, the argument
after <CODE>-t</CODE> gives the target system. The following arguments are object
files or libraries. Since the target library resolves imports in <CODE>hello.o</CODE>
and <CODE>text.o</CODE>, it must be specified <EM>after</EM> those files.</P>
<P>After a successful linker run, we have a file named "<CODE>hello</CODE>", ready for
our C64!</P>
<P>For more information about the linker, see
<A HREF="ld65.html">ld65.html</A>.</P>
<H2><A NAME="using-cl65"></A> <A NAME="s5">5.</A> <A HREF="#toc5">The easy way (using the cl65 utility)</A></H2>
<P>The <B>cl65</B> 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.</P>
<P>To compile both files into one executable, enter:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
cl65 -O hello.c text.s
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>The <B>cl65</B> 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.</P>
<P>The one-liner above should give you a C64 executable named "<CODE>hello</CODE>" in the
current directory.</P>
<P>For more information about the compile & link utility, see
<A HREF="cl65.html">cl65.html</A>.</P>
<H2><A NAME="s6">6.</A> <A HREF="#toc6">Running The Executable</A></H2>
<P><EM>Note: this section is incomplete!</EM></P>
<P>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.</P>
<H2><A NAME="ss6.1">6.1</A> <A HREF="#toc6.1">Apple</A>
</H2>
<H3>AppleWin</H3>
<P>Available at
<A HREF="https://github.com/AppleWin/AppleWin">https://github.com/AppleWin/AppleWin</A>:</P>
<P>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 <B>AppleCommander 1.4.0</B> or later (available at
<A HREF="https://applecommander.github.io/">https://applecommander.github.io/</A>).</P>
<P>Compile the tutorial with</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
cl65 -O -t apple2 hello.c text.s
</PRE>
</CODE></BLOCKQUOTE>
for the Apple ][, or:
<BLOCKQUOTE><CODE>
<PRE>
cl65 -O -t apple2enh hello.c text.s
</PRE>
</CODE></BLOCKQUOTE>
for the enhanced Apple //e.</P>
<P>Then, put the file onto an Apple disk image, for use with an emulator. Copy
the <CODE>master.dsk</CODE> which comes with <B>AppleWin</B>, and rename it to
<CODE>cc65.dsk</CODE>, then use <B>AppleCommander</B>:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
java -jar ac.jar -as cc65.dsk test < hello
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>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.</P>
<P>Start the emulator, click on the <B>Disk 1</B> icon, and point to <B>cc65.dsk</B>;
then, click the big Apple logo, to boot the system. Then, type this on the
Apple:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
BRUN TEST
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>You will see "Hello, World!" appear on the same line. Thanks to
<A HREF="mailto:ol.sc@web.de">Oliver Schmidt</A> for his help
in completing this section.</P>
<H2><A NAME="ss6.2">6.2</A> <A HREF="#toc6.2">Atari</A>
</H2>
<H3>Atari800Win PLus</H3>
<P>Available at
<A HREF="http://www.atari.org.pl/PLus/index_us.htm">http://www.atari.org.pl/PLus/index_us.htm</A>:</P>
<P>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).</P>
<P>Compile the tutorial with</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
cl65 -O -t atari hello.c text.s
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Start the emulator, choose <B>File>Autoboot image</B> or <B>File>Load
executable</B>, and point to the "<B>hello</B>" executable. It is customary to
rename executables of that type to "<B>hello.xex</B>". The file has a 7-byte
header meant to be loaded directly from Atari DOS 2/2.5 or compatibles.</P>
<P>On a real Atari, you would need a disk drive, and Atari DOS 2.5 or compatible.
Turn on the computer, type</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
DOS
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>at the BASIC prompt, then choose <B>N. CREATE MEM.SAV</B>,
then choose <B>L. BINARY LOAD</B>, and enter <CODE>HELLO</CODE>.</P>
<P>The emulation, also, supports that method. Look at <B>Atari>Settings</B>, and
check <B>Enable H: Patch for Hard Disk Devices</B>, then <B>Atari>Hard
disks</B>, and set the path of <B>H1:</B> to your executables directory, then use
"<B>H0:HELLO.XEX</B>" in the above procedure (after pressing <CODE>L</CODE>), to access
your harddrive directly.</P>
<P><EM>Note:</EM> 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.</P>
<H3>Stella</H3>
<P>Available at
<A HREF="http://stella.sourceforge.net">http://stella.sourceforge.net</A>:</P>
<P>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, ..).</P>
<P>Compile the Atari 2600 sample with</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
make SYS=atari2600 samples
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Then execute it with</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
stella samples/atari2600hello
</PRE>
</CODE></BLOCKQUOTE>
</P>
<H3>Harmony Cartridge</H3>
<P>Available at
<A HREF="http://harmony.atariage.com/Site/Harmony.html">http://harmony.atariage.com/Site/Harmony.html</A>:</P>
<P>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.</P>
<H2><A NAME="ss6.3">6.3</A> <A HREF="#toc6.3">Atmos</A>
</H2>
<H3>Oricutron</H3>
<P>Available at
<A HREF="http://code.google.com/p/oriculator/">http://code.google.com/p/oriculator/</A>:</P>
<P>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.</P>
<P>Compile the tutorial with</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
cl65 -O -t atmos hello.c text.s -o hello.tap
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Start the emulator, choose <B>F1</B> and <B>Insert tape...</B>, and point to
the "<B>hello.tap</B>" executable. After it has finished loading, type</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
RUN
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>On a real Atmos, you would need a tape drive.
Turn on the computer, type</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
CLOAD""
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>at the BASIC prompt. After it has finished loading, type</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
RUN
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>The emulation, also, supports that method.</P>
<H2><A NAME="ss6.4">6.4</A> <A HREF="#toc6.4">Commander X16</A>
</H2>
<H3>x16-emulator</H3>
<P>Available at
<A HREF="https://github.com/commanderx16/x16-emulator/releases">https://github.com/commanderx16/x16-emulator/releases</A>:</P>
<P>Emulates the Commander X16 Single Board Computer, with sound, SD card images,
VGA and NTSC video, and a NES game controller emulation. Includes a monitor.
It runs on all SDL2 platforms.</P>
<P>Compile the tutorial with
<BLOCKQUOTE><CODE>
<PRE>
cl65 -O -t cx16 hello.c text.s
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Start the emulator. Then, type
<BLOCKQUOTE><CODE>
<PRE>
LOAD"HELLO",1
RUN
</PRE>
</CODE></BLOCKQUOTE>
(Type those lines in lower-case; but, they will appear as upper-case.)</P>
<P>On a real computer, you would type an <CODE>8</CODE> instead of a <CODE>1</CODE>.</P>
<H2><A NAME="ss6.5">6.5</A> <A HREF="#toc6.5">Commodore</A>
</H2>
<H3>VICE</H3>
<P>Available at
<A HREF="https://vice-emu.sourceforge.net/">https://vice-emu.sourceforge.net/</A>:</P>
<P>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.</P>
<P>Compile the tutorial with
<BLOCKQUOTE><CODE>
<PRE>
cl65 -O -t <sys> hello.c text.s
</PRE>
</CODE></BLOCKQUOTE>
Substitute the name of a Commodore computer for that <CODE><sys></CODE>:
<UL>
<LI><CODE>c128</CODE></LI>
<LI><CODE>c16</CODE></LI>
<LI><CODE>c64</CODE></LI>
<LI><CODE>cbm510</CODE></LI>
<LI><CODE>cbm610</CODE></LI>
<LI><CODE>pet</CODE></LI>
<LI><CODE>plus4</CODE></LI>
<LI><CODE>vic20</CODE></LI>
</UL>
</P>
<P>Start the desired version of the emulator (CBM610 programs run on
the CBM II [<CODE>xcbm2</CODE>] emulator).</P>
<P>Choose <B>File>Autostart disk/tape image...</B>, choose your executable,
and click <B>OK</B>.</P>
<P>The file has a 14-byte header which corresponds to a PRG-format BASIC program,
consisting of a single line, similar to this:</P>
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
1000 sys2061
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<P>On a real Commodore with attached disk drive, you would type:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
LOAD "0:HELLO",8
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>for VIC-20/C64, or:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
DLOAD "HELLO"
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>on PET/CBM II/C128/C16/Plus 4; then, type</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
RUN
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>On a Commodore 128, you can combine those two commands:
<BLOCKQUOTE><CODE>
<PRE>
RUN "HELLO"
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>The output will appear on a separate line, and you will be returned to a BASIC
prompt.</P>
<H2><A NAME="ss6.6">6.6</A> <A HREF="#toc6.6">Gamate</A>
</H2>
<P>Before you can run the cartridge image produced by the linker, the binary has to
be patched using the <B>gamate-fixcart</B> tool that is included in the cc65
package in the util/gamate/ directory.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
gamate-fixcart <image.bin>
</PRE>
</CODE></BLOCKQUOTE>
</P>
<H3>MESS</H3>
<P>Available at
<A HREF="https://www.mamedev.org">https://www.mamedev.org</A>:</P>
<P>MESS (Multiple Emulator Super System) is a multi system emulator that emulates
various cc65 targets. It once started as a MAME fork, but was marged into MAME
again at some point.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
mess gamate -debug -window -skip_gameinfo -cart <image.bin>
</PRE>
</CODE></BLOCKQUOTE>
</P>
<H2><A NAME="ss6.7">6.7</A> <A HREF="#toc6.7">GEOS</A>
</H2>
<P>Available at <I>Click Here Software's</I>
<A HREF="http://cbmfiles.com/geos/index.html">GEOS download section</A>:</P>
<P><I><B>G</B>raphics <B>E</B>nvironment <B>O</B>perating <B>S</B>ystem.</I>
It provides a WIMP GUI (Windows, Icons, and Mouse-Pointer Graphical User
Interface) for Commodore's computer models <B>64</B> and <B>128</B>. It can be
controlled by many different types of input devices:
<UL>
<LI>keyboard</LI>
<LI>joysticks</LI>
<LI>mice</LI>
<LI>trackballs</LI>
<LI>graphics drawing tablets</LI>
<LI>light-pens</LI>
</UL>
</P>
<P>The tutorial files are different for GEOS. You will find them "next door," in
"<CODE>cc65/samples/geos</CODE>"; they are called "<CODE>hello1.c</CODE>" and
"<CODE>hello1res.grc</CODE>".</P>
<P>Compile the tutorial with
<BLOCKQUOTE><CODE>
<PRE>
cl65 -t geos-cbm -O -o hello1 hello1res.grc hello1.c
</PRE>
</CODE></BLOCKQUOTE>
Copy the resulting file "<CODE>hello1</CODE>" onto a (GEOS-format) disk.</P>
<P>Boot the GEOS master disk/image.</P>
<P>
<BLOCKQUOTE>
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.
</BLOCKQUOTE>
</P>
<P>
<BLOCKQUOTE>
In VICE, got to <B>Settings</B> -> <B>Settings</B>, then <B>Peripheral devices</B> ->
<B>Drive</B>. Then, you must enable the <B>True drive emulation</B> checkbox.
</BLOCKQUOTE>
</P>
<P>Find the <B>CONVERT</B> program on the boot disk [tap the 6-key; then, you
should see its icon in the fourth position on the <B>deskTop</B>'s directory
notePad]. Move GEOS's pointer over to <B>CONVERT</B>'s icon; double-click
it to run that program. Click on the <B>Disk</B> icon; put the disk with
"<CODE>hello1</CODE>" into the drive; and, click the <B>OK</B> icon. Use the little
icons under the list of file-names to move through that list until you find
"<CODE>hello1</CODE>". Click on it; and then, click on the <B>Convrt</B> icon.
<B>CONVERT</B> will ask you to confirm that you choose the correct file; click
<B>YES</B> if you did (or, click <B>NO</B> if you made a mistake). After the
program has converted "<CODE>hello1</CODE>" from a CBM file into a GEOS file, it will
announce what it did -- click on <B>OK</B>. <B>CONVERT</B> will show the file list
again. This time, click on <B>Quit</B>.</P>
<P>(You might need to put the boot disk back into the drive, in order to reload
<B>deskTop</B>. 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].)</P>
<P>Now, you must find <B>hello1</B>. Click on the lower left-hand corner of the
directory notePad. Look at the eight file-positions on each page until you see
<B>hello1</B>. Double-click on its icon.</P>
<P>The output is shown in a GEOS dialog box; click <B>OK</B> when you have finished
reading it.</P>
<P>Alternatively you can use the <B>c1541</B> program that comes with VICE to write the
file to a disk image directly in GEOS format, so it can be used in GEOS directly
without having to use the <B>CONVERT</B> program.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
c1541 -attach geos.d64 -geoswrite hello1
</PRE>
</CODE></BLOCKQUOTE>
</P>
<H2><A NAME="ss6.8">6.8</A> <A HREF="#toc6.8">Nintendo Entertainment System</A>
</H2>
<H3>Mednafen (NES)</H3>
<P>Available at
<A HREF="https://mednafen.github.io/releases/">https://mednafen.github.io/releases/</A>:</P>
<P>Mednafen is a multi system emulator that emulates a couple of the supported
targets of cc65: Apple II/II+, Atari Lynx, Nintendo Entertainment System and
PC Engine/TurboGrafx 16.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
mednafen -force_module nes <image.bin>
</PRE>
</CODE></BLOCKQUOTE>
</P>
<H2><A NAME="ss6.9">6.9</A> <A HREF="#toc6.9">Ohio Scientific Challenger 1P</A>
</H2>
<P>The <CODE>osic1p</CODE> 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.</P>
<P>In addition to that, the <CODE>osic1p</CODE> target does not yet have support for stdio
functions. Only the functions from the conio library are available.</P>
<P>Therefore, modify the "<CODE>hello.c</CODE>" source file, as follows:</P>
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
#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;
}
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<P>Compile the tutorial with</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
cl65 -O -t osic1p -u __BOOT__ -o hello.lod hello.c text.s
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>The program is configured for a Challenger 1P computer with, at least, 32 kB
of RAM. See the
<A HREF="osi.html">Ohio Scientifc-specific documentation</A> for instructions about how to
compile for other RAM sizes.</P>
<P>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.)</P>
<P>Tap the "<B>BREAK</B>" key, to display the boot prompt; then, tap the "<CODE>M</CODE>"
key, to enter the 65V PROM monitor. Tap the "<CODE>L</CODE>" key. Either start the
cassette player (with a tape of the program), or start a transfer of the
program file "<CODE>hello.lod</CODE>" from the PC. After a while, you should see the
following text on the screen:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
Hello world!
Press <RETURN>.
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>(Stop the cassette player.) After hitting the RETURN key, you should see the
boot prompt again.</P>
<H3>WinOSI</H3>
<P>Available at
<A HREF="http://osi.marks-lab.com/#Emulator">http://osi.marks-lab.com/#Emulator</A>:</P>
<P>Emulates the Ohio Scientific Challenger computers in different configurations.
Configure it to emulate a C1P (model 600 board) with 32 kB of RAM.</P>
<P>Compile the tutorial with the same command that is used to make the program
for a real machine.</P>
<P>Start the emulator. Tap the "<CODE>M</CODE>" key, to enter the 65V PROM monitor; then,
tap the "<CODE>L</CODE>" 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
"<CODE>hello.lod</CODE>". After a moment, you should see the following text on the
screen:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
Hello world!
Press <RETURN>.
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>After hitting the RETURN key, you should see the boot prompt again.</P>
<H3>C1Pjs</H3>
<P>Available at
<A HREF="http://www.pcjs.org/docs/c1pjs/">http://www.pcjs.org/docs/c1pjs/</A>:</P>
<P>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
<A HREF="http://www.pcjs.org/devices/c1p/machine/32kb/">here</A>.</P>
<P>In addition to cc65, the <B>srec_cat</B> program from
<A HREF="http://srecord.sourceforge.net/">the SRecord tool collection</A>
must be installed. Some Linux distributions also provide srecord directly as
an installable package.</P>
<P>Compile the tutorial with this command line:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
cl65 -O -t osic1p hello.c text.s
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Convert the binary file into a text file that can be loaded via
the Ohio Scientific 65V PROM monitor, at start address 0x200:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
srec_cat hello -binary -offset 0x200 -o hello.c1p -Ohio_Scientific -execution-start-address=0x200
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Open the URL that points to the 32 kB machine; and, wait until the emulator
has been loaded. Click on the "<B>BREAK</B>" button to display the boot prompt;
then, press the "<CODE>M</CODE>" key to enter the 65V PROM monitor. Click the
"<B>Browse...</B>" button; and, select the file "<CODE>hello.c1p</CODE>" that was
created as the output of the above invocation of the "<CODE>srec_cat</CODE>" command.
Press the "<B>Load</B>" button. You should see the following text on the screen:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
Hello world!
Press <RETURN>.
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>After hitting the RETURN key, you should see the boot prompt again.</P>
<H2><A NAME="ss6.10">6.10</A> <A HREF="#toc6.10">PC Engine/TurboGrafx 16</A>
</H2>
<P>For the cartridge image produced by the linker to work in emulators and on real
hardware, its content must be rearranged so the first 8k block becomes the last
8k block in the image.</P>
<P>For example, for a 32k image this can be done using <B>dd</B> as follows:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
dd if=infile.bin bs=8K skip=3 > outfile.pce
dd if=infile.bin bs=8K count=3 >> outfile.pce
</PRE>
</CODE></BLOCKQUOTE>
</P>
<H3>Mednafen</H3>
<P>Available at
<A HREF="https://mednafen.github.io/releases/">https://mednafen.github.io/releases/</A>:</P>
<P>Mednafen is a multi system emulator that emulates a couple of the supported
targets of cc65: Apple II/II+, Atari Lynx, Nintendo Entertainment System and
PC Engine/TurboGrafx 16.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
mednafen -force_module pce <image.pce>
</PRE>
</CODE></BLOCKQUOTE>
</P>
<H2><A NAME="ss6.11">6.11</A> <A HREF="#toc6.11">Contributions wanted</A>
</H2>
<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.</P>
<P>Finally, emulators which run on Unix or Windows would help to reach a wider
audience.</P>
</BODY>
</HTML>