readme.sizeReduction

   1 TITLE: REDUCING PEGASUS STATIC FOOTPRINT
   2
   3 Author: M. Brasher, Karl Schopmeyer
   4
   5 Date: 3 Aug 2006
   6
   7 This readme describes how to build Pegasus for the smallest possible footprint.
   8 It defines a number of changes that you can make to reduce both  the Pegasus
   9 code size and class repository size.
  10
  11 COMPILER ISSUES
  12
  13     1.  When using GCC, always use 4.0 or later. There are two advantages:
  14
  15         (*) GCC 4 does a better job of optimizing C++ for size.
  16
  17         (*) Pegasus limits symbol visisibility from shared libraries using
  18             special features of GCC 4.0 and later.
  19
  20     2.  If you can't use at least GCC 4.0, at least try to use GCC 3.0 or
  21         better. GCC 3.0 introduced the -fno-enforce-eh-specs option, which
  22         reduces the object code size of Pegasus by 20%.
  23
  24     3.  On 64-bit Intel systems, build 32-bit to save around 30% of the
  25         footprint (64-bit code is large since the operands are twice as
  26         long). This technique of course will produces slower code.
  27
  28 REPOSITORY SIZE REDUCTION
  29
  30     1.  Configure Pegasus to use a binary CIM repository. This is done by
  31         setting the PEGASUS_REPOSITORY_MODE environment variable to BIN.
  32         This technique will improve the performance of the repository. There is
  33         a readme that describes this feature.
  34
  35     2.  Configure Pegasus to compress the CIM repository. This is done by
  36         setting the PEGASUS_ENABLE_COMPRESSED_REPOSITORY environment variable
  37         to true. This technique will slightly degrade the performance of the
  38         repository but reduce size by better than 50%. There is a readme
  39         that describes this feature and how to set it up.
  40
  41 COMPILE OPTIONS
  42
  43     1.  Be sure that the PEGASUS_DEBUG environment variable is not defined
  44         when you build Pegasus. Otherwise, you will end up with a much
  45         larger image.
  46     2.  Define PEGASUS_NO_FILE_LINE_TRACE=true to eliminate __FILE__ and
  47         __LINE__ macros from tracer expansion. This reduces the overall size
  48         by about 50k by not including the line and file information into
  49         the code.  However, it means the resulting traces do not have this
  50         information in the trace output.
  51
  52      3. Turn off the compile of the trace completely.  The flag PEGASUS_DISABLE_TRACE
  53         will force the compile without any of the trace code.  This can save at least
  54         100k but means that there is no means to trace including the XMLIO traces.
  55
  56      4. Define the PEGASUS_OPTIMIZE_FOR_SIZE environment variable
  57         that causes Pegasus to build with -Os rather than -O2.
  58
  59      5. Disable use of OOP.  This eliminates the extra use of memory that occurs because
  60         of the extra process created to load providers.
  61
  62 STATIC BUILD VS. DYNAMIC BUILD
  63
  64 Originally Pegasus was built with a series of dynamic libraries, one for each
  65 source directory (common, WQL, CQL, etc.).  While this has proven a good tool
  66 for developers the result is a significantly larger footprint for a number of
  67 reasons. See PEP 253 for more information.  Today you have the choice of building
  68 the dynamic version or a static build which results in a much smaller footprint.
  69 Generally the static build can save up to 40% in code footprint.
  70
  71 The same basic build mechanism is used for both static and dynamic builds
  72 with the choice being controlled by the use of two variables:
  73
  74         PEGASUS_USE_STATIC_LIBRARIES - The environment variable
  75         PEGASUS_USE_STATIC_LIBRARIES if it exists will result in a static build.
  76         In order to determine which of the libraries go into the static build, a
  77         second variable is used in the Makefile for the libraries that are to be
  78         included in the executable.
  79
  80         STATIC - Setting the variable STATIC=1 in the Makefile for a Pegasus
  81         component causes that component to be included in the static executable
  82         instead of building a shared library.
  83
  84 As part of the definition of the static build mechanisms into the build
  85 environment, a lot of work was put into determining which of the existing
  86 libraries could logically be in the executable since this means that they
  87 are NOT available as shared libraries for use with providers and clients.
  88
  89 Currently the following libraries are in the static build as supplied with
  90 the CVS Pegasus 2.6 checkout. Different users may elect to either add or remove
  91 some of these libraries from the static build depending on their needs for
  92 the availability of shared libraries for providers or clients..
  93
  94         src/Pegasus/Server
  95         src/Pegasus/Server/ProviderRegistrationManager
  96         src/Pegasus/Security/Authentication
  97         src/Pegasus/Security/UserManager
  98         src/Pegasus/WQL
  99         src/Pegasus/ProviderManager2
 100         src/Pegasus/ProviderManager2/Default
 101         src/Pegasus/IndicationService
 102         src/Pegasus/ControlProviders/QueryCapabilitiesProvider
 103         src/Pegasus/ControlProviders/NamespaceProvider
 104         src/Pegasus/ControlProviders/Statistic
 105         src/Pegasus/ControlProviders/UserAuthProvider
 106         src/Pegasus/ControlProviders/InteropProvider
 107         src/Pegasus/ControlProviders/ConfigSettingProvider
 108         src/Pegasus/ControlProviders/ProviderRegistrationProvider
 109         src/Pegasus/Repository
 110         src/Pegasus/ExportServer
 111         src/Pegasus/HandlerService
 112         src/Pegasus/Query/QueryExpression
 113         src/Pegasus/Query/QueryCommon
 114         src/Pegasus/CQL
 115         src/Service
 116
 117 NOTE: To see this list for yourself, grep -r Makefiles for STATIC=1.
 118 NOTE: This list may change with time.
 119
 120 The components that remain dynamic libraries with are as follows:
 121
 122        src/Pegasus/Common
 123        src/Pegasus/Client
 124        src/Pegasus/Config
 125        src/Pegasus/Provider
 126
 127 This list represents the libraries required by providers.
 128
 129 Building with the static build options does result in static builds for the client
 130 utilities which might include the static libraries which means that some client
 131 utilities could be significantly larger.
 132
 133 Today you only gain if you do not use the out-of-process providers (OOP) feature
 134 because if you build static, the resulting remote agent is effectivly as large
 135 as the server because of all the static libraries that must be built into it.
 136
 137 The steps to create a static build instead of the dynamic build:
 138
 139
 140     1. Set the PEGASUS_USE_STATIC_LIBRARIES environment variable to true to
 141         cause Pegasus to use static libraries where appropriate (rather than
 142         dynamic libraries).
 143
 144
 145     2. Rebuild Pegasus. This will create a single executable for the server
 146        and dynamic libraries for those components not defined to be included
 147        in the static build.
 148
 149
 150
 151
 152
 153