TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Invocation

The Apex C and Apex C++ compilers are invoked using the Apex code, link, build, and run commands. These are available through the GUI interface or from the command line. The command-line descriptions of these commands can be found in the Command Reference.

Invocation and execution of the Apex C/C++ compiler is controlled in several ways. Some options are automatically set by the build management process. This includes the options that correspond to the DEBUGGING and OPTIMIZATION_LEVEL switches. Build management is discussed in detail in C/C++ Build Management. Other options are controlled by individual switches, where the value of the switch is a list of options to use. The following switches are used in the following contexts:

C_PRE_OPTIONS and C_OPTIONS: compiling C source files.

CPP_PRE_OPTIONS and CPP_OPTIONS: compiling C++ source files.

C_LINK_PRE_OPTIONS and C_LINK_OPTIONS: linking a C main program.

CPP_LINK_PRE_OPTIONS and CPP_LINK_OPTIONS: linking a C++ main program.

In all the above cases, the switches of the form *_PRE_* precede all the other options, including the options automatically supplied by build management. The switches without *_PRE_* as part of their name go at the end, after all the other options. The meaning of most options do not depend on their location, so they can be put in either switch. But a few options, such as -Idirectory, -lname, -Ldirectory, and -Wx,arg, are order-dependent and cannot be freely moved around.


Invocation Options

The following is a list of the options that can be used with these switches. Unless otherwise specified, the option is useful for both C and C++, and is useful only when compiling. Options that are specific to one language or the other, or that are useful when linking, are explicitly noted.

In addition to the options listed here, the compiler may also support options that are recognized by the system C and C++ compilers or the system linker. These options should behave the same as they do with the host system tools. They vary from system to system and are not documented here.

-Atext 

Define a preprocessor assertion, as if an #assert directive appeared at the beginning of the source file. See the description of #assert in Extensions

-bitfield_packing

Causes bitfield packing to be turned on, as if

-C

Causes source code comments to be included in the preprocessed results generated using the -E or -P option.

-Cppcmt

Allows c++ style comments to be accepted in c source code.

-Dname
-Dname=value 

name is defined in the preprocessor as if it appeared in a #define directive at the beginning of the file. If no value is specified, a value of 1 is used.

+d 

Same as -noinline. (C++ only)

-dynamic

Have the system linker link with shared libraries whenever possible. This is the default on most systems. See also -static. (Linking only)

-E 

Preprocess the source files and send the result to the standard output. Nothing is compiled and no other actions are performed by the compiler.

+e0
+e1 

Control virtual table generation. +e0 suppresses the generation of all virtual tables and creates external references to those that are needed. +e1 causes generation of virtual tables for all classes that have at least one virtual function. These options are present for compatibility with other compilers, and their use is very strongly discouraged. (C++ only)

-ef 

Trap floating point arithmetic overflow. The default is to ignore overflow.

-ei 

Trap signed integer arithmetic overflow. The default is to ignore overflow. Unsigned integer arithmetic is defined to be modulo arithmetic and can never overflow.

-fastpath

Enable fast-path recompilation, which causes the compiler to check whether or not a source file really needs to be compiled. If the compiler decides that compiling would produce an identical object file, the compilation is skipped. This option is the default, and therefore has no effect.

-fastpathverbose

Enable fast-path recompilation in verbose mode, in which the compiler prints why a file needs to be recompiled.

-fpfold

Cause the compiler and optimizer to do folding of floating-point constants. For example, with this option, the compiler would compile

as if it were

-FWname

Treat the named warning as if it were an error. If the warning is triggered, it is printed as "Fatal warning" rather than "Warning," and causes the compilation to fail. The name of the warning is printed as part of the warning message. See also the options -Wname and +Wname.

-g 

In previous versions of the compiler, this option was used to turn on debugging. But debugging information is now generated by default, so this option has no effect. See also the option -nosienna.

-H

Print to standard output the pathname of each file included while compiling.

-Idirectory 

Add directory to the list of directories searched for files specified in #include directives. Directories listed by -I options are searched in the order listed and before the standard include directories.

-implicitarch

With architectural control checking enabled (which is the default), this option relaxes the rules used when performing the checks. If file A includes file B, then the view VA which contains A no longer has to directly import the view VB which contains B. VB only has to be in the import closure of VA. When the option -noarch is used, -implicitarch has no effect and is silently ignored.

