The compiler may be called as follows:
+---------------------------------------------------------------------------
Usage: cc65 [options] file
- -d Debug mode
- -g Add debug info to object files
- -h Print this help
- -j Default characters are signed
- -o name Name the output file
- -s Print some statistics
- -tx Set target system x
- -v Verbose mode
- -A Strict ANSI mode
- -Cl Make local variables static
- -Dsym[=defn] Define a symbol
- -I path Set include directory
- -O Optimize code
- -Oi Optimize code, inline more code
- -Or Enable register variables
- -Os Inline some known functions
- -T Include source as comment
- -V Print version number
- -W Suppress warnings
-
-The -A option disables any compiler exensions. Have a look at section 5
-for a discussion of compiler extensions. In addition, the macro
+Short options:
+ -d Debug mode
+ -g Add debug info to object file
+ -h Help (this text)
+ -j Default characters are signed
+ -o name Name the output file
+ -t sys Set the target system
+ -v Increase verbosity
+ -A Strict ANSI mode
+ -Cl Make local variables static
+ -Dsym[=defn] Define a symbol
+ -I dir Set an include directory search path
+ -O Optimize code
+ -Oi Optimize code, inline more code
+ -Or Enable register variables
+ -Os Inline some known functions
+ -T Include source as comment
+ -V Print the compiler version number
+ -W Suppress warnings
+
+Long options:
+ --ansi Strict ANSI mode
+ --cpu type Set cpu type
+ --debug Debug mode
+ --debug-info Add debug info to object file
+ --help Help (this text)
+ --include-dir dir Set an include directory search path
+ --signed-chars Default characters are signed
+ --static-locals Make local variables static
+ --target sys Set the target system
+ --verbose Increase verbosity
+ --version Print the compiler version number
+---------------------------------------------------------------------------
+
+
+ -A
+ --ansi
+
+ This option disables any compiler exensions. Have a look at section 5
+ for a discussion of compiler extensions. In addition, the macro
__STRICT_ANSI__
-is defined, when compiling with -A.
+ is defined, when using one of these options.
--d enables debug mode, something that should not be needed for mere
-mortals:-)
--g will cause the compiler to insert a .DEBUGINFO command into the
-generated assembler code. This will cause the assembler to include all
-symbols in a special section in the object file.
+ --cpu CPU
--h and -s print some statistics, nothing spectacular.
+ A new, still experimental option. You may specify "6502" or "65C02" as
+ the CPU. 6502 is the default, so this will not change anything.
+ Specifying 65C02 will use a few 65C02 instructions when generating code.
+ Don't expect too much from this option: It is still new (and may have
+ bugs), and the additional instructions for the 65C02 are not that
+ overwhelming.
-Using -j you can make the default characters signed. Since the 6502 has
-no provisions for sign extending characters (which is needed on almost
-any load operation), this will make the code larger and slower. A better
-way is to declare characters explicitly as "signed" if needed. You can
-also use "#pragma signedchars" for better control of this option (see
-section 7).
-The -t option is used to set the target system. The target system
-determines things like the character set that is used for strings and
-character constants. The following target systems are supported:
+ -d
+ --debug
- none
- c64
- c128
- ace (no library support)
- plus4
+ Enables debug mode, something that should not be needed for mere
+ mortals:-)
+
+
+ -D sym[=definition]
+
+ Define a macro on the command line. If no definition is given, the macro
+ is defined to the value "1".
+
+
+ -g
+ --debug-info
+
+ This will cause the compiler to insert a .DEBUGINFO command into the
+ generated assembler code. This will cause the assembler to include all
+ symbols in a special section in the object file.
+
+
+ -h
+ --help
+
+ Print the short option summary shown above.
+
+
+ -j
+ --signed-chars
+
+ Using this option, you can make the default characters signed. Since the
+ 6502 has no provisions for sign extending characters (which is needed on
+ almost any load operation), this will make the code larger and slower. A
+ better way is to declare characters explicitly as "signed" if needed.
+ You can also use "#pragma signedchars" for better control of this option
+ (see section 7).
+
+
+ -t target
+ --target target
+
+ This option is used to set the target system. The target system
+ determines things like the character set that is used for strings and
+ character constants. The following target systems are supported:
+
+ none
+ c64
+ c128
+ ace (no library support)
+ plus4
cbm610
- pet (all CBM PET systems except the 2001)
- nes (Nintendo Entertainment System)
- apple2
- geos
+ pet (all CBM PET systems except the 2001)
+ nes (Nintendo Entertainment System)
+ apple2
+ geos
+
+
+ -v
+ --verbose
-Using -v, the compiler will be somewhat more verbose if errors or warnings
-are encountered.
+ Using this option, the compiler will be somewhat more verbose if errors
+ or warnings are encountered.
+
--Cl will use static storage for local variables instead of storage on the
-stack. Since the stack is emulated in software, this gives shorter and
-usually faster code, but the code is no longer reentrant. The difference
-between -Cl and declaring local variables as static yourself is, that
-initializer code is executed each time, the function is entered. So when
-using
+ -Cl
+ --static-locals
- void f (void)
- {
- unsigned a = 1;
- ...
- }
+ Use static storage for local variables instead of storage on the stack.
+ Since the stack is emulated in software, this gives shorter and usually
+ faster code, but the code is no longer reentrant. The difference between
+ -Cl and declaring local variables as static yourself is, that
+ initializer code is executed each time, the function is entered. So when
+ using
-the variable a will always have the value 1 when entering the function and
-using -Cl, while in
+ void f (void)
+ {
+ unsigned a = 1;
+ ...
+ }
- void f (void)
- {
- static unsigned a = 1;
- ....
- }
+ the variable a will always have the value 1 when entering the function
+ and using -Cl, while in
-the variable a will have the value 1 only the first time, the function is
-entered, and will keep the old value from one call of the function to the
-next.
+ void f (void)
+ {
+ static unsigned a = 1;
+ ....
+ }
-You may also use #pragma staticlocals to change this setting in your
-sources (see section 7).
+ the variable a will have the value 1 only the first time, the function
+ is entered, and will keep the old value from one call of the function to
+ the next.
--I sets the directory where the compiler searches for include files. You
-may use -I multiple times to add more than one directory to the search
-list.
+ You may also use #pragma staticlocals to change this setting in your
+ sources (see section 7).
--O will enable an optimizer run over the produced code. Using -Oi, the
-code generator will inline some code where otherwise a runtime functions
-would have been called, even if the generated code is larger. This will
-not only remove the overhead for a function call, but will make the code
-visible for the optimizer.
--Or will make the compiler honor the "register" keyword. Local variables
-may be placed in registers (which are actually zero page locations).
-There is some overhead involved with register variables, since the old
-contents of the registers must be saved and restored. In addition, the
-current implementation does not make good use of register variables, so
-using -Or may make your program even slower and larger. Use with care!
+ -I dir
+ --include-dir dir
-Using -Os will force the compiler to inline some known functions from the
-C library like strlen. Note: This has two consequences:
+ Set a directory where the compiler searches for include files. You may
+ use this option multiple times to add more than one directory to the
+ search list.
- * You may not use names of standard C functions in your own code. If
- you do that, your program is not standard compliant anyway, but
- using -Os will actually break things.
- * The inlined string and memory functions will not handle strings or
- memory areas larger than 255 bytes. Similar, the inlined is..()
- functions will not work with values outside char range.
+ -o name
+
+ Specify the name of the output file. If you don't specify a name, the
+ name of the C input file is used, with the extension replaced by ".s".
-It is possible to concatenate the modifiers for -O. For example, to
-enable register variables and inlining of known functions, you may use
--Ors.
--T will include the source code as comments in the generated code. This is
-normally not needed.
+ -O, -Oi, -Or, -Os
--V prints the version number of the compiler. When submitting a bug
-report, please include the operating system you're using, and the compiler
-version.
+ Enable an optimizer run over the produced code.
-The -W switch suppresses any warnings generated by the compiler. Since any
-source file may be written in a manner that it will not produce compiler
-warnings, using this option is usually not a good idea.
+ Using -Oi, the code generator will inline some code where otherwise a
+ runtime functions would have been called, even if the generated code is
+ larger. This will not only remove the overhead for a function call, but
+ will make the code visible for the optimizer.
+
+ -Or will make the compiler honor the "register" keyword. Local variables
+ may be placed in registers (which are actually zero page locations).
+ There is some overhead involved with register variables, since the old
+ contents of the registers must be saved and restored. In addition, the
+ current implementation does not make good use of register variables, so
+ using -Or may make your program even slower and larger. Use with care!
+
+ Using -Os will force the compiler to inline some known functions from
+ the C library like strlen. Note: This has two consequences:
+
+ * You may not use names of standard C functions in your own code. If
+ you do that, your program is not standard compliant anyway, but
+ using -Os will actually break things.
+
+ * The inlined string and memory functions will not handle strings or
+ memory areas larger than 255 bytes. Similar, the inlined is..()
+ functions will not work with values outside char range.
+
+ It is possible to concatenate the modifiers for -O. For example, to
+ enable register variables and inlining of known functions, you may use
+ -Ors.
+
+
+ -T
+
+ This include the source code as comments in the generated code. This is
+ normally not needed.
+
+
+ -V
+ --version
+
+ Print the version number of the compiler. When submitting a bug report,
+ please include the operating system you're using, and the compiler
+ version.
+
+
+ -W
+
+ This option will suppress any warnings generated by the compiler. Since
+ any source file may be written in a manner that it will not produce
+ compiler warnings, using this option is usually not a good idea.
* The compiler has some additional keywords:
- asm, __asm__, fastcall, __fastcall__, __AX__, __EAX__, __func__
+ asm, __asm__, fastcall, __fastcall__, __AX__, __EAX__, __func__,
+ __attribute__
The keywords without the underlines are disabled in strict ANSI mode.
an additional macro needed to access parameters in a variable
parameter list in a C function.
- * The compiler has only one symbol table. Because of that, it's not
- possible to use the name of a local variable in a nested block in the
- same function (global and local names are distinct, however).
-
- + The preprocessor does not understand the "defined" keyword in
- expressions evaluated in #if statements.
-
- * Functions may not return structs, struct assignment is not possible.
-
- * The size of any struct referenced via a pointer may not exceed 256
- bytes (this is because the Y register is used as index).
-
- * In a function, the size of the parameters plus the size of all local
- variables may not exceed 256 bytes (in fact, the limit may be even less
- depeding on the complexity of your expressions).
+ * Functions may not return structs. However, struct assignment *is*
+ possible.
* Part of the C library is available only with fastcall calling
conventions (see below). This means, that you may not mix pointers to
those functions with pointers to user written functions.
There may be some more minor differences, I'm currently not aware off. The
-biggest problems are the missing const and float data types. With both
-these things in mind, you should be able to write fairly portable code.
+biggest problem is the missing float data type. With this limitation in
+mind, you should be able to write fairly portable code.
is called. This will reduce the cost when calling assembler functions
significantly, especially when the function itself is rather small.
- BEWARE: You must not declare C functions as fastcall! This will not
- work for now and is not checked by the assembler, so you will get
- wrong code.
-
* There are two pseudo variables named __AX__ and __EAX__. Both refer to
the primary register that is used by the compiler to evaluate
expressions or return function results. __AX__ is of type unsigned int
Changed the signedness of the default character type. If the argument
is not zero, default characters are signed, otherwise characters are
unsigned. The compiler default is to make characters unsigned since this
- creates a lot better code.
+ creates a lot better code.
#pragma staticlocals (<const int>)
Compile and link utility for cc65
- (C) Copyright 1999 Ullrich von Bassewitz
+ (C) Copyright 1998-2000 Ullrich von Bassewitz
(uz@musoftware.de)
-2. Usage
---------
+2. Basic Usage
+--------------
The cl65 compile and link utility may be used to compile, assemble and
link files. While the separate tools do just one step, cl65 knows how to
build object files from C files (by calling the compiler, then the
assembler) and other things.
- Usage: cl65 [options] file
- Options:
- -A Strict ANSI mode
- -C name Use linker config file
- -D sym[=defn] Define a preprocessor symbol
- -I path Set an include directory path
- -Ln name Create a VICE label file
- -O Optimize code
- -Oi Optimize code, inline functions
- -Or Optimize code, honour the register keyword
- -Os Optimize code, inline known C funtions
- -S Compile but don't assemble and link
- -V Print the version number
- -W Suppress warnings
- -c Compiler and assemble but don't link
- -d Debug mode
- -g Add debug info
- -h Help (this text)
- -m name Create a map file
- -o name Name the output file
- -t system Set the target system
- -v Verbose mode
- -vm Verbose map file
+---------------------------------------------------------------------------
+Usage: cl65 [options] file
+Short options:
+ -A Strict ANSI mode
+ -C name Use linker config file
+ -Cl Make local variables static
+ -D sym[=defn] Define a preprocessor symbol
+ -I dir Set a compiler include directory path
+ -Ln name Create a VICE label file
+ -O Optimize code
+ -Oi Optimize code, inline functions
+ -Or Optimize code, honour the register keyword
+ -Os Optimize code, inline known C funtions
+ -S Compile but don't assemble and link
+ -V Print the version number
+ -W Suppress warnings
+ -c Compiler and assemble but don't link
+ -d Debug mode
+ -g Add debug info
+ -h Help (this text)
+ -m name Create a map file
+ -o name Name the output file
+ -t sys Set the target system
+ -v Verbose mode
+ -vm Verbose map file
+
+Long options:
+ --ansi Strict ANSI mode
+ --asm-include-dir dir Set an assembler include directory
+ --debug Debug mode
+ --debug-info Add debug info
+ --help Help (this text)
+ --include-dir dir Set a compiler include directory path
+ --target sys Set the target system
+ --version Print the version number
+ --verbose Verbose mode
+---------------------------------------------------------------------------
Most of the options have the same meaning than the corresponding compiler,
-assembler or linker option. If an option is available for more than one
-of the tools, it is set for all tools, where it is available. One example
-for this is -v: The compiler, the assembler and the linker are all called
-with the -v switch.
+assembler or linker option. See the documentation for these tools for an
+explanation. If an option is available for more than one of the tools, it
+is set for all tools, where it is available. One example for this is -v:
+The compiler, the assembler and the linker are all called with the -v
+switch.
There are a few remaining options that control the behaviour of cl65:
-The -S option forces cl65 to stop after the assembly step. This means that
-C files are translated into assembler files, but nothing more is done.
-Assembler files, object files and libraries given on the command line are
-ignored.
+ -S
+
+ This option forces cl65 to stop after the assembly step. This means that
+ C files are translated into assembler files, but nothing more is done.
+ Assembler files, object files and libraries given on the command line
+ are ignored.
+
+
+ -c
+
+ This options forces cl65 to stop after the assembly step. This means
+ that C and assembler files given on the command line are translated into
+ object files, but there is no link step, and object files and libraries
+ given on the command line are ignored.
+
+
+ -o name
+
+ The -o option is used for the target name in the final step. This causes
+ problems, if the linker will not be called, and there are several input
+ files on the command line. In this case, the name given with -o will be
+ used for all of them, which makes the option pretty useless. You
+ shouldn't use -o when more than one output file is created.
-The -c options forces cl65 to stop after the assembly step. This means
-that C and assembler files given on the command line are translated into
-object files, but there is no link step, and object files and libraries
-given on the command line are ignored.
-The -o option is used for the target name in the final step. This causes
-problems, if the linker will not be called, and there are several input
-files on the command line. In this case, the name given with -o will be
-used for all of them, which makes the option pretty useless. You shouldn't
-use -o when more than one output file is created.
+ -t sys
+ --target sys
-The default for the -t option is different from the compiler and linker in
-the case that the option is missing: While the compiler and linker will
-use the "none" system settings by default, cl65 will use the C64 as a
-target system by default. This was choosen since most people seem to use
-cc65 to develop for the C64.
+ The default for this option is different from the compiler and linker in
+ the case that the option is missing: While the compiler and linker will
+ use the "none" system settings by default, cl65 will use the C64 as a
+ target system by default. This was choosen since most people seem to use
+ cc65 to develop for the C64.
especially in makefiles to build object files directly from C files. Use
.c.o:
- cl65 -g -Oi $<
+ cl65 -g -Oi $<
to do this.
6. Copyright
------------
-cl65 is (C) Copyright 1998 Ullrich von Bassewitz. For usage of the
+cl65 is (C) Copyright 1998-2000 Ullrich von Bassewitz. For usage of the
binaries and/or sources the following conditions do apply:
This software is provided 'as-is', without any expressed or implied
projects / cc65 / commitdiff