]> git.sur5r.net Git - cc65/blob - doc/cc65.txt
Added an older conversion program
[cc65] / doc / cc65.txt
1
2
3                                    cc65
4
5                        A C Compiler for 6502 Systems
6
7                     (C) Copyright 1989 John R. Dunning
8                (C) Copyright 1998-2000 Ullrich von Bassewitz
9                             (uz@musoftware.de)
10
11
12
13 Contents
14 --------
15
16   1. Overview
17
18   2. Usage
19
20   3. Input and output
21
22   4. Differences to the ISO standard
23
24   5. Extensions
25
26   6. Predefined macros
27
28   7. #pragmas
29
30   8. Bugs/Feedback
31
32   9. Copyright
33
34
35
36 1. Overview
37 -----------
38
39 cc65 was originally a C compiler for the Atari 8-bit machines written by
40 John R. Dunning. In prior releases I've described the compiler by listing
41 up the changes made by me. I have made many more changes in the meantime
42 (and rewritten major parts of the compiler), so I will no longer do that,
43 since the list would be too large and of no use to anyone. Instead I will
44 describe the compiler in respect to the ANSI/ISO C standard. In fact, I'm
45 planning a complete rewrite (that is, a complete new compiler) for the
46 next release, since there are too many limitations in the current code,
47 and removing these limitations would mean a rewrite of many more parts of
48 the compiler.
49
50 There is a separate document named "library.txt" that covers the library
51 available for the compiler. If you know C and are interested in doing
52 actual programming, the library documentation is probably of much more use
53 than this document.
54
55 If you need some hints for getting the best code out of the compiler, you
56 may have a look at "coding.txt" which covers some code generation issues.
57
58
59
60 2. Usage
61 --------
62
63 The compiler translates C files into files containing assembler code that
64 may be translated by the ca65 macroassembler (for more information about
65 the assembler, have a look at ca65.txt).
66
67 The compiler may be called as follows:
68
69 ---------------------------------------------------------------------------
70 Usage: cc65 [options] file
71 Short options:
72   -d                    Debug mode
73   -g                    Add debug info to object file
74   -h                    Help (this text)
75   -j                    Default characters are signed
76   -o name               Name the output file
77   -t sys                Set the target system
78   -v                    Increase verbosity
79   -A                    Strict ANSI mode
80   -Cl                   Make local variables static
81   -Dsym[=defn]          Define a symbol
82   -I dir                Set an include directory search path
83   -O                    Optimize code
84   -Oi                   Optimize code, inline more code
85   -Or                   Enable register variables
86   -Os                   Inline some known functions
87   -T                    Include source as comment
88   -V                    Print the compiler version number
89   -W                    Suppress warnings
90
91 Long options:
92   --ansi                Strict ANSI mode
93   --cpu type            Set cpu type
94   --debug               Debug mode
95   --debug-info          Add debug info to object file
96   --help                Help (this text)
97   --include-dir dir     Set an include directory search path
98   --signed-chars        Default characters are signed
99   --static-locals       Make local variables static
100   --target sys          Set the target system
101   --verbose             Increase verbosity
102   --version             Print the compiler version number
103 ---------------------------------------------------------------------------
104
105
106   -A
107   --ansi
108
109   This option disables any compiler exensions. Have a look at section 5
110   for a discussion of compiler extensions. In addition, the macro
111
112         __STRICT_ANSI__
113
114   is defined, when using one of these options.
115
116
117   --cpu CPU
118
119   A new, still experimental option. You may specify "6502" or "65C02" as
120   the CPU. 6502 is the default, so this will not change anything.
121   Specifying 65C02 will use a few 65C02 instructions when generating code.
122   Don't expect too much from this option: It is still new (and may have
123   bugs), and the additional instructions for the 65C02 are not that
124   overwhelming.
125
126
127   -d
128   --debug
129
130   Enables debug mode, something that should not be needed for mere
131   mortals:-)
132
133
134   -D sym[=definition]
135
136   Define a macro on the command line. If no definition is given, the macro
137   is defined to the value "1".
138
139
140   -g
141   --debug-info
142
143   This will cause the compiler to insert a .DEBUGINFO command into the
144   generated assembler code. This will cause the assembler to include all
145   symbols in a special section in the object file.
146
147
148   -h
149   --help
150
151   Print the short option summary shown above.
152
153
154   -j
155   --signed-chars
156
157   Using this option, you can make the default characters signed. Since the
158   6502 has no provisions for sign extending characters (which is needed on
159   almost any load operation), this will make the code larger and slower. A
160   better way is to declare characters explicitly as "signed" if needed.
161   You can also use "#pragma signedchars" for better control of this option
162   (see section 7).
163
164
165   -t target
166   --target target
167
168   This option is used to set the target system. The target system
169   determines things like the character set that is used for strings and
170   character constants. The following target systems are supported:
171
172         none
173         c64
174         c128
175         ace             (no library support)
176         plus4
177         cbm610
178         pet             (all CBM PET systems except the 2001)
179         nes             (Nintendo Entertainment System)
180         apple2
181         geos
182
183
184   -v
185   --verbose
186
187   Using this option, the compiler will be somewhat more verbose if errors
188   or warnings are encountered.
189  
190
191   -Cl
192   --static-locals
193
194   Use static storage for local variables instead of storage on the stack.
195   Since the stack is emulated in software, this gives shorter and usually
196   faster code, but the code is no longer reentrant. The difference between
197   -Cl and declaring local variables as static yourself is, that
198   initializer code is executed each time, the function is entered. So when
199   using
200
201         void f (void)
202         {
203             unsigned a = 1;
204             ...
205         }
206
207   the variable a will always have the value 1 when entering the function
208   and using -Cl, while in
209
210         void f (void)
211         {
212             static unsigned a = 1;
213             ....
214         }
215
216   the variable a will have the value 1 only the first time, the function
217   is entered, and will keep the old value from one call of the function to
218   the next.
219
220   You may also use #pragma staticlocals to change this setting in your
221   sources (see section 7).
222
223
224   -I dir
225   --include-dir dir
226
227   Set a directory where the compiler searches for include files. You may
228   use this option multiple times to add more than one directory to the
229   search list.   
230
231
232   -o name
233   
234   Specify the name of the output file. If you don't specify a name, the
235   name of the C input file is used, with the extension replaced by ".s".
236
237
238   -O, -Oi, -Or, -Os
239
240   Enable an optimizer run over the produced code.
241
242   Using -Oi, the code generator will inline some code where otherwise a
243   runtime functions would have been called, even if the generated code is
244   larger. This will not only remove the overhead for a function call, but
245   will make the code visible for the optimizer.
246
247   -Or will make the compiler honor the "register" keyword. Local variables
248   may be placed in registers (which are actually zero page locations).
249   There is some overhead involved with register variables, since the old
250   contents of the registers must be saved and restored. In addition, the
251   current implementation does not make good use of register variables, so
252   using -Or may make your program even slower and larger. Use with care!
253
254   Using -Os will force the compiler to inline some known functions from
255   the C library like strlen. Note: This has two consequences:
256
257     * You may not use names of standard C functions in your own code. If
258       you do that, your program is not standard compliant anyway, but
259       using -Os will actually break things.
260
261     * The inlined string and memory functions will not handle strings or
262       memory areas larger than 255 bytes. Similar, the inlined is..()
263       functions will not work with values outside char range.
264
265   It is possible to concatenate the modifiers for -O. For example, to
266   enable register variables and inlining of known functions, you may use
267   -Ors.
268
269
270   -T
271
272   This include the source code as comments in the generated code. This is
273   normally not needed.
274
275
276   -V   
277   --version
278
279   Print the version number of the compiler. When submitting a bug report,
280   please include the operating system you're using, and the compiler
281   version.
282     
283
284   -W
285
286   This option will suppress any warnings generated by the compiler. Since
287   any source file may be written in a manner that it will not produce
288   compiler warnings, using this option is usually not a good idea.
289
290
291
292 3. Input and output
293 -------------------
294
295 The compiler will accept one C file per invocation and create a file with
296 the same base name, but with the extension replaced by ".s". The output
297 file contains assembler code suitable for the use with the ca65 macro
298 assembler.
299
300 In addition to the paths named in the -I option on the command line, the
301 directory named in the environment variable CC65_INC is added to the
302 search path for include files on startup.
303
304
305
306 4. Differences to the ISO standard
307 ----------------------------------
308
309 Here is a list of differences between the language, the compiler accepts,
310 and the one defined by the ISO standard:
311
312
313   * The compiler allows single line comments that start with //. This
314     feature is disabled in strict ANSI mode.
315
316   * The compiler allows unnamed parameters in parameter lists. The
317     compiler will not issue warnings about unused parameters that don't
318     have a name. This feature is disabled in strict ANSI mode.
319
320   * The compiler has some additional keywords:
321
322         asm, __asm__, fastcall, __fastcall__, __AX__, __EAX__, __func__,
323         __attribute__
324
325     The keywords without the underlines are disabled in strict ANSI mode.
326
327   * The "const" modifier is available, but has no effect.
328
329   * The datatypes "float" and "double" are not available.
330
331   * The compiler does not support bit fields.
332
333   * Initialization of local variables is only possible for scalar data
334     types (that is, not for arrays and structs).
335
336   * Because of the "wrong" order of the parameters on the stack, there is
337     an additional macro needed to access parameters in a variable
338     parameter list in a C function.
339
340   * Functions may not return structs. However, struct assignment *is*
341     possible.
342
343   * Part of the C library is available only with fastcall calling
344     conventions (see below). This means, that you may not mix pointers to
345     those functions with pointers to user written functions.
346
347 There may be some more minor differences, I'm currently not aware off. The
348 biggest problem is the missing float data type. With this limitation in
349 mind, you should be able to write fairly portable code.
350
351
352
353 5. Extensions
354 -------------
355
356 This cc65 version has some extensions to the ISO C standard.
357
358   * The compiler allows // comments (like in C++ and in the proposed C9x
359     standard). This feature is disabled by -A.
360
361   * The compiler allows to insert assembler statements into the output
362     file. The syntax is
363
364         asm (<string literal>) ;
365
366     or
367
368         __asm__ (<string literal>) ;
369
370     The first form is in the user namespace and is disabled if the -A
371     switch is given.
372
373     The given string is inserted literally into the output file, and a
374     newline is appended. The statements in this string are not checked by
375     the compiler, so be careful!
376
377     The asm statement may be used inside a function and on global file
378     level.
379
380   * There is a special calling convention named "fastcall". This calling
381     convention is currently only usable for functions written in
382     assembler. The syntax for a function declaration using fastcall is
383
384         <return type> fastcall <function name> (<parameter list>)
385
386     or
387
388         <return type> __fastcall__ <function name> (<parameter list>)
389
390     An example would be
391
392         void __fastcall__ f (unsigned char c)
393
394     The first form of the fastcall keyword is in the user namespace and is
395     therefore disabled in strict ANSI mode.
396
397     For functions declared as fastcall, the rightmost parameter is not
398     pushed on the stack but left in the primary register when the function
399     is called. This will reduce the cost when calling assembler functions
400     significantly, especially when the function itself is rather small.
401
402   * There are two pseudo variables named __AX__ and __EAX__. Both refer to
403     the primary register that is used by the compiler to evaluate
404     expressions or return function results. __AX__ is of type unsigned int
405     and __EAX__ of type long unsigned int respectively. The pseudo
406     variables may be used as lvalue and rvalue as every other variable.
407     They are most useful together with short sequences of assembler code.
408     For example, the macro
409
410         #define hi(x) (__AX__=(x),asm("\ttxa\n\tldx\t#$00",__AX__)
411
412     will give the high byte of any unsigned value.
413
414   * Inside a function, the identifier __func__ gives the name of the
415     current function as a string. Outside of functions, __func__ is
416     undefined.
417     Example:
418
419         #define PRINT_DEBUG(s)  printf ("%s: %s\n", __func__, s);
420
421     The macro will print the name of the current function plus a given
422     string.
423
424
425
426 6. Predefined macros
427 --------------------
428
429 The compiler defines several macros at startup:
430
431
432   __CC65__        This macro is always defined. Its value is the version
433                   number of the compiler in hex. Version 2.0.1 of the
434                   compiler will have this macro defined as 0x0201.
435
436   __CBM__         This macro is defined if the target system is one of the
437                   CBM targets.
438
439   __C64__         This macro is defined if the target is the c64 (-t c64).
440
441   __C128__        This macro is defined if the target is the c128 (-t c128).
442
443   __PLUS4__       This macro is defined if the target is the plus/4
444                   (-t plus4).
445
446   __CBM610__      This macro is defined if the target is one of the CBM
447                   600/700 family of computers (called B series in the US).
448
449   __PET__         This macro is defined if the target is the PET family of
450                   computers (-t pet).
451
452   __NES__         This macro is defined if the target is the Nintendo
453                   Entertainment System (-t nes).
454
455   __ATARI__       This macro is defined if the target is one of the Atari
456                   computers (400/800/130XL/800XL). Note that there is no
457                   runtime and C library support for atari systems.
458
459   __ACE__         This macro is defined if the target is Bruce Craigs ACE
460                   operating system. Note that there is no longer runtime
461                   and library support for ACE.
462
463   __APPLE2__      This macro is defined if the target is the Apple ][
464                   (-t apple2).
465
466   __GEOS__        This macro is defined if you are compiling for the GEOS
467                   system (-t geos).
468
469   __FILE__        This macro expands to a string containing the name of
470                   the C source file.
471
472   __LINE__        This macro expands to the current line number.
473
474   __STRICT_ANSI__ This macro is defined to 1 if the -A compiler option was
475                   given, and undefined otherwise.
476
477   __OPT__         Is defined if the compiler was called with the -O command
478                   line option.
479
480   __OPT_i__       Is defined if the compiler was called with the -Oi command
481                   line option.
482
483   __OPT_r__       Is defined if the compiler was called with the -Or command
484                   line option.
485
486   __OPT_s__       Is defined if the compiler was called with the -Os command
487                   line option.
488
489
490
491 7. #pragmas
492 -----------
493
494 The compiler understands some pragmas that may be used to change code
495 generation and other stuff.
496
497
498 #pragma bssseg (<name>)
499
500   This pragma changes the name used for the BSS segment (the BSS segment
501   is used to store uninitialized data). The argument is a string enclosed
502   in double quotes.
503
504   Note: The default linker configuration file does only map the standard
505   segments. If you use other segments, you have to create a new linker
506   configuration file.
507
508   Beware: The startup code will zero only the default BSS segment. If you
509   use another BSS segment, you have to do that yourself, otherwise
510   uninitialized variables do not have the value zero.
511
512   Example:
513
514         #pragma bssseg ("MyBSS")
515
516
517 #pragma codeseg (<name>)
518
519   This pragma changes the name used for the CODE segment (the CODE segment
520   is used to store executable code). The argument is a string enclosed in
521   double quotes.
522
523   Note: The default linker configuration file does only map the standard
524   segments. If you use other segments, you have to create a new linker
525   configuration file.
526
527   Example:
528
529         #pragma bssseg ("MyCODE")
530
531
532 #pragma dataseg (<name>)
533
534   This pragma changes the name used for the DATA segment (the DATA segment
535   is used to store initialized data). The argument is a string enclosed in
536   double quotes.
537
538   Note: The default linker configuration file does only map the standard
539   segments. If you use other segments, you have to create a new linker
540   configuration file.
541
542   Example:
543
544         #pragma bssseg ("MyDATA")
545
546
547 #pragma rodataseg (<name>)
548
549   This pragma changes the name used for the RODATA segment (the RODATA
550   segment is used to store readonly data). The argument is a string
551   enclosed in double quotes.
552
553   Note: The default linker configuration file does only map the standard
554   segments. If you use other segments, you have to create a new linker
555   configuration file.
556
557   Example:
558
559         #pragma bssseg ("MyRODATA")
560
561
562 #pragma regvaraddr (<const int>)
563
564   The compiler does not allow to take the address of register variables.
565   The regvaraddr pragma changes this. Taking the address of a register
566   variable is allowed after using this pragma, if the argument is not
567   zero. Using an argument of zero changes back to the default behaviour.
568
569   Beware: The C standard does not allow taking the address of a variable
570   declared as register. So your programs become non-portable if you use
571   this pragma. In addition, your program may not work. This is usually the
572   case if a subroutine is called with the address of a register variable,
573   and this subroutine (or a subroutine called from there) uses itself
574   register variables. So be careful with this #pragma.
575
576   Example:
577
578         #pragma regvaraddr(1)   /* Allow taking the address
579                                  * of register variables
580                                  */
581
582
583 #pragma signedchars (<const int>)
584
585   Changed the signedness of the default character type. If the argument
586   is not zero, default characters are signed, otherwise characters are
587   unsigned. The compiler default is to make characters unsigned since this
588   creates a lot better code.
589
590
591 #pragma staticlocals (<const int>)
592
593   Use variables in the bss segment instead of variables on the stack. This
594   pragma changes the default set by the compiler option -Cl. If the argument
595   is not zero, local variables are allocated in the BSS segment, leading to
596   shorter and in most cases faster, but non-reentrant code.
597
598
599 #pragma zpsym (<name>)
600
601   Tell the compiler that the - previously as external declared - symbol with
602   the given name is a zero page symbol (usually from an assembler file).
603   The compiler will create a matching import declaration for the assembler.
604
605   Example:
606
607         extern int foo;
608         #pragma zpsym ("foo");  /* foo is in the zeropage */
609
610
611
612 8. Bugs/Feedback
613 ----------------
614
615 If you have problems using the compiler, if you find any bugs, or if
616 you're doing something interesting with the compiler, I would be glad to
617 hear from you. Feel free to contact me by email (uz@musoftware.de).
618
619
620
621 9. Copyright
622 ------------
623
624 This is the original compiler copyright:
625
626 --------------------------------------------------------------------------
627   -*- Mode: Text -*-
628
629      This is the copyright notice for RA65, LINK65, LIBR65, and other
630   Atari 8-bit programs.  Said programs are Copyright 1989, by John R.
631   Dunning.  All rights reserved, with the following exceptions:
632
633       Anyone may copy or redistribute these programs, provided that:
634
635   1:  You don't charge anything for the copy.  It is permissable to
636       charge a nominal fee for media, etc.
637
638   2:  All source code and documentation for the programs is made
639       available as part of the distribution.
640
641   3:  This copyright notice is preserved verbatim, and included in
642       the distribution.
643
644       You are allowed to modify these programs, and redistribute the
645   modified versions, provided that the modifications are clearly noted.
646
647       There is NO WARRANTY with this software, it comes as is, and is
648   distributed in the hope that it may be useful.
649
650       This copyright notice applies to any program which contains
651   this text, or the refers to this file.
652
653       This copyright notice is based on the one published by the Free
654   Software Foundation, sometimes known as the GNU project.  The idea
655   is the same as theirs, ie the software is free, and is intended to
656   stay that way.  Everybody has the right to copy, modify, and re-
657   distribute this software.  Nobody has the right to prevent anyone
658   else from copying, modifying or redistributing it.
659
660 --------------------------------------------------------------------------
661
662 In acknowledgment of this copyright, I will place my own changes to the
663 compiler under the same copyright. Please note however, that the library
664 and all binutils are covered by another copyright, and that I'm planning
665 to do a complete rewrite of the compiler, after which the compiler
666 copyright will also change.
667
668 For the list of changes requested by this copyright see newvers.txt.
669
670
671