-inline

Normally, the inlining of large functions is suppressed, even if they were defined inline. This option causes functions to be inlined regardless of their size. (C++ only)

-K 

Compile C source files in compatibility, or traditional, mode. The compiler uses a slightly different language definition that imitates the language that most C compilers accepted just before the ANSI standard was released. Most ANSI constructs are still accepted, but traditional semantics are used when there is a conflict. See Compatibility Mode for more details. (C only)

-Ldirectory 

Add directory to the list of directories that the linker searches when looking for libraries. Directories listed by -L options are searched in the order listed and before the standard directories. (Linking only)

-lname 

Add the file libname.so or libname.a to the list of libraries searched by the linker. (Linking only)

-mt

Enable multi-thread support. This option must be used if a program uses threads. It causes the preprocessor macros _REENTRANT and _THREAD_SAFE to be defined, and causes thread-safe versions of the standard libraries and the thread library itself to be linked in. This option is currently supported only on Solaris and Digital UNIX systems. (This option must be used both when compiling and when linking.)

-newlib

Use the new version of the C++ library, rather than the default C++ library. In each C++ library, the -newlib switch must be established for both compiling and linking. This is done by setting the following switches to -newlib:

CPP_OPTIONS: -newlib
CPP_LINK_OPTIONS: -newlib
LINK_CONTRIBUTION_OPTIONS: -newlib

If using this switch on the command line, you must use single quotes and a liading space before the -newlib:

(C++ only. This option must be used both when compiling and when linking.)

-noaltkeywords

Turns off the keywords and, and_eq, bitand, bitor, compl, not, not_eq, or, or_eq, xor, and xor_eq. They are treated as regular identifiers instead. See Options that affect the language. (C++ only.)

-noarch

Turn off architectural control checks. Without this option, the compiler checks every #include directive for validity. File A is allowed to include file B only if A and B are in the same view or if the view containing A imports the view containing B. See also -implicitarch.

-nobool

Disable the keywords bool, true, and false, which become ordinary identifiers. See Options that affect the language. (C++ only)

-nocode

Suppress code generation. The compiler will do semantic checking of the code, including printing any warnings or error messages, along with any side effects such as generating debugging information or include file dependencies, but no object file will be created.

-nodef 

Turn off any preprocessor symbols normally defined by the compiler (such as sparc and unix). Symbols required by the language definition (such as __LINE__ and __DATE__) are still defined.

-nodemangle

Suppress the filtering of messages from the linker. Normally, the compiler demangles any mangled names that are part of linker messages, so that the messages are much easier to understand. This option turns that feature off, leaving the symbol names in their mangled form. (C++ only, linking only)

-noex 

Turn off all support for exception handling. Use of the keywords throw, try, or catch results in a warning. See Options that affect the language. (C++ only. This option must be used both when compiling and when linking.)

-nofastpath

Disable fast-path recompilation. The compiler will recompile the source file, even if it could have determined that recompilation was unnecessary. See also the option -fastpath.

-noinc 

Suppress the searching of the standard include directories for files specified in #include directives. The compiler only searches directories specified by -I options.

-noinline

Do not expand inline functions. Instead, inline functions that are called are treated like static functions. No code is generated for inline functions that are never called. (C++ only)

-nolib 

Do not link in any of the standard system libraries. Only libraries specified on the command line (archive files or -l options) are linked in. (Linking only)

-norose

Turn off the generation of special Rose annotations in the debugging information. This option has no effect on the generated code, but if it is used, it may not be possible to reverse engineer Rose diagrams from the source code. (C++ only)

-nortti

Turn off the generation of RTTI data. See Options that affect the language. (C++ only)

-nosienna

Turn off the generation of Sienna intermediate representation. Sienna is required to symbolically debug, use the C/C++ Code Rule Checker, and to carry out faster reverse engineering with Rose. Use of this option yields faster compile times at the expense of these capabilities (debugging, code rule checking, and reverse engineering). The default is to generate the Sienna intermediate representation.

-notdbld 

Do not run the template prelinker before linking. As a result, template instantiations will not get linked in automatically. (C++ only, linking only)

-ns_std

