This chapter lists and describes the compiler language options for the command-line tools. These options control the way the compiler parses and translates source code.
The Metrowerks command line compilers translate source code (for example, C and C++) into object code. Object code generated by these compilers is processed by the Metrowerks command line linkers to produce executable objects like applications, dynamic link libraries (DLLs), code resources, and static libraries.
Each compiler has various options that you can set. If you are familiar with the CodeWarrior development environment you will see that many of these options correspond to settings in the CodeWarrior target settings dialogs.
This chapter organizes information into these topics:
In all cases, text in bracketts-the [ and ] characters-is optional.
The bracketts themselves never appear in the actual command. For
example, you could write -str[ings] pool as either -strings pool or -str pool.
Where an option has several possible permutations, the possibilities
are separated by a pipe-the | character. For example, -sym on|off|full|fullpath reflects the fact that the -sym command may be followed by one or more of four possibilities.
So you might have -sym on, -sym off, -sym full, or -sym on, fullpath.
The + (plus sign) it means that the parameter to an option must
"stick" to the option name and not be separated by a space.For
example, /D+name[=value] means that you should specify
/DVAR or /DVAR=3, but not /D VAR.
In cases where you provide a variable parameter, like a file name,
that item is in italic text. For example, -precompile filename means you must provide a file name. The explanation that accompanies
each compiler option makes it clear what you must provide.
This section describes the options for handling preprocessing and precompilation for the Embedded PowerPC tools.
Use this option to compile only, do not link.
See also -e[2].
Tells the compiler to make sure the settings in precompiled header files match the settings for the currently compiling source code.
Use this option only when creating a precompiled header. When
used, the compiler ensures that the precompiled header's settings
for sizeof(int), sizeof(double), and use of floating point math are the same as for the current
file settings.
Precompiled headers that do not rely on these settings should not use this option. Precompiled headers that depend on these settings (like the Standard ANSI C and ANSI C++ library header files that use int and double) should use this option.
See also -precompile filename
Use this option to specify #include file searching semantics. Several different values for keyword are possible:
proj means begin search in current working directory. The -cwd proj option is equal to the default behavior; the default directory
is always searched first.
source means begin search in directory of source file, this is the default.
Some compilers from a UNIX background do not use the current working
directory as the first directory to search. Instead, they search
the directory of the current source file first. You can duplicate
this behavior with -cwd source.
explicit means begin search with first (-i- or -I-)nclude path. The -cwd explicit option tells the compiler to not search in the default directory
or FooFolder, but to begin the search in the first explicitly passed directory.
Tells the compiler to define a preprocessor symbol with the name name. The default value for the defined symbol is 1. Use the optional item, value, to specify a value other than 1.
-d debug_on
#define debug_on 1
in the first line of the source code file being compiled.
-d version=2.01
#define version 2.01
at the beginning of source code file being compiled.
-d debug_on=
This option is the same as -d name [ = [ value ] ]
Sends preprocessor output to standard output without generating object code (no compliation). Use this option to verify preprocessor directives and definition expansions.
See also -c.
Specify extension for generated object files. If used with a leading period ('.'), this option appends the extension. Without the leading period character, it replaces the source file's extension.
For extension, a maximum length of 14 characters is imposed. The
default extension is .o
Use fat extensions for generated object files, of the form .<arch>.o, where <arch> is the tool architecture.
Delimit groups of user paths (before -i-) from system paths (after
-i-); system paths are searched with #include <...> as well as #include "...". Default system includes (see and -nostdinc) are searched after paths specified on the command line; implies
-cwd explicit
See also -cwd keyword.
Add path to list of #include search paths
Specify #include searching semantics, using the following keyword possibilties:
standard|std|normal is used to distinguish system paths (#include <...>) from user
paths (#include "..."). This is the default.
ignoresys[tem] |nosys[tem] is used to treat #include <...> like #include "..."
Generate Makefile from source dependencies. Do not compile, instead,
use -o filename to redirect output to a file.
Check syntax only, do not compile.
Continue working after errors are encountered in earlier files.
Do not use standard system include paths (specified by the environment
variable %MWCIncludes%
In a nutshell, treat #include <...> like #include "...".
Tells the compiler to treat #include <header> directives as if they are #include "header" directives. In other words, "system" include files (#include <header>) are searched for in the same way as normal include files (#include "header") are searched for.
Not all compilers are so rigorous that they only search the system directories when they encounter angle brackets. As a result, there is a lot of source code out there that has include directives with <> where they really should be "". In those situations you can use -nosyspath. -nosyspath forces the compiler to treat all <> as "".
The -once option tells the compiler to read include files only once, even
if they are included more than one time with the #include preprocessor directive.
The -notonce option tells the compiler to read include files each time they
are included with the #include directive.
This option is equivalent to the #pragma once directive.
Prevent header files from being processed more than once.
Specify output filename or directory for object file(s) or preprocessor output, or output filename for executable; if specifying a directory, '-o xxxx' must appear before any source files
There are a few situations where a legal pragma doesn't have a
command line option. Use -pragma to pass a pragma to the top of each source file.
The precise position of the pragma will depend on whether the
-pragma option was passed before -d, -u, -prefix, -s and -once options as these options are all "inserted"
to the top of the source file in the order the options are passed.
The command line parser does not validate the pragma. You will get feedback on whether the syntax was correct if you have -w pragmas (on by default). Multi-word pragmas must be passed within quotes. For example -pragma "export on" will insert #pragma export on at the top of your file.
Tells the compiler to precompile a header source code file and save the resulting file as filename.
mwcceppc myfile.h -precompile myprecomp
will precompile the header file myfile.h and save the precompiled file as myprecomp.
Note that the file to be precompiled cannot contain any statements that generate data or object code.
If you use this option and you have code like this
#pragma precompile_target
in your source code you, will receive a warning. The warning tells you that the compiler is ignoring the pragma.
Tells the compiler to include the file filename at the beginning of the source code files specified in the command line.
Use this option to include often-used header files or precompiled header files.
Preprocess only, do not compile.
Search #include paths for source files specified on the command line; may specify
object code and libraries as well; this option provides the IDE's
'access paths' functionality
This section contains information about command-line options for controlling language attributes of code compilation.
Keywords include off/on/relaxed/strict.
The -ansi options control ANSI C/C++ conformance.
The default is -ansi off. This allows you to use platform-specific keywords, does not
require ANSI C/C++ conformance, and sets the -enum option to min.
Use this option when you write platform-specific code.
"On" and "relaxed" are synonymous. For example, with this option,
keywords for Mac OS programming-the far, pascal, and asm keywords-are not accepted. Only ANSI keywords are accepted. This option also turns
on strict ANSI C/C++ conformance. This option works differently
depending on whether your source code files contain C or C++ code.
For C source code this option disallows:
For C++ source code, this option disallows: empty array struct members, '#' tokens in a macro definitions that are not followed by a parameter,
identifier token after #endif.
The -ansi strict option adds one more limitation to those specified for -ansi on. Enumerated types are always of type int. This additional restriction is the same as the -enum int option.
This option may also be manipulated with the #pragma ANSI_strict directive.
If on, this tells the compiler to recognize Apple's extended keywords:
far, asm, and pascal. These keywords are not defined in the ANSI
C and ANSI C++ standards. .
If off, this tells the compiler to signal an error if it reads Apple's
extended keywords: far, asm, and pascal. These keywords are not
defined in the ANSI C and ANSI C++ standards.
If on, this tells the compiler to enforce some C++ language specifications
described in the Annotated C++ Reference Manual, Ellis and Stroustrup (ARM) rather than enforcing some conflicting
ANSI C++ specifications. This disables certain ANSI C++ features
that conflict with the ARM C++ specification. This is mainly used
for compatibility testing.
Off tells the compiler not to enforce some C++ language specifications described in the Annotated C++ Reference Manual, Ellis and Stroustrup (ARM) that conflict with the ANSI C++ specifications.
This option is equivalent to the #pragma ARM_conform directive.
The compilers allow for the use of the new C++ type bool in source code. The C++ language standard evolved to allow the use of this new type. An example of how to use this new type is shown here:
bool foobar( short NewVal )
{
bool myVar = true;
if ( NewVal != 0 ) myVar = false;
return myVar;
}
This option is equivalent to the #pragma bool directive.
This options turns true C++ exception handling on and off. It
is passed to the linker. When disabled, locals are destroyed with
direct destructor call. The default is on.
Treat unspecified characters as signed or unsigned. The default is signed.
This option may also be manipulated with the #pragma unsigned char directive.
This option instructs the compiler whether to compile code as C or C++ code.
If this option is not invoked in any way, source files ending
with the extension .c are compiled as C language files. Source
files ending with .cp, .cpp, .cc, or .c++ are compiled as C++ language files.
The -dialect c option behaves the same way. It does not force C++ files to be compiled by the C compiler (an effort very likely to fail in any event).
If -dialect cplus is invoked, files ending with .c are compiled as C++ language files.
If -dialect krc is invoked, it is substituted with -dialect c and also -proto ignoreoldstyle
CodeWarrior has minimal support for Kernighan and Ritchie (K&R) C.
If -dialect ecplusplus or -dialect ec++ is invoked, the compiler will generate warnings for use of C++
features outside Embedded C++ subset (this implies -dialect cplus).
If -dialect objective-c or -dialect objc is invoked, the compiler will allow Objective C extensions.
This option may also be manipulated with the #pragma cplusplus directive.
Specify word size for enumeration types.
Specify inline options for compilation.
Control Microsoft VC++ extensions.
Enable multi-byte character encodings for source text, comments, and strings.
auto/strict/ignoreoldstyle ar ethe valid keywords for this option.
Tell the compiler whether to require prototypes. The default value
is auto which does not require prototypes. The strict option is the same as -r[equireprotos]. The -proto ignoreoldstyle option tells the compiler to ignore
old-style C function prototyping.
Relaxes the rules for char pointers (char, unsigned char, and Ptr). This option is especially useful if you are working with code
written before the ANSI C Standard. This old code used these types
interchangeably.
This option does not work correctly when used with C++ source code because of the strong type checking enforced by C++.
Tells the compiler to require ANSI-style function prototypes when compiling C and C++ source code. Default is -proto auto, which means that prototypes are not required. -warnings all turns on this option.
See also -w[arnings] option[,option...].
This option is equivalent to the #pragma require_prototypes directive.
Enables run-time type information for C++ code.
This option may be manipulated with the #pragma RTTI directive.
Enable Apple's Direct-to-SOM implementation.
Enables automatic SOM environment and new allocation checking; implies -som.
Specify string constant options, using the following keywords:
This option enforces a strict interpretation of the ANSI standard. In other words, language-related restrictions are put in place as detailed in -ansi keyword.
Trigraph sequences are special codes that signify a single character. Trigraph sequences are meant to represent characters that are not on some non-English computer keyboards.
An ANSI trigraph sequence is two question mark characters followed by a third character. For example, use ??\ to represent a backslash, \.
On tells the compiler to recognize ANSI trigraph sequences.
Off tells the compiler not to recognize ANSI trigraph sequences.
The default is -trigraphs off.
This option may be manipulated with the #pragma trigraphs directive.
Enable wchar_t as a built-in C++ type.The default is on.
This section contains information about command-line options for controlling error and warning message generation.
Tailors compatibility warning options using the following keywords:
Tailors compatibility warning options using the following keywords:
Specify structure/array alignment options:
Move all uninitialized data into a common section, thedefault is off.
Specify floating-point code generation options:
-fp hard and -fp_contract on | off
|
See -maf on | off.
Generate fused multiply-add instructions, teh default is off. This is the same as -fp_contract on | off.
-O is the same as -O2. See also -opt keyword[,...]
-opt off|on|all|space|speed|level=...
are for backwards compatibility; other optimization options may
be superceded by the use of -opt level=xxx.
To control optimization, you may combine options as in -O4,p
default is 0 |
|
|
|
Pool like data objects; default is on.
Specify processor for scheduling and inline assembler:
See -readonlystrings.
Make string constants read-only. This is the same as -rostr.
Generate debugging information, same as -sym full.
This section includes information on the Embedded PowerPC linker command-line options.
If a linker command file is passed, -codeaddr, -dataaddr, -sdataaddr, and -sdata2addr are ignored.
If a linker command file is not passed, the linker will start
the codesections at 0x00010000 and follow contiguously with the
large const sections, the large data sections, the small data section, the small const section and then the bss sections.If you pass one or more of the following options: -codeaddr, -dataaddr, -sdataaddr, or -sdata2addr, the addresses you pass affect thestarting addresses of the sections
referred to.
All addresses are valid, including 0x0.
This is synonymous with -xma.
Set address for code. The default is 65536.
Set address for data; default is to have large data sections follow the code and large const sections.
Perform final work on a partial link; implies-xm p[artial[link]].
Generate debugging information, the same as -sym full.
See also-sym keyword[,...].
Set address for the heap, default is computed by starting with the stack address and subtracting the heapsize and stacksize.
Set size of data heap in kilobytes, the defaultis 384.
Use the linker command file in filename for code and data addresses; -codeaddr, -dataaddr, -sdataaddr, or -sdata2addr are ignored if -lcf is present. filename must end in .lcf.
Generate a static library; same as -xm l[ibrary]
Add library search paths. The default is to search the current working directory and then system directories. The search paths have global scope over the command line and are searched in the order given.
Search library paths for library in form lib<file>.<ext> where <ext> is a typical library extension. This is added before system libraries
(see '-nodefaults').
Set main entry point for application or sharedlibrary. For symbol, maximum length is 63 characters. The default entry pointis __start.
Generate link map file. The default name is generated by adding
.MAP to <outfile>. If filename parameter specified, then output to filename.
Include list of unused symbols in map file.
absolute - absolute code and data addressing. This is the default.
Specify warning options, using a keyword specified here.
Same as -nomain.
Do not use system library files or system paths. By default the
environment variable %MWLibraries% contains system paths to search and the environment variable
%MWLibraryFiles% contains a list of system libraries to link; both lists contain
items separated by ';'
Specifies the name of the output file as filename.
Emit debugging SYM file information to filename (recommended extension .xSYM). The default name is <outfile>.?SYM.
Partial link; same as -xm p[artial[link]].
Set address for ROM image;default is not to generate a ROMimage.
Set address for RAM buffer used by ROM images. The default is to not generate a ROM image. This option is ignored if -romaddr addr is absent.
Set address for small data; default is to have sdata/.sbss sections follow the large data sections.
Set address for small constant data; default is to have .sdata2/.sbss2 sections follow the .sbss section.
The stack; default is 0x3dfff0.
Set maximum size in bytes for mutable data objects before being spilled from small data section into data section. The default is 8.
Set maximum size in bytes for constant data objects before being spilled from constant section into data section. The default is 8.
Set end-of-line separator for S-record file. Thisimplies -[no]srec is enabled.
Specify length of S-records. This implies -[no]srec is enabled. For length the valid is range 8 - 255, the default is 254.
Set size of stack in kilobytes, the default for number is 64.
Perform dead-stripping on a partial link, this implies
-xm p[artial[link]].
Specify debugging options, using a keyword shown here:
Implies -map [filename].
Links object code into a double-clickable application. This is the default linker setting.
See also -application.
Synonymous with -xm a[pplication].
Tells the linker to generate an object code library.
Same as -xm l[ibrary].
Partially links the output file. See also -partial.
Generate debugging information, same as -sym full.
Disassembly translates object code into assembly language. You can recover the text assembly language code when performing disassembly on a binary object file.
For DWARF information, relocate addends in .rela.text and .rela.debug
Show exception tables; default is on.
Set address for code; default is 65536.
Set address for data; default is to have large data sections follow the code and large const sections.
Use the linker command filename for all code and data addresses. Note that -codeaddr, -dataaddr, -sdataaddr, -sdata2addr are ignored if -lcf is present;
The file specified by filename mustend in .lcf
Set address for the heap; default is computed by starting with the stack address and subtracting the heapsize and stacksize.
Set main entry point for application or shared library; for symbol, maximum length 63 chars; default is __start
Include list of unused symbols in map file.
Same as -nomain.
Set address for RAM buffer used by ROM images. The default is to not generate a ROM image.
This option is ignored if -romaddr is absent.
Set address for ROM image;default is not to generate a ROM image.
Set address for small data; default is to have sdata/.sbss sections follow the large data sections.
Set address for small constant data; default is to have .sdata2/.sbss2 sections follow the .sbss section.
Set end-of-line separator for S-record file; implies -srec.
Specify length of S-records; implies -srec for length, range 8 - 255; default is 254.
If a linker command file is passed, -codeaddr, -dataaddr,
-sdataaddr, and -sdata2addr are ignored.
If a linker command file is not passed, the linker will start
the codesections at 0x00010000 and follow contiguously with the
large const sections, the large data sections, the small data
section, the small const section and then the bss sections.If
you pass one or more of -codeaddr, -dataaddr, -sdataaddr and -sdata2addr, the addresses you pass affect the starting addresses of the
sections referred to.
All addresses are valid, including 0x0.
The stack address, the default is 0x3dfff0.
Implies use of the -map option.
Generate code and link for a big-endian target. This is the default.
Generate code and link for a little-endian target.
absolute - absolute code and data addressing, this is the default.
Set maximum size in bytes for mutable data objects before being spilled from small data section into data section. The default is 8.
Set maximum size in bytes for constant data objects before being spilled from constant section into data section. The default is 8.
Generate debugging information, same as -sym full.