1 karl  1.1 Pegasus - A Manageability Services Broker for the DMTF CIM/WBEM Standards
  2           

  3 mike  1.3 Author: Mike Brasher, Karl Schopmeyer
  4           

  5 karl  1.1 Tagline: Pegasus is an object manager for DMTF CIM objects written in C++

  6 karl  1.5          and supported by The Open Group

  7 karl  1.4 

  8 mike  1.7 Overview:
  9           =========
 10           

 11 karl  1.5 Pegasus is an open-source object manager for DMTF CIM objects. It is written
 12           in C++ and includes the Object manager, a set of defined interfaces, and SDKs
 13           for both client, providers, and services extensions.  It is maintained
 14           consistent with the DMTF CIM and WBEM specifications except for any exceptions
 15           noted in the documentation.

 16 karl  1.1 
 17           This distribution represents a work in progress towards building a Pegasus

 18 mike  1.3 release. Pegasus is open source and is covered under the following license.

 19 karl  1.1 This version is incomplete and is directed towards evaluators and developers
 20           of the Pegasus Architecture.
 21           
 22           Pegasus is being developed and maintained under the auspices of The Open
 23           Group. Pegasus is maintained under the license defined in the doc directory
 24           (LICENSE) of this release.  This licensing is intended to support as wide a
 25           distribution as possible with minimal demands on the users.
 26           
 27           This distribution represnts a snapshot of the current work. Currently Pegasus
 28           is in phase 1 of a multiphase development project. This snapshot is primarily
 29           for developers and for evaluation of the project.
 30           

 31 mike  1.3 More information on this project, access to the CVS, and documentation on
 32           Pegasus are available from the OpenGroup WEB site.

 33 karl  1.1 
 34           There are separate files in the release for
 35           
 36           	History of releases - HISTORY
 37           	What's new for this release - WHATSNEW
 38           	What's Broken - BUGS
 39           
 40           In addition, the roadmap for Pegasus and further information on the project is
 41           available on The Opengroup Pegasus WEB Site.
 42           
 43           http://www.opengroup.org/MSB
 44           

 45 mike  1.7 Availability of Pegasus:
 46           ========================

 47 karl  1.1 
 48           Pegasus is distributed as open source.  Today the distribution is limited
 49           because we want to reach a predefined level of development before making the
 50           project publically available. The move from limited to open distribution will
 51           be a decision of the Pegasus development team and The Open Group and should
 52           occur before March 2001.
 53           
 54           To get on the distribution list for Pegasus today, send an email to
 55           

 56 mike  1.7     m.kirk@opengroup.org

 57 mike  1.3 

 58 mike  1.7     or

 59 mike  1.3 

 60 mike  1.7     k.schopmeyer@opengroup.org

 61 karl  1.1 

 62 mike  1.7 Pegasus Major Components:
 63           =========================

 64 mike  1.3 

 65 karl  1.1 The major components of Pegasus are:
 66           

 67 mike  1.3 Pegasus Server - WBEM/CIM Server with interfaces for providers and clients

 68 karl  1.1 

 69 karl  1.5 Pegasus Repositories - Today Pegasus provides a defined class repository
 70               interface and a simple file based class repository. It also includes
 71               an instance repository. Note that these repository were created for
 72               functionality, not efficieny. It is expected that they will be replaced
 73               with other implementations of the respository function as the need arrses.

 74 mike  1.3 

 75 karl  1.4 Pegasus Client SDK - Tools for building Pegasus clients based on the Pegasus
 76               C++ interfaces and using the WBEM HTTP/XML protocols or directly

 77 mike  1.3     interfacing with Pegasus.
 78           

 79 karl  1.4 Pegasus Test Clients - Simple test clients being developed as part of the

 80 mike  1.3     Pegasus development process
 81           

 82 karl  1.4 Pegasus HTML Test Client - To aid in testing we created a test client for
 83               Pegasus that uses a WEB server (ex. Apache) with a set of CGI modules and
 84               HTML to allow the entry of Pegasus operations from a WEB browser as forms
 85               and the recept of the response as WEB pages. This has proven useful as a

 86 mike  1.3     test tool and can be used for a wide variety of demonstrations.

 87 karl  1.1 

 88 karl  1.5 Pegasus Provider SDK - Tools for build Pegasus clients based on the Pegasus
 89               C++ interfaces.
 90           
 91           Pegasus Providers - A sampling of key providers to make the environment
 92           complete as well as test providers and demonstration providers for the
 93           Pegasus.

 94 karl  1.1 
 95           Pegasus Service Extensions -  Future (version 1.0)
 96           

 97 karl  1.5 Pegasus MOF Compiler - FA standalone compiler for MOF files that can be used
 98           to install MOF into the Pegasus schema repository and also to check syntax

 99 karl  1.1 

