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

260 karl  1.1 

261 mike  1.7 5.  To test the build type "make tests".

262 karl  1.1 

263 mike  1.7 The following make targets are supported:

264 karl  1.1 

265 mike  1.7     <default> - Build everything.
266               clean - Clean out all objects, libs, and executables.
267               depend - Create the dependencies.
268               tests  - Execute all tests (except client server tests).
269               rebuild - clean, depend, <default>
270               world - depend, <default>

271 karl  1.1 

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

275 karl  1.1 
276               ATTN: Add the procedure for Client/Server Test start here.
277           

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

279 karl  1.6 each platform see the appropriate sections below:

280 karl  1.1 
281           Generally the build commands are as follows:
282           

283 karl  1.6     1. There is a Makefile in the Pegasus root directory.   Simply executing
284               make in the Pegasus root directory will make everything. "Make rebuild"
285               will clean and rebuild everything. The "make rebuild" will also populate
286               the repository with the current CIM Schemas.

287 karl  1.1 

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

289 karl  1.1 
290           		"make world".
291           
292           

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

294 karl  1.4     tests except the Client/Server tests.

295 karl  1.1 

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

297 karl  1.1 

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

299 karl  1.1 

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

302 karl  1.1 

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

304 karl  1.1 
305           The MU Utility
306           ==============
307           

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

312 karl  1.1 
313           
314               C:\> mu rm myfile.cpp yourfile.cpp
315           
316           
317           You may type "mu" to get a list of valid commands. Here are some
318           of them:
319           
320           

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

322 karl  1.1 
323           
324           The MU utility supports globing (expansion of wildcards) so
325           you can do things like this:
326           
327           
328               C:\> mu rm *.obj *.exe
329           

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

332 karl  1.1 

333 mike  1.7 Notes about Building Pegasus on Linux:
334           ======================================

335 karl  1.1 

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

337 karl  1.1 

338 karl  1.5 Building Pegasus on NT or Windows 2000 With Microsoft Visual C++
339           ================================================================

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

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

350 karl  1.1 

351 mike  1.7 Installing the Pegasus HTML Test Client:
352           ========================================

353 karl  1.1 

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

359 karl  1.1 

360 mike  1.7 Development with Pegasus and Pegasus Tools:
361           ===========================================

362 karl  1.1 
363           ATTN: This section needs to be completed.  It should reference the more
364           complete documentation
365           

366 mike  1.7 Documentation:
367           ==============

368 karl  1.1 

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

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

374 karl  1.4 
375           Note that the Pegasus WEB site at The Open Group will be the source of most
376           documentation in the future and today is the source of most discussion and
377           design documentation.

378 karl  1.1 
379           Participate!
380           ============

381 mike  1.7 

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