1 Explanation of some unusual compiler flags used when building the

     2 Apache Standard C++ Library:

     3 

     4 1. CFLAGS

     5 

     6 All the -D_STRICT_STDC -D_STRICT_STDC__ -D_STDC_C99 -D_ISOC99_SOURCE:

     7 

     8 Since we are building a Standard conforming library, compliance with

     9 Strict Standard C is assumed and expected.

    10 

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

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

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

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

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

    16 _XOPEN_SOURCE=500.

    17 

    18 2. CXXFLAGS

    19 

    20 -library=no%Cstd :

    21 

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

    23 

    24 -library=Crun :

    25 

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

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

    28 the Solaris C++ run-time support.

    29 

    30 -Qoption ccfe ++boolflag:sunwcch=false :

    31 

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

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

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

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

    36 

    37 -Qoption ccfe +d2,-xgeninl=system :

    38 

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

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

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

    42 unless its address is needed. 

    43 

    44 -Qoption ccfe -expand=10000 :

    45 

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

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

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

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

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

    51 inlining of all but the largest functions. 

    52 

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

    54 

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

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

    57 usually important, so we trade size for speed.

    58 

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

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

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

    62 wind up with circular dependencies among the various program parts.

    63 

    64 Explanation:

    65 

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

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

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

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

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

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

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

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

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

    75 program failures, since you cannot satisfy the circular dependency.

    76 

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

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

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

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

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

    82 the library. 

    83 

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

    85 

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

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

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

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

    90 updates to the C++ Compiler.

    91 

    92 -template=geninlinefuncs :

    93 

    94 Instantiate inline member functions for the explicitly instantiated

    95 class template which were not generated previously.

    96 

    97 -verbose=template :

    98 

    99 Be verbose about template instantiations. This is useful for tracking

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

   101 in case we end up with undefined class template symbols.

   102 

   103 -xlang=c99 :

   104 

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

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

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

   108 

   109 -xbuiltin=%none : 

   110 

   111 No builtins whatsoever.

   112 

   113 -xinline= :

   114 

   115 (nothing after the '=').

   116 

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

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

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

   120 

   121 -xlibmieee :

   122 

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

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

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

   126 

   127 3. LDFLAGS

   128 

   129 -lumem :

   130 

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

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

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

   134 pointers.

   135