100 mike  1.7 Pegasus Dependencies:
101           =====================

102 karl  1.1 
103           We have worked to minimize the dependence of Pegasus on other software
104           packages and tools. Currently Pegasus has the following dependencies
105           

106 mike  1.7 1.  GNUMAKE - To simplify the building of Pegasus across multiple platforms we 
107               have standardized on a set of build tools including: GNUMAKE. We are using 
108               GNUAKE 4.79.1 successfully both in Windows and Linux environments.

109 karl  1.1 

110 mike  1.7     GNUMAKE is available from

111 karl  1.1 
112               http://www.gnu.org
113           

114 mike  1.7     ATTN: I think we need to make our version available on the TOG site.

115 karl  1.1 

116 mike  1.7     COMMENT: Unless other users of Pegasus demand it, we will NOT create 
117               any build environment for Pegasus that does not require GNUMAKE (e.g., 
118               Visual C++). We are open to other developers who want to contribute 
119               other build structures for particular environments.
120           
121           2.  MU.EXE - To minimize the difference between Linux and Windows for GUNMAKE,
122               we have created a utility called MU.exe.  This utility is required for 
123               Pegasus make with Windows environment. It is provided as an alternative to 
124               requiring a number of UNIX utilities (SH, RM, etc.) on the windows platform
125               and effectively provides the functions of these utilities that GNUMAKE 
126               needs. MU is not required on UNIX or LINUX platforms.
127           
128               NOTE: The binary for MU.EXE is not distributed in the Pegasus bin directory.
129               You must build it separately.  MU source code is part of the distribution
130               in the directory src/utils/MU with its own make file.  You must compile MU
131               before you initiate the Pegausu make.
132           
133               NOTE: We will make a copy of the binary available on the MSB WEB site to
134               eliminate the requirement to build this utility.
135           
136           3.  FLEX and BISON - These tools were used to develop the compiler, anybody
137 mike  1.7     intending to recompile the compiler from scratch will be required to have
138               these tools.
139           
140           4.  DOC++ - The Pegasus documentation is taken from a combination of text files
141               and the Pegasus header files themselves.  This documentation is formatted 
142               with DOC++ and GAWK.  These tools are required if the documentation is to 
143               be recreated but we expect that only the core team will be recreating 
144               documentaiton.

145 mike  1.3 

146 karl  1.1 The Pegasus Directory Structure
147           ===============================
148           

149 karl  1.4 Pegasus is distributed as a complete directory structure that should be

150 mike  1.3 installed either from one of the snapshots or from CVS.

151 karl  1.1 
152           This structure is generally as follows

153 mike  1.3 

154 karl  1.4 Pegasus                     Pegasus Root directory

155 karl  1.5 
156           
157               build                   Default destination for runtime if PEGASUS_HOME
158               			    is not specified.  Does not exist if PEGASUS_HOME
159               			    is specified
160           
161           
162               cgi                     Source for the Pegasus WEB Based Test client
163                   cgi-bin		    CGI Directories for WEB demonstration.
164                   		    This directory is normally empty but can
165                   		    be populated from the runtime with the make
166                   		    from cgi.
167                   htdocs		    HTML Pages for Pegasus WEB emonstration
168               doc                     Miscellaneous Pegasus Documents.

169 karl  1.4     	DevManual	    Source and build files for developes manual
170               mak                     General make files (used by other makes)

171 karl  1.1     src                     All Pegasus Source Files

172 karl  1.4         ACEExample         Test directrory with examples of the use of ACE
173                   Clients		    Source for various test clients and client SDK
174                       CGICLIENT       Pegasus test client that uses a WEB browser

175 karl  1.1         Pegasus

176 karl  1.4             Client          Pegasus Client API Tests

