README file for base of Pablo distribution directory structure - Release 3.0

-----------------------------------------------------------------------------
The Pablo Environment:

The Pablo performance analysis environment is designed to provide unobtrusive
performance data capture, analysis, and presentation across a wide variety 
of scalable parallel systems.  The Pablo software consists of two primary
components: portable software instrumentation and portable data analysis and 
presentation.  A data meta-format called the Self-Defining Data Format (SDDF)
couples the instrumentation with the data analysis and data presentation.

Pablo is a registered trademark of the Board of Trustees of the University
of Illinois, registered in the U.S. Patent and Trademark Office.

See the file README.LICENSE for licensing restrictions.

The software and associated documentation is available via anonymous ftp 
from bugle.cs.uiuc.edu (128.174.237.148) under the directory pub/Release.

Additional Information on the Picasso group:
       WWW Pointer: http://www-picasso.cs.uiuc.edu/

This is Release 3.0 of the environment.  Changes since the last release are
outlined in the file README.RELNOTES.

------------------------------------------------------------------------------

Supported platforms and disk space requirments:

The Pablo instrumentation library was developed and tested on Intel
iPSC/2, iPSC/860, and Paragon systems and on the Thinking Machines CM-5 
using CMMD 3.0.  There is also a portable version which may be used to
instrument serial programs on BSD UNIX machines.  The instrumenting
parser and GUI (iPablo) are supported on the same machines as the
Pablo visualization software.

The Pablo visualization environment in this distribution was 
developed and tested on the following hardware/software platforms:  

      + SparcStation 10-GX 
        SunOS                   4.1.3
        gnumake                 3.70
        g++/gcc                 2.5.8
	 -or- 
	ATT Cfront		3.0.1
        X11R5                   patch level 26
        Motif                   1.2.3 with patches released by OSF 1/21/94
        perl                    4.0

      + DecStation 5000/200
        Ultrix                  4.2
        gnumake                 3.70
        g++/gcc                 2.5.8
        X11R5                   patch level 25
        Motif                   1.2.2
        perl                    3.0

      + Intel Paragon:			
	OSF/1			Release 1.1.5
	gnumake			3.70
	CC			Release 3.0
	cc, icc			Paragon Rel 4.1.1
        X11R5                   patch level 25
        Motif                   1.2.2
	* This was compiled on a SparcStation using the cross-development
	  tools provided by Intel.  

Total disk space required for the Pablo source and binaries should not
exceed 50Mb on a SparcStation with dynamic libraries.  More will be
required for systems that do not support dynamic libraries. Approximate 
space requirements (in Mb) for individual components of the distribution are:

        Sample Trace Data Files & Executables      12Mb 
        Visualization Source & Binaries, 
	 (including widgets and motif wrapper 
          classes) 				   18
	Instrumentation Environment - Source &
	  Binaries				   10

------------------------------------------------------------------------------

Directories making up the distribution:

Contributed - software developed at other sites that uses SDDF and Pablo.
	     See Contributed/README for more details.

DataFiles -  directory structure containing data files. See DataFiles/README
	     for more details

MakeRules -  directory containing definitions for gnumake implicit rules used
	     by most of the makefiles in the SDDFlibrary and Visual branches.

SDDFlibrary - directory structure containging source for standalone SDDF
	     library and sample programs that use the library. See 
	     SDDFlibrary/README for more details.

Instrument - the Pablo Instrumentation system.  See Instrument/README for
	     more details.

Visual -     the Pablo Visualization system.  See Visual/README
	     for further information on the organization of the source tree
             for visualization system.

----------------------------------------------------------------------------

How to build the system:

To build the distribution, edit the file "Makefile.defines" in the
current directory and follow the comments in that file to set the 
correct compilers, paths, and build options for your site.   
When you have finished making changes, type "gnumake all" to build 
the executables.

After the build finishes, you may change to the directory
	./Visual/Src/System/Build
and run the Pablo visualization environment by typing "runPablo".
Executables for the SDDF conversion programs, the Sound subsystem, and
the Instrumentation environment are left in their respective Build
directories.

To install the executables and libraries in the directories you 
specified in "Makefile.defines", type "gnumake install".

The command "gnumake clean" will remove the *.o, *.a, *.dep, and
executable files generated by "gnumake all" from the current
directory subtree.

------------------------------------------------------------------------------

Things that may go wrong:

1) After changing Makefile.defines, you should do a "gnumake clean"
   and then "gnumake all" for the modifications to take effect.

