The Palm OS compiler chain consists of the following tools:
Palm OS Protein C/C++ Compiler
The Palm OS Protein C/C++ Compiler is a full-featured, standards-based, optimizing C/C++ compiler.
- The Palm OS compiler supports the C++ language standard ANSI/ISO 14882:1998(E).
- The Palm OS compiler supports the C language standard ANSI/ISO/IEC 9899:1999, commonly known as "C99."
The compiler, pacc
, takes one or more C/C++ language text files as input, and produces a corresponding number of assembly language source files as output. Optionally, pacc
assembles the assembly language files into object code by calling Palm OS Assembler, and links the object code files into an ARM executable file by calling Palm OS Linker.
NOTE: The Palm OS Protein C/C++ Compiler supports both standard C/C++ keyword extensions (see "Keywords" of the book Palm OS Protein C/C++ Compiler Language and Library Reference) as well as several predefined macros specific to the
pacc
compiler (see "Preprocessor Directives" of the Palm OS Protein C/C++ Compiler Language and Library Reference).
Compiler Command Line Interface
The general format of the pacc
command line interface is this:
pacc [options] source_file [source_files]
-
options
- Compiler options, as described in the section "Compiler Options."
-
source_file [source_files]
- pacc supports the following types of input files:
-
.c
- C source program.
-
.cc, .cxx, .cp .c++, .cpp
- A C++ source program. The
.c++
extension is not recognized by the Palm OS Developer Suite, even though the compiler supports it. -
.sx
- An assembly source program that should be preprocessed by the C preprocessor before assembly.
-
.asm
- An assembly source program, as input to the Palm OS assembler.
-
.s
- An assembly source program, as input to the Palm OS assembler.
-
.o
- A relocateable object file, as input to the Palm OS linker.
-
.l, .a, .lib
- A library object file, as input to the Palm OS linker.
Compiler Options
pacc
has options which control its behavior, as is standard for all compilers. The following compiler options are supported.
-
-c
- The compiler stops the compilation before invoking the linker, leaving the object
(.o
or.obj
) files in the current directory. Any source files are compiled and/or assembled into an object file. - Use the compiler option
-o
to specify the output object file name. -
-C
-
pacc
retains comments in the C preprocessor output, when used with-E
or-P
option. -
-D string
-
pacc
defines names as specified by string. This option applies only to source files passed through the C preprocessor. - Note: Whitespace is optional between
-D
and string. -
string
- Can be of the form
name=
def orname
. - In the first case,
name
is defined with value def exactly as if a corresponding#define
statement is the first line of the program. - In the second case,
name
is defined with the value1
. - The
-D
option has a lower precedence than the-U
option, which is described below. -
-E
-
pacc
stops after preprocessing source. - For this option,
pacc
preprocesses any source files, writing the output either tostdout
, or to the file specified with by the compiler option-o
, which is described below. - The preprocessor removes comment lines by default. To retain comment lines, use the compiler option
-C
, which is described above. -
-ex
- This option enables
pacc
's exception handling support. -
-g
-
pacc
includes symbolic debugging information in the assembly files, and sets the default optimization level to-O1
. - See also the compiler option
-g0
, described below. -
-g0
- Note:
"0"
is the number zero. - This compiler option is similar to the option
-g
, butpacc
inlines functions declared with the inline specifier. - This option usually improve run-time speed and reduces code size, but may make it more difficult to debug inline functions.
-
-I dir
- This option changes the search path used to find files named in the C
#include
statements.
The search order for #include
statements is defined as follows:
- For filenames that are absolute pathnames,
pacc
uses only the filename as specified. - For filenames that are not absolute pathnames and that are enclosed in quotation marks (" "),
pacc
searches relative to the following directories, in the listed order: - For file names that are not absolute pathnames and that are enclosed in angle brackets (< >),
pacc
searches relative to the following directories, in the listed order:
-
-Ldir
- This option specifies a library path, which is passed to the linker via the
palink
-libpath
option.palink
uses the directory specified by dir to look for libraries that cannot otherwise be found. - If you specify this option without a directory, then
palink
will not search the default directories.
-
-logo
-
pacc
displays the logo banner, consisting of the version and copyright notice, on each run. This is the default setting. - To turn this feature off, use the compiler option
-nologo
. -
-noex
- This option disables
pacc
's exception handling support. This is the default setting. - To enable exception handling support, use the compiler option
-ex
. -
-nologo
-
pacc
does not display the logo banner. -
-nostackwarn
- Disables stack size warnings. This is the same as
-stackwarn=0
. -
-o outfile
- Use this option to set the name of the output file to something other than what the default rules would have generated.
- Certain restrictions on the suffix of outfile are enforced if compilation is stopped before calling the linker,
palink
. This restriction prevents accidental overwriting of the source file, for instance.
-
-O
- Note:
"O"
is the capital letter"o"
. -
pacc
sets the optimization level to the generally useful level of global optimization. This option is an abbreviation for the compiler option-O3
. -
-On
- Note:
"O"
is the capital letter"o"
. -
pacc
sets the optimization to the value specified by n, wheren
is a number between zero (0) and five (5). -
0 (zero)
- No optimization.
-
1
- Local (basic-block scope) optimization of blocks, only.
-
2
- The same as option
-O1
, plus intraprocedural global optimization, scheduling, and variables may reside in registers. -
3
- The same as option
-O2
, plus more extensive global optimizations. -
4
- The same as
-O3
, plus interprocedural global optimization and inlining. -
5
- The same as
-O4
, plus more extensive inlining and global optimizations. - Interprocedural optimization only applies to multiple C files compiled to object files within a single invocation of
pacc
. - You should be careful when handling object (
.o
) files produced by the options-O4
and-O5
. In these modes, when multiple files are passed to the compiler, interprocedural optimization occurs across files, so the resultant object files are dependent on each other for correct execution. If you make a change in one of these source files, you must recompile all of the related files. - The default level of optimization is
-O1
.
-
-P
-
pacc
preprocesses all C/C++ source files, with the preprocessing result for each file written to a file name that has the file extension.i
substituted for the file name suffix of the source file. - The preprocessor removes comment lines by default. To retain comment lines, use the compiler option
-C
, which is described above. -
--preinclude=filename
- Each
--preinclude
argument supplies a filename that will be implicitly included in each compiled source file, as if there were a corresponding#include
directive at the beginning of the source file. There must not be a space between--preinclude=
and the filename. -
-S
-
pacc
stops after producing assembly from C/C++ source. Any source files are compiled as far as an assembly language (.s
) file. Use-o
to specify the output assembly language filename.pacc
stops the compilation before invoking the assembler and leaves all of the assembly source files produced by the compilation in the current directory. -
-stackwarn
- Sets the stack warning size to 8,192 bytes. This is the same as
-stackwarn=8192
. -
-stackwarn=n
- Sets the stack warning size to n bytes, where n is an integer. If any function allocates more stack than this value, a warning will be emitted describing how much stack the function would use. If n is 0, stack warning is disabled. The default value is 8,192, which results in a warning for functions using more than 8K or more of stack space.
-
-strict
-
pacc
is more strict about ANSI rules when compiling C/C++ source code, and emits error messages for behavior that is unsupported by the ANSI standard. - Use the compiler option
-Wstrict
if you wantpacc
to treat these errors as warnings. -
-U name
-
pacc
undefines the name specified by name. This option applies only to source files passed through the C/C++ preprocessor. - The
-U
option overrides a-D
option for the same name regardless of the order of the options on the command line. Any initial definition of name is removed.
-
-V
-
pacc
writes the its version numbers tostderr
, and exits without performing any further actions. -
-v
-
pacc
uses verbose output, showing all commands used for compilation, assembly, and linking. -
-vv
-
pacc
uses verbose output, showing all commands used for compilation, assembly, and linking, but does not execute the commands. -
-w
- Use
-w
to suppress all warning messages from compiler and preprocessor. This option suppresses warnings from preprocessors, but not from the assembler or linker. -
-wall
- Use
-wall
to enable all warning messages from compiler and preprocessor. This is the default setting. -
-wen
- This option makes the message number, specified by n, into an error message.
-
-wdn
- This option suppresses the warning or error number specified by n, if the message is suppressible. (Some errors are not suppressible.)
-
-won
- This option prevents the remark, warning, or suppressible error number, specified by n, from being emitted more than once, within a single source file.
-
-Wn
- This option suppresses messages, based on the value of n:
-
0
- Suppresses all remarks, warnings, and suppressible errors
-
2
- Suppresses only remarks
-
4
- Suppresses nothing. All remarks, warnings, and errors are reported.
- The default is 2. The option
-W0
is the same as the option-w
. (The option-W1
is treated the same as the option-W2
, and the option-W3
is treated as the option-W4
.) -
-Werror
-
pacc
treats all compiler warnings as errors, so they prevent the compilation from succeeding. This option does not affect errors from the Palm OS assembler or Palm OS linker. -
-Wstrict
-
pacc
is less strict about compiling C/C++ source code with the ANSI rules, and issues warnings for behavior unsupported by the standard. - For example, the ANSI standard requires a semicolon to delineate items in a
struct
definition. In the code example below, the missing semicolon afteruint32_t item
is an error when the-strict
option is used. - However, with the
-Wstrict
option specified, this coding error is treated as a warning.
typedef struct { uint32_t item } MyType;
Palm OS Assembler
The Palm OS assembler, paasm, processes the assembly language text files produced by pacc
, and produces binary object files conforming to the ARM-ELF standard (SWS ESPC 0003 B-01).
paasm
recognizes and assembles the entire ARM 4T instruction set with the following exceptions:
- THUMB instructions
Palm OS Protein C/C++ Compiler is not a Thumb compiler, but Thumb is specified as part of the 4T architecture.
- MRS/MSR
There is no support for the instructions that read and write the status register.
- LDRT/STRT
- LDM(2), LDM(3) and STM(2)
As a developer, you do not generally use this program directly. Rather, pacc
compiles source files and calls paasm
for you.
NOTE: This assembler is intended for assembling output of Palm OS Protein C/C++ Compiler,
pacc
. This is not a general purpose assembler; it does not support assembling manually-created assembly language programs.
However, in certain debugging situations, you may be interested in inspecting the assembly files before they are converted into ARM-ELF binary object files.
Differences Between the Palm OS Assembler and the ARM Assembler
There are several differences between the Palm OS assembler and that provided by ARM in its development suite:
- The Palm OS assembler requires that all opcodes be in lower case.
- Opcodes do not need to be indented.
- Labels must be terminated with a colon.
- Labels are only available for use with directives and cannot be used for references in opcode parameters.
- The directives are completely different.
- An ARM assembly file must begin and end with
area
andend
directives; the Palm OS assembler rejects those directives. - "&" to indicate a hexadecimal literal is not supported by
paasm
. Neither is "2_" to indicate a binary literal, nor "n_" to indicate other bases. - Branches to
<label> + <number>
are not supported bypaasm
. - References of the form "
mov r2, #label
", where "label
" is a label, are not supported. - Opcode/register combination instructions are accepted by the ARM assembler (with unpredictable results) but are rejected by the Palm OS assembler.
NOTE: The Palm OS Assembler is not intended for use other than by the C/C++ Compiler. PalmSource™ does not recommend using it to directly write assembly language code.
Assembler Command Line Interface
The general format of the Palm OS assembler command line interface is this:
paasm [options] asmfile.s
-
options
- Assembler options, as described in the section "Assembler Options."
Assembler Options
Palm OS Linker
The Palm OS linker combines linkable ARM-ELF object files into a single ARM executable file. As a developer, you do not generally use this program directly. Rather, the pacc
calls palink
for you.
However, in certain situations, you may want to run the linker independent from the compiler. For example, you may be interested in changing linker options for debugging reasons without wanting to recompile source into object files.
Linker Command Line Interface
The general format of the Palm OS linker command line interface is this:
palink [options] inputFiles
-
options
- Linker options, as described in the section "Linker Options."
-
inputFiles
- Space-separated list of object files or libraries. Input files are put into output in the order given.
Linker Options
-
-help
-
palink
prints a summary of help. -
-d | -debug
-
palink
includes debug information (debug input sections and the symbol and string tables) in the output file. - This is the default setting. To turn off this option, use the option
-nodebug
. -
-entry location
-
palink
uses the given numeric value or a symbol specified by location as the unique entry point of the output file. -
-errors file
- Use this option to tell
palink
to redirect error output to the specified file instead of usingstderr
. -
-first sectionid
- Use this option to tell
palink
that the section specified by sectionid is to be placed first in the output file. -
-info topics
-
palink
displays information on specific items, defined by topics: -
sizes
-
palink
gives a list and the totals of the code and data sizes (for read-only data, read-write data, zero-initialized data, and debug data) for each input object and library member in the ELF object file. Using this option is equivalent to using this option:-info sizes,totals
. -
totals
-
palink
gives the totals of the code and data sizes (for read-only data, read-write data, zero-initialized data, and debug data) for input objects and libraries. -
unused
-
palink
lists all unused sections that were eliminated when the output file was created. - These topics can be specified alone or can be used together, separated by commas but with no spaces:
-info sizes,totals,unused
-
-libpath pathlist
- This option instructs
palink
where to search for library files when an unqualified library file does not exist in the current working directory. -
pathlist
- Specifies a list of directories. pathlist must contain at least one directory. pathlist is a comma-delimited list of directories. (The delimiter can only be a single comma with no intervening whitespace.)
- You can specify this option multiple times; the resulting pathlist is the set of all directories you have specified.
- Linker input files that are specified with path qualifiers are only searched in the resulting directories. Linker input files with no path qualification are first searched for in the current working directory then in each of the directories in the resulting pathlist, in sequential order.
-
-list file
- Use this option to tell
palink
to redirect standard output to the specified file. -
-locals
-
palink
adds local symbols to the output symbol table. - This is the default setting. To turn off this option, use the option
-nolocals
. -
-mangled
-
palink
uses object file values for the C++ symbols in error messages and in the text output created by the-info
,-map
,-symbols
, and-xref
options. The symbol table itself is not altered. - This option overrides the default option
-unmangled
. -
-map
-
palink
outputs an object file map. -
-nodebug
-
palink
does not include debug information in the output file. - This option overrides the default option
-debug
. -
-nolocals
-
palink
does not add local symbols to the output symbol table. - This option overrides the default option
-locals
. -
-o filename | -output filename
-
palink
sets the name of the output file to the name specified by filename. - The default output filename from
palink
iself.o
. -
-symbols
-
palink
outputs symbols that are used in the link step. -
-unmangled
-
palink
uses source code equivalents for the C++ symbols in error messages and in the text output created by the-info
,-map
,-symbols
, and-xref
options. The symbol table itself is not altered. - This option is the default. To turn off this option, use the option
-mangled
. -
-V
-
palink
writes the its version numbers tostderr
, and exits without performing any further actions. -
-via file
- Use this option to tell
palink
to read more options from the specified file. -
-xref
- Use this option to tell
palink
to create an intersectional cross-reference table.