177 karl  1.1                 depends
178                           tests
179                       Common          Pegasus Common Functions (C++ source and headers
180                           tests       Test programs for the common functions
181                       Protocol        Pegasus Client HTTP/XML Protocol Modules
182                           depends

183 karl  1.4             Provider	    Pegasus Provider interface functions
184                       Repository      Pegasus Repository Interfaces and Simple

185 karl  1.5 		            Repository

186 karl  1.1                 tests       Tests for Repository Functions
187                       Server          Pegasus Server Modules

188 karl  1.5         Providers	    Pegasus test and required providers
189           

190 karl  1.1         Utils

191 karl  1.5 
192           Runtime Directories
193                $PEGASUS_HOME$	    Home directory for runtime.  All compiler, linker
194                                       documentation creation, etc. is put here.
195           	bin                 Destination for executable and DLL modules from
196           				    Pegasus build
197           	Manual		    HTML output of the Pegasus Manual
198           	lib		    Destination for Pegasus LIB modules
199           	obj		    Destination for object modules
200                   Repository	    This Directory containes the created repository
201           

202 karl  1.1 
203           In the near future we will add directories for:
204           
205               Service Extensions

206 karl  1.5     Servers - Today the server executable is built from /server/test.

207 karl  1.1 

208 mike  1.7 Installation:
209           =============

210 karl  1.1 

211 karl  1.4 Pegasus today is provided only as a source distribution.  You download compile

212 mike  1.7 and use it. Pegasus currently compiles and runs under Linux, AIX, HPUX,
213           Windows NT, and Windows 2000.

214 karl  1.4 
215           The installation of Pegasus involves expanding the snapshot distribution
216           files, building the runtime, the test files and test clients, and building the
217           repository.
218           

219 mike  1.7 Building Pegasus:
220           =================
221           
222           1.  Check that you have requisite programs (listed in Pegasus Dependencies).
223           
224               These include GNU Make, MU.EXE, Flex, and Bison
225           
226               Be sure these are on your path.
227           
228           2.  Define the following two environment variables:
229           
230               PEGASUS_HOME - to point to a directory to contain output binary files
231               (e.g., set it to $HOME/pegasus_home).
232           
233               PEGASUS_PLATFORM - this must be set to a supported platform identifier.
234               The following are supported:
235           
236           	WIN32_IX86_MSVC 
237           	LINUX_IX86_GNU 
238           	AIX_RS_IBMCXX 
239           	HPUX_PARISC_ACC

240 marek 1.10 	ZOS_ZSERIES_IBM

241 mike  1.7  
242                This identifier has the following form:
243            
244            	<Operating-System>_<Architecture>_<Compiler>
245            
246                Note: if you plan on doing parallel builds, you might consider setting
247                PEGASUS_HOME to something like this:
248            
249            	$HOME/pegasus_home_LINUX_IX86_GNU
250            
251                That way, the output of each build will be placed in its own directory.
252            
253            3.  Now place $PEGASUS_HOME/bin on your path
254            
255                and
256            
257                Placd $PEGASUS_HOME/lib on your LD_LIBRARY_PATH (for Unix only).
258            
259            4.  Now change to the root of the Pegasus distrubution and type "make"
260                (where make referes to GNU make).

261 karl  1.1  

262 mike  1.9  5.  Then create the repository, which is needed for some test cases -
263                "make repository"
264            
265            6.  To test the build type "make tests".

266 karl  1.1  

267 mike  1.7  The following make targets are supported:

268 karl  1.1  

269 mike  1.7      <default> - Build everything.
270                clean - Clean out all objects, libs, and executables.
271                depend - Create the dependencies.

272 mike  1.9      repository - Create the repository in $PEGASUS_HOME/repository

273 mike  1.7      tests  - Execute all tests (except client server tests).
274                rebuild - clean, depend, <default>
275                world - depend, <default>

276 karl  1.1  

277 karl  1.4  The Pegasus Client server tests are executed separately from the above because
278            they require the initiation of separate process for the Pegasus server and
279            Pegasus client. These tests can be executed as follows:

280 karl  1.1  
281                ATTN: Add the procedure for Client/Server Test start here.
282            

283 karl  1.4  For information on particular installation characteristics, tools, etc. for

284 karl  1.6  each platform see the appropriate sections below:

285 karl  1.1  
286            Generally the build commands are as follows:
287            

288 karl  1.6      1. There is a Makefile in the Pegasus root directory.   Simply executing
289                make in the Pegasus root directory will make everything. "Make rebuild"
290                will clean and rebuild everything. The "make rebuild" will also populate
291                the repository with the current CIM Schemas.

292 karl  1.1  

293 karl  1.6      2. To test a fresh release, go to the pegasus root and type

294 karl  1.1  
295            		"make world".
296            
297            

298 karl  1.6      This will build dependencies, build binaries, and then run all

299 karl  1.4      tests except the Client/Server tests.

300 karl  1.1  

301 karl  1.6      3. To execute the basic test suite that is shipped with pegasus type

302 karl  1.1  

303 karl  1.6  	   "make tests". This also reintalls the repository.

304 karl  1.1  

305 karl  1.4      Running "make -s tests" suppresses extraneous output such as the
306                enter/leave directory messages.

307 karl  1.1  

308 karl  1.6      4. "Make Clean" removes all object and library files from the structure.

309 karl  1.1  
310            The MU Utility
311            ==============
312            

313 karl  1.4  In order to provide a consistent build structure across multiple platforms, we
314            developed a small utility to provide a consistent set of small utilities
315            across these platforms. The MU utilityis a simple utility that contains many
316            commands. For example:

317 karl  1.1  
318            
319                C:\> mu rm myfile.cpp yourfile.cpp
320            
321            
322            You may type "mu" to get a list of valid commands. Here are some
323            of them:
324            
325            

326 karl  1.2      rm, rmdirhier, mkdirhier, echo, touch, pwd, copy, move, compare depend

327 karl  1.1  
328            
329            The MU utility supports globing (expansion of wildcards) so
330            you can do things like this:
331            
332            
333                C:\> mu rm *.obj *.exe
334            

335 karl  1.4  MU is required to build under the Windows environment.MU is available as part
336            of the distribution of Pegasus.

337 karl  1.1  

338 mike  1.7  Notes about Building Pegasus on Linux:
339            ======================================

340 karl  1.1  

341 mike  1.7  ATTN: put something here (but only what is not mentioned above).

342 karl  1.1  

343 karl  1.5  Building Pegasus on NT or Windows 2000 With Microsoft Visual C++
344            ================================================================

345 karl  1.1  
346            Today we build Pegasus on Windows NT using a set of make files contained
347            in the source distribution, the Microsoft compilers (tested so far with
348            versions 5 and 6) and the GNUMAKE make utility. The following is the basic
349            set up steps for the
350            

351 mike  1.7  Setup the environment variables and path for the Micrososft Visual C
352            compiler. Typically this can be done by running the VCVARS32.BAT file
353            supplied with Microsoft Visual C++. (contained in the same directory
354            as cl.exe).

355 karl  1.1  

356 mike  1.7  Installing the Pegasus HTML Test Client:
357            ========================================

358 karl  1.1  

359 karl  1.4  This is a separate test tool that allows Pegasus requests to be initiated from
360            any WEB browser and that uses a WEB browser, CGI scritps and HTML pages for
361            the formating and connections. It requires a WEB server, etc.  The
362            instructions for setting up this environment are maintained in a separate
363            readme in the CGI directory.

364 karl  1.1  

365 mike  1.7  Development with Pegasus and Pegasus Tools:
366            ===========================================

367 karl  1.1  
368            ATTN: This section needs to be completed.  It should reference the more
369            complete documentation
370            

371 mike  1.7  Documentation:
372            ==============

373 karl  1.1  

374 karl  1.4  The documentation is currently in preperation. The preliminary documentation
375            is not provided with this snapshot but is avialable from the OpenGroup Pegasus
376            WEB pages. The current documentation is maintained both as a manual created

377 karl  1.5  under the tool DOC++ in the runtime subdirectory manual/html and as other
378            miscelaneous documentation in the doc directory.

379 karl  1.4  
380            Note that the Pegasus WEB site at The Open Group will be the source of most
381            documentation in the future and today is the source of most discussion and
382            design documentation.

383 karl  1.1  
384            Participate!
385            ============

386 mike  1.7  

387 karl  1.4  We are looking for people who want to join the Pegasus work group and
388            contribute to effort of getting this Pegasus off the ground.  Please send
389            email for details to k.schopmeyer@opengroup.org or m.kirk@opengroup.org or
390            m.brasher@opengroup.org