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 old 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).
48 The compiler may be called as follows:
51 ---------------------------------------------------------------------------
52 Usage: cc65 [options] file
55 -g Add debug info to object file
57 -j Default characters are signed
58 -o name Name the output file
59 -t sys Set the target system
62 -Cl Make local variables static
63 -Dsym[=defn] Define a symbol
64 -I dir Set an include directory search path
66 -Oi Optimize code, inline more code
67 -Or Enable register variables
68 -Os Inline some known functions
69 -T Include source as comment
70 -V Print the compiler version number
74 --ansi Strict ANSI mode
75 --cpu type Set cpu type
77 --debug-info Add debug info to object file
78 --help Help (this text)
79 --include-dir dir Set an include directory search path
80 --signed-chars Default characters are signed
81 --static-locals Make local variables static
82 --target sys Set the target system
83 --verbose Increase verbosity
84 --version Print the compiler version number
85 ---------------------------------------------------------------------------
88 Here is a description of all the command line options:
92 <tag><tt>-A, --ansi</tt></tag>
94 This option disables any compiler exensions. Have a look at section 5
95 for a discussion of compiler extensions. In addition, the macro
96 <tt/__STRICT_ANSI__/ is defined, when using one of these options.
99 <tag><tt>--cpu CPU</tt></tag>
101 A new, still experimental option. You may specify "6502" or "65C02" as
102 the CPU. 6502 is the default, so this will not change anything.
103 Specifying 65C02 will use a few 65C02 instructions when generating code.
104 Don't expect too much from this option: It is still new (and may have
105 bugs), and the additional instructions for the 65C02 are not that
109 <tag><tt>-d, --debug</tt></tag>
111 Enables debug mode, something that should not be needed for mere
115 <tag><tt>-D sym[=definition]</tt></tag>
117 Define a macro on the command line. If no definition is given, the macro
118 is defined to the value "1".
121 <tag><tt>-g, --debug-info</tt></tag>
123 This will cause the compiler to insert a <tt/.DEBUGINFO/ command into the
124 generated assembler code. This will cause the assembler to include all
125 symbols in a special section in the object file.
128 <tag><tt>-h, --help</tt></tag>
130 Print the short option summary shown above.
133 <tag><tt>-j, --signed-chars</tt></tag>
135 Using this option, you can make the default characters signed. Since the
136 6502 has no provisions for sign extending characters (which is needed on
137 almost any load operation), this will make the code larger and slower. A
138 better way is to declare characters explicitly as "signed" if needed.
139 You can also use <tt/#pragma signedchars/ for better control of this option
140 (see section <ref id="pragmas" name="#pragmas">).
143 <tag><tt>-t target, --target target</tt></tag>
145 This option is used to set the target system. The target system
146 determines things like the character set that is used for strings and
147 character constants. The following target systems are supported:
154 <item>cbm610 (all CBM series-II computers with 80 column video)
155 <item>pet (all CBM PET systems except the 2001)
160 <tag><tt>-v, --verbose</tt></tag>
162 Using this option, the compiler will be somewhat more verbose if errors
163 or warnings are encountered.
166 <tag><tt>-Cl, --static-locals</tt></tag>
168 Use static storage for local variables instead of storage on the stack.
169 Since the stack is emulated in software, this gives shorter and usually
170 faster code, but the code is no longer reentrant. The difference between
171 <tt/-Cl/ and declaring local variables as static yourself is, that
172 initializer code is executed each time, the function is entered. So when
183 the variable a will always have the value 1 when entering the function
184 and using <tt/-Cl/, while in
189 static unsigned a = 1;
194 the variable a will have the value 1 only the first time, the function
195 is entered, and will keep the old value from one call of the function to
198 You may also use <tt/#pragma staticlocals/ to change this setting in your
199 sources (see section <ref id="pragmas" name="#pragmas">).
202 <tag><tt>-I dir, --include-dir dir</tt></tag>
204 Set a directory where the compiler searches for include files. You may
205 use this option multiple times to add more than one directory to the
209 <tag><tt>-o name</tt></tag>
211 Specify the name of the output file. If you don't specify a name, the
212 name of the C input file is used, with the extension replaced by ".s".
215 <tag><tt>-O, -Oi, -Or, -Os</tt></tag>
217 Enable an optimizer run over the produced code.
219 Using <tt/-Oi/, the code generator will inline some code where otherwise a
220 runtime functions would have been called, even if the generated code is
221 larger. This will not only remove the overhead for a function call, but will
222 make the code visible for the optimizer.
224 <tt/-Or/ will make the compiler honor the <tt/register/ keyword. Local
225 variables may be placed in registers (which are actually zero page
226 locations). There is some overhead involved with register variables, since
227 the old contents of the registers must be saved and restored. In addition,
228 the current implementation does not make good use of register variables, so
229 using <tt/-Or/ may make your program even slower and larger. Use with care!
231 Using <tt/-Os/ will force the compiler to inline some known functions from
232 the C library like strlen. Note: This has two consequences:
235 <item>You may not use names of standard C functions in your own code. If you
236 do that, your program is not standard compliant anyway, but using
237 <tt/-Os/ will actually break things.
239 <item>The inlined string and memory functions will not handle strings or
240 memory areas larger than 255 bytes. Similar, the inlined <tt/is..()/
241 functions will not work with values outside char range.
245 It is possible to concatenate the modifiers for <tt/-O/. For example, to
246 enable register variables and inlining of known functions, you may use
250 <tag><tt>-T</tt></tag>
252 This include the source code as comments in the generated code. This is
256 <tag><tt>-V, --version</tt></tag>
258 Print the version number of the compiler. When submitting a bug report,
259 please include the operating system you're using, and the compiler
263 <tag><tt>-W</tt></tag>
265 This option will suppress any warnings generated by the compiler. Since
266 any source file may be written in a manner that it will not produce
267 compiler warnings, using this option is usually not a good idea.
272 <sect>Input and output<p>
274 The compiler will accept one C file per invocation and create a file with
275 the same base name, but with the extension replaced by ".s". The output
276 file contains assembler code suitable for the use with the ca65 macro
279 In addition to the paths named in the <tt/-I/ option on the command line, the
280 directory named in the environment variable <tt/CC65_INC/ is added to the
281 search path for include files on startup.
285 <sect>Differences to the ISO standard<p>
287 Here is a list of differences between the language, the compiler accepts,
288 and the one defined by the ISO standard:
292 <item> The compiler allows single line comments that start with //. This
293 feature is disabled in strict ANSI mode.
295 <item> The compiler allows unnamed parameters in parameter lists. The
296 compiler will not issue warnings about unused parameters that don't
297 have a name. This feature is disabled in strict ANSI mode.
299 <item> The compiler has some additional keywords:
305 <item><tt/__fastcall__/
309 <item><tt/__attribute__/
312 The keywords without the underlines are disabled in strict ANSI mode.
314 <item> The datatypes "float" and "double" are not available.
316 <item> The compiler does not support bit fields.
318 <item> Initialization of local variables is only possible for scalar data
319 types (that is, not for arrays and structs).
321 <item> Because of the "wrong" order of the parameters on the stack, there is
322 an additional macro needed to access parameters in a variable
323 parameter list in a C function.
325 <item> Functions may not return structs. However, struct assignment *is*
328 <item> Part of the C library is available only with fastcall calling
329 conventions (see below). This means, that you may not mix pointers to
330 those functions with pointers to user written functions.
334 There may be some more minor differences, I'm currently not aware off. The
335 biggest problem is the missing float data type. With this limitation in
336 mind, you should be able to write fairly portable code.
342 This cc65 version has some extensions to the ISO C standard.
346 <item> The compiler allows // comments (like in C++ and in the proposed C9x
347 standard). This feature is disabled by <tt/-A/.
349 <item> The compiler allows to insert assembler statements into the output
352 <tt/asm (<string literal>) ;/
356 <tt/__asm__ (<string literal>) ;/
359 The first form is in the user namespace and is disabled if the <tt/-A/
362 The given string is inserted literally into the output file, and a
363 newline is appended. The statements in this string are not checked by
364 the compiler, so be careful!
366 The asm statement may be used inside a function and on global file
369 <item> There is a special calling convention named "fastcall". This calling
370 convention is currently only usable for functions written in
371 assembler. The syntax for a function declaration using fastcall is
373 <tt/<return type> fastcall <function name> (<parameter list>)/
377 <tt/<return type> __fastcall__ <function name> (<parameter list>)/
381 <tt/void __fastcall__ f (unsigned char c)/
383 The first form of the fastcall keyword is in the user namespace and is
384 therefore disabled in strict ANSI mode.
386 For functions declared as <tt/fastcall/, the rightmost parameter is not
387 pushed on the stack but left in the primary register when the function
388 is called. This will reduce the cost when calling assembler functions
389 significantly, especially when the function itself is rather small.
391 <item> There are two pseudo variables named <tt/__AX__/ and <tt/__EAX__/.
392 Both refer to the primary register that is used by the compiler to
393 evaluate expressions or return function results. <tt/__AX__/ is of
394 type <tt/unsigned int/ and <tt/__EAX__/ of type <tt/long unsigned int/
395 respectively. The pseudo variables may be used as lvalue and rvalue as
396 every other variable. They are most useful together with short
397 sequences of assembler code. For example, the macro
400 #define hi(x) (__AX__=(x),asm("\ttxa\n\tldx\t#$00",__AX__)
403 will give the high byte of any unsigned value.
405 <item> Inside a function, the identifier <tt/__func__/ gives the name of the
406 current function as a string. Outside of functions, <tt/__func__/ is
411 #define PRINT_DEBUG(s) printf ("%s: %s\n", __func__, s);
414 The macro will print the name of the current function plus a given
420 <sect>Predefined macros<p>
422 The compiler defines several macros at startup:
426 <tag><tt>__CC65__</tt></tag>
428 This macro is always defined. Its value is the version number of the
429 compiler in hex. Version 2.0.1 of the compiler will have this macro defined
432 <tag><tt>__CBM__</tt></tag>
434 This macro is defined if the target system is one of the CBM targets.
436 <tag><tt>__C64__</tt></tag>
438 This macro is defined if the target is the c64 (-t c64).
440 <tag><tt>__C128__</tt></tag>
442 This macro is defined if the target is the c128 (-t c128).
444 <tag><tt>__PLUS4__</tt></tag>
446 This macro is defined if the target is the plus/4 (-t plus4).
448 <tag><tt>__CBM610__</tt></tag>
450 This macro is defined if the target is one of the CBM 600/700 family of
451 computers (called B series in the US).
453 <tag><tt>__PET__</tt></tag>
455 This macro is defined if the target is the PET family of computers (-t pet).
457 <tag><tt>__ATARI__</tt></tag>
459 This macro is defined if the target is one of the Atari computers
460 (400/800/130XL/800XL).
462 <tag><tt>__APPLE2__</tt></tag>
464 This macro is defined if the target is the Apple ][ (-t apple2).
466 <tag><tt>__GEOS__</tt></tag>
468 This macro is defined if you are compiling for the GEOS system (-t geos).
470 <tag><tt>__FILE__</tt></tag>
472 This macro expands to a string containing the name of the C source file.
474 <tag><tt>__LINE__</tt></tag>
476 This macro expands to the current line number.
478 <tag><tt>__STRICT_ANSI__</tt></tag>
480 This macro is defined to 1 if the <tt/-A/ compiler option was given, and
483 <tag><tt>__OPT__</tt></tag>
485 Is defined if the compiler was called with the <tt/-O/ command line option.
487 <tag><tt>__OPT_i__</tt></tag>
489 Is defined if the compiler was called with the <tt/-Oi/ command line option.
491 <tag><tt>__OPT_r__</tt></tag>
493 Is defined if the compiler was called with the <tt/-Or/ command line option.
495 <tag><tt>__OPT_s__</tt></tag>
497 Is defined if the compiler was called with the <tt/-Os/ command line option.
502 <sect>#pragmas<label id="pragmas"><p>
504 The compiler understands some pragmas that may be used to change code
505 generation and other stuff.
509 <tag><tt>#pragma bssseg (<name>)</tt></tag>
511 This pragma changes the name used for the BSS segment (the BSS segment
512 is used to store uninitialized data). The argument is a string enclosed
515 Note: The default linker configuration file does only map the standard
516 segments. If you use other segments, you have to create a new linker
519 Beware: The startup code will zero only the default BSS segment. If you
520 use another BSS segment, you have to do that yourself, otherwise
521 uninitialized variables do not have the value zero.
525 #pragma bssseg ("MyBSS")
529 <tag><tt>#pragma codeseg (<name>)</tt></tag>
531 This pragma changes the name used for the CODE segment (the CODE segment
532 is used to store executable code). The argument is a string enclosed in
535 Note: The default linker configuration file does only map the standard
536 segments. If you use other segments, you have to create a new linker
541 #pragma bssseg ("MyCODE")
545 <tag><tt>#pragma dataseg (<name>)</tt></tag>
547 This pragma changes the name used for the DATA segment (the DATA segment
548 is used to store initialized data). The argument is a string enclosed in
551 Note: The default linker configuration file does only map the standard
552 segments. If you use other segments, you have to create a new linker
557 #pragma bssseg ("MyDATA")
561 <tag><tt>#pragma rodataseg (<name>)</tt></tag>
563 This pragma changes the name used for the RODATA segment (the RODATA
564 segment is used to store readonly data). The argument is a string
565 enclosed in double quotes.
567 Note: The default linker configuration file does only map the standard
568 segments. If you use other segments, you have to create a new linker
573 #pragma bssseg ("MyRODATA")
577 <tag><tt>#pragma regvaraddr (<const int>)</tt></tag>
579 The compiler does not allow to take the address of register variables.
580 The regvaraddr pragma changes this. Taking the address of a register
581 variable is allowed after using this pragma, if the argument is not
582 zero. Using an argument of zero changes back to the default behaviour.
584 Beware: The C standard does not allow taking the address of a variable
585 declared as register. So your programs become non-portable if you use
586 this pragma. In addition, your program may not work. This is usually the
587 case if a subroutine is called with the address of a register variable,
588 and this subroutine (or a subroutine called from there) uses itself
589 register variables. So be careful with this #pragma.
593 #pragma regvaraddr(1) /* Allow taking the address
594 * of register variables
599 <tag><tt>#pragma signedchars (<const int>)</tt></tag>
601 Changed the signedness of the default character type. If the argument
602 is not zero, default characters are signed, otherwise characters are
603 unsigned. The compiler default is to make characters unsigned since this
604 creates a lot better code. This default may be overridden by the
605 <tt/--signed-chars/ command line option.
608 <tag><tt>#pragma staticlocals (<const int>)</tt></tag>
610 Use variables in the bss segment instead of variables on the stack. This
611 pragma changes the default set by the compiler option <tt/-Cl/. If the
612 argument is not zero, local variables are allocated in the BSS segment,
613 leading to shorter and in most cases faster, but non-reentrant code.
616 <tag><tt>#pragma zpsym (<name>)</tt></tag>
618 Tell the compiler that the - previously as external declared - symbol with
619 the given name is a zero page symbol (usually from an assembler file).
620 The compiler will create a matching import declaration for the assembler.
625 #pragma zpsym ("foo"); /* foo is in the zeropage */
632 <sect>Bugs/Feedback<p>
634 If you have problems using the compiler, if you find any bugs, or if you're
635 doing something interesting with it, I would be glad to hear from you. Feel
636 free to contact me by email (<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">).
642 This is the original compiler copyright:
645 --------------------------------------------------------------------------
648 This is the copyright notice for RA65, LINK65, LIBR65, and other
649 Atari 8-bit programs. Said programs are Copyright 1989, by John R.
650 Dunning. All rights reserved, with the following exceptions:
652 Anyone may copy or redistribute these programs, provided that:
654 1: You don't charge anything for the copy. It is permissable to
655 charge a nominal fee for media, etc.
657 2: All source code and documentation for the programs is made
658 available as part of the distribution.
660 3: This copyright notice is preserved verbatim, and included in
663 You are allowed to modify these programs, and redistribute the
664 modified versions, provided that the modifications are clearly noted.
666 There is NO WARRANTY with this software, it comes as is, and is
667 distributed in the hope that it may be useful.
669 This copyright notice applies to any program which contains
670 this text, or the refers to this file.
672 This copyright notice is based on the one published by the Free
673 Software Foundation, sometimes known as the GNU project. The idea
674 is the same as theirs, ie the software is free, and is intended to
675 stay that way. Everybody has the right to copy, modify, and re-
676 distribute this software. Nobody has the right to prevent anyone
677 else from copying, modifying or redistributing it.
679 --------------------------------------------------------------------------
682 In acknowledgment of this copyright, I will place my own changes to the
683 compiler under the same copyright. Please note however, that the library
684 and all binutils are covered by another copyright, and that I'm planning
685 to do a complete rewrite of the compiler, after which the compiler
686 copyright will also change.
688 For the list of changes requested by this copyright see newvers.txt.