Explanation of some unusual compiler flags used when building the

Apache Standard C++ Library:

1. CFLAGS

All the -D_STRICT_STDC -D_STRICT_STDC__ -D_STDC_C99 -D_ISOC99_SOURCE:

Since we are building a Standard conforming library, compliance with

Strict Standard C is assumed and expected.

However, the Apache Standard C++ Library provides some extensions to

the C++ Standard, by allowing some C99 functions. Visibility of C99

is enabled by passing -D_XPG6 -D_XOPEN_SOURCE=600 in CFLAGS. However,

Standard C++ disallows _XPG6 and _XOPEN_SOURCE=600, and only allows

_XPG5 and _XOPEN_SOURCE=500, so for CXXFLAGS we raise _XPG5 and

_XOPEN_SOURCE=500.

2. CXXFLAGS

-library=no%Cstd :

do *NOT*, under any circumstances, use the Solaris libCstd.so.1.

-library=Crun :

Use the Solaris libCrun.so.1. This library is very important: it provides

the symbols for the Standard C++ exception classes, and it also provides

the Solaris C++ run-time support.

-Qoption ccfe ++boolflag:sunwcch=false :

do *NOT*, under any circumstances, use the default Studio 12 header

files for the libCstd.so.1 Solaris C++ Library. This flag is very

important. We must build the Apache C++ Library using its own header

files, and we must ignore any other C++ header files.

-Qoption ccfe +d2,-xgeninl=system :

The +d2,-xgeninl=system options causes functions that are generated

inline also to be generated also as closed functions in the object file.

By default, a function that is always inlined is not actually generated

unless its address is needed. 

-Qoption ccfe -expand=10000 :

The C++ front end decides whether to inline a function in part depending

on a complexity measure. The -expand=N option, where N is a decimal number,

sets the complexity limit. Functions of greater complexity are not inlined

by the front end. The default limit is in the range 100-500 depending on

the optimization level. Setting the limit to 10,000 effectively allows

inlining of all but the largest functions. 

We use these options when building our system libraries for two reasons:

2.1. We want to allow maximum inlining of functions to improve runtime

performance. The size of a library (especially a shared library) is not

usually important, so we trade size for speed.

2.2. A library function defined as inline in a standard header will be

inlined in user code, unless inlining is disabled or the function address

is taken. If library functions get defined in user code, the program can

wind up with circular dependencies among the various program parts.

Explanation:

Suppose library function F is defined as inline, but the library uses the

address of F. Function F will be generated as a closed function in the

library. If user code also needs the address of F, it will be generated in

user code. The linker picks the first definition of F it sees, which will

be in user code in this case, and discards any others. The library then

calls F in user code instead of the one inside the library. If F is used

as part of initializing the library, then the library has an initialization

dependency on the main program. The main program always has an

initialization dependency on the library. You can wind up with strange

program failures, since you cannot satisfy the circular dependency.

To prevent this possibility, we generate F unconditionally as a closed

function in the library. When a user function needs the address of F,

the compiler first checks to see whether F is defined in the library.

If so, it just generates a reference to F instead of generating a definition

of F. There is then only one copy of F in the entire program, and it is in

the library. 

-features=except,rtti,export,extensions,nestedaccess,tmplife,tmplrefstatic :

We want to enable specific and Standard-mandated C++ Compiler features,

and we want to be explicit about them, just in case the default C++

Compiler default features change in the future. This way, we are guaranteed

that the Library builds in a consistent way, independent of any future

updates to the C++ Compiler.

-template=geninlinefuncs :

Instantiate inline member functions for the explicitly instantiated

class template which were not generated previously.

-verbose=template :

Be verbose about template instantiations. This is useful for tracking

what the compiler is doing when instantiating templates, and for debugging,

in case we end up with undefined class template symbols.

-xlang=c99 :

Assume non-standard compatibility with C99. Allows C programming language

behavior for objects which were compiled either with the c99 driver, or

with the cc -xc99=%all driver, and are being linked with the Library.

-xbuiltin=%none : 

No builtins whatsoever.

-xinline= :

(nothing after the '=').

We've already told the compiler frontend (with the -Qoption ccfe flags)

how to inline, and what the inlining limits are. Therefore, do not make any

other heuristic decisions about inlining (i.e. assume nothing is inlined).

-xlibmieee :

Cause strict conformance to the IEEE 754 Standard for math routines in

exceptional cases. The C++ Standard implicitly mandates IEEE 754

(cf. see libstdcxx4.3lib man page).

3. LDFLAGS

-lumem :

The PAE Group and myself have tested the performance of the Apache Standard

C++ Library, and determined that linking with libumem provides the best

malloc(3C) performance. libmtmalloc.so.1 was spending a lot of time chasing

pointers.