-
Notifications
You must be signed in to change notification settings - Fork 17
Expand file tree
/
Copy pathcc65.html
More file actions
2359 lines (1918 loc) · 87.3 KB
/
cc65.html
File metadata and controls
2359 lines (1918 loc) · 87.3 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
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!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 Users Guide</TITLE>
</HEAD>
<BODY>
<H1>cc65 Users Guide</H1>
<H2>
<A HREF="mailto:uz@cc65.org">Ullrich von Bassewitz</A>,<BR>
<A HREF="mailto:gregdk@users.sf.net">Greg King</A></H2>
<HR>
<EM>cc65 is a C compiler for 6502 targets. It supports several 6502-based home
computers such as the Commodore and Atari machines, but it easily is
retargetable.</EM>
<HR>
<P>
<H2><A NAME="toc1">1.</A> <A HREF="cc65.html#s1">Overview</A></H2>
<P>
<H2><A NAME="toc2">2.</A> <A HREF="cc65.html#s2">Usage</A></H2>
<UL>
<LI><A NAME="toc2.1">2.1</A> <A HREF="cc65.html#ss2.1">Command line option overview</A>
<LI><A NAME="toc2.2">2.2</A> <A HREF="cc65.html#ss2.2">Command line options in detail</A>
</UL>
<P>
<H2><A NAME="toc3">3.</A> <A HREF="cc65.html#s3">Input and output</A></H2>
<P>
<H2><A NAME="toc4">4.</A> <A HREF="cc65.html#s4">Differences to the ISO standard</A></H2>
<P>
<H2><A NAME="toc5">5.</A> <A HREF="cc65.html#s5">Extensions</A></H2>
<P>
<H2><A NAME="toc6">6.</A> <A HREF="cc65.html#s6">Predefined macros</A></H2>
<P>
<H2><A NAME="toc7">7.</A> <A HREF="cc65.html#s7">#pragmas</A></H2>
<UL>
<LI><A NAME="toc7.1">7.1</A> <A HREF="cc65.html#ss7.1"><CODE>#pragma allow-eager-inline ([push,] on|off)</CODE></A>
<LI><A NAME="toc7.2">7.2</A> <A HREF="cc65.html#ss7.2"><CODE>#pragma bss-name ([push, ]<name>[ ,<addrsize>])</CODE></A>
<LI><A NAME="toc7.3">7.3</A> <A HREF="cc65.html#ss7.3"><CODE>#pragma charmap (<index>, <code>)</CODE></A>
<LI><A NAME="toc7.4">7.4</A> <A HREF="cc65.html#ss7.4"><CODE>#pragma check-stack ([push,] on|off)</CODE></A>
<LI><A NAME="toc7.5">7.5</A> <A HREF="cc65.html#ss7.5"><CODE>#pragma code-name ([push, ]<name>[ ,<addrsize>])</CODE></A>
<LI><A NAME="toc7.6">7.6</A> <A HREF="cc65.html#ss7.6"><CODE>#pragma codesize ([push,] <int>)</CODE></A>
<LI><A NAME="toc7.7">7.7</A> <A HREF="cc65.html#ss7.7"><CODE>#pragma data-name ([push, ]<name>[ ,<addrsize>])</CODE></A>
<LI><A NAME="toc7.8">7.8</A> <A HREF="cc65.html#ss7.8"><CODE>#pragma inline-stdfuncs ([push,] on|off)</CODE></A>
<LI><A NAME="toc7.9">7.9</A> <A HREF="cc65.html#ss7.9"><CODE>#pragma local-strings ([push,] on|off)</CODE></A>
<LI><A NAME="toc7.10">7.10</A> <A HREF="cc65.html#ss7.10"><CODE>#pragma message (<message>)</CODE></A>
<LI><A NAME="toc7.11">7.11</A> <A HREF="cc65.html#ss7.11"><CODE>#pragma optimize ([push,] on|off)</CODE></A>
<LI><A NAME="toc7.12">7.12</A> <A HREF="cc65.html#ss7.12"><CODE>#pragma rodata-name ([push, ]<name>[ ,<addrsize>])</CODE></A>
<LI><A NAME="toc7.13">7.13</A> <A HREF="cc65.html#ss7.13"><CODE>#pragma regvaraddr ([push,] on|off)</CODE></A>
<LI><A NAME="toc7.14">7.14</A> <A HREF="cc65.html#ss7.14"><CODE>#pragma register-vars ([push,] on|off)</CODE></A>
<LI><A NAME="toc7.15">7.15</A> <A HREF="cc65.html#ss7.15"><CODE>#pragma signed-chars ([push,] on|off)</CODE></A>
<LI><A NAME="toc7.16">7.16</A> <A HREF="cc65.html#ss7.16"><CODE>#pragma static-locals ([push,] on|off)</CODE></A>
<LI><A NAME="toc7.17">7.17</A> <A HREF="cc65.html#ss7.17"><CODE>#pragma warn (name, [push,] on|off)</CODE></A>
<LI><A NAME="toc7.18">7.18</A> <A HREF="cc65.html#ss7.18"><CODE>#pragma wrapped-call (push, <name>, <identifier>)</CODE></A>
<LI><A NAME="toc7.19">7.19</A> <A HREF="cc65.html#ss7.19"><CODE>#pragma writable-strings ([push,] on|off)</CODE></A>
<LI><A NAME="toc7.20">7.20</A> <A HREF="cc65.html#ss7.20"><CODE>#pragma zpsym (<name>)</CODE></A>
</UL>
<P>
<H2><A NAME="toc8">8.</A> <A HREF="cc65.html#s8">Register variables</A></H2>
<P>
<H2><A NAME="toc9">9.</A> <A HREF="cc65.html#s9">Inline assembler</A></H2>
<P>
<H2><A NAME="toc10">10.</A> <A HREF="cc65.html#s10">Implementation-defined behavior</A></H2>
<P>
<H2><A NAME="toc11">11.</A> <A HREF="cc65.html#s11">Copyright</A></H2>
<HR>
<H2><A NAME="s1">1.</A> <A HREF="#toc1">Overview</A></H2>
<P>cc65 was originally a C compiler for the Atari 8-bit machines written by
John R. Dunning. In prior releases I've described the compiler by listing
up the changes made by me. I have made many more changes in the meantime
(and rewritten major parts of the compiler), so I will no longer do that,
since the list would be too large and of no use to anyone. Instead I will
describe the compiler in respect to the ANSI/ISO C standard.</P>
<P>There are separate documents named
<A HREF="library.html">library.html</A> and
<A HREF="funcref.html">funcref.html</A> that cover the library that is available for the compiler.
If you know C, and are interested in doing actual programming, the library
documentation is probably of much more use than this document.</P>
<P>If you need some hints for getting the best code out of the compiler, you
may have a look at
<A HREF="coding.html">coding.html</A> which covers some code generation
issues.</P>
<H2><A NAME="s2">2.</A> <A HREF="#toc2">Usage</A></H2>
<P>The compiler translates C files into files containing assembly code that
may be translated by the ca65 macroassembler (for more information about
the assembler, have a look at
<A HREF="ca65.html">ca65.html</A>).</P>
<H2><A NAME="ss2.1">2.1</A> <A HREF="#toc2.1">Command line option overview</A>
</H2>
<P>The compiler may be called as follows:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
---------------------------------------------------------------------------
Usage: cc65 [options] file
Short options:
-Cl Make local variables static
-Dsym[=defn] Define a symbol
-E Stop after the preprocessing stage
-I dir Set an include directory search path
-O Optimize code
-Oi Optimize code, inline more code
-Or Enable register variables
-Os Inline some standard functions
-T Include source as comment
-V Print the compiler version number
-W [-+]warning[,...] Control warnings ('-' disables, '+' enables)
-d Debug mode
-dM Output all user macros (needs -E)
-dP Output all predefined macros (needs -E)
-g Add debug info to object file
-h Help (this text)
-j Default characters are signed
-mm model Set the memory model
-o name Name the output file
-r Enable register variables
-t sys Set the target system
-v Increase verbosity
Long options:
--add-source Include source as comment
--all-cdecl Make functions default to __cdecl__
--bss-name seg Set the name of the BSS segment
--check-stack Generate stack overflow checks
--code-name seg Set the name of the CODE segment
--codesize x Accept larger code by factor x
--cpu type Set cpu type (6502, 65c02)
--create-dep name Create a make dependency file
--create-full-dep name Create a full make dependency file
--data-name seg Set the name of the DATA segment
--debug Debug mode
--debug-tables name Write symbol table debug info to a file
--debug-info Add debug info to object file
--debug-opt name Debug optimization steps
--debug-opt-output Debug output of each optimization step
--dep-target target Use this dependency target
--disable-opt name Disable an optimization step
--eagerly-inline-funcs Eagerly inline some known functions
--enable-opt name Enable an optimization step
--help Help (this text)
--include-dir dir Set an include directory search path
--inline-stdfuncs Inline some standard functions
--list-opt-steps List all optimizer steps and exit
--list-warnings List available warning types for -W
--local-strings Emit string literals immediately
--memory-model model Set the memory model
--register-space b Set space available for register variables
--register-vars Enable register variables
--rodata-name seg Set the name of the RODATA segment
--signed-chars Default characters are signed
--standard std Language standard (c89, c99, cc65)
--static-locals Make local variables static
--target sys Set the target system
--verbose Increase verbosity
--version Print the compiler version number
--warnings-as-errors Treat warnings as errors
--writable-strings Make string literals writable
---------------------------------------------------------------------------
</PRE>
</CODE></BLOCKQUOTE>
</P>
<H2><A NAME="ss2.2">2.2</A> <A HREF="#toc2.2">Command line options in detail</A>
</H2>
<P>Here is a description of all the command line options:</P>
<P>
<DL>
<DT><B><CODE>--all-cdecl</CODE></B><DD>
<P>Tells the compiler that functions which aren't declared explicitly with
either the <CODE>__cdecl__</CODE> or <CODE>__fastcall__</CODE> calling conventions should
have the cdecl convention. (Normally, functions that aren't variadic are
fast-called.)</P>
<P>
<A NAME="option-bss-name"></A> </P>
<DT><B><CODE>--bss-name seg</CODE></B><DD>
<P>Set the name of the bss segment. See also <CODE>
<A HREF="#pragma-bss-name">#pragma bss-name</A></CODE>.</P>
<P>
<A NAME="option-check-stack"></A> </P>
<DT><B><CODE>--check-stack</CODE></B><DD>
<P>Tells the compiler to generate code that checks for stack overflows. See
<CODE>
<A HREF="#pragma-check-stack">#pragma check-stack</A></CODE> for an
explanation of this feature.</P>
<P>
<A NAME="option-code-name"></A> </P>
<DT><B><CODE>--code-name seg</CODE></B><DD>
<P>Set the name of the code segment. See also <CODE>
<A HREF="#pragma-code-name">#pragma code-name</A></CODE></P>
<P>
<A NAME="option-codesize"></A> </P>
<DT><B><CODE>--codesize x</CODE></B><DD>
<P>This options allows finer control about speed vs. size decisions in the code
generation and optimization phases. It gives the allowed size increase
factor (in percent). The default is 100 when not using <CODE>-Oi</CODE> and 200 when
using <CODE>-Oi</CODE> (<CODE>-Oi</CODE> is the same as <CODE>-O --codesize 200</CODE>).</P>
<P>
<A NAME="option--cpu"></A> </P>
<DT><B><CODE>--cpu CPU</CODE></B><DD>
<P>Set the CPU, the compiler generates code for. You may specify "6502" or
"65C02" as the CPU. The default depends on the selected target (see option
<CODE>
<A HREF="#option-t">-t</A></CODE>). It is the 6502 CPU for most targets or
if no target has been set. Specifying 65C02 will use a few 65C02
instructions when generating code. Don't expect too much from this option:
In most cases the difference in size and speed is just 1-2%.</P>
<P>
<A NAME="option-create-dep"></A> </P>
<DT><B><CODE>--create-dep name</CODE></B><DD>
<P>Tells the compiler to generate a file containing the dependency list for the
compiled module in makefile syntax. The output is written to a file with the
given name. The output does not include system include files (in angle
brackets).</P>
<P>
<A NAME="option-create-full-dep"></A> </P>
<DT><B><CODE>--create-full-dep name</CODE></B><DD>
<P>Tells the compiler to generate a file containing the dependency list for the
compiled module in makefile syntax. The output is written to a file with the
given name. The output does include system include files (in angle
brackets).</P>
<P>
<A NAME="option-data-name"></A> </P>
<DT><B><CODE>--data-name seg</CODE></B><DD>
<P>Set the name of the data segment. See also <CODE>
<A HREF="#pragma-data-name">#pragma data-name</A></CODE></P>
<DT><B><CODE>-d, --debug</CODE></B><DD>
<P>Enables debug mode, for debugging the behavior of cc65.</P>
<P>
<A NAME="option-dM"></A> </P>
<DT><B><CODE>-dM</CODE></B><DD>
<P>When used with -E, will output <CODE>#define</CODE> directives for all the user
macros defined during execution of the preprocessor. This does not include
macros defined by the compiler.</P>
<P>Note: Can be combined with <CODE>
<A HREF="#option-dP">-dP</A></CODE> by using
<CODE>-dMP</CODE>.</P>
<P>
<A NAME="option-dP"></A> </P>
<DT><B><CODE>-dP</CODE></B><DD>
<P>When used with -E, will output <CODE>#define</CODE> directives for all the macros
defined by the compiler itself. This does not include any user defined macros.</P>
<P>Note: Can be combined with <CODE>
<A HREF="#option-dM">-dM</A></CODE> by using
<CODE>-dMP</CODE>.</P>
<DT><B><CODE>--debug-tables name</CODE></B><DD>
<P>Writes symbol table information to a file, which includes details on structs, unions
functions, and global variables. For example, given the following code:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
struct l {
unsigned char m;
unsigned char n;
};
struct hello {
unsigned char j;
unsigned char k;
struct l l;
};
struct sub {
unsigned char x;
unsigned char y;
};
union xy {
struct sub xy;
unsigned int mem;
};
typedef struct hello thingy;
unsigned char single;
unsigned char test_local_vars_main(void) {
static unsigned char wahoo;
static unsigned char bonanza = 0x42;
unsigned char i;
unsigned int j;
unsigned int *random;
unsigned char *lol;
signed char whoa;
struct hello wow;
thingy *cool;
union xy xy;
return 0;
}
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>The following output would be produced:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
SC_FUNC: _test_local_vars_main: Symbol table
============================================
__fixargs__:
Flags: SC_CONST SC_DEF
Type: unsigned int
__argsize__:
Flags: SC_CONST SC_DEF
Type: unsigned char
wahoo:
AsmName: M0001
Flags: SC_STATIC SC_DEF SC_REF
Type: unsigned char
bonanza:
AsmName: M0002
Flags: SC_STATIC SC_DEF SC_REF
Type: unsigned char
i:
Flags: SC_AUTO SC_DEF SC_REF
Type: unsigned char
j:
Flags: SC_AUTO SC_DEF SC_REF
Type: unsigned int
random:
Flags: SC_AUTO SC_DEF SC_REF
Type: unsigned int *
lol:
Flags: SC_AUTO SC_DEF SC_REF
Type: unsigned char *
whoa:
Flags: SC_AUTO SC_DEF SC_REF
Type: signed char
wow:
Flags: SC_AUTO SC_DEF SC_REF
Type: struct hello
cool:
Flags: SC_AUTO SC_DEF SC_REF
Type: struct hello *
xy:
Flags: SC_AUTO SC_DEF SC_REF
Type: union xy
Global symbol table
===================
thingy:
AsmName: _thingy
Flags: SC_TYPEDEF 0x100000
Type: struct hello
single:
AsmName: _single
Flags: SC_STATIC SC_EXTERN SC_STORAGE SC_DEF SC_REF 0x100000
Type: unsigned char
test_local_vars_main:
AsmName: _test_local_vars_main
Flags: SC_FUNC SC_STATIC SC_EXTERN SC_DEF 0x100000
Type: unsigned char (void)
Global tag table
================
l:
Flags: SC_STRUCT SC_DEF
Type: (none)
hello:
Flags: SC_STRUCT SC_DEF
Type: (none)
sub:
Flags: SC_STRUCT SC_DEF
Type: (none)
xy:
Flags: SC_UNION SC_DEF
Type: (none)
Global struct and union definitions
=========================
SC_STRUCT: l
============
m:
Flags: SC_STRUCTFIELD
Type: unsigned char
n:
Flags: SC_STRUCTFIELD
Type: unsigned char
SC_STRUCT: hello
================
j:
Flags: SC_STRUCTFIELD
Type: unsigned char
k:
Flags: SC_STRUCTFIELD
Type: unsigned char
l:
Flags: SC_STRUCTFIELD
Type: struct l
SC_STRUCT: sub
==============
x:
Flags: SC_STRUCTFIELD
Type: unsigned char
y:
Flags: SC_STRUCTFIELD
Type: unsigned char
SC_UNION: xy
============
xy:
Flags: SC_STRUCTFIELD
Type: struct sub
mem:
Flags: SC_STRUCTFIELD
Type: unsigned int
</PRE>
</CODE></BLOCKQUOTE>
</P>
<DT><B><CODE>--debug-opt name</CODE></B><DD>
<P>The named file contains a list of specific optimization steps to enable or disable.
Each line contains the name of an optimization step with either a
<CODE>+</CODE> (enable) or <CODE>-</CODE> (disable) prefix.
The name <CODE>all</CODE> can be used to enable or disable all optimizations.
Comment lines may begin with <CODE>#</CODE> or <CODE>;</CODE>.</P>
<P>Use <CODE>--list-opt-steps</CODE> to generate a complete list of available optimization steps.</P>
<P>Use <CODE>--debug</CODE> to see a list of optimizations applied during compilation.</P>
<DT><B><CODE>--debug-opt-output</CODE></B><DD>
<P>For debugging the output of each optimization pass, step by step.
Generates a <CODE>name.opt</CODE> output listing for each optimized function <CODE>name</CODE>.</P>
<P>
<A NAME="option-dep-target"></A> </P>
<DT><B><CODE>--dep-target target</CODE></B><DD>
<P>When generating a dependency file, don't use the actual output file as the
target of the dependency, but the file specified with this option. The
option has no effect if neither <CODE>
<A HREF="#option-create-dep">--create-dep</A></CODE> nor <CODE>
<A HREF="#option-create-full-dep">--create-full-dep</A></CODE> is specified.</P>
<DT><B><CODE>-D sym[=definition]</CODE></B><DD>
<P>Define a macro on the command line. If no definition is given, the macro
is defined to the value "1".</P>
<DT><B><CODE>-g, --debug-info</CODE></B><DD>
<P>This will cause the compiler to insert a <CODE>.DEBUGINFO</CODE> command into the
generated assembler code. This will cause the assembler to include all
symbols in a special section in the object file.</P>
<P>
<A NAME="option-eagerly-inline-funcs"></A> </P>
<DT><B><CODE>--eagerly-inline-funcs</CODE></B><DD>
<P>Have the compiler eagerly inline these functions from the C library:
<UL>
<LI><CODE>memcpy()</CODE></LI>
<LI><CODE>memset()</CODE></LI>
<LI><CODE>strcmp()</CODE></LI>
<LI><CODE>strcpy()</CODE></LI>
<LI><CODE>strlen()</CODE></LI>
</UL>
</P>
<P>Note: This has two consequences:
<UL>
<LI>You may not use names of standard C functions for your own functions.
If you do that, your program is not standard-compliant anyway; but,
using <CODE>--eagerly-inline-funcs</CODE> actually will break things.
</LI>
<LI>The inlined string and memory functions will not handle strings or
memory areas larger than 255 bytes.
</LI>
</UL>
</P>
<P><CODE>--eagerly-inline-funcs</CODE> implies the <CODE>
<A HREF="#option-inline-stdfuncs">--inline-stdfuncs</A></CODE> command line option.</P>
<P>See also <CODE>
<A HREF="#pragma-allow-eager-inline">#pragma allow-eager-inline</A></CODE>.</P>
<DT><B><CODE>-h, --help</CODE></B><DD>
<P>Print the short option summary shown above.</P>
<P>
<A NAME="option-inline-stdfuncs"></A> </P>
<DT><B><CODE>--inline-stdfuncs</CODE></B><DD>
<P>Allow the compiler to inline some standard functions from the C library like
strlen. This will not only remove the overhead for a function call, but will
make the code visible for the optimizer. See also the <CODE>
<A HREF="#option-O">-Os</A></CODE> command line option and <CODE>
<A HREF="#pragma-inline-stdfuncs">#pragma inline-stdfuncs</A></CODE>.</P>
<P>
<A NAME="option-list-warnings"></A> </P>
<DT><B><CODE>--list-warnings</CODE></B><DD>
<P>List the names of warning types available for use with <CODE>
<A HREF="#option-W">-W</A></CODE>.</P>
<P>
<A NAME="option-local-strings"></A> </P>
<DT><B><CODE>--local-strings</CODE></B><DD>
<P>Emit string literals into the rodata segment as soon as they're encountered
in the source (even if you do nothing but get the sizeof those strings). The
default is to keep string literals until end of assembly, merge read only
literals if possible, and then output the literals into the data or rodata
segment that is active at that point. Use of this option prevents merging of
duplicate strings, but the options that change the name of one of the data
segments will work.</P>
<P>You can also use <CODE>
<A HREF="#pragma-local-strings">#pragma local-strings</A></CODE> for fine grained control.</P>
<DT><B><CODE>-mm model, --memory-model model</CODE></B><DD>
<P>This option sets the code and data models for the compiler to use. Please
note that memory models are an unfinished feature and using this option
with any other memory model than <CODE>near</CODE> will cause compile errors.
Possible arguments are:</P>
<P>
<DL>
<DT><B>near</B><DD>
<P>This memory model uses 16 bit addresses for code and data. It is
currently the only supported memory model and suited for the 6502.</P>
<DT><B>far</B><DD>
<P>This memory model uses 24 bit addresses for code and 16 bit addresses
for data. It is suited for the 65816 but currently unsupported.</P>
<DT><B>huge</B><DD>
<P>This memory model uses 24 bit addresses for code and data. It is
suited for the 65816 but currently unsupported.</P>
</DL>
</P>
<DT><B><CODE>-o name</CODE></B><DD>
<P>Specify the name of the output file. If you don't specify a name, the
name of the C input file is used, with the extension replaced by ".s".</P>
<P>
<A NAME="option-register-vars"></A> </P>
<DT><B><CODE>-r, --register-vars</CODE></B><DD>
<P><CODE>-r</CODE> will make the compiler honor the <CODE>register</CODE> keyword. Local
variables may be placed in registers (which are actually zero page
locations). There is some overhead involved with register variables, since
the old contents of the registers must be saved and restored. Since register
variables are of limited use without the optimizer, there is also a combined
switch: <CODE>-Or</CODE> will enable both, the optimizer and register variables.</P>
<P>For more information about register variables see
<A HREF="#register-vars">register variables</A>.</P>
<P>The compiler setting can also be changed within the source file by using
<CODE>
<A HREF="#pragma-register-vars">#pragma register-vars</A></CODE>.</P>
<P>
<A NAME="option-register-space"></A> </P>
<DT><B><CODE>--register-space</CODE></B><DD>
<P>This option takes a numeric parameter and is used to specify, how much
zero page register space is available. Please note that just giving this
option will not increase or decrease by itself, it will just tell the
compiler about the available space. You will have to allocate that space
yourself using an assembler module with the necessary allocations, and a
linker configuration that matches the assembler module. The default value
for this option is 6 (bytes).</P>
<P>If you don't know what all this means, please don't use this option.</P>
<P>
<A NAME="option-rodata-name"></A> </P>
<DT><B><CODE>--rodata-name seg</CODE></B><DD>
<P>Set the name of the rodata segment (the segment used for readonly data).
See also <CODE>
<A HREF="#pragma-rodata-name">#pragma rodata-name</A></CODE></P>
<P>
<A NAME="option-signed-chars"></A> </P>
<DT><B><CODE>-j, --signed-chars</CODE></B><DD>
<P>Using this option, you can make the default characters signed. Since the
6502 has no provisions for sign extending characters (which is needed on
almost any load operation), this will make the code larger and slower. A
better way is to declare characters explicitly as "signed" if needed. You
can also use <CODE>
<A HREF="#pragma-signed-chars">#pragma signed-chars</A></CODE> for better control of this option.</P>
<P>
<A NAME="option--standard"></A> </P>
<DT><B><CODE>--standard std</CODE></B><DD>
<P>This option allows to set the language standard supported. The argument is
one of
<DL>
<DT><B>c89</B><DD>
<P>This disables anything that is illegal in C89/C90. Among those things
are <CODE>//</CODE> comments and the non-standard keywords without
underscores. Please note that cc65 is not a fully C89 compliant compiler
despite this option. A few more things (like floats) are missing.</P>
<DT><B>c99</B><DD>
<P>This enables a few features from the C99 standard. With this option,
<CODE>//</CODE> comments are allowed. It will also cause warnings and even
errors in a few situations that are allowed with <CODE>--standard c89</CODE>.
For example, a call to a function without a prototype is an error in
this mode.</P>
<DT><B>cc65</B><DD>
<P>This is the default mode. It is like c99 mode, but additional features
are enabled. Among these are "void data", non-standard keywords without
the underlines, unnamed function parameters and the requirement for
main() to return an int.</P>
</DL>
</P>
<P>Please note that the compiler does not support the C99 standard and never
will. c99 mode is actually c89 mode with a few selected C99 extensions.</P>
<P>
<A NAME="option-t"></A> </P>
<DT><B><CODE>-t target, --target target</CODE></B><DD>
<P>This option is used to set the target system. The target system determines
the character set that is used for strings and character constants and the
default CPU. The CPU setting can be overridden by use of the <CODE>
<A HREF="#option--cpu">--cpu</A></CODE> option.</P>
<P>The following target systems are supported:</P>
<P>
<UL>
<LI>none</LI>
<LI>agat (a russian apple2 like computer)</LI>
<LI>apple2</LI>
<LI>apple2enh</LI>
<LI>atari</LI>
<LI>atari2600</LI>
<LI>atari5200</LI>
<LI>atari7800</LI>
<LI>atarixl</LI>
<LI>atmos</LI>
<LI>bbc</LI>
<LI>c16 (works also for the c116 with memory up to 32K)</LI>
<LI>c64</LI>
<LI>c65</LI>
<LI>c128</LI>
<LI>cbm510 (CBM-II series with 40 column video)</LI>
<LI>cbm610 (all CBM-II II computers with 80 column video)</LI>
<LI>creativision</LI>
<LI>cx16</LI>
<LI>gamate</LI>
<LI>geos-apple</LI>
<LI>geos-cbm</LI>
<LI>geos (alias for geos-cbm)</LI>
<LI>kim1</LI>
<LI>lunix</LI>
<LI>lynx</LI>
<LI>mega65</LI>
<LI>nes</LI>
<LI>osic1p</LI>
<LI>pce (PC engine)</LI>
<LI>pet (all CBM PET systems except the 2001)</LI>
<LI>plus4</LI>
<LI>rp6502</LI>
<LI>sim6502</LI>
<LI>sim65c02</LI>
<LI>supervision</LI>
<LI>sym1</LI>
<LI>telestrat</LI>
<LI>vic20</LI>
</UL>
</P>
<DT><B><CODE>-v, --verbose</CODE></B><DD>
<P>Using this option, the compiler will be somewhat more verbose if errors
or warnings are encountered.</P>
<P>
<A NAME="option--warnings-as-errors"></A> </P>
<DT><B><CODE>--warnings-as-errors</CODE></B><DD>
<P>Treat all warnings as error. This makes the compiler exit with an appropriate
error code in case of warnings. The effect of this switch is identical to
the command line option <CODE>
<A HREF="#option-W">-W error</A></CODE>. It is
available for compatibility with the other tools.</P>
<P>
<A NAME="option-writable-strings"></A> </P>
<DT><B><CODE>--writable-strings</CODE></B><DD>
<P>Make string literals writable by placing them into the data segment instead
of the rodata segment. You can also use <CODE>
<A HREF="#pragma-writable-strings">#pragma writable-strings</A></CODE> to control this option from within
the source file.</P>
<P>
<A NAME="option-static-locals"></A> </P>
<DT><B><CODE>-Cl, --static-locals</CODE></B><DD>
<P>Use static storage for local variables instead of storage on the stack.
Since the stack is emulated in software, this gives shorter and usually
faster code, but the code is no longer reentrant as required for recursion.
The difference between <CODE>-Cl</CODE> and declaring local variables as static
yourself is, that initializer code is executed each time, the function is
entered. So when using</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
void f (void)
{
unsigned a = 1;
...
}
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>the variable <CODE>a</CODE> will always have the value <CODE>1</CODE> when entering the
function and using <CODE>-Cl</CODE>, while in</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
void f (void)
{
static unsigned a = 1;
....
}
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>the variable <CODE>a</CODE> will have the value <CODE>1</CODE> only the first time that the
function is entered, and will keep the old value from one call of the
function to the next.</P>
<P>You may also use <CODE>
<A HREF="#pragma-static-locals">#pragma static-locals</A></CODE> to change this setting in your
sources.</P>
<P>
<A NAME="option-include-dir"></A> </P>
<DT><B><CODE>-I dir, --include-dir dir</CODE></B><DD>
<P>Set a directory where the compiler searches for include files. You may
use this option multiple times to add more than one directory to the
search list.</P>
<P>
<A NAME="option-O"></A> </P>
<DT><B><CODE>-O, -Oi, -Or, -Os</CODE></B><DD>
<P>Enable an optimizer run over the produced code.</P>
<P>Using <CODE>-Oi</CODE>, the code generator will inline some code where otherwise a
runtime functions would have been called, even if the generated code is
larger. This will not only remove the overhead for a function call, but will
make the code visible for the optimizer. <CODE>-Oi</CODE> is an alias for
<CODE>-O --codesize 200</CODE>.</P>
<P><CODE>-Or</CODE> will make the compiler honor the <CODE>register</CODE> keyword. Local
variables may be placed in registers (which are actually zero page
locations). See also the <CODE>
<A HREF="#option-register-vars">--register-vars</A></CODE> command line option, and the
<A HREF="#register-vars">discussion of register variables</A> below.</P>
<P>Using <CODE>-Os</CODE> will allow the compiler to inline some standard functions
from the C library like strlen. This will not only remove the overhead
for a function call, but will make the code visible for the optimizer.
See also the <CODE>
<A HREF="#option-inline-stdfuncs">--inline-stdfuncs</A></CODE>
command line option.</P>
<P>It is possible to concatenate the modifiers for <CODE>-O</CODE>. For example, to
enable register variables and inlining of standard functions, you may use
<CODE>-Ors</CODE>.</P>
<DT><B><CODE>-T, --add-source</CODE></B><DD>
<P>This include the source code as comments in the generated code. This is
normally not needed.</P>
<DT><B><CODE>-V, --version</CODE></B><DD>
<P>Print the version number of the compiler. When submitting a bug report,
please include the operating system you're using, and the compiler
version.</P>
<P>
<A NAME="option-W"></A> </P>
<DT><B><CODE>-W name[,name,...]</CODE></B><DD>
<P>This option allows to control warnings generated by the compiler. It is
followed by a comma-separated list of warnings that should be enabled or
disabled. To disable a warning, its name is prefixed by a minus sign. If
no such prefix exists, or the name is prefixed by a plus sign, the warning
is enabled.</P>
<P>The following warning names currently are recognized:
<DL>
<DT><B><CODE>const-comparison</CODE></B><DD>
<P>Warn if the result of a comparison is constant.</P>
<DT><B><CODE>error</CODE></B><DD>
<P>Treat all warnings as errors. This has the same effect as using the
<CODE>
<A HREF="#option--warnings-as-errors">--warnings-as-errors</A></CODE>
option.</P>
<DT><B><CODE>no-effect</CODE></B><DD>
<P>Warn about statements that don't have an effect.</P>
<DT><B><CODE>pointer-sign</CODE></B><DD>
<P>Warn if a pointer assignment changes the signedness of the target
of a pointer value, and the new signedness wasn't cast explicitly.</P>
<DT><B><CODE>pointer-types</CODE></B><DD>
<P>Warn if a pointer assignment changes the type of the target
of a pointer value, and the new type wasn't cast explicitly.</P>
<DT><B><CODE>remap-zero</CODE></B><DD>
<P>Warn about a <CODE>
<A HREF="#pragma-charmap">#pragma charmap()</A></CODE>
that changes a character's code number from/to 0x00.</P>
<DT><B><CODE>return-type</CODE></B><DD>
<P>Warn about no return statement in function returning non-void.</P>
<DT><B><CODE>struct-param</CODE></B><DD>
<P>Warn when passing structs by value. (Disabled by default.)</P>
<DT><B><CODE>unknown-pragma</CODE></B><DD>
<P>Warn about #pragmas that aren't recognized by cc65.</P>
<DT><B><CODE>unreachable-code</CODE></B><DD>
<P>Warn about unreachable code in cases of comparing constants, etc.</P>
<DT><B><CODE>unused-func</CODE></B><DD>
<P>Warn about unused functions.</P>
<DT><B><CODE>unused-label</CODE></B><DD>
<P>Warn about unused labels.</P>
<DT><B><CODE>unused-param</CODE></B><DD>
<P>Warn about unused function parameters.</P>
<DT><B><CODE>unused-var</CODE></B><DD>
<P>Warn about unused variables.</P>
<DT><B><CODE>const-overflow</CODE></B><DD>
<P>Warn if numerical constant conversion implies overflow. (Disabled by default.)</P>
</DL>
</P>
<P>The full list of available warning names can be retrieved by using the
option <CODE>
<A HREF="#option-list-warnings">--list-warnings</A></CODE>.</P>
<P>You may use also <CODE>
<A HREF="#pragma-warn">#pragma warn</A></CODE> to
control this setting, for smaller pieces of code, from within your sources.</P>
</DL>
</P>
<H2><A NAME="s3">3.</A> <A HREF="#toc3">Input and output</A></H2>
<P>The compiler will accept one C file per invocation and create a file with
the same base name, but with the extension replaced by ".s". The output
file contains assembler code suitable for use with the ca65 macro
assembler.</P>
<P>Include files in quotes are searched in the following places:
<OL>
<LI>The current file's directory.</LI>
<LI>Any directory added with the <CODE>-I</CODE> option on the command line.</LI>
<LI>The value of the environment variable <CODE>CC65_INC</CODE> if it is defined.</LI>
</OL>
</P>
<P>Include files in angle brackets are searched in the following places:
<OL>
<LI>Any directory added with the <CODE>-I</CODE> option on the command line.</LI>
<LI>The value of the environment variable <CODE>CC65_INC</CODE> if it is defined.</LI>
<LI>A subdirectory named <CODE>include</CODE> of the directory defined in the
environment variable <CODE>CC65_HOME</CODE>, if it is defined.</LI>
<LI>An optionally compiled-in directory.</LI>
</OL>
</P>
<H2><A NAME="s4">4.</A> <A HREF="#toc4">Differences to the ISO standard</A></H2>
<P>Apart from the things listed below, the compiler does support additional
keywords, has several functions in the standard headers with names outside the
reserved namespace and a few syntax extensions. All these can be disabled with
the <CODE>
<A HREF="#option--standard">--standard</A></CODE> command line
option. Its use for maximum standards compatibility is advised.</P>
<P>Here is a list of differences between the language, the compiler accepts,
and the one defined by the ISO standard:</P>
<P>
<UL>
<LI> The datatypes "float" and "double" are not available.
Floating point constants may be used, though they will have to be
converted and stored into integer values.
Floating point arithmetic expressions are not supported.
</LI>
<LI> C Functions may pass and return structs (or unions) by value, but only
of 1, 2 or 4 byte sizes.
</LI>
<LI> Most of the C library is available with only the fastcall calling
convention (
<A HREF="#extension-fastcall">see below</A>). It means
that you must not mix pointers to those functions with pointers to
user-written, cdecl functions (the calling conventions are incompatible).
</LI>
<LI> The <CODE>volatile</CODE> keyword has almost no effect. That is not as bad
as it sounds, since the 6502 has so few registers that it isn't
possible to keep values in registers anyway.
</LI>
<LI> In <CODE>cc65</CODE> mode, <CODE>main()</CODE> cannot be called recursively. If this
is necessary, the program must be compiled in <CODE>c89</CODE> or <CODE>c99</CODE> mode
using the <CODE>
<A HREF="#option--standard">--standard</A></CODE>
command line option.
</LI>
</UL>
</P>
<P>There may be some more minor differences I'm currently not aware of. The
biggest problem is the missing float data type. With this limitation in
mind, you should be able to write fairly portable code.</P>
<H2><A NAME="s5">5.</A> <A HREF="#toc5">Extensions</A></H2>
<P>This cc65 version has some extensions to the ISO C standard.</P>
<P>
<UL>
<LI> The compiler allows to insert inline assembler code in the form of the
<CODE>asm</CODE> expression into the output file. The syntax is
<BLOCKQUOTE><CODE>
<PRE>
asm [optional volatile] (<string literal>[, optional parameters])
</PRE>
</CODE></BLOCKQUOTE>
or
<BLOCKQUOTE><CODE>
<PRE>
__asm__ [optional volatile] (<string literal>[, optional parameters])
</PRE>
</CODE></BLOCKQUOTE>
The first form is in the user namespace; and, is disabled if the <CODE>-A</CODE>
switch is given.
There is a whole section covering the inline assembler,
<A HREF="#inline-asm">see there</A>.
<P>
<A NAME="extension-fastcall"></A> </P>