TIOGA DATASPLASH INSTALLATION INSTRUCTIONS
== BINARY DISTRIBUTION ==
Copyright (c) 1997 The Regents of the University of California
Permission to use, copy, modify, and distribute this software and
its documentation for any purpose, without fee, and without a
written agreement is hereby granted, provided that the above copyright
notice and this paragraph and the following two paragraphs appear in
all copies.
IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR
DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING
LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION,
EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON
AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO
PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
------------------------------------------------------------------------------
This file contains the installation instructions for the binary distribution
of DataSplash and the Datasplash-supplied Postgres95 Database Management
System.
PLEASE NOTE! This install file will only explain how to install the
pre-compiled binary distribution for DataSplash.
For more information on how to compile DataSplash from the source
distribution, please retrieve the source distribution from our FTP site.
------------------------------------------------------------------------------
REQUIREMENTS TO RUN DATASPLASH
------------------------------
DataSplash has been tested on the following platforms:
alpha - DEC Alpha/OSF1
(compiled on: OSF1/alpha V3.2)
hpux - HP/UX
(compiled on: HP/UX v9.00 9000/877)
linux - Intel x86 on Linux/ELF
(compiled on: Linux/x86 v2.0.27 ELF)
solaris/sparc - Sun Solaris/Sparc
(compiled on: Sun Solaris 2.5.1 Sparc)
sunos/sparc - SunOS/Sparc
(compiled on: SunOS Sparc 4.1.4 Sparc)
DataSplash was compiled and statically-linked against the following:
postgres95 - Postgres95 Database Management System
(specific: postgres95-1.08)
xforms - XForms Forms Library
(specific: xforms-0.81)
tooltips - Tooltips Library for XForms
(specific: tooltips-0.02f)
Mesa - Mesa 3-D Graphics Library
(specific: Mesa-2.0)
XPM - XPM Library
(specific: XPM-4.x)
DataSplash REQUIRES a functioning Postgres95 DBMS!
If you DO NOT have a functioning Postgres95 DBMS, please download
binaries for a scaled-down Postgres95 DBMS from our FTP site.
------------------------------------------------------------------------------
WHERE TO GET THE SOFTWARE
-------------------------
DataSplash source code and statically-linked binaries:
(also contains binaries for a scaled-down Postgres95 DBMS)
ftp://datasplash.cs.berkeley.edu/pub/tioga/distribution
------------------------------------------------------------------------------
DOCUMENTATION
-------------
Documentation is available with this distribution. This includes the
user manual and tutorials.
This is available in the datasplash/docs directory.
------------------------------------------------------------------------------
INSTALLING DATASPLASH-SUPPLIED POSTGRES95 DBMS
----------------------------------------------
If you already have a Postgres95 database installed/accessible, please
skip down to "INSTALLING DATASPLASH."
1) Unpack the gzipped tar file containing the Datasplash-supplied Postgres95
DBMS distribution. It will extract into the directory postgres95.
gzcat [YOUR postgres95.tar.gz] | tar xvf -
Example:
gzcat postgres95-1.08-linux-2.0.24-x86elf.tar.gz | tar xvf -
NOTE: On some Linux systems, gzcat does not exist. In this case,
substitute zcat for gzcat.
2) Make sure that the directory the Datasplash-supplied Postgres95 DBMS
binaries are located is in your path.
Example:
under csh/tcsh:
setenv PATH `pwd`/postgres95/bin\:$PATH
rehash
under bash:
PATH=`pwd`/postgres95/bin\:$PATH
export PATH
3) Make sure that your PGDATA and PGHOST environment variables are set
correctly. Set PGDATA to the directory postgres95/data is located in.
Set PGHOST to the host you will be running the Postgres95 DBMS on.
Example:
under csh/tcsh:
setenv PGDATA `pwd`/postgres95/data
setenv PGHOST localhost
under bash:
PGDATA=`pwd`/postgres95/data
export PGDATA
PGHOST=localhost
export PGHOST
NOTE: Currently, if you use the DataSplash-supplied Postgres95
DBMS, you must run the postmaster server and DataSplash
on the same machine. This will be fixed in future
releases. For now, you must set PGHOST to localhost for
the DataSplash-supplied Postgres95 distribution.
4) Add yourself as a user to the database by typing the following:
datasplash_adduser [YOUR_USERNAME] [YOUR_USERID]
YOUR_USERID is your user ID on this machine.
Example:
datasplash_adduser mmchu `id -u mmchu`
NOTE: If id does not exist on your system, simply replace
the `id -u [YOUR_USERNAME]` section with your user id.
NOTE: To find out your user ID, type:
id
6) Now, you can start the Postgres95 postmaster (server) by typing the
following:
postmaster -S
NOTE: Do not try to background this process. The program will
fork itself off. Trying to background the process may
cause unpredictable behavior.
5) Create a Postgres95 database into which you will later load the demo data
and visualizations.
Example:
createdb datasplash_demo
7) Continue with "INSTALLING DATASPLASH."
------------------------------------------------------------------------------
INSTALLING DATASPLASH
---------------------
At this point, please make sure you either, 1) already have a Postgres95
database installed/accessible, or 2) have successfully completed
"INSTALLING DATASPLASH-SUPPLIED POSTGRES95 DBMS."
NOTE: You will be UNABLE to continue without a functioning database!
1) Make sure that your PGHOST environment variable is set to the host running
the Postgres95 postmaster (server).
Example:
under csh/tcsh:
setenv PGHOST localhost
under bash:
PGHOST=localhost
export PGHOST
NOTE: Currently, if you use the DataSplash-supplied Postgres95
DBMS, you must run the postmaster server and DataSplash
on the same machine. This will be fixed in future
releases. For now, you must set PGHOST to localhost if
you are using the DataSplash-supplied Postgres95 distribution.
If you are running your own installation of Postgres95 DBMS,
you do not need to worry.
2) Make sure that your Postgres95 postmaster (server) is running on the
host that you set PGHOST to.
If you are using a pre-existing Postgres95 installation, please see
your system administrator concerning the Postgres95 postmaster.
If you installed the Datasplash-supplied Postgres95 DBMS, see the
above section as to how to start the Postgres95 postmaster.
3) Make sure that the directory containing the Postgres95 binaries is in
your path.
If you are using a pre-existing Postgres95 installation, please see
your system administrator concerning the Postgres95 binaries.
If you installed the Datasplash-supplied Postgres95 DBMS, see the
above section as to how to place the binary directory in your
path.
4) Make sure that you have been added as a user to the Postgres95 DBMS.
If you are using a pre-existing Postgres95 installation, please see
your system administrator concerning being added as a user to the
Postgres95 DBMS. If you installed the Dataplash-supplied
Postgres95 DBMS, see the above section as to how to add yourself
as a user to the DBMS.
5) Make sure that a database has been created for you in the Postgres95
DBMS for you to install the demo data and visualizations.
If you are using a pre-existing Postgres95 installation, please see
your system administrator concerning creating a database for the
demo data and visualizations in the Postgres95 DBMS. If you
installed the Datasplash-supplied Postgres95 DBMS, see the above
section as to how to create a database for the demo data and canvases.
5) Unpack the gzipped tar file containing the DataSplash binary
distribution. It will extract into the directory datasplash.
gzcat [YOUR datasplash.tar.gz] | tar xvf -
Example:
gzcat datasplash-0.1-linux-2.0.24-x86elf.tar.gz | tar xvf -
NOTE: On some Linux systems, gzcat does not exist. In this case,
substitute zcat for gzcat.
6) Make sure that the directory the DataSplash binaries are
located is in your path.
Example:
under csh/tcsh:
setenv PATH `pwd`/datasplash/bin\:$PATH
rehash
under bash:
PATH=`pwd`/datasplash/bin\:$PATH
export PATH
7) Change directory to datasplash/data.
cd datasplash/data
8) Type the following to load the demo data and visualizations into the
Postgres95 database:
./demo_load [DEMO_DATABASE_NAME]
DEMO_DATABASE_NAME is the name of the database in the Postgres95 DBMS
in which the demo data and visualizations will be installed.
Example:
./demo_load datasplash_demo
NOTE: There will be some warning/error messages here. This is normal.
Please see the file demo_load.log in the data directory
to see the output of a normal ./demo_load run.
9) Make sure that your DISPLAY environment variable is set to the
X Window display you are using.
Example:
under csh/tcsh:
setenv DISPLAY localhost:0
under bash:
DISPLAY=localhost:0
export DISPLAY
NOTE: Also, you must make sure your have "authorization" to
display on the X Window display you are using. This is
done with the command: xhost +[REMOTE_HOST].
NOTE: You only need to do this if you are not running this from your
local machine.
10) At this point, you are ready to run DataSplash! Type the following
to start DataSplash:
datasplash
11) Good luck and enjoy!
Remember, for the user manual and tutorials, see the "DOCUMENTATION"
section above.
------------------------------------------------------------------------------
RESTARTING THE DATASPLASH-SUPPLIED POSTGRES95 DBMS
--------------------------------------------------
The purpose of this section is to explain how to restart the
Dataplash-supplied Postgres95 DBMS.
1) Make sure that the directory the Datasplash-supplied Postgres95 DBMS
binaries are located is in your path.
Example:
under csh/tcsh:
setenv PATH `pwd`/postgres95/bin\:$PATH
rehash
under bash:
PATH=`pwd`/postgres95/bin\:$PATH
export PATH
2) Make sure that your PGDATA and PGHOST environment variables are set
correctly. Set PGDATA to the directory postgres95/data is located in.
Set PGHOST to the host you will be running the Postgres95 DBMS on.
Example:
under csh/tcsh:
setenv PGDATA `pwd`/postgres95/data
setenv PGHOST localhost
under bash:
PGDATA=`pwd`/postgres95/data
export PGDATA
PGHOST=localhost
export PGHOST
NOTE: Currently, if you use the DataSplash-supplied Postgres95
DBMS, you must run the postmaster server and DataSplash
on the same machine. This will be fixed in future
releases. For now, you must set PGHOST to localhost for
the DataSplash-supplied Postgres95 distribution.
3) Now, you can start the Postgres95 postmaster (server) by typing the
following:
postmaster -S
NOTE: Do not try to background this process. The program will
fork itself off. Trying to background the process may
cause unpredictable behavior.
------------------------------------------------------------------------------
RUNNING AN EXISTING INSTALLATION OF DATASPLASH
----------------------------------------------
At this point, please make sure you either, 1) already have a Postgres95
database installed/accessible, or 2) have successfully completed
"INSTALLING DATASPLASH-SUPPLIED POSTGRES95 DBMS."
NOTE: You will be UNABLE to continue without a functioning database!
1) Make sure that your PGHOST environment variable is set to the host running
the Postgres95 postmaster (server).
Example:
under csh/tcsh:
setenv PGHOST localhost
under bash:
PGHOST=localhost
export PGHOST
NOTE: Currently, if you use the DataSplash-supplied Postgres95
DBMS, you must run the postmaster server and DataSplash
on the same machine. This will be fixed in future
releases. For now, you must set PGHOST to localhost if
you are using the DataSplash-supplied Postgres95 distribution.
If you are running your own installation of Postgres95 DBMS,
you do not need to worry.
2) Make sure that your Postgres95 postmaster (server) is running on the
host that you set PGHOST to.
If you are using a pre-existing Postgres95 installation, please see
your system administrator concerning the Postgres95 postmaster.
If you installed the Datasplash-supplied Postgres95 DBMS, see the
above section as to how to start/restart the Postgres95 postmaster.
3) Make sure that you have been added as a user to the Postgres95 DBMS.
If you are using a pre-existing Postgres95 installation, please see
your system administrator concerning being added as a user to the
Postgres95 DBMS. If you installed the Dataplash-supplied
Postgres95 DBMS, see the above section as to how to add yourself
as a user to the DBMS.
4) Make sure that the directory the DataSplash binaries are
located is in your path.
Example:
under csh/tcsh:
setenv PATH `pwd`/datasplash/bin\:$PATH
rehash
under bash:
PATH=`pwd`/datasplash/bin\:$PATH
export PATH
5) Make sure that your DISPLAY environment variable is set to the
X Window display you are using.
Example:
under csh/tcsh:
setenv DISPLAY localhost:0
under bash:
DISPLAY=localhost:0
export DISPLAY
NOTE: Also, you must make sure your have "authorization" to
display on the X Window display you are using. This is
done with the command: xhost +[REMOTE_HOST].
NOTE: You only need to do this if you are not running this from your
local machine.
6) At this point, you are ready to run DataSplash! Type the following
to start DataSplash:
datasplash
------------------------------------------------------------------------------
PLATFORM SPECIFIC ISSUES
------------------------
1) HP/UX:
Due to the lack of a statically linkable version of libX11, the
HP/UX binary distributed is dynamically linked.
2) Solaris/Sparc:
Due to the lack of a statically linkable version of libdl, the
Solaris/Sparc binary distributed is dynamically linked to the
following libraries:
libdl.so
libm.so
libc.so
3) Postgres95:
The Postgres95 binaries have been compiled, more-or-less, out of
the box. No provisions were made to make them statically linked.
Therefore, they may be dynamically linked.
------------------------------------------------------------------------------
QUESTIONS/BUGS/FEEDBACK
-----------------------
If you have any questions or feedback, please send them to:
datasplash@cs.berkeley.edu
If you have any bugs, please send them to:
datasplash-bugs@cs.berkeley.edu
NOTE: Please make sure to follow the bug reporting procedure on our
web site (http://datasplash.cs.berkeley.edu/bug_report.html).
This will ensure that your bug report can be handled most efficiently.