The compiler understands some pragmas that may be used to change code
generation and other stuff. Some of these pragmas understand a special form:
If the first parameter is push, the old value is saved onto a stack
before changing it. The value may later be restored by using the pop
parameter with the #pragma.
#pragma bss-name ([push,] <name>)
This pragma changes the name used for the BSS segment (the BSS segment is used to store uninitialized data). The argument is a string enclosed in double quotes.
Note: The default linker configuration file does only map the standard segments. If you use other segments, you have to create a new linker configuration file.
Beware: The startup code will zero only the default BSS segment. If you use another BSS segment, you have to do that yourself, otherwise uninitialized variables do not have the value zero.
The #pragma understands the push and pop parameters as explained above.
Example:
#pragma bss-name ("MyBSS")
#pragma charmap (<index>, <code>)
Each literal string and each literal character in the source is translated by use of a translation table. This translation table is preset when the compiler is started depending on the target system, for example to map ISO-8859-1 characters into PETSCII if the target is a commodore machine.
This pragma allows to change entries in the translation table, so the translation for individual characters, or even the complete table may be adjusted.
Both arguments are assumed to be unsigned characters with a valid range of 1-255.
Beware of two pitfalls:
#pragma charmap is not
portable -- it depends on the build environment.Example:
/* Use a space wherever an 'a' occurs in ISO-8859-1 source */
#pragma charmap (0x61, 0x20);
#pragma check-stack ([push,] on|off)
Tells the compiler to insert calls to a stack checking subroutine to detect stack overflows. The stack checking code will lead to somewhat larger and slower programs, so you may want to use this pragma when debugging your program and switch it off for the release version. If a stack overflow is detected, the program is aborted.
If the argument is "off", stack checks are disabled (the default), otherwise they're enabled.
The #pragma understands the push and pop parameters as explained above.
#pragma code-name ([push,] <name>)
This pragma changes the name used for the CODE segment (the CODE segment is used to store executable code). The argument is a string enclosed in double quotes.
Note: The default linker configuration file does only map the standard segments. If you use other segments, you have to create a new linker configuration file.
The #pragma understands the push and pop parameters as explained above.
Example:
#pragma code-name ("MyCODE")
#pragma codesize ([push,] <int>)
This pragma allows finer control about speed vs. size decisions in the code
generation and optimization phase. It gives the allowed size increase factor
(in percent). The default is can be changed by use of the
--codesize compiler option.
The #pragma understands the push and pop parameters as explained above.
#pragma data-name ([push,] <name>)
This pragma changes the name used for the DATA segment (the DATA segment is used to store initialized data). The argument is a string enclosed in double quotes.
Note: The default linker configuration file does only map the standard segments. If you use other segments, you have to create a new linker configuration file.
The #pragma understands the push and pop parameters as explained above.
Example:
#pragma data-name ("MyDATA")
#pragma local-strings ([push,] on|off)
When "on", emit string literals to the data segment when they're encountered in the source. The default ("off") is to keep string literals until end of assembly, merge read only literals if possible, and then output the literals into the data or rodata segment that is active at that point.
Using this #pragma it is possible to control the behaviour from within
the source. When #pragma local-strings is active, string literals are
output immediately, which means that they go into the currently active data
or rodata segment, but cannot be merged. When inactive, string literals are
remembered and output as a whole when translation is finished.
#pragma optimize ([push,] on|off)
Switch optimization on or off. If the argument is "off", optimization is disabled, otherwise it is enabled. Please note that this pragma only effects whole functions. The setting in effect when the function is encountered will determine if the generated code is optimized or not.
Optimization and code generation is also controlled by the codesize pragma.
The default is "off", but may be changed with the
-O compiler option.
The #pragma understands the push and pop parameters as explained above.
#pragma rodata-name ([push,] <name>)
This pragma changes the name used for the RODATA segment (the RODATA segment is used to store readonly data). The argument is a string enclosed in double quotes.
Note: The default linker configuration file does only map the standard segments. If you use other segments, you have to create a new linker configuration file.
The #pragma understands the push and pop parameters as explained above.
Example:
#pragma rodata-name ("MyRODATA")
#pragma regvaraddr ([push,] on|off)
The compiler does not allow to take the address of register variables. The regvaraddr pragma changes this. Taking the address of a register variable is allowed after using this pragma with "on" as argument. Using "off" as an argument switches back to the default behaviour.
Beware: The C standard does not allow taking the address of a variable declared as register. So your programs become non-portable if you use this pragma. In addition, your program may not work. This is usually the case if a subroutine is called with the address of a register variable, and this subroutine (or a subroutine called from there) uses register variables. So be careful with this #pragma.
The #pragma understands the push and pop parameters as explained above.
Example:
#pragma regvaraddr(on) /* Allow taking the address
* of register variables
*/
#pragma register-vars ([push,] on|off)
Enables or disables use of register variables. If register variables are
disabled (the default), the register keyword is ignored. Register
variables are explained in more detail in
a separate chapter.
The #pragma understands the push and pop parameters as explained above.
#pragma signed-chars ([push,] on|off)
Changes the signedness of the default character type. If the argument is
"on", default characters are signed, otherwise characters are unsigned. The
compiler default is to make characters unsigned since this creates a lot
better code. This default may be overridden by the
--signed-chars command line option.
The #pragma understands the push and pop parameters as explained above.
#pragma static-locals ([push,] on|off)
Use variables in the bss segment instead of variables on the stack. This
pragma changes the default set by the compiler option
--static-locals. If the argument is "on",
local variables are allocated in the BSS segment, leading to shorter and in
most cases faster, but non-reentrant code.
The #pragma understands the push and pop parameters as explained above.
#pragma warn (name, [push,] on|off)
Switch compiler warnings on or off. "name" is the name of a warning (see the
-W compiler option for a list). The name is
either followed by "pop", which restores the last pushed state, or by "on" or
"off", optionally preceeded by "push" to push the current state before
changing it.
Example:
/* Don't warn about the unused parameter in function func */
#pragma warn (unused-param, push, off)
static int func (int unused)
{
return 0;
}
#pragma warn (unused-param, pop)
#pragma writable-strings ([push,] on|off)
Changes the storage location of string literals. For historical reasons, the C standard defines that string literals are of type "char[]", but writing to such a literal causes undefined behaviour. Most compilers (including cc65) place string literals in the read-only data segment, which may cause problems with old C code that writes to string literals.
Using this pragma (or the corresponding command line option
--writable-strings) causes the
literals to be placed in the data segment so they can be written to without
worry.
The #pragma understands the push and pop parameters as explained above.
#pragma zpsym (<name>)
Tell the compiler that the -- previously as external declared -- symbol with the given name is a zero page symbol (usually from an assembler file). The compiler will create a matching import declaration for the assembler.
Example:
extern int foo;
#pragma zpsym ("foo"); /* foo is in the zeropage */