The Palm OS compiler chain consists of the following tools:

• "Palm OS Protein C/C++ Compiler"
• "Palm OS Assembler"
• "Palm OS Linker"

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.

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.

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.

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.

-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, 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.

-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.

-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.

-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 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.

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.

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.