Put most of the C++ standard library in the namespace std, as required by the C++ standard, rather than at global scope. For example, with this option, including <vector> would define the template class std::vector rather than ::vector. The I/O streams part of the library is still at global scope, even with this option. When -newlib is also used, this option has no effect, since the library is already in the namespace std. See also Old C++ Library.

-O[0-9] 

Specify the optimization level. -O0 turns off all optimization. -O, which is equivalent to -O9, is maximum optimization. The default is -O4. Levels -O1 through -O4 perform minimal optimizations that do not involve instruction scheduling. Levels -O5 through -O9 perform progressively more aggressive optimizations. Debugging is still possible (and is turned on by default) with optimizations turned on, but may be problematic at higher levels of optimization. For example, with optimization on, you may receive a message that a variable is no longer active or is not yet active. -old_for 

Variable declared in the initialization expression of a for statement are in the scope that contains the for statement, rather than in the scope of the for statement itself. See Options that affect the language. (C++ only.)

-oldlib

Use the default C++ library. See C++ standard library. This option currently has no effect, but in some future release of the compiler it may be required to get the C++ library that is now the default. (C++ only, linking only)

-P 

Preprocess the source files and put the results in a file with the file's extension changed to .i. Nothing is compiled, and the compiler performs no other actions.

+p 

Do not allow anachronistic constructs. The compiler instead treats them as errors. In a future release of this compiler, some anachronistic constructs may be treated as errors by default, so use of this option is encouraged. See Options that affect the language. (C++ only)

-p
-pg 

Generate profiling information. -p generates information that can be used with the program prof. -pg generates information that can be used with the program gprof. These options must be present both when compiling and when linking. They may not be fully supported on all targets.

-partial

Perform a partial link. The given object files, and any template instantiations that they use, are linked together into a single relocatable object file rather than an executable file. Same as -r option. (Linking only)

-pic

Generate position-independent code. This option is needed when compiling if the resulting objects will later be added to a shared library. See also -xgot.

-pta
-ptn 

Instantiate an entire template class rather than just those member functions which are actually used. These options are provided for compatibility only. Their use is not encouraged. (C++ only)

-ptipath 

Add path to the template source path. The template source path specifies a list of directories to search for template source files. This option is provided for compatibility only. The -I options should be used instead. (C++ only)

-pto
-pts 

One-file mode for templates. Causes generated templates to be instantiated in the compilation unit rather than in the template database. This forces generated templates to be static. These options are provided for compatibility only. Their use is not encouraged. (C++ only)

-ptv 

Display templates that are being instantiated and other information about the template database. (C++ only)

-r

Same as -partial. (Linking only)

-shortenum 

Causes enumeration types in C++ to use the smallest integral type that will hold all the enumeration values. See Options that affect the language. (C++ only)

-signed

Have the type char be a signed type with the same range as the type signed char. This is the default on Solaris, HP-UX, Digital Unix, and all non-PowerPC embedded systems. See also the option -unsigned, and Options that affect the language.

-static

Have the linker use only static archive libraries when linking. The resulting executable should not refer to any shared libraries. See also -dynamic. (Linking only)

-Uname 

Cause the preprocessor symbol name to be undefined, as if by a #undef directive at the beginning of the source file. All -U options are processed after all -D options. This option is usually used to get rid of symbols that are normally predefined by the preprocessor (such as sparc and unix). Preprocessor symbols that are defined by the language (such as __LINE__ and __DATE__) cannot be undefined.

-ue 

Change the format of compiler messages to be similar to most UNIX command-line compilers. The messages contain less information, but this option may be necessary when messages must be parsed by some other tool that expects them in a certain format.

-unsigned

Have the type char be an unsigned type with the same range as the type unsigned char. This is the default on AIX, IRIX, and all PowerPC embedded systems. See also the option -signed, and Options that affect the language.

-v 

Verbose mode. Print out the command line for each of the passes of the compiler.

-W[acflopt],arg
-W[acflopt],arg,arg[...]

Pass arg to a particular pass of the compiler, as indicated by the character preceding the comma.

a
assembler
c
code generator
f
front end
l
linker
o
optimizer
p
post-linker
t
template manager