2) Warnings about truncated filenames when library archives are being
   created can be ignored.

3) If you do an "gnumake install" and then try to do another one at a
   later date, you may have permission problems when trying to copy
   some of the files during the installation process.  You can
   change to your destination directory and remove all the files
   from the original install before doing the second "gnumake install"

4) If you try to run the sample DEMOS, IO, and TUTORIALS visualization 
   configurations from the installation directory for your site, you 
   will probably have problems finding the required data files.   

   To fix this, first edit the files matching the patterns
	$(PABLOCONFIGDIR)/DEMOS/*/Layout
	$(PABLOCONFIGDIR)/IO/*/Layout
	$(PABLOCONFIGDIR)/TUTORIALS/*/Layout
   where $(PABLOCONFIGDIR) is the path you set in the configuration file
   Makefile.defines.

   For each Layout file, replace the string "../../../../DataFiles/SDDF/"
   in the path to the data file with the absolute path of the 
   files at your site.  (This is in the first line of the file.)
   For example, change
        iw GameStatistics ../../../../DataFiles/SDDF/Game1.ascii
   to
        iw GameStatistics /usr/local/Pablo/DataFiles/SDDF/Game1.ascii

   Next, copy the files in ./DataFiles/SDDF into $(PABLOCONFIGDIR).

5) If you compile using ATT Cfront 3.0.1, you may run into a problem
   with the library routine form() which is often build incorrectly
   when Cfront 3.0.1 is installed on sparcs.  
   
   To test for this problem, make Pablo (or at least the first part of it
   where the DataFiles programs are compiled). Change into DataTraits/Bin 
   and execute the command "ConvertPICL".  When prompted for an Ascii 
   SDDF file, enter a non-existant filename (/XXX for example).  If 
   you get an error message that the file can't be opened, you don't 
   have the problem.  If you get a core dump, you do have the problem.

   If you have the problem, you need to rebuild the object "oldformat.o"
   that is part of libC.a and reinstall it in the library.  Under your
   cfront source directory, change into lib/stream.  Then do

        CC -O4 -DVSPRINTF=vsprintf -c oldformat.c -o oldformat.o
        ar r /usr/local/CC/lib/libC.a oldformat.o
        ranlib /usr/local/CC/lib/libC.a
    
   You may have to enlist a system administrator to do this if you do
   not have root access.  The path to libC.a may also be different
   for you site.

   After fixing libC.a, remake Pablo.

6) When linking Pablo with shared libraries, you may get a warning from ld 
   that _vendorShellWidgetClass is multiply defined in the library 
   libXaw.sa.5.0.   The Pablo executable will still be produced, but it will 
   cause a memory fault - core dump when run.  If this happens on your
   system, edit the file ./Visual/Src/System/Build/Makefile and
   change the occurrence of -lXaw to /.../libXaw.a (where ... is the 
   complete path to your libXaw.a file) to force the executable to 
   be linked with the static version of the Xaw library.

         Old:          
	    -lXm -lXaw -lXt -lXmu -lXext -lX11 -lm
         New:          
	    -lXm /usr/local/X11R5/lib/libXaw.a -lXt -lXmu -lXext -lX11 -lm

   This change was not made in the distribution source because with Motif 1.2.2
   and later, it seems you must use the dynamic Xaw if you use the dynamic Xm. 
   The static version seems to be required with Motif 1.2.1.

7) Some earlier versions of X and Motif do not correctly display the Records
   of the "Bind Records to Input Ports and Output Record Fields" dialog
   when the Input Pipe is selected.  If you notice this behavior on your
   system, you can try replacing 
     ./Visual/Src/System/Interface/RecordBindingDialog.C
   with
     ./Visual/Src/System/Interface/RBD.C.1.9
   and rerunning "gnumake" from the ./Visual/Src/System/Build directory.
   We recommend you save a copy of the original RecordBindingDialog.C before
   replacing it with the older version.

---------------------------------------------------------------------------
Reporting Bugs & Suggesting Enhancements:

The file "Pablo.patches" in the ftp directory pub/Release-3.0/Pablo 
on bugle.cs.uiuc.edu will be updated with the latest bug reports for this
release.  If you encounter a problem, first check this file to see if it
has been reported and solved.  

If you encounter unreported bugs or see things that could be improved or 
extended, we want feedback!  Please send any bug reports and suggestions for 
enhancements to

        pablo-bugs@guitar.cs.uiuc.edu

