home *** CD-ROM | disk | FTP | other *** search
/ Peanuts NeXT Software Archives / Peanuts-2.iso / Science / mathematics / hippoplotamus.README < prev    next >
Encoding:
Text File  |  1993-08-23  |  8.4 KB  |  203 lines
  1. Copyright (C)  1992  The Board of Trustees of The Leland Stanford
  2. Junior University.  All Rights Reserved.
  3.  
  4.  
  5.  
  6.                                Disclaimer Notice
  7.      
  8.      
  9.         The items furnished herewith were developed under the sponsorship
  10.    of the U.S. Government.  Neither the U.S., nor the U.S. D.O.E., nor the
  11.    Leland Stanford Junior University, nor their employees, makes any war-
  12.    ranty, express or implied, or assumes any liability or responsibility
  13.    for accuracy, completeness or usefulness of any information, apparatus,
  14.    product or process disclosed, or represents that its use will not in-
  15.    fringe privately-owned rights.  Mention of any product, its manufactur-
  16.    er, or suppliers shall not, nor is it intended to, imply approval, dis-
  17.    approval, or fitness for any particular use.  The U.S. and the Univer-
  18.    sity at all times retain the right to use and disseminate the furnished
  19.    items for any purpose whatsoever.                       Notice 91 02 01
  20.  
  21.  
  22.  
  23. Hippoplotamus
  24. =============
  25.  
  26.      Hippoplotamus (hippo) is a histogramming library based on n-tuples.
  27. The original implementation was by Jonas Karlsson. It is being written at
  28. SLAC by Paul Rensing, Paul Kunz, Mike Gravina, plus contributions from
  29. Tom Pavel and others. It is designed to be used as an n-tuple collection
  30. library and as the guts of an interactive application to view n-tuples.
  31.  
  32.  
  33. Building hippo
  34. ==============
  35.      We have provided some ways of building hippo. You can also make it
  36. yourself. 
  37.  
  38.      A minimum set of files which provide support for collecting n-tuples
  39. only is:
  40.     hippontuple.c hippoio.c hippoxdr.c hippoutil.c ntuple-parse.c
  41.     hippo.h hippostruct.h hippoxdr.h hippoutil.h
  42.  
  43. There are three utility programs:
  44.     nt2text.c text2nt.c hb2hippo.f
  45.  
  46.  
  47.  
  48. UNIX
  49. ====
  50.      This package includes a makefile for UNIX machines. The file is built
  51. with machine independent parts (Makefile and make.common) and a machine
  52. dependent part (make.<machine>). The machine architecture is determined by
  53. the script "architecture" and is set when make.common is called from
  54. Makefile. Architectures on which we have tested hippo are sun, next,
  55. ultrix, sgi and aix (rs6000). If you are adding a new machine, check that
  56. architecture gives a sensible answer.
  57.  
  58.      Because there are a number of plot drivers available, and one may want
  59. more than one driver available on a given architecture, we have designed
  60. the make file to build different libraries for the different (major)
  61. drivers. For example, on a NeXT, you would build only libhippoNext.a, while
  62. on a Sun, you might build libhippoX11.a and libhippoXIV.a (the Interviews
  63. driver). If you don't have any of these packages to link to, you could
  64. build a library (make target "hippo") which only contains the PostScript
  65. and line printer drivers, no screen drivers.
  66.  
  67.      There are a number of macros which may need to be tailored to your
  68. system.  The machine dependency file is included late so that it can
  69. override any macro defined in Makefile.
  70.  
  71. in make.common:
  72. SRC_DIR  - this is the directory containing the source code
  73. LIB_INSTALLDIR - directory in which to install the libraries
  74. INC_INSTALLDIR - directory in which to install the header files
  75. LIB_DIR  - directory in which the libraries are built. Is include as a -L
  76.            option when linking, so it should be defined ("." means current
  77.            directory). 
  78.  
  79. in make.<flavor>:
  80. CC, CPLUSPLUS - your compiler commands
  81. FC            - your FORTRAN compiler
  82. FBINDINGS - the Fortran binding files. Set to blank here if you don't have
  83.             a Fortran compiler.
  84. LIB_LIST - list of libraries to build for this machine
  85. DEBUGLIB_LIST - list of debug libraries to build
  86.  
  87. FORTRAN
  88. -------
  89.      We have provided a set of FORTRAN bindings for some of the function
  90. calls in hippo. If you don't have FORTRAN, comment out the macro FBINDINGS,
  91. or override the definition (set it to blank) in the machine dependent file.
  92.  
  93.           
  94. Plot Drivers
  95. ------------
  96.  
  97.      Hippo provides a number of plot drivers, which can be select for
  98. compilation in any combination. See make.next or make.sun4 for examples.
  99.  
  100. DrvrName  CodeFile         IncludeFile      C_Define      Description
  101. -------------------------------------------------------------------------------
  102. LPR       (none)           (none)           (none)        line printer driver
  103.  
  104. PS        (none)           (none)           (none)        PostScript to file
  105.  
  106. NEXT      hippoplotNeXT.c  hippoplotNeXT.h  _NEXT_PLOT_   NeXT DPS driver
  107.           hippowrapsps.c   hippowrapsps.h                 (from hippowraps.psw)
  108.  
  109. UNIXPLOT  hippoplotUP.c    hippoplotUP.h    _UNIXPLOT_PLOT_  UNIXPlot driver
  110.  
  111. XIVPLOT   hippoplotXIV.cc  hippoplotXIV.h   _XIVPLOT_     Interviews driver
  112.  
  113. X11PLOT   hippoplotX11.cc  hippoplotX11.h   _X11PLOT_     X-11 driver (R4)
  114.  
  115. By default, one of the screen drivers is included in each library, eg.
  116. libhippoX11.a is built using the X11PLOT driver.
  117.  
  118. If you wish to have a combination of drivers, you could build your own library.
  119. A driver must be selected at compile time in order to be able to use it in
  120. a program. To select a driver:
  121. 1) add the codefile to MACH_DEP_MEMS in the form "$(LIBRARY)(<codefile>.o)",
  122.    where <codefile>.o is the compiled object file of the files listed above.
  123. 2) add the include file to DRVR_INCS
  124. 3) add the C macro definition for C_Define (above) to PLOTCFLAGS, 
  125.    eg. -D_NEXT_PLOT_
  126.  
  127. Finally, you should choose one default plot driver by defining the C macro
  128. DEF_PLOT_DRVR; eg.  -DDEF_PLOT_DRVR=NEXT (use the DrvrName from above). LPR and
  129. PS are always defined and one should be used as a default if you don't want any
  130. other driver defined.
  131.  
  132. Make Targets
  133. ------------
  134. all       - build the regular and debug libraries and utilities
  135. libs      - (default) build the standard libraries
  136. debuglibs - build the debug libraries
  137. <name>    - build library lib<name>.a, eg. hippoX11, hippoNext.debug,
  138.                   hippoXIV.profile 
  139. util      - build the text/hippo converter programs
  140. clean     - delete backup files
  141. install   - copy libraries and certain include files to specified place
  142. hb2hippo  - an HBOOK to hippo converter. Needs CERN's PackLib.
  143. test      - run a few tests to see that hippo is working.
  144.  
  145. VMS
  146. ===
  147.      We have included an MMS file for VMS under the name make.vms (this does
  148. not need the file Makefile). The file is written to compile with the X11
  149. driver. You may need to change the logicals defined under .First to point to
  150. the correct directories (this is for RPC include files). Otherwise, many of the
  151. macro are the same as for the UNIX makefile. We do not change the name of the
  152. the Fortran file hippof.f.
  153.  
  154.      When linking a program with hippo on VMS, you will need the RPC and
  155. Multinet libraries. On my system, they are located at
  156.   multinet_root:[multinet.library]rpc.olb
  157.   multinet_root:[multinet]multinet_socket_library.exe
  158. (The socket library is really only needed to resolve bcopy and bset,
  159. something that Multinet should have put in the RPC library). The file
  160. hippo.opt is used to specify these libraries.
  161.  
  162. The C macro GLOB_QUAL is defined to be "noshare" on VMS. This should allow one
  163. to build a sharable library.
  164.  
  165. Miscellaneous Files
  166. ===================
  167.  
  168. architecture        - determine machine type on UNIX.
  169. example.hippo       - example hippo ntuple in binary format (used for 
  170.                        make test).
  171. example.hiptxt      - example hippo ntuple in text format (used in
  172.                        make test).
  173. fhippo.c, hippof.f  - the FORTRAN binding files.
  174. getarg.c            - provide proper version of FORTRAN callable getarg()
  175.                        for NeXT. Used only in hb2hippo.
  176. hippo.opt           - options file for VAX/VMS linker.
  177. hshrtnm.h           - header file with short names for most of the hippo
  178.                        functions. (necessary on IBM VM)
  179. h_test.c            - program to test basic display functions.
  180. h_test.out          - reference output of h_test
  181. h_testX11.c         - program to exercise the X11 driver.
  182.  
  183. Problems, Changes and Bug Reports
  184. =================================
  185.  
  186.      We are very interested in hearing about bugs and improvements.
  187.  
  188.      If you find a bug, please send mail to
  189. "hippo_bug@ebnextk.slac.stanford.edu" and we will do our best. Please try
  190. to be as specific as possible.
  191.  
  192.      If you have any suggestions or wish to make some contribution (eg. a
  193. new plot driver), please contact the authors. Send mail to
  194. "hippo_comment@ebnextk.slac.stanford.edu".
  195.  
  196.  
  197. Registration
  198. ============
  199.  
  200.      It is recommended that if you are using hippo, you send mail to
  201. hippo_comment to "register" your copy. This will allow us to inform you
  202. about major updates and bug fixes.
  203.