1
0
mirror of https://github.com/cc65/cc65.git synced 2024-06-26 05:29:30 +00:00

Update for new features

git-svn-id: svn://svn.cc65.org/cc65/trunk@101 b7a2c559-68d2-44c3-8de9-860c34a00d81
This commit is contained in:
cuz 2000-06-22 12:06:30 +00:00
parent 553063a498
commit a13e897291
2 changed files with 275 additions and 177 deletions

View File

@ -66,139 +66,226 @@ the assembler, have a look at ca65.txt).
The compiler may be called as follows: The compiler may be called as follows:
---------------------------------------------------------------------------
Usage: cc65 [options] file Usage: cc65 [options] file
-d Debug mode Short options:
-g Add debug info to object files -d Debug mode
-h Print this help -g Add debug info to object file
-j Default characters are signed -h Help (this text)
-o name Name the output file -j Default characters are signed
-s Print some statistics -o name Name the output file
-tx Set target system x -t sys Set the target system
-v Verbose mode -v Increase verbosity
-A Strict ANSI mode -A Strict ANSI mode
-Cl Make local variables static -Cl Make local variables static
-Dsym[=defn] Define a symbol -Dsym[=defn] Define a symbol
-I path Set include directory -I dir Set an include directory search path
-O Optimize code -O Optimize code
-Oi Optimize code, inline more code -Oi Optimize code, inline more code
-Or Enable register variables -Or Enable register variables
-Os Inline some known functions -Os Inline some known functions
-T Include source as comment -T Include source as comment
-V Print version number -V Print the compiler version number
-W Suppress warnings -W Suppress warnings
The -A option disables any compiler exensions. Have a look at section 5 Long options:
for a discussion of compiler extensions. In addition, the macro --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__ __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 --cpu CPU
generated assembler code. This will cause the assembler to include all
symbols in a special section in the object file.
-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 -d
determines things like the character set that is used for strings and --debug
character constants. The following target systems are supported:
none Enables debug mode, something that should not be needed for mere
c64 mortals:-)
c128
ace (no library support)
plus4 -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 cbm610
pet (all CBM PET systems except the 2001) pet (all CBM PET systems except the 2001)
nes (Nintendo Entertainment System) nes (Nintendo Entertainment System)
apple2 apple2
geos geos
Using -v, 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 -v
stack. Since the stack is emulated in software, this gives shorter and --verbose
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
void f (void) Using this option, the compiler will be somewhat more verbose if errors
{ or warnings are encountered.
unsigned a = 1;
...
}
the variable a will always have the value 1 when entering the function and -Cl
using -Cl, while in --static-locals
void f (void) Use static storage for local variables instead of storage on the stack.
{ Since the stack is emulated in software, this gives shorter and usually
static unsigned a = 1; 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 have the value 1 only the first time, the function is void f (void)
entered, and will keep the old value from one call of the function to the {
next. unsigned a = 1;
...
}
You may also use #pragma staticlocals to change this setting in your the variable a will always have the value 1 when entering the function
sources (see section 7). and using -Cl, while in
-I sets the directory where the compiler searches for include files. You void f (void)
may use -I multiple times to add more than one directory to the search {
list. static unsigned a = 1;
....
}
-O will enable an optimizer run over the produced code. Using -Oi, the the variable a will have the value 1 only the first time, the function
code generator will inline some code where otherwise a runtime functions is entered, and will keep the old value from one call of the function to
would have been called, even if the generated code is larger. This will the next.
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 You may also use #pragma staticlocals to change this setting in your
may be placed in registers (which are actually zero page locations). sources (see section 7).
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 -I dir
you do that, your program is not standard compliant anyway, but --include-dir dir
using -Os will actually break things.
* The inlined string and memory functions will not handle strings or Set a directory where the compiler searches for include files. You may
memory areas larger than 255 bytes. Similar, the inlined is..() use this option multiple times to add more than one directory to the
functions will not work with values outside char range. search list.
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 -o name
normally not needed.
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".
-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.
The -W switch suppresses any warnings generated by the compiler. Since any -O, -Oi, -Or, -Os
source file may be written in a manner that it will not produce compiler
warnings, using this option is usually not a good idea. 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!
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.
@ -232,7 +319,8 @@ and the one defined by the ISO standard:
* The compiler has some additional keywords: * 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. The keywords without the underlines are disabled in strict ANSI mode.
@ -249,29 +337,16 @@ and the one defined by the ISO standard:
an additional macro needed to access parameters in a variable an additional macro needed to access parameters in a variable
parameter list in a C function. parameter list in a C function.
* The compiler has only one symbol table. Because of that, it's not * Functions may not return structs. However, struct assignment *is*
possible to use the name of a local variable in a nested block in the possible.
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).
* Part of the C library is available only with fastcall calling * Part of the C library is available only with fastcall calling
conventions (see below). This means, that you may not mix pointers to conventions (see below). This means, that you may not mix pointers to
those functions with pointers to user written functions. those functions with pointers to user written functions.
There may be some more minor differences, I'm currently not aware off. The 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 biggest problem is the missing float data type. With this limitation in
these things in mind, you should be able to write fairly portable code. mind, you should be able to write fairly portable code.
@ -324,10 +399,6 @@ This cc65 version has some extensions to the ISO C standard.
is called. This will reduce the cost when calling assembler functions is called. This will reduce the cost when calling assembler functions
significantly, especially when the function itself is rather small. 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 * There are two pseudo variables named __AX__ and __EAX__. Both refer to
the primary register that is used by the compiler to evaluate the primary register that is used by the compiler to evaluate
expressions or return function results. __AX__ is of type unsigned int expressions or return function results. __AX__ is of type unsigned int
@ -514,7 +585,7 @@ generation and other stuff.
Changed the signedness of the default character type. If the argument Changed the signedness of the default character type. If the argument
is not zero, default characters are signed, otherwise characters are is not zero, default characters are signed, otherwise characters are
unsigned. The compiler default is to make characters unsigned since this 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>) #pragma staticlocals (<const int>)

