1 <!doctype linuxdoc system>
4 <title>cc65 Users Guide
5 <author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
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.
13 <!-- Table of contents -->
16 <!-- Begin the document -->
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. In fact, I'm
27 planning a complete rewrite (that is, a complete new compiler) for the
28 next release, since there are too many limitations in the current code,
29 and removing these limitations would mean a rewrite of many more parts of
32 There is a separate document named "library.txt" that covers the library
33 available for the compiler. If you know C and are interested in doing
34 actual programming, the library documentation is probably of much more use
37 If you need some hints for getting the best code out of the compiler, you
38 may have a look at "coding.txt" which covers some code generation issues.
44 The compiler translates C files into files containing assembler code that
45 may be translated by the ca65 macroassembler (for more information about
46 the assembler, have a look at ca65.txt).
49 <sect1>Command line option overview<p>
51 The compiler may be called as follows:
54 ---------------------------------------------------------------------------
55 Usage: cc65 [options] file
58 -g Add debug info to object file
60 -j Default characters are signed
61 -o name Name the output file
62 -t sys Set the target system
65 -Cl Make local variables static
66 -Dsym[=defn] Define a symbol
67 -I dir Set an include directory search path
69 -Oi Optimize code, inline more code
70 -Or Enable register variables
71 -Os Inline some known functions
72 -T Include source as comment
73 -V Print the compiler version number
77 --ansi Strict ANSI mode
78 --bss-name seg Set the name of the BSS segment
79 --check-stack Generate stack overflow checks
80 --code-name seg Set the name of the CODE segment
81 --cpu type Set cpu type
82 --data-name seg Set the name of the DATA segment
84 --debug-info Add debug info to object file
85 --help Help (this text)
86 --include-dir dir Set an include directory search path
87 --rodata-name seg Set the name of the RODATA segment
88 --signed-chars Default characters are signed
89 --static-locals Make local variables static
90 --target sys Set the target system
91 --verbose Increase verbosity
92 --version Print the compiler version number
93 ---------------------------------------------------------------------------
97 <sect1>Command line options in detail<p>
99 Here is a description of all the command line options:
103 <label id="option-A">
104 <tag><tt>-A, --ansi</tt></tag>
106 This option disables any compiler exensions. Have a look at section 5
107 for a discussion of compiler extensions. In addition, the macro
108 <tt/__STRICT_ANSI__/ is defined, when using one of these options.
111 <tag><tt>--bss-name seg</tt></tag>
113 Set the name of the bss segment.
116 <tag><tt>--check-stack</tt></tag>
118 Tells the compiler to generate code that checks for stack overflows. See
119 <tt><ref id="pragma-checkstack" name="#pragma checkstack"></tt> for an
120 explanation of this feature.
123 <tag><tt>--code-name seg</tt></tag>
125 Set the name of the code segment.
128 <tag><tt>--cpu CPU</tt></tag>
130 A new, still experimental option. You may specify "6502" or "65C02" as
131 the CPU. 6502 is the default, so this will not change anything.
132 Specifying 65C02 will use a few 65C02 instructions when generating code.
133 Don't expect too much from this option: It is still new (and may have
134 bugs), and the additional instructions for the 65C02 are not that
138 <tag><tt>-d, --debug</tt></tag>
140 Enables debug mode, something that should not be needed for mere
144 <tag><tt>-D sym[=definition]</tt></tag>
146 Define a macro on the command line. If no definition is given, the macro
147 is defined to the value "1".
150 <tag><tt>-g, --debug-info</tt></tag>
152 This will cause the compiler to insert a <tt/.DEBUGINFO/ command into the
153 generated assembler code. This will cause the assembler to include all
154 symbols in a special section in the object file.
157 <tag><tt>-h, --help</tt></tag>
159 Print the short option summary shown above.
162 <tag><tt>--rodata-name seg</tt></tag>
164 Set the name of the rodata segment (the segment used for readonly data).
167 <tag><tt>-j, --signed-chars</tt></tag>
169 Using this option, you can make the default characters signed. Since the
170 6502 has no provisions for sign extending characters (which is needed on
171 almost any load operation), this will make the code larger and slower. A
172 better way is to declare characters explicitly as "signed" if needed. You
173 can also use <tt><ref id="pragma-signedchars" name="#pragma
174 signedchars"></tt> for better control of this option.
177 <tag><tt>-t target, --target target</tt></tag>
179 This option is used to set the target system. The target system
180 determines things like the character set that is used for strings and
181 character constants. The following target systems are supported:
189 <item>cbm610 (all CBM series-II computers with 80 column video)
190 <item>pet (all CBM PET systems except the 2001)
195 <tag><tt>-v, --verbose</tt></tag>
197 Using this option, the compiler will be somewhat more verbose if errors
198 or warnings are encountered.
201 <tag><tt>-Cl, --static-locals</tt></tag>
203 Use static storage for local variables instead of storage on the stack.
204 Since the stack is emulated in software, this gives shorter and usually
205 faster code, but the code is no longer reentrant. The difference between
206 <tt/-Cl/ and declaring local variables as static yourself is, that
207 initializer code is executed each time, the function is entered. So when
218 the variable a will always have the value 1 when entering the function
219 and using <tt/-Cl/, while in
224 static unsigned a = 1;
229 the variable a will have the value 1 only the first time, the function
230 is entered, and will keep the old value from one call of the function to
233 You may also use <tt><ref id="pragma-staticlocals" name="#pragma
234 staticlocals"></tt> to change this setting in your sources.
237 <tag><tt>-I dir, --include-dir dir</tt></tag>
239 Set a directory where the compiler searches for include files. You may
240 use this option multiple times to add more than one directory to the
244 <tag><tt>-o name</tt></tag>
246 Specify the name of the output file. If you don't specify a name, the
247 name of the C input file is used, with the extension replaced by ".s".
250 <tag><tt>-O, -Oi, -Or, -Os</tt></tag>
252 Enable an optimizer run over the produced code.
254 Using <tt/-Oi/, the code generator will inline some code where otherwise a
255 runtime functions would have been called, even if the generated code is
256 larger. This will not only remove the overhead for a function call, but will
257 make the code visible for the optimizer.
259 <tt/-Or/ will make the compiler honor the <tt/register/ keyword. Local
260 variables may be placed in registers (which are actually zero page
261 locations). There is some overhead involved with register variables, since
262 the old contents of the registers must be saved and restored. In addition,
263 the current implementation does not make good use of register variables, so
264 using <tt/-Or/ may make your program even slower and larger. Use with care!
266 Using <tt/-Os/ will force the compiler to inline some known functions from
267 the C library like strlen. Note: This has two consequences:
270 <item>You may not use names of standard C functions in your own code. If you
271 do that, your program is not standard compliant anyway, but using
272 <tt/-Os/ will actually break things.
274 <item>The inlined string and memory functions will not handle strings or
275 memory areas larger than 255 bytes. Similar, the inlined <tt/is..()/
276 functions will not work with values outside char range.
280 It is possible to concatenate the modifiers for <tt/-O/. For example, to
281 enable register variables and inlining of known functions, you may use
285 <tag><tt>-T</tt></tag>
287 This include the source code as comments in the generated code. This is
291 <tag><tt>-V, --version</tt></tag>
293 Print the version number of the compiler. When submitting a bug report,
294 please include the operating system you're using, and the compiler
298 <tag><tt>-W</tt></tag>
300 This option will suppress any warnings generated by the compiler. Since
301 any source file may be written in a manner that it will not produce
302 compiler warnings, using this option is usually not a good idea.
307 <sect>Input and output<p>
309 The compiler will accept one C file per invocation and create a file with
310 the same base name, but with the extension replaced by ".s". The output
311 file contains assembler code suitable for the use with the ca65 macro
314 In addition to the paths named in the <tt/-I/ option on the command line, the
315 directory named in the environment variable <tt/CC65_INC/ is added to the
316 search path for include files on startup.
320 <sect>Differences to the ISO standard<p>
322 Here is a list of differences between the language, the compiler accepts,
323 and the one defined by the ISO standard:
327 <item> The compiler allows single line comments that start with //. This
328 feature is disabled in strict ANSI mode.
330 <item> The compiler allows unnamed parameters in parameter lists. The
331 compiler will not issue warnings about unused parameters that don't
332 have a name. This feature is disabled in strict ANSI mode.
334 <item> The compiler has some additional keywords:
340 <item><tt/__fastcall__/
344 <item><tt/__attribute__/
347 The keywords without the underlines are disabled in strict ANSI mode.
349 <item> The datatypes "float" and "double" are not available.
351 <item> The compiler does not support bit fields.
353 <item> Initialization of local variables is only possible for scalar data
354 types (that is, not for arrays and structs).
356 <item> Because of the "wrong" order of the parameters on the stack, there is
357 an additional macro needed to access parameters in a variable
358 parameter list in a C function.
360 <item> Functions may not return structs. However, struct assignment *is*
363 <item> Part of the C library is available only with fastcall calling
364 conventions (see below). This means, that you may not mix pointers to
365 those functions with pointers to user written functions.
369 There may be some more minor differences, I'm currently not aware off. The
370 biggest problem is the missing float data type. With this limitation in
371 mind, you should be able to write fairly portable code.
377 This cc65 version has some extensions to the ISO C standard.
381 <item> The compiler allows // comments (like in C++ and in the proposed C9x
382 standard). This feature is disabled by <tt><ref id="option-A"
386 <item> The compiler allows to insert assembler statements into the output
390 asm (<string literal>) ;
394 __asm__ (<string literal>) ;
397 The first form is in the user namespace and is disabled if the <tt/-A/
400 The given string is inserted literally into the output file, and a
401 newline is appended. The statements in this string are not checked by
402 the compiler, so be careful!
404 The asm statement may be used inside a function and on global file
408 <item> There is a special calling convention named "fastcall". This calling
409 convention is currently only usable for functions written in
410 assembler. The syntax for a function declaration using fastcall is
413 <tt/<return type> fastcall <function name> (<parameter list>)/
417 <tt/<return type> __fastcall__ <function name> (<parameter list>)/
421 <tt/void __fastcall__ f (unsigned char c)/
423 The first form of the fastcall keyword is in the user namespace and is
424 therefore disabled in strict ANSI mode.
426 For functions declared as <tt/fastcall/, the rightmost parameter is not
427 pushed on the stack but left in the primary register when the function
428 is called. This will reduce the cost when calling assembler functions
429 significantly, especially when the function itself is rather small.
432 <item> There are two pseudo variables named <tt/__AX__/ and <tt/__EAX__/.
433 Both refer to the primary register that is used by the compiler to
434 evaluate expressions or return function results. <tt/__AX__/ is of
435 type <tt/unsigned int/ and <tt/__EAX__/ of type <tt/long unsigned int/
436 respectively. The pseudo variables may be used as lvalue and rvalue as
437 every other variable. They are most useful together with short
438 sequences of assembler code. For example, the macro
441 #define hi(x) (__AX__=(x),asm("\ttxa\n\tldx\t#$00",__AX__)
444 will give the high byte of any unsigned value.
447 <item> Inside a function, the identifier <tt/__func__/ gives the name of the
448 current function as a string. Outside of functions, <tt/__func__/ is
453 #define PRINT_DEBUG(s) printf ("%s: %s\n", __func__, s);
456 The macro will print the name of the current function plus a given
460 <item> cc65 allows the initialization of <tt/void/ variables. This may be
461 used to create variable structures that are more compatible with
462 interfaces written for assembler languages. Here is an example:
465 void GCmd = { (char)3, (unsigned)0x2000, (unsigned)0x3000 };
468 This will be translated as follows:
477 Since the variable is of type <tt/void/ you may not use it as is.
478 However, taking the address of the variable results in a <tt/void*/
479 which may be passed to any function expecting a pointer.
481 See the <htmlurl url="geos.html" name="GEOS library"> for examples on
482 how to use this feature.
489 <sect>Predefined macros<p>
491 The compiler defines several macros at startup:
495 <tag><tt>__CC65__</tt></tag>
497 This macro is always defined. Its value is the version number of the
498 compiler in hex. Version 2.0.1 of the compiler will have this macro defined
501 <tag><tt>__CBM__</tt></tag>
503 This macro is defined if the target system is one of the CBM targets.
505 <tag><tt>__C64__</tt></tag>
507 This macro is defined if the target is the c64 (-t c64).
509 <tag><tt>__C128__</tt></tag>
511 This macro is defined if the target is the c128 (-t c128).
513 <tag><tt>__PLUS4__</tt></tag>
515 This macro is defined if the target is the plus/4 (-t plus4).
517 <tag><tt>__CBM610__</tt></tag>
519 This macro is defined if the target is one of the CBM 600/700 family of
520 computers (called B series in the US).
522 <tag><tt>__PET__</tt></tag>
524 This macro is defined if the target is the PET family of computers (-t pet).
526 <tag><tt>__ATARI__</tt></tag>
528 This macro is defined if the target is one of the Atari computers
529 (400/800/130XL/800XL).
531 <tag><tt>__APPLE2__</tt></tag>
533 This macro is defined if the target is the Apple ][ (-t apple2).
535 <tag><tt>__GEOS__</tt></tag>
537 This macro is defined if you are compiling for the GEOS system (-t geos).
539 <tag><tt>__FILE__</tt></tag>
541 This macro expands to a string containing the name of the C source file.
543 <tag><tt>__LINE__</tt></tag>
545 This macro expands to the current line number.
547 <tag><tt>__STRICT_ANSI__</tt></tag>
549 This macro is defined to 1 if the <tt/-A/ compiler option was given, and
552 <tag><tt>__OPT__</tt></tag>
554 Is defined if the compiler was called with the <tt/-O/ command line option.
556 <tag><tt>__OPT_i__</tt></tag>
558 Is defined if the compiler was called with the <tt/-Oi/ command line option.
560 <tag><tt>__OPT_r__</tt></tag>
562 Is defined if the compiler was called with the <tt/-Or/ command line option.
564 <tag><tt>__OPT_s__</tt></tag>
566 Is defined if the compiler was called with the <tt/-Os/ command line option.
571 <sect>#pragmas<label id="pragmas"><p>
573 The compiler understands some pragmas that may be used to change code
574 generation and other stuff.
577 <sect1><tt>#pragma bssseg (<name>)</tt><p>
579 This pragma changes the name used for the BSS segment (the BSS segment
580 is used to store uninitialized data). The argument is a string enclosed
583 Note: The default linker configuration file does only map the standard
584 segments. If you use other segments, you have to create a new linker
587 Beware: The startup code will zero only the default BSS segment. If you
588 use another BSS segment, you have to do that yourself, otherwise
589 uninitialized variables do not have the value zero.
593 #pragma bssseg ("MyBSS")
597 <sect1><tt>#pragma checkstack (<const int>)</tt><label
598 id="pragma-checkstack"><p>
600 Tells the compiler to insert calls to a stack checking subroutine to detect
601 stack overflows. The stack checking code will lead to somewhat larger and
602 slower programs, so you may want to use this pragma when debugging your
603 program and switch it off for the release version. If a stack overflow is
604 detected, the program is aborted.
606 If the argument is zero, stack checks are disabled (the default), otherwise
610 <sect1><tt>#pragma codeseg (<name>)</tt><p>
612 This pragma changes the name used for the CODE segment (the CODE segment
613 is used to store executable code). The argument is a string enclosed in
616 Note: The default linker configuration file does only map the standard
617 segments. If you use other segments, you have to create a new linker
622 #pragma bssseg ("MyCODE")
626 <sect1><tt>#pragma dataseg (<name>)</tt><p>
628 This pragma changes the name used for the DATA segment (the DATA segment
629 is used to store initialized data). The argument is a string enclosed in
632 Note: The default linker configuration file does only map the standard
633 segments. If you use other segments, you have to create a new linker
638 #pragma bssseg ("MyDATA")
642 <sect1><tt>#pragma rodataseg (<name>)</tt><p>
644 This pragma changes the name used for the RODATA segment (the RODATA
645 segment is used to store readonly data). The argument is a string
646 enclosed in double quotes.
648 Note: The default linker configuration file does only map the standard
649 segments. If you use other segments, you have to create a new linker
654 #pragma bssseg ("MyRODATA")
658 <sect1><tt>#pragma regvaraddr (<const int>)</tt><p>
660 The compiler does not allow to take the address of register variables.
661 The regvaraddr pragma changes this. Taking the address of a register
662 variable is allowed after using this pragma, if the argument is not
663 zero. Using an argument of zero changes back to the default behaviour.
665 Beware: The C standard does not allow taking the address of a variable
666 declared as register. So your programs become non-portable if you use
667 this pragma. In addition, your program may not work. This is usually the
668 case if a subroutine is called with the address of a register variable,
669 and this subroutine (or a subroutine called from there) uses itself
670 register variables. So be careful with this #pragma.
674 #pragma regvaraddr(1) /* Allow taking the address
675 * of register variables
680 <sect1><tt>#pragma signedchars (<const int>)</tt><label
681 id="pragma-signedchars"><p>
683 Changes the signedness of the default character type. If the argument
684 is not zero, default characters are signed, otherwise characters are
685 unsigned. The compiler default is to make characters unsigned since this
686 creates a lot better code. This default may be overridden by the
687 <tt/--signed-chars/ command line option.
690 <sect1><tt>#pragma staticlocals (<const int>)</tt><label
691 id="pragma-staticlocals"<p>
693 Use variables in the bss segment instead of variables on the stack. This
694 pragma changes the default set by the compiler option <tt/-Cl/. If the
695 argument is not zero, local variables are allocated in the BSS segment,
696 leading to shorter and in most cases faster, but non-reentrant code.
699 <sect1><tt>#pragma zpsym (<name>)</tt><p>
701 Tell the compiler that the - previously as external declared - symbol with
702 the given name is a zero page symbol (usually from an assembler file).
703 The compiler will create a matching import declaration for the assembler.
708 #pragma zpsym ("foo"); /* foo is in the zeropage */
714 <sect>Bugs/Feedback<p>
716 If you have problems using the compiler, if you find any bugs, or if you're
717 doing something interesting with it, I would be glad to hear from you. Feel
718 free to contact me by email (<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">).
724 This is the original compiler copyright:
727 --------------------------------------------------------------------------
730 This is the copyright notice for RA65, LINK65, LIBR65, and other
731 Atari 8-bit programs. Said programs are Copyright 1989, by John R.
732 Dunning. All rights reserved, with the following exceptions:
734 Anyone may copy or redistribute these programs, provided that:
736 1: You don't charge anything for the copy. It is permissable to
737 charge a nominal fee for media, etc.
739 2: All source code and documentation for the programs is made
740 available as part of the distribution.
742 3: This copyright notice is preserved verbatim, and included in
745 You are allowed to modify these programs, and redistribute the
746 modified versions, provided that the modifications are clearly noted.
748 There is NO WARRANTY with this software, it comes as is, and is
749 distributed in the hope that it may be useful.
751 This copyright notice applies to any program which contains
752 this text, or the refers to this file.
754 This copyright notice is based on the one published by the Free
755 Software Foundation, sometimes known as the GNU project. The idea
756 is the same as theirs, ie the software is free, and is intended to
757 stay that way. Everybody has the right to copy, modify, and re-
758 distribute this software. Nobody has the right to prevent anyone
759 else from copying, modifying or redistributing it.
761 --------------------------------------------------------------------------
764 In acknowledgment of this copyright, I will place my own changes to the
765 compiler under the same copyright. Please note however, that the library
766 and all binutils are covered by another copyright, and that I'm planning
767 to do a complete rewrite of the compiler, after which the compiler
768 copyright will also change.
770 For the list of changes requested by this copyright see newvers.txt.