changeset 402 94ae4d75524c
equal deleted inserted replaced
401:bf52ef48020c 402:94ae4d75524c
     1 Explanation of some unusual compiler flags used when building the
     2 Apache Standard C++ Library:
     4 1. CFLAGS
     8 Since we are building a Standard conforming library, compliance with
     9 Strict Standard C is assumed and expected.
    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.
    18 2. CXXFLAGS
    20 -library=no%Cstd :
    22 do *NOT*, under any circumstances, use the Solaris
    24 -library=Crun :
    26 Use the Solaris 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.
    30 -Qoption ccfe ++boolflag:sunwcch=false :
    32 do *NOT*, under any circumstances, use the default Studio 12 header
    33 files for the 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.
    37 -Qoption ccfe +d2,-xgeninl=system :
    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. 
    44 -Qoption ccfe -expand=10000 :
    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. 
    53 We use these options when building our system libraries for two reasons:
    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.
    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.
    64 Explanation:
    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.
    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. 
    84 -features=except,rtti,export,extensions,nestedaccess,tmplife,tmplrefstatic :
    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.
    92 -template=geninlinefuncs :
    94 Instantiate inline member functions for the explicitly instantiated
    95 class template which were not generated previously.
    97 -verbose=template :
    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.
   103 -xlang=c99 :
   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.
   109 -xbuiltin=%none : 
   111 No builtins whatsoever.
   113 -xinline= :
   115 (nothing after the '=').
   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).
   121 -xlibmieee :
   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).
   127 3. LDFLAGS
   129 -lumem :
   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. was spending a lot of time chasing
   134 pointers.