The argument arg is passed through directly without being interpreted by the compiler. These options are useful when an option used by one of the passes of the compiler conflicts with an option understood by the compiler itself. For example, suppose that there is a system linker which accepts -D as an option. Because the compiler already has a meaning for -D, the option -Wl,-D needs to be used instead. Multiple arguments may be separated by commas. These arguments will be kept together when passed to desired program. For example, the option -Wl,-z,text will cause -z and text to be passed to the linker as successive options. If a comma needs to part of an option rather than a separator between options, @, (an at-sign followed by a comma) must be used.

-Wname 

Turn off the named warning. The name of each warning is normally printed as part of the message.

+Wname 

Turn on the named warning. This is useful if all warnings have been turned off with the -w option, but one or several particular warnings should still be printed.

-w 

Suppress the printing of all warnings.

-wabort 

Treat warnings and anachronism messages as fatal errors. The messages still appear as warnings, but the return code from the compiler will be non-zero if there were any warnings, causing the Apex command that invoked the compiler to fail, as if the compiler had detected an error.

-wi 

This option is no longer supported and is silently ignored.

-xgot

This option is only meaningful when used in conjunction with -pic. It may be necessary when compiling large programs with -pic to prevent overflow of the global offset table. It is not the default because it results in slower code.

There are some compiler options that are normally only used by Apex. These may be encountered or used when editing build keys or calling the compiler directly from the command line, but they generally should not be used or be part of any Apex switches.

-c 

Don't link the object files into an executable.

-cfg config_file

Use config_file for the compiler's configuration file, rather than the default compiler_home/Spire.cfg where compiler_home is the value of the CPP_COMPILER_HOME switch.

-dryrun

No execution mode. Print commands, but do not execute them.

-flags 

Print a brief explanation of all available options.

-gls

Generate a link script. Rather than calling the linker, the compiler sends to standard output the command that it would have used to call the linker.

-help

Same as -flags.

-M

Same as -MDonly, except dependencies are sent to the standard output rather than put in a .dep file.

-MD
-MDdir
directory_name
-MDonly

Cause dependency information, in a form suitable to be used in makefiles, to be put in a file with the extension .dep. The -MDonly option generates dependency information without compiling the source files. The -MDdir option is used to specify the directory (indicated by directory_name) in which the .dep file should be placed. If this option is not used, the .dep file is placed in the current working directory.

-MDdummytargets

Create a dummy target for each header file dependency. This option has no effect unless one of -M, -MD, or -MDonly is specified. For example, if foo.c includes bar.h, then compiling with -MD causes the line

to appear in the generated .dep file. With -MDdummytargets, the .dep file will contain

Use of this option allows make to still work if bar.h is removed and foo.c is changed to not include it. make will think bar.h is a dummy target that is always out of date and will rebuild foo.o. Without the dummy target, make would complain that it did not know how to make bar.h and would not rebuild foo.o.

Compiling with the -O0 option can alleviate some of these problems.

-o file 

Use file for the output of the compiler, whether it is an executable (the default), an object file (-c option), a shared library (-shared option), a partially linked object (-r and -partial options), or an archive library (-xar option).

-options_file filename 

Read additional options from file filename. Entries in the options file should be separated by white space (spaces, tabs, or newlines). There is no limit to the number of options in an options file. Additional -options_file flags can be embedded within a file being included. Recursive inclusions are not detected and will cause the compiler to fail.

-ptgetobj

Print to standard output the names of all the template object files used by the object files listed on the command line. Nothing is linked, and no output files are produced.

-ptrdirectory 

Specify the location of the template database, Templates. directory is the directory which contains Templates. You can use -ptr more than once on the command line to handle multiple databases. The first -ptr entry specifies your working template database. If you omit this option, a database, Templates, will be created in your current working directory if necessary. (C++ only)

-ptupdate

Bring the template database up to date, recompiling any out-of-date template instantiations. No other actions are performed.

-sh 
-shl

Print the executable program used for each of the passes of the compiler. -shl is more verbose than -sh. Nothing is compiled or linked when either of these options is used.

-shared

Build a shared library. The given object files, and any template instantiations that they use, are linked together into a single shared library rather than an executable file. All object files added to the shared library must have been compiled with -pic. If they were not, the linker will fail with an error message. (Linking only)

-xar 

Build an archive. The given object files, along with any template instantiations that they use, are put into an archive library rather than being linked into an executable. The -o option, used to specify the name of the archive, is required when -xar is used. (Linking only)


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2002, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS