]> git.sur5r.net Git - cc65/blob - doc/cc65.sgml
More driver cleanup.
[cc65] / doc / cc65.sgml
1 <!doctype linuxdoc system>
2
3 <article>
4 <title>cc65 Users Guide
5 <author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
6 <date>2000-09-03, 2001-10-02, 2005-08-01
7
8 <abstract>
9 cc65 is a C compiler for 6502 targets. It supports several 6502 based home
10 computers like the Commodore and Atari machines, but it is easily retargetable.
11 </abstract>
12
13 <!-- Table of contents -->
14 <toc>
15
16 <!-- Begin the document -->
17
18
19 <sect>Overview<p>
20
21 cc65 was originally a C compiler for the Atari 8-bit machines written by
22 John R. Dunning. In prior releases I've described the compiler by listing
23 up the changes made by me. I have made many more changes in the meantime
24 (and rewritten major parts of the compiler), so I will no longer do that,
25 since the list would be too large and of no use to anyone. Instead I will
26 describe the compiler in respect to the ANSI/ISO C standard.
27
28 There are separate documents named <url url="library.html"> and <url
29 url="funcref.html"> that cover the library that is available for the compiler.
30 If you know C, and are interested in doing actual programming, the library
31 documentation is probably of much more use than this document.
32
33 If you need some hints for getting the best code out of the compiler, you
34 may have a look at <url url="coding.html"> which covers some code generation
35 issues.
36
37
38
39 <sect>Usage<p>
40
41 The compiler translates C files into files containing assembly code that
42 may be translated by the ca65 macroassembler (for more information about
43 the assembler, have a look at <url url="ca65.html">).
44
45
46 <sect1>Command line option overview<p>
47
48 The compiler may be called as follows:
49
50 <tscreen><verb>
51 ---------------------------------------------------------------------------
52 Usage: cc65 [options] file
53 Short options:
54   -Cl                   Make local variables static
55   -Dsym[=defn]          Define a symbol
56   -I dir                Set an include directory search path
57   -O                    Optimize code
58   -Oi                   Optimize code, inline more code
59   -Or                   Enable register variables
60   -Os                   Inline some known functions
61   -T                    Include source as comment
62   -V                    Print the compiler version number
63   -W name[,name]        Enable or disable warnings
64   -d                    Debug mode
65   -g                    Add debug info to object file
66   -h                    Help (this text)
67   -j                    Default characters are signed
68   -o name               Name the output file
69   -r                    Enable register variables
70   -t sys                Set the target system
71   -v                    Increase verbosity
72
73 Long options:
74   --add-source          Include source as comment
75   --bss-name seg        Set the name of the BSS segment
76   --check-stack         Generate stack overflow checks
77   --code-name seg       Set the name of the CODE segment
78   --codesize x          Accept larger code by factor x
79   --cpu type            Set cpu type
80   --create-dep          Create a make dependency file
81   --data-name seg       Set the name of the DATA segment
82   --debug               Debug mode
83   --debug-info          Add debug info to object file
84   --forget-inc-paths    Forget include search paths
85   --help                Help (this text)
86   --include-dir dir     Set an include directory search path
87   --local-strings       Emit string literals immediately
88   --register-space b    Set space available for register variables
89   --register-vars       Enable register variables
90   --rodata-name seg     Set the name of the RODATA segment
91   --signed-chars        Default characters are signed
92   --standard std        Language standard (c89, c99, cc65)
93   --static-locals       Make local variables static
94   --target sys          Set the target system
95   --verbose             Increase verbosity
96   --version             Print the compiler version number
97   --writable-strings    Make string literals writable
98 ---------------------------------------------------------------------------
99 </verb></tscreen>
100
101
102 <sect1>Command line options in detail<p>
103
104 Here is a description of all the command line options:
105
106 <descrip>
107
108   <label id="option-bss-name">
109   <tag><tt>--bss-name seg</tt></tag>
110
111   Set the name of the bss segment. See also <tt/<ref id="pragma-bss-name"
112   name="#pragma&nbsp;bss-name">/.
113
114
115   <label id="option-check-stack">
116   <tag><tt>--check-stack</tt></tag>
117
118   Tells the compiler to generate code that checks for stack overflows. See
119   <tt/<ref id="pragma-check-stack" name="#pragma&nbsp;check-stack">/ for an
120   explanation of this feature.
121
122
123   <label id="option-code-name">
124   <tag><tt>--code-name seg</tt></tag>
125
126   Set the name of the code segment. See also <tt/<ref id="pragma-code-name"
127   name="#pragma&nbsp;code-name">/
128
129
130   <label id="option-codesize">
131   <tag><tt>--codesize x</tt></tag>
132
133   This options allows finer control about speed vs. size decisions in the code
134   generation and optimization phases. It gives the allowed size increase
135   factor (in percent). The default is 100 when not using <tt/-Oi/ and 200 when
136   using <tt/-Oi/ (<tt/-Oi/ is the same as <tt/-O --codesize&nbsp;200/).
137
138
139   <label id="option-cpu">
140   <tag><tt>--cpu CPU</tt></tag>
141
142   A new, still experimental option. You may specify "6502" or "65C02" as
143   the CPU. 6502 is the default, so this will not change anything.
144   Specifying 65C02 will use a few 65C02 instructions when generating code.
145   Don't expect too much from this option: It is still new (and may have
146   bugs), and the additional instructions for the 65C02 are not that
147   overwhelming.
148
149
150   <label id="option-create-dep">
151   <tag><tt>--create-dep</tt></tag>
152
153   Tells the compiler to generate a file containing the dependency list for
154   the compiled module in makefile syntax. The file is named as the C input
155   file with the extension replaced by <tt/.u/.
156
157
158   <label id="option-data-name">
159   <tag><tt>--data-name seg</tt></tag>
160
161   Set the name of the data segment. See also <tt/<ref id="pragma-data-name"
162   name="#pragma&nbsp;data-name">/
163
164
165   <tag><tt>-d, --debug</tt></tag>
166
167   Enables debug mode, something that should not be needed for mere
168   mortals:-)
169
170
171   <tag><tt>-D sym[=definition]</tt></tag>
172
173   Define a macro on the command line. If no definition is given, the macro
174   is defined to the value "1".
175
176
177   <tag><tt>--forget-inc-paths</tt></tag>
178
179   Forget the builtin include paths. This is most useful when building
180   customized C or runtime libraries, in which case the standard header
181   files should be ignored.
182
183
184   <tag><tt>-g, --debug-info</tt></tag>
185
186   This will cause the compiler to insert a <tt/.DEBUGINFO/ command into the
187   generated assembler code. This will cause the assembler to include all
188   symbols in a special section in the object file.
189
190
191   <tag><tt>-h, --help</tt></tag>
192
193   Print the short option summary shown above.
194
195
196   <label id="option-local-strings">
197   <tag><tt>--local-strings</tt></tag>
198
199   Emit string literals to the data segment when they're encountered in the
200   source. The default is to keep string literals until end of assembly, merge
201   read only literals if possible, and then output the literals into the data
202   or rodata segment that is active at that point. Use of this option prevents
203   merging of duplicate strings, but the options that change the name of one of
204   the data segments will work.
205
206   You can also use <tt><ref id="pragma-local-strings"
207   name="#pragma&nbsp;local-strings"></tt> for fine grained control.
208
209
210   <tag><tt>-o name</tt></tag>
211
212   Specify the name of the output file. If you don't specify a name, the
213   name of the C input file is used, with the extension replaced by ".s".
214
215
216   <label id="option-register-vars">
217   <tag><tt>-r, --register-vars</tt></tag>
218
219   <tt/-r/ will make the compiler honor the <tt/register/ keyword. Local
220   variables may be placed in registers (which are actually zero page
221   locations). There is some overhead involved with register variables, since
222   the old contents of the registers must be saved and restored. Since register
223   variables are of limited use without the optimizer, there is also a combined
224   switch: <tt/-Or/ will enable both, the optimizer and register variables.
225
226   For more information about register variables see <ref id="register-vars"
227   name="register variables">.
228
229   The compiler setting can also be changed within the source file by using
230   <tt/<ref id="pragma-register-vars" name="#pragma&nbsp;register-vars">/.
231
232
233   <label id="option-register-space">
234   <tag><tt>--register-space</tt></tag>
235
236   This option takes a numeric parameter and is used to specify, how much
237   zero page register space is available. Please note that just giving this
238   option will not increase or decrease by itself, it will just tell the
239   compiler about the available space. You will have to allocate that space
240   yourself using an assembler module with the necessary allocations, and a
241   linker configuration that matches the assembler module. The default value
242   for this option is 6 (bytes).
243
244   If you don't know what all this means, please don't use this option.
245
246
247   <label id="option-rodata-name">
248   <tag><tt>--rodata-name seg</tt></tag>
249
250   Set the name of the rodata segment (the segment used for readonly data).
251   See also <tt/<ref id="pragma-rodata-name" name="#pragma&nbsp;rodata-name">/
252
253   <label id="option-signed-chars">
254   <tag><tt>-j, --signed-chars</tt></tag>
255
256   Using this option, you can make the default characters signed. Since the
257   6502 has no provisions for sign extending characters (which is needed on
258   almost any load operation), this will make the code larger and slower. A
259   better way is to declare characters explicitly as "signed" if needed. You
260   can also use <tt><ref id="pragma-signed-chars"
261   name="#pragma&nbsp;signed-chars"></tt> for better control of this option.
262
263
264   <label id="option--standard">
265   <tag><tt>--standard std</tt></tag>
266
267   This option allows to set the language standard supported. The argument is
268   one of
269   <itemize>
270   <item>c89
271   <item>c99
272   <item>cc65
273   </itemize>
274
275   Please note that the compiler does not support the c99 standard and never
276   will. c99 mode is actually c89 mode with a few selected c99 extensions
277   (// comments for example).
278
279
280   <label id="option-standard">
281   <tag><tt>-t target, --target target</tt></tag>
282
283   This option is used to set the target system. The target system
284   determines things like the character set that is used for strings and
285   character constants. The following target systems are supported:
286
287   <itemize>
288   <item>none
289   <item>apple2
290   <item>apple2enh
291   <item>atari
292   <item>atmos
293   <item>c16 (works also for the c116 with memory up to 32K)
294   <item>c64
295   <item>c128
296   <item>cbm510 (CBM-II series with 40 column video)
297   <item>cbm610 (all CBM-II II computers with 80 column video)
298   <item>geos
299   <item>lunix
300   <item>lynx
301   <item>nes
302   <item>pet (all CBM PET systems except the 2001)
303   <item>plus4
304   <item>supervision
305   <item>vic20
306   </itemize>
307
308   <tag><tt>-v, --verbose</tt></tag>
309
310   Using this option, the compiler will be somewhat more verbose if errors
311   or warnings are encountered.
312
313
314   <label id="option-writable-strings">
315   <tag><tt>--writable-strings</tt></tag>
316
317   Make string literals writable by placing them into the data segment instead
318   of the rodata segment. You can also use <tt><ref id="pragma-writable-strings"
319   name="#pragma&nbsp;writable-strings"></tt> to control this option from within
320   the source file.
321
322
323   <label id="option-static-locals">
324   <tag><tt>-Cl, --static-locals</tt></tag>
325
326   Use static storage for local variables instead of storage on the stack.
327   Since the stack is emulated in software, this gives shorter and usually
328   faster code, but the code is no longer reentrant. The difference between
329   <tt/-Cl/ and declaring local variables as static yourself is, that
330   initializer code is executed each time, the function is entered. So when
331   using
332
333   <tscreen><verb>
334         void f (void)
335         {
336             unsigned a = 1;
337             ...
338         }
339   </verb></tscreen>
340
341   the variable <tt/a/ will always have the value <tt/1/ when entering the
342   function and using <tt/-Cl/, while in
343
344   <tscreen><verb>
345         void f (void)
346         {
347             static unsigned a = 1;
348             ....
349         }
350   </verb></tscreen>
351
352   the variable <tt/a/ will have the value <tt/1/ only the first time that the
353   function is entered, and will keep the old value from one call of the
354   function to the next.
355
356   You may also use <tt><ref id="pragma-static-locals"
357   name="#pragma&nbsp;static-locals"></tt> to change this setting in your
358   sources.
359
360
361   <label id="option-include-dir">
362   <tag><tt>-I dir, --include-dir dir</tt></tag>
363
364   Set a directory where the compiler searches for include files. You may
365   use this option multiple times to add more than one directory to the
366   search list.
367
368
369   <label id="option-O">
370   <tag><tt>-O, -Oi, -Or, -Os</tt></tag>
371
372   Enable an optimizer run over the produced code.
373
374   Using <tt/-Oi/, the code generator will inline some code where otherwise a
375   runtime functions would have been called, even if the generated code is
376   larger. This will not only remove the overhead for a function call, but will
377   make the code visible for the optimizer. <tt/-Oi/ is an alias for
378   <tt/-O --codesize&nbsp;200/.
379
380   <tt/-Or/ will make the compiler honor the <tt/register/ keyword. Local
381   variables may be placed in registers (which are actually zero page
382   locations). See also the <tt/<ref id="option-register-vars"
383   name="--register-vars">/ command line option, and the <ref
384   id="register-vars" name="discussion of register variables"> below.
385
386   Using <tt/-Os/ will force the compiler to inline some known functions from
387   the C library like strlen. Note: This has two consequences:
388   <p>
389   <itemize>
390   <item>You may not use names of standard C functions in your own code. If you
391         do that, your program is not standard compliant anyway, but using
392         <tt/-Os/ will actually break things.
393         <p>
394   <item>The inlined string and memory functions will not handle strings or
395         memory areas larger than 255 bytes. Similarly, the inlined <tt/is..()/
396         functions will not work with values outside the char. range (such as
397         <tt/EOF/).
398         <p>
399   </itemize>
400   <p>
401   It is possible to concatenate the modifiers for <tt/-O/. For example, to
402   enable register variables and inlining of known functions, you may use
403   <tt/-Ors/.
404
405
406   <tag><tt>-T, --add-source</tt></tag>
407
408   This include the source code as comments in the generated code. This is
409   normally not needed.
410
411
412   <tag><tt>-V, --version</tt></tag>
413
414   Print the version number of the compiler. When submitting a bug report,
415   please include the operating system you're using, and the compiler
416   version.
417
418
419   <label id="option-W">
420   <tag><tt>-W name[,name]</tt></tag>
421
422   This option allows to control warnings generated by the compiler. It is
423   followed by a comma separated list of warnings that should be enabled or
424   disabled. To disable a warning, its name is prefixed by a minus sign. If
425   no such prefix exists, or the name is prefixed by a plus sign, the warning
426   is enabled.
427
428   The following warning names are currently recognized:
429   <descrip>
430   <tag><tt/error/</tag>
431         Treat all warnings as errors.
432   <tag><tt/unknown-pragma/</tag>
433         Warn about known #pragmas.
434   <tag><tt/unused-label/</tag>
435         Warn about unused labels.
436   <tag><tt/unused-param/</tag>
437         Warn about unused function parameters.
438   <tag><tt/unused-var/</tag>
439         Warn about unused variables.
440   </descrip>
441
442   You may also use <tt><ref id="pragma-warn" name="#pragma&nbsp;warn"></tt> to
443   control this setting for smaller pieces of code from within your code.
444
445 </descrip><p>
446
447
448 <sect>Input and output<p>
449
450 The compiler will accept one C file per invocation and create a file with
451 the same base name, but with the extension replaced by ".s". The output
452 file contains assembler code suitable for the use with the ca65 macro
453 assembler.
454
455 Include files in single quotes are searched in the following places:
456 <enum>
457 <item>The current directory.
458 <item>The value of the environment variable <tt/CC65_INC/ if it is defined.
459 <item>Any directory added with the <tt/-I/ option on the command line.
460 </enum>
461
462 Include files in angle brackets are searched in the following places:
463 <enum>
464 <item>A compiled in directory which is often <tt>/usr/lib/cc65/include</tt> on
465       Linux systems.
466 <item>The value of the environment variable <tt/CC65_INC/ if it is defined.
467 <item>A subdirectory named <tt/include/ of the directory defined in the
468       environment variable <tt/CC65_HOME/, if it is defined.
469 <item>Any directory added with the <tt/-I/ option on the command line.
470 </enum>
471
472
473
474 <sect>Differences to the ISO standard<p>
475
476 Apart from the things listed below, the compiler does support additional
477 keywords, has several functions in the standard headers with names outside the
478 reserved namespace and a few syntax extensions. All these can be disabled with
479 the <tt><ref id="option--standard" name="--standard"></tt> command line
480 option. Its use for maximum standards compatibility is advised.
481
482 Here is a list of differences between the language, the compiler accepts,
483 and the one defined by the ISO standard:
484
485 <itemize>
486
487 <item>  The datatypes "float" and "double" are not available.
488         <p>
489 <item>  C Functions may not return structs (or unions), and structs may not
490         be passed as parameters by value. However, struct assignment *is*
491         possible.
492         <p>
493 <item>  Part of the C library is available only with fastcall calling
494         conventions (see below).  It means that you must not mix pointers to
495         those functions with pointers to user-written, not-fastcall functions.
496         <p>
497 <item>  The <tt/volatile/ keyword doesn't have an effect. This is not as bad
498         as it sounds, since the 6502 has so few registers that it isn't
499         possible to keep values in registers anyway.
500         <p>
501 </itemize>
502
503 There may be some more minor differences I'm currently not aware of. The
504 biggest problem is the missing float data type. With this limitation in
505 mind, you should be able to write fairly portable code.
506
507
508
509 <sect>Extensions<p>
510
511 This cc65 version has some extensions to the ISO C standard.
512
513 <itemize>
514
515 <item>  The compiler allows to insert assembler statements into the output
516         file. The syntax is
517
518         <tscreen><verb>
519         asm (&lt;string literal&gt;[, optional parameters]) ;
520         </verb></tscreen>
521         or
522         <tscreen><verb>
523         __asm__ (&lt;string literal&gt;[, optional parameters]) ;
524         </verb></tscreen>
525
526         The first form is in the user namespace and is disabled if the <tt/-A/
527         switch is given.
528
529         There is a whole section covering inline assembler statements,
530         <ref id="inline-asm" name="see there">.
531         <p>
532
533 <item>  There is a special calling convention named "fastcall".
534         The syntax for a function declaration using fastcall is
535
536         <tscreen><verb>
537         &lt;return type&gt; fastcall &lt;function name&gt; (&lt;parameter list&gt;)
538         </verb></tscreen>
539         or
540         <tscreen><verb>
541         &lt;return type&gt; __fastcall__ &lt;function name&gt; (&lt;parameter list&gt;)
542         </verb></tscreen>
543         An example would be
544         <tscreen><verb>
545         void __fastcall__ f (unsigned char c)
546         </verb></tscreen>
547         The first form of the fastcall keyword is in the user namespace and can
548         therefore be disabled with the <tt><ref id="option--standard"
549         name="--standard"></tt> command line option.
550
551         For functions declared as <tt/fastcall/, the rightmost parameter is not
552         pushed on the stack but left in the primary register when the function
553         is called. This will reduce the cost when calling assembler functions
554         significantly, especially when the function itself is rather small.
555         <p>
556
557 <item>  There are two pseudo variables named <tt/__AX__/ and <tt/__EAX__/.
558         Both refer to the primary register that is used by the compiler to
559         evaluate expressions or return function results. <tt/__AX__/ is of
560         type <tt/unsigned int/ and <tt/__EAX__/ of type <tt/long unsigned int/
561         respectively. The pseudo variables may be used as lvalue and rvalue as
562         every other variable. They are most useful together with short
563         sequences of assembler code. For example, the macro
564
565         <tscreen><verb>
566         #define hi(x)           \
567             (__AX__ = (x),      \
568              asm ("txa"),       \
569              asm ("ldx #$00"),  \
570              __AX__)
571         </verb></tscreen>
572
573         will give the high byte of any unsigned value.
574         <p>
575
576 <item>  Inside a function, the identifier <tt/__func__/ gives the name of the
577         current function as a string. Outside of functions, <tt/__func__/ is
578         undefined.
579         Example:
580
581         <tscreen><verb>
582         #define PRINT_DEBUG(s)  printf ("%s: %s\n", __func__, s);
583         </verb></tscreen>
584
585         The macro will print the name of the current function plus a given
586         string.
587         <p>
588
589 <item>  cc65 allows the initialization of <tt/void/ variables. This may be
590         used to create variable structures that are more compatible with
591         interfaces written for assembler languages. Here is an example:
592
593         <tscreen><verb>
594         void GCmd = {   (char)3, (unsigned)0x2000, (unsigned)0x3000 };
595         </verb></tscreen>
596
597         This will be translated as follows:
598
599         <tscreen><verb>
600         _GCmd:
601                 .byte   3
602                 .word   $2000
603                 .word   $3000
604         </verb></tscreen>
605
606         Since the variable is of type <tt/void/ you may not use it as is.
607         However, taking the address of the variable results in a <tt/void*/
608         which may be passed to any function expecting a pointer.
609
610         See the <url url="geos.html" name="GEOS library document"> for examples
611         on how to use this feature.
612         <p>
613
614 <item>  cc65 implements flexible array struct members as defined in the C99 ISO
615         standard. As an extension, these fields may be initialized. There are
616         several exceptions, however (which is probably the reason why the
617         standard does not define this feature, because it is highly
618         unorthogonal). Flexible array members cannot be initialized ...
619
620         <itemize>
621         <item>... when defining an array of structs with flexible
622                 members.
623         <item>... if such a struct is a member field of another struct
624                 which is not the last field.
625         <item>... if the struct which contains a flexible array member is
626                 declared as <tt/register/, and the size and compiler settings
627                 do allow the compiler actually to place the struct into the
628                 register bank in the zero page.
629         </itemize>
630
631         Please note that -- as defined in the ISO C standard -- the <tt/sizeof/
632         operator returns the struct size with the flexible array member having
633         size zero, even if it is initialized.
634         <p>
635
636 </itemize>
637 <p>
638
639
640 <sect>Predefined macros<p>
641
642 The compiler defines several macros at startup:
643
644 <descrip>
645
646   <tag><tt>__CC65__</tt></tag>
647
648   This macro is always defined. Its value is the version number of the
649   compiler in hex.  For example, version 2.10.1 of the compiler has this macro
650   defined as <tt/0x02A1/.
651
652   <tag><tt>__APPLE2__</tt></tag>
653
654   This macro is defined if the target is the Apple ][ (-t apple2).
655
656   <tag><tt>__APPLE2ENH__</tt></tag>
657
658   This macro is defined if the target is the enhanced Apple //e (-t apple2enh).
659
660   <tag><tt>__ATARI__</tt></tag>
661
662   This macro is defined if the target is one of the Atari computers
663   (400/800/130XL/800XL).
664
665   <tag><tt>__ATMOS__</tt></tag>
666
667   This macro is defined if the target is the Oric Atmos (-t atmos).
668
669   <tag><tt>__CBM__</tt></tag>
670
671   This macro is defined if the target system is one of the CBM targets.
672
673   <tag><tt>__C16__</tt></tag>
674
675   This macro is defined if the target is the c16 (-t c16).
676
677   <tag><tt>__C64__</tt></tag>
678
679   This macro is defined if the target is the c64 (-t c64).
680
681   <tag><tt>__C128__</tt></tag>
682
683   This macro is defined if the target is the c128 (-t c128).
684
685   <tag><tt>__CBM510__</tt></tag>
686
687   This macro is defined if the target is the CBM 500 series of computers.
688
689   <tag><tt>__CBM610__</tt></tag>
690
691   This macro is defined if the target is one of the CBM 600/700 family of
692   computers (called B series in the US).
693
694   <tag><tt>__GEOS__</tt></tag>
695
696   This macro is defined if you are compiling for the GEOS system (-t geos).
697
698   <tag><tt>__LUNIX__</tt></tag>
699
700   This macro is defined if you are compiling for the LUnix system (-t lunix).
701
702   <tag><tt>__LYNX__</tt></tag>
703
704   This macro is defined if the target is the Atari Lynx (-t lynx).
705
706   <tag><tt>__NES__</tt></tag>
707
708   This macro is defined if the target is the NES (-t nes).
709
710   <tag><tt>__PET__</tt></tag>
711
712   This macro is defined if the target is the PET family of computers (-t pet).
713
714   <tag><tt>__PLUS4__</tt></tag>
715
716   This macro is defined if the target is the plus/4 (-t plus4).
717
718   <tag><tt>__SUPERVISION__</tt></tag>
719
720   This macro is defined if the target is the supervision (-t supervision).
721
722   <tag><tt>__VIC20__</tt></tag>
723
724   This macro is defined if the target is the vic20 (-t vic20).
725
726   <tag><tt>__FILE__</tt></tag>
727
728   This macro expands to a string containing the name of the C source file.
729
730   <tag><tt>__LINE__</tt></tag>
731
732   This macro expands to the current line number.
733
734   <tag><tt>__CC65_STD__</tt></tag>
735
736   This macro is defined to one of the following depending on the <tt><ref
737   id="option--standard" name="--standard"></tt> command line option:
738   <itemize>
739   <item><tt/__CC65_STD_C89__/
740   <item><tt/__CC65_STD_C99__/
741   <item><tt/__CC65_STD_CC65__/
742   </itemize>
743
744   <tag><tt>__OPT__</tt></tag>
745
746   Is defined if the compiler was called with the <tt/-O/ command line option.
747
748   <tag><tt>__OPT_i__</tt></tag>
749
750   Is defined if the compiler was called with the <tt/-Oi/ command line option.
751
752   <tag><tt>__OPT_r__</tt></tag>
753
754   Is defined if the compiler was called with the <tt/-Or/ command line option.
755
756   <tag><tt>__OPT_s__</tt></tag>
757
758   Is defined if the compiler was called with the <tt/-Os/ command line option.
759
760 </descrip>
761
762
763 <sect>&num;pragmas<label id="pragmas"><p>
764
765 The compiler understands some pragmas that may be used to change code
766 generation and other stuff. Some of these pragmas understand a special form:
767 If the first parameter is <tt/push/, the old value is saved onto a stack
768 before changing it. The value may later be restored by using the <tt/pop/
769 parameter with the <tt/#pragma/.
770
771 <sect1><tt>#pragma bss-name (&lsqb;push,&rsqb; &lt;name&gt;)</tt><label id="pragma-bss-name"><p>
772
773   This pragma changes the name used for the BSS segment (the BSS segment
774   is used to store uninitialized data). The argument is a string enclosed
775   in double quotes.
776
777   Note: The default linker configuration file does only map the standard
778   segments. If you use other segments, you have to create a new linker
779   configuration file.
780
781   Beware: The startup code will zero only the default BSS segment. If you
782   use another BSS segment, you have to do that yourself, otherwise
783   uninitialized variables do not have the value zero.
784
785   The <tt/#pragma/ understands the push and pop parameters as explained above.
786
787   Example:
788   <tscreen><verb>
789         #pragma bss-name ("MyBSS")
790   </verb></tscreen>
791
792
793 <sect1><tt>#pragma charmap (&lt;index&gt;, &lt;code&gt;)</tt><label id="pragma-charmap"><p>
794
795   Each literal string and each literal character in the source is translated
796   by use of a translation table. This translation table is preset when the
797   compiler is started depending on the target system, for example to map
798   ISO-8859-1 characters into PETSCII if the target is a commodore machine.
799
800   This pragma allows to change entries in the translation table, so the
801   translation for individual characters, or even the complete table may be
802   adjusted.
803
804   Both arguments are assumed to be unsigned characters with a valid range of
805   1-255.
806
807   Beware of two pitfalls:
808
809     <itemize>
810     <item>The character index is actually the code of the character in the
811           C source, so character mappings do always depend on the source
812           character set. This means that <tt/#pragma&nbsp;charmap/ is not
813           portable -- it depends on the build environment.
814     <item>While it is possible to use character literals as indices, the
815           result may be somewhat unexpected, since character literals are
816           itself translated. For this reason I would suggest to avoid
817           character literals and use numeric character codes instead.
818     </itemize>
819
820   Example:
821   <tscreen><verb>
822         /* Use a space wherever an 'a' occurs in ISO-8859-1 source */
823         #pragma charmap (0x61, 0x20);
824   </verb></tscreen>
825
826
827 <sect1><tt>#pragma check-stack ([push,] on|off)</tt><label id="pragma-check-stack"><p>
828
829   Tells the compiler to insert calls to a stack checking subroutine to detect
830   stack overflows. The stack checking code will lead to somewhat larger and
831   slower programs, so you may want to use this pragma when debugging your
832   program and switch it off for the release version. If a stack overflow is
833   detected, the program is aborted.
834
835   If the argument is "off", stack checks are disabled (the default), otherwise
836   they're enabled.
837
838   The <tt/#pragma/ understands the push and pop parameters as explained above.
839
840 <sect1><tt>#pragma code-name ([push,] &lt;name&gt;)</tt><label id="pragma-code-name"><p>
841
842   This pragma changes the name used for the CODE segment (the CODE segment
843   is used to store executable code). The argument is a string enclosed in
844   double quotes.
845
846   Note: The default linker configuration file does only map the standard
847   segments. If you use other segments, you have to create a new linker
848   configuration file.
849
850   The <tt/#pragma/ understands the push and pop parameters as explained above.
851
852   Example:
853   <tscreen><verb>
854         #pragma code-name ("MyCODE")
855   </verb></tscreen>
856
857
858 <sect1><tt>#pragma codesize ([push,] &lt;int&gt;)</tt><label id="pragma-codesize"><p>
859
860   This pragma allows finer control about speed vs. size decisions in the code
861   generation and optimization phase. It gives the allowed size increase factor
862   (in percent). The default is can be changed by use of the <tt/<ref
863   id="option-codesize" name="--codesize">/ compiler option.
864
865   The <tt/#pragma/ understands the push and pop parameters as explained above.
866
867
868 <sect1><tt>#pragma data-name ([push,] &lt;name&gt;)</tt><label id="pragma-data-name"><p>
869
870   This pragma changes the name used for the DATA segment (the DATA segment
871   is used to store initialized data). The argument is a string enclosed in
872   double quotes.
873
874   Note: The default linker configuration file does only map the standard
875   segments. If you use other segments, you have to create a new linker
876   configuration file.
877
878   The <tt/#pragma/ understands the push and pop parameters as explained above.
879
880   Example:
881   <tscreen><verb>
882         #pragma data-name ("MyDATA")
883   </verb></tscreen>
884
885
886 <sect1><tt>#pragma local-strings ([push,] on|off)</tt><label id="pragma-local-strings"><p>
887
888   When "on", emit string literals to the data segment when they're encountered
889   in the source. The default ("off") is to keep string literals until end of
890   assembly, merge read only literals if possible, and then output the literals
891   into the data or rodata segment that is active at that point.
892
893   Using this <tt/#pragma/ it is possible to control the behaviour from within
894   the source. When <tt/#pragma local-strings/ is active, string literals are
895   output immediately, which means that they go into the currently active data
896   or rodata segment, but cannot be merged. When inactive, string literals are
897   remembered and output as a whole when translation is finished.
898
899
900 <sect1><tt>#pragma optimize ([push,] on|off)</tt><label id="pragma-optimize"><p>
901
902   Switch optimization on or off. If the argument is "off", optimization is
903   disabled, otherwise it is enabled. Please note that this pragma only effects
904   whole functions. The setting in effect when the function is encountered will
905   determine if the generated code is optimized or not.
906
907   Optimization and code generation is also controlled by the <ref
908   id="pragma-codesize" name="codesize pragma">.
909
910   The default is "off", but may be changed with the <tt/<ref name="-O"
911   id="option-O">/ compiler option.
912
913   The <tt/#pragma/ understands the push and pop parameters as explained above.
914
915
916 <sect1><tt>#pragma rodata-name ([push,] &lt;name&gt;)</tt><label id="pragma-rodata-name"><p>
917
918   This pragma changes the name used for the RODATA segment (the RODATA
919   segment is used to store readonly data). The argument is a string
920   enclosed in double quotes.
921
922   Note: The default linker configuration file does only map the standard
923   segments. If you use other segments, you have to create a new linker
924   configuration file.
925
926   The <tt/#pragma/ understands the push and pop parameters as explained above.
927
928   Example:
929   <tscreen><verb>
930         #pragma rodata-name ("MyRODATA")
931   </verb></tscreen>
932
933
934 <sect1><tt>#pragma regvaraddr ([push,] on|off)</tt><label id="pragma-regvaraddr"><p>
935
936   The compiler does not allow to take the address of register variables.
937   The regvaraddr pragma changes this. Taking the address of a register
938   variable is allowed after using this pragma with "on" as argument.
939   Using "off" as an argument switches back to the default behaviour.
940
941   Beware: The C standard does not allow taking the address of a variable
942   declared as register. So your programs become non-portable if you use
943   this pragma. In addition, your program may not work. This is usually the
944   case if a subroutine is called with the address of a register variable,
945   and this subroutine (or a subroutine called from there) uses
946   register variables. So be careful with this #pragma.
947
948   The <tt/#pragma/ understands the push and pop parameters as explained above.
949
950   Example:
951   <tscreen><verb>
952         #pragma regvaraddr(on)  /* Allow taking the address
953                                  * of register variables
954                                  */
955   </verb></tscreen>
956
957
958 <sect1><tt>#pragma register-vars ([push,] on|off)</tt><label id="pragma-register-vars"><p>
959
960   Enables or disables use of register variables. If register variables are
961   disabled (the default), the <tt/register/ keyword is ignored. Register
962   variables are explained in more detail in <ref id="register-vars" name="a separate
963   chapter">.
964
965   The <tt/#pragma/ understands the push and pop parameters as explained above.
966
967
968 <sect1><tt>#pragma signed-chars ([push,] on|off)</tt><label id="pragma-signed-chars"><p>
969
970   Changes the signedness of the default character type. If the argument is
971   "on", default characters are signed, otherwise characters are unsigned. The
972   compiler default is to make characters unsigned since this creates a lot
973   better code. This default may be overridden by the <tt/<ref
974   name="--signed-chars" id="option-signed-chars">/ command line option.
975
976   The <tt/#pragma/ understands the push and pop parameters as explained above.
977
978
979 <sect1><tt>#pragma static-locals ([push,] on|off)</tt><label id="pragma-static-locals"<p>
980
981   Use variables in the bss segment instead of variables on the stack. This
982   pragma changes the default set by the compiler option <tt/<ref
983   name="--static-locals" id="option-static-locals">/. If the argument is "on",
984   local variables are allocated in the BSS segment, leading to shorter and in
985   most cases faster, but non-reentrant code.
986
987   The <tt/#pragma/ understands the push and pop parameters as explained above.
988
989
990 <sect1><tt>#pragma warn (name, [push,] on|off)</tt><label id="pragma-warn"><p>
991
992   Switch compiler warnings on or off. "name" is the name of a warning (see the
993   <tt/<ref name="-W" id="option-W">/ compiler option for a list). The name is
994   either followed by "pop", which restores the last pushed state, or by "on" or
995   "off", optionally preceeded by "push" to push the current state before
996   changing it.
997
998   Example:
999   <tscreen><verb>
1000         /* Don't warn about the unused parameter in function func */
1001         #pragma warn (unused-param, push, off)
1002         static int func (int unused)
1003         {
1004             return 0;
1005         }
1006         #pragma warn (unused-param, pop)
1007   </verb></tscreen>
1008
1009 <sect1><tt>#pragma writable-strings ([push,] on|off)</tt><label id="pragma-writable-strings"><p>
1010
1011   Changes the storage location of string literals. For historical reasons,
1012   the C standard defines that string literals are of type "char[]", but
1013   writing to such a literal causes undefined behaviour. Most compilers
1014   (including cc65) place string literals in the read-only data segment, which
1015   may cause problems with old C code that writes to string literals.
1016
1017   Using this pragma (or the corresponding command line option <tt/<ref
1018   name="--writable-strings" id="option-writable-strings">/) causes the
1019   literals to be placed in the data segment so they can be written to without
1020   worry.
1021
1022   The <tt/#pragma/ understands the push and pop parameters as explained above.
1023
1024
1025 <sect1><tt>#pragma zpsym (&lt;name&gt;)</tt><p>
1026
1027   Tell the compiler that the -- previously as external declared -- symbol with
1028   the given name is a zero page symbol (usually from an assembler file).
1029   The compiler will create a matching import declaration for the assembler.
1030
1031   Example:
1032   <tscreen><verb>
1033         extern int foo;
1034         #pragma zpsym ("foo");  /* foo is in the zeropage */
1035   </verb></tscreen>
1036
1037
1038
1039
1040 <sect>Register variables<label id="register-vars"><p>
1041
1042 The runtime for all supported platforms has 6 bytes of zero page space
1043 available for register variables (this could be increased, but I think it's a
1044 good value). So you can declare register variables up to a total size of 6 per
1045 function. The compiler will allocate register space on a "first come, first
1046 served" base and convert any <tt/register/ declarations that exceed the
1047 available register space silently to <tt/auto/. Parameters can also be
1048 declared as <tt/register/, this will in fact give slightly shorter code than
1049 using a register variable.
1050
1051 Since a function must save the current values of the registers on entry and
1052 restore them on exit, there is an overhead associated with register variables,
1053 and this overhead is quite high (about 20 bytes per variable). This means that
1054 just declaring anything as <tt/register/ is not a good idea.
1055
1056 The best use for register variables are pointers, especially those that point
1057 to structures. The magic number here is about 3 uses of a struct field: If the
1058 function contains this number or even more, the generated code will be usually
1059 shorter and faster when using a register variable for the struct pointer. The
1060 reason for this is that the register variable can in many cases be used as a
1061 pointer directly. Having a pointer in an auto variable means that this pointer
1062 must first be copied into a zero page location, before it can be dereferenced.
1063
1064 Second best use for register variables are counters. However, there is not
1065 much difference in the code generated for counters, so you will need at least
1066 100 operations on this variable (for example in a loop) to make it worth the
1067 trouble. The only savings you get here are by the use of a zero page variable
1068 instead of one on the stack or in the data segment.
1069
1070 Register variables must be explicitly enabled, either by using <tt/<ref
1071 name="-Or" id="option-O">/ or <tt/<ref name="--register-vars"
1072 id="option-register-vars">/ on the command line or by use of <tt/<ref
1073 name="#pragma register-vars" id="pragma-register-vars">/. Register variables
1074 are only accepted on function top level, register variables declared in
1075 interior blocks are silently converted to <tt/auto/. With register variables
1076 disabled, all variables declared as <tt/register/ are actually auto variables.
1077
1078 Please take care when using register variables: While they are helpful and can
1079 lead to a tremendous speedup when used correctly, improper usage will cause
1080 bloated code and a slowdown.
1081
1082
1083
1084 <sect>Inline assembler<label id="inline-asm"><p>
1085
1086 The compiler allows to insert assembler statements into the output file. The
1087 syntax is
1088
1089 <tscreen><verb>
1090         asm (&lt;string literal&gt;[, optional parameters]) ;
1091 </verb></tscreen>
1092 or
1093 <tscreen><verb>
1094         __asm__ (&lt;string literal&gt;[, optional parameters]) ;
1095 </verb></tscreen>
1096 <p>
1097
1098 The first form is in the user namespace and is disabled by <tt><ref
1099 id="option--standard" name="--standard"></tt> if the argument is not <tt/cc65/.
1100
1101 The asm statement may be used inside a function and on global file level. An
1102 inline assembler statement is a primary expression, so it may also be used as
1103 part of an expression. Please note however that the result of an expression
1104 containing just an inline assembler statement is always of type <tt/void/.
1105
1106 The contents of the string literal are preparsed by the compiler and inserted
1107 into the generated assembly output, so that the can be further processed by
1108 the backend and especially the optimizer. For this reason, the compiler does
1109 only allow regular 6502 opcodes to be used with the inline assembler. Pseudo
1110 instructions (like <tt/.import/, <tt/.byte/ and so on) are <em/not/ allowed,
1111 even if the ca65 assembler (which is used to translate the generated assembler
1112 code) would accept them. The builtin inline assembler is not a replacement for
1113 the full blown macro assembler which comes with the compiler.
1114
1115 Note: Inline assembler statements are subject to all optimizations done by the
1116 compiler. There is currently no way to protect an inline assembler statement
1117 from being moved or removed completely by the optimizer. If in doubt, check
1118 the generated assembler output, or disable optimizations.
1119
1120 The string literal may contain format specifiers from the following list. For
1121 each format specifier, an argument is expected which is inserted instead of
1122 the format specifier before passing the assembly code line to the backend.
1123
1124 <itemize>
1125   <item><tt/%b/ - Numerical 8-bit value
1126   <item><tt/%w/ - Numerical 16-bit value
1127   <item><tt/%l/ - Numerical 32-bit value
1128   <item><tt/%v/ - Assembler name of a (global) variable or function
1129   <item><tt/%o/ - Stack offset of a (local) variable
1130   <item><tt/%g/ - Assembler name of a C label
1131   <item><tt/%s/ - The argument is converted to a string
1132   <item><tt/%%/ - The % sign itself
1133 </itemize><p>
1134
1135 Using these format specifiers, you can access C <tt/#defines/, variables or
1136 similar stuff from the inline assembler. For example, to load the value of
1137 a C <tt/#define/ into the Y register, one would use
1138
1139 <tscreen><verb>
1140         #define OFFS  23
1141         __asm__ ("ldy #%b", OFFS);
1142 </verb></tscreen>
1143
1144 Or, to access a struct member of a static variable:
1145
1146 <tscreen><verb>
1147         typedef struct {
1148             unsigned char x;
1149             unsigned char y;
1150             unsigned char color;
1151         } pixel_t;
1152         static pixel_t pixel;
1153         __asm__ ("ldy #%b", offsetof(pixel_t, color));
1154         __asm__ ("lda %v,y", pixel);
1155 </verb></tscreen>
1156 <p>
1157
1158 Note: Do not embed the assembler labels that are used as names of global
1159 variables or functions into your asm statements. Code like this
1160
1161 <tscreen><verb>
1162         int foo;
1163         int bar () { return 1; }
1164         __asm__ ("lda _foo");           /* DON'T DO THAT! */
1165         ...
1166         __asm__ ("jsr _bar");           /* DON'T DO THAT EITHER! */
1167 </verb></tscreen>
1168 <p>
1169
1170 may stop working if the way, the compiler generates these names is changed in
1171 a future version. Instead use the format specifiers from the table above:
1172
1173 <tscreen><verb>
1174         __asm__ ("lda %v", foo);        /* OK */
1175         ...
1176         __asm__ ("jsr %v", bar);        /* OK */
1177 </verb></tscreen>
1178 <p>
1179
1180
1181 <sect>Implementation-defined behavior<p>
1182
1183 This section describes the behavior of cc65 when the standard describes the
1184 behavior as implementation-defined.
1185
1186 (to be done)
1187
1188 <sect>Bugs/Feedback<p>
1189
1190 If you have problems using the compiler, if you find any bugs, or if you're
1191 doing something interesting with it, I would be glad to hear from you. Feel
1192 free to contact me by email (<htmlurl url="mailto:uz@cc65.org"
1193 name="uz@cc65.org">).
1194
1195
1196
1197 <sect>Copyright<p>
1198
1199 This is the original compiler copyright:
1200
1201 <tscreen><verb>
1202 --------------------------------------------------------------------------
1203   -*- Mode: Text -*-
1204
1205      This is the copyright notice for RA65, LINK65, LIBR65, and other
1206   Atari 8-bit programs.  Said programs are Copyright 1989, by John R.
1207   Dunning.  All rights reserved, with the following exceptions:
1208
1209       Anyone may copy or redistribute these programs, provided that:
1210
1211   1:  You don't charge anything for the copy.  It is permissable to
1212       charge a nominal fee for media, etc.
1213
1214   2:  All source code and documentation for the programs is made
1215       available as part of the distribution.
1216
1217   3:  This copyright notice is preserved verbatim, and included in
1218       the distribution.
1219
1220       You are allowed to modify these programs, and redistribute the
1221   modified versions, provided that the modifications are clearly noted.
1222
1223       There is NO WARRANTY with this software, it comes as is, and is
1224   distributed in the hope that it may be useful.
1225
1226       This copyright notice applies to any program which contains
1227   this text, or the refers to this file.
1228
1229       This copyright notice is based on the one published by the Free
1230   Software Foundation, sometimes known as the GNU project.  The idea
1231   is the same as theirs, ie the software is free, and is intended to
1232   stay that way.  Everybody has the right to copy, modify, and re-
1233   distribute this software.  Nobody has the right to prevent anyone
1234   else from copying, modifying or redistributing it.
1235
1236 --------------------------------------------------------------------------
1237 </verb></tscreen>
1238
1239 Small parts of the compiler (parts of the preprocessor and main parser) are
1240 still covered by this copyright. The main portion is covered by the usual
1241 cc65 license, which reads:
1242
1243 This software is provided 'as-is', without any expressed or implied
1244 warranty.  In no event will the authors be held liable for any damages
1245 arising from the use of this software.
1246
1247 Permission is granted to anyone to use this software for any purpose,
1248 including commercial applications, and to alter it and redistribute it
1249 freely, subject to the following restrictions:
1250
1251 <enum>
1252 <item>  The origin of this software must not be misrepresented; you must not
1253         claim that you wrote the original software. If you use this software
1254         in a product, an acknowledgment in the product documentation would be
1255         appreciated but is not required.
1256 <item>  Altered source versions must be plainly marked as such, and must not
1257         be misrepresented as being the original software.
1258 <item>  This notice may not be removed or altered from any source
1259         distribution.
1260 </enum>
1261
1262 </article>
1263