View File

@ -4,7 +4,7 @@
Compile and link utility for cc65 Compile and link utility for cc65
(C) Copyright 1999 Ullrich von Bassewitz (C) Copyright 1998-2000 Ullrich von Bassewitz
(uz@musoftware.de) (uz@musoftware.de)
@ -35,67 +35,94 @@ available, and the use of cl65 is much simpler.
2. Usage 2. Basic Usage
-------- --------------
The cl65 compile and link utility may be used to compile, assemble and 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 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 build object files from C files (by calling the compiler, then the
assembler) and other things. assembler) and other things.
Usage: cl65 [options] file ---------------------------------------------------------------------------
Options: Usage: cl65 [options] file
-A Strict ANSI mode Short options:
-C name Use linker config file -A Strict ANSI mode
-D sym[=defn] Define a preprocessor symbol -C name Use linker config file
-I path Set an include directory path -Cl Make local variables static
-Ln name Create a VICE label file -D sym[=defn] Define a preprocessor symbol
-O Optimize code -I dir Set a compiler include directory path
-Oi Optimize code, inline functions -Ln name Create a VICE label file
-Or Optimize code, honour the register keyword -O Optimize code
-Os Optimize code, inline known C funtions -Oi Optimize code, inline functions
-S Compile but don't assemble and link -Or Optimize code, honour the register keyword
-V Print the version number -Os Optimize code, inline known C funtions
-W Suppress warnings -S Compile but don't assemble and link
-c Compiler and assemble but don't link -V Print the version number
-d Debug mode -W Suppress warnings
-g Add debug info -c Compiler and assemble but don't link
-h Help (this text) -d Debug mode
-m name Create a map file -g Add debug info
-o name Name the output file -h Help (this text)
-t system Set the target system -m name Create a map file
-v Verbose mode -o name Name the output file
-vm Verbose map 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, 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 assembler or linker option. See the documentation for these tools for an
of the tools, it is set for all tools, where it is available. One example explanation. If an option is available for more than one of the tools, it
for this is -v: The compiler, the assembler and the linker are all called is set for all tools, where it is available. One example for this is -v:
with the -v switch. 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: 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 -S
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.
The -c options forces cl65 to stop after the assembly step. This means This option forces cl65 to stop after the assembly step. This means that
that C and assembler files given on the command line are translated into C files are translated into assembler files, but nothing more is done.
object files, but there is no link step, and object files and libraries Assembler files, object files and libraries given on the command line
given on the command line are ignored. 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.
The default for the -t option is different from the compiler and linker in -c
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 This options forces cl65 to stop after the assembly step. This means
target system by default. This was choosen since most people seem to use that C and assembler files given on the command line are translated into
cc65 to develop for the C64. 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.
-t sys
--target sys
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.
@ -141,7 +168,7 @@ As a general rule, you may use cl65 instead of cc65 at most times,
especially in makefiles to build object files directly from C files. Use especially in makefiles to build object files directly from C files. Use
.c.o: .c.o:
cl65 -g -Oi $< cl65 -g -Oi $<
to do this. to do this.
@ -159,7 +186,7 @@ Feel free to contact me by email (uz@musoftware.de).
6. Copyright 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: binaries and/or sources the following conditions do apply:
This software is provided 'as-is', without any expressed or implied This software is provided 'as-is', without any expressed or implied