1 karl  1.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 karl  1.1 	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 karl  1.1     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 karl  1.1 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 karl  1.1 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 karl  1.1 	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 karl  1.1 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 karl  1.1 
149           
150           
151           
152           
153