TIOGA DATASPLASH COMPILATION INSTRUCTIONS
== SOURCE 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 compilation instructions for the source distribution
of DataSplash.
PLEASE NOTE! This compilation file only contains instructions on how to
compile DataSplash. It is assumed that you can or have installed and compiled
the other non-DataSplash components necessary to compile DataSplash.
If you do not wish to compile DataSplash yourself, please retrieve the
binary distribution from our FTP site.
If you do not have access to a Postgres95 Database Management System, please
retrieve the DataSplash-supplied Postgres95 DBMS from our site FTP site.
------------------------------------------------------------------------------
REQUIREMENTS TO COMPILE DATASPLASH
----------------------------------
DataSplash has been compiled 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 4.1.4 Sparc)
DataSplash REQUIRES the following components to compile and link:
postgres95 - Postgres95 Database Management System
(tested with: postgres95-1.08)
xforms - XForms Forms Library
(tested with: xforms-0.81)
tooltips - Tooltips Library for XForms
(tested with: tooltips-0.02f)
Mesa - Mesa 3-D Graphics Library
(tested with: Mesa-2.0)
XPM - XPM Library
(tested with: 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)
http://datasplash.cs.berkeley.edu/software.html
Postgres95 source code:
ftp://ftp.postgresql.org/pub/oldstuff
XForms binaries:
ftp://laue.phys.uwm.edu/pub/xforms
Tooltips source code:
ftp://ftp.wco.com/users/mmchu/tooltips
Mesa source code:
ftp://iris.ssec.wisc.edu/pub/Mesa
Xpm source code:
ftp://koala.inria.fr/pub/xpm
------------------------------------------------------------------------------
DOCUMENTATION
-------------
Documentation is available with this distribution. This includes the
user manual and tutorials.
This is available in the datasplash/docs directory.
------------------------------------------------------------------------------
COMPILING DATASPLASH
--------------------
At this point, it is assumed that you have retrieved, installed, and
compiled all the packages necessary to compile DataSplash. This document
will NOT explain how to compile any of those packages. For compilation or
installation help for those packages, please contact the author of the
package.
NOTE: Both the libraries and the header files for the libraries are
necessary from each of the required packages. In addition, some
header files are necessary from the postgres95/src directory.
Therefore, it is advisable that you obtain a FULL source distribution
of Postgres95 for compilation purposes!
NOTE: When describing how to set the Makefile variables, double quotes
are used to surround the values to set the variables to. Do NOT
actually include the double quotes when editing the Makefile.
1) Unpack the gzipped tar file containing the DataSplash source
distribution. It will extract into the directory datasplash/.
gzcat [YOUR datasplash-src.tar.gz] | tar xvf -
Example:
gzcat dataplash-0.1-src.tar.gz | tar xvf -
NOTE: On some Linux systems, gzcat does not exist. In this case,
substitute zcat for gzcat.
2) Change directory to datasplash/dv.
cd datasplash/dv
3) Open Makefile in your favorite editor.
Example:
vi Makefile
4) Select your target architecture with the variable ARCH.
Example:
If you are compiling on a Linux system, then make sure
ARCH is only set to "LINUX_PORT".
5) If you wish to have DataSplash linked statically, then make sure
the variable STATICLINK is set to "-static". Otherwise, make sure
the variable STATICLINK is set to nothing.
Example:
If you want to use static linking, then make sure
STATICLINK is set to "-static".
NOTE: If you wish to link DataSplash statically, you must make
sure that you have statically-linkable versions of all
the libraries from the required packages. These are usually
denoted by the extension ".a".
NOTE: On Sun Solaris, libdl.so is required in order to link.
However, it may not be available in a statically-linkable
version. Therefore, in the Makefile, setting ARCH to
SOLARIS_SPARC_PORT will cause STATICLINK to be ignored.
6) If you wish to have DataSplash compiled with debugging information,
then make sure the variable DEVELOPMENTAL is set to "true". Otherwise,
make sure the variable DEVELOPMENTAL is set to "false".
Example:
If you do not plan to do source-level debugging on the
DataSplash binary, then make sure DEVELOPMENTAL is set
to "false".
7) If you will be compiling against the Mesa library instead of an
official OpenGL library, then make sure the variable USING_MESA is
set to "true". Otherwise, make sure the variable USING_MESA is set to
"false".
Example:
If you are using the freely-distributed Mesa library,
then make sure USING_MESA is set to "true".
8) Set the location of the pixmaps directory with the variable XPM_DIR.
Example:
If you have extracted the source package as instructed
and have not moved directories, you can safely set
XPM_DIR to "../xpm".
9) Set the location of the XForms include and library directories with
the variables XFORMS_INC_DIR and XFORMS_LIB_DIR.
Example:
If you have installed XForms in /usr/local/xforms,
then set XFORMS_INC_DIR to "/usr/local/xforms/FORMS" and
set XFORMS_LIB_DIR to "/usr/local/xforms/FORMS".
10) Set the location of the Tooltips include and library directories with
the variables TOOLTIPS_INC_DIR and TOOLTIPS_LIB_DIR.
Example:
If you have installed Tooltips in /usr/local/tooltips,
then set TOOLTIPS_INC_DIR to "/usr/local/tooltips" and
set TOOLTIPS_LIB_DIR to "/usr/local/tooltips".
11) Set the location of the OpenGL or Mesa include and library directories
with the variables OPENGL_INC_DIR and OPENGL_LIB_DIR.
Example:
If you have installed Mesa in /usr/local/Mesa, then set
OPENGL_INC_DIR to "/usr/local/Mesa/include" and set
OPENGL_LIB_DIR to "/usr/local/Mesa/lib".
12) Set the location of the Postgres95 include, source, and library directories
with the variables POSTGRES_INC_DIR, POSTGRES_SRC_DIR, and
POSTGRES_LIB_DIR.
Example:
If you have installed Postgres95 in /usr/local/postgres95,
then set POSTGRES_INC_DIR to "/usr/local/postgres95/include"
and set POSTGRES_SRC_DIR to "/usr/local/postgres95/src" and
set POSTGRES_LIB_DIR to "/usr/local/postgres95/lib".
13) Set the location of the X Windows include and library directories
with the variables X_INC_DIR and X_LIB_DIR.
Example:
Most systems can set X_INC_DIR to "/usr/include/X11" and
set X_LIB_DIR to "/usr/X11/lib".
14) Set the location of other directories that may be necessary to
compile and link DataSplash.
Example:
To remove some warnings due to C++ header files, you can
set OTHER_INC_DIR to "/usr/lib/g++-include".
15) Save the current file and exit your editor.
No further changes should need to be made to the Makefile.
16) Remake the dependencies. If there are any errors or warning from this
command, please double-check your directory setting in Makefile.
gmake depend
17) Make sure any old binaries have been removed.
gmake clean
18) Compile DataSplash!
gmake
19) If the compile was successful, then continue to "INSTALLING DATASPLASH".
Otherwise, double-check that your target platform is supported
and that all your above setting are correct.
------------------------------------------------------------------------------
INSTALLING DATASPLASH
---------------------
If you have successfully compiled DataSplash for your platform, you can
now install the necessary files for the system to run.
At this point, please make sure you either, 1) already have a Postgres95
DBMS installed/accessible, or 2) have successfully installed the
DataSplash-supplied Postgres95 DBMS (available in the binary section
of our FTP site).
NOTE: You will be UNABLE to continue without a functioning database system!
1) Make sure that your PGHOST environment variable is set to the host running
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 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
that 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
that 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 that section as to how to add yourself
as a user to the database.
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 that
section as to how to create a database for the demo data and canvases.
5) Change directory to the place where you extracted/compiled the source
distribution.
Example:
cd ~/datasplash
6) Make sure that the directory the DataSplash binaries are
located in is your path.
Example:
under csh/tcsh:
setenv PATH `pwd`/dv/bin\:$PATH
rehash
under bash:
PATH=`pwd`/dv/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 database in the Postgres95 DBMS that
you wish to install the demo data and visualizations in.
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]. You only
need to do this if you are not running this from your
localhost 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.
------------------------------------------------------------------------------
RUNNING AN EXISTING INSTALLATION OF DATASPLASH
----------------------------------------------
At this point, please make sure you either, 1) already have a Postgres95
DBMS installed/accessible, or 2) have successfully installed the
DataSplash-supplied Postgres95 DBMS (available in the binary section
of our FTP site).
NOTE: You will be UNABLE to continue without a functioning database system!
1) Make sure that your PGHOST environment variable is set to the host running
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 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
that section as to how to 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 that section as to how to add yourself
as a user to the database.
4) Make sure that the directory the DataSplash binaries are
located in is your path.
Example:
under csh/tcsh:
setenv PATH `pwd`/dv/bin\:$PATH
rehash
under bash:
PATH=`pwd`/dv/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]. You only
need to do this if you are not running this from your
localhost machine.
6) At this point, you are ready to run DataSplash! Type the following
to start DataSplash:
datasplash
------------------------------------------------------------------------------
QUESTIONS/BUGS/FEEDBACK
-----------------------
If you get DataSplash to compile on a platform that is not listed above,
then please let us know:
datasplash@cs.berkeley.edu
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.