Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

3    Using the Palm OS Compiler Chain

Palm OS® Protein C/C++ Compiler Tools Guide

Palm OS® Developer Suite

The Palm OS compiler chain consists of the following tools:

Palm OS Protein C/C++ Compiler ^TOP^

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 ^TOP^

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.

NOTE: These file extensions are accepted regardless of case.

Compiler Options ^TOP^

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 or name.
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 value 1.
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 to stdout, 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, but pacc 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.

NOTE: Whitespace is optional between -I and dir.

The search order for #include statements is defined as follows:

  1. For filenames that are absolute pathnames, pacc uses only the filename as specified.
  2. 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:
    1. The directory containing the source file that contains the #include statement.
    2. The directories listed in any -I compiler options, in the order the options occur on the command line.
    3. The directories where the pacc standard headers have been installed.
  3. 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:
    1. The directories listed in any -I compiler options, in the order the options occur on the command line.
    2. The directories where the pacc standard headers have been installed.
-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.

NOTE: Do not use any whitespace between -L and dir when you specify this option.
-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.

NOTE: You must have whitespace between -o and outfile when you specify this option.
-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, where n 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.

NOTE: You must not have any whitespace between -O and n when you specify this option.
-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 want pacc 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.

NOTE: Whitespace is optional between -U and name.
-V
pacc writes the its version numbers to stderr, 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.

NOTE: You must not have whitespace between -we and n when you specify this option.
-wdn
This option suppresses the warning or error number specified by n, if the message is suppressible. (Some errors are not suppressible.)

NOTE: You must not have whitespace between -wd and n when you specify this option.
-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.

NOTE: You must not have whitespace between -wo and n when you specify this option.
-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 after uint32_t item is an error when the -strict option is used.

		typedef struct { 
			uint32_t item 
		} MyType; 

However, with the -Wstrict option specified, this coding error is treated as a warning.

Palm OS Assembler ^TOP^

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

    These are only useful for privileged exception handlers.

  • LDM(2), LDM(3) and STM(2)

    These are unpredictable in User or System modes.

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 ^TOP^

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 and end 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 by paasm.
  • 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 ^TOP^

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 ^TOP^

-o outputFileName
Specifies the output ARM-ELF file name.
-V
paasm writes the its version numbers to stderr, and exits without performing any further actions.

Palm OS Linker ^TOP^

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 ^TOP^

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 ^TOP^

-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 using stderr.
-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 is elf.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 to stderr, 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.