Version 0.1
The Shore Project Group
Computer Sciences Department
UW-Madison
Madison, WI
Thu Nov 3 14:11:49 CST 1994
The Shore Software distribution consists of documentation, binary, and source releases. This document describes how to install the releases, and how to build Shore from the source release. To begin using Shore to write applications, it is sufficient to install just the binary and documentation releases.
To install and run the Shore documentation and binary releases, you will need:
If you also wish to compile the Shore source code, you will need:
We debated the gcc 2.6.0 requirement. Unfortunately, we had a lot of trouble getting the code to compile with both 2.5.8 and 2.6.0 because of bugs in gcc. We do all of your testing with 2.6.0, but it seems that 2.5.8 will work as well. The GNU software is available via ftp from ftp://prep.ai.mit.edu/pub/gnu or ftp://gatekeeper.dec.com/pub/GNU.
If you are unfamiliar with Tcl, it stands for ``tool command language''. It was developed by Dr. John Ousterhout at UC-Berkeley for providing interfaces for tools, although it can be used for more than that. In Shore, it is used for test programs for the Shore Storage Manager and the Shore Value-Added Server. With the Alpha release, you must have Tcl to build Shore, however this might change with later releases. Tcl is available via ftp from ftp://ftp.cs.berkeley.edu/ucb/tcl. A FAQ is also available.
For all the following installation steps, we use two variables, so that you can ``cut and paste'' the instructions below.
set TARDIR=directory-that-holds-tar-files
set SHROOT=directory-in-which-to-install-shore
(If you use the Bourne shell (/bin/sh) or one of the shells derived
from it, such as ksh, omit the word ``set''.)
Whatever shell you use, make a directory in which to install Shore:
mkdir $SHROOT
cd $SHROOT
gunzip -c $TARDIR/shore.0.1.doc.tar.gz | tar xvf -
This installs html, ps and examples directories. The $SHROOT/html directory contains HTML versions of the documentation. You can read these documents with a World-Wide-Web (WWW) browser such as Mosaic or Lynx. When using Mosaic, press the ``Open...'' button and enter: $SHROOT/html/alpha.html (but you'll have to expand $SHROOTyourself). When using Lynx, use the Go command and enter: file://localhost/$SHROOT/html/alpha.html (but you'll have to expand $SHROOTyourself). The $SHROOT/ps directory contains Postscript versions of the documents.
The examples directory contains example and test programs discussed in the documentation.
A Shore binary release contains contains everything needed to write, compile and run Shore applications. A binary release is specific to a particular hardware/OS platform and is compiled with either debugging/auditing support or is compiled with optimization on and no debugging support.
Follow these steps to install a binary release:
cd $SHROOT
gunzip -c $TARDIR/shore.0.1.sunos.debug.tar.gz | tar xvf -
This installs bin, lib and include
directories in $SHROOT.
If you are installing both debugging and
non-debugging binaries
($TARDIR/shore.0.1.sunos.nodebug.tar.gz),
be sure to un-tar them
in separate directories.
That's it! You can test your installation by following the
instructions in
Section 6.
This section describes how to compile the Shore source release. Of course, there is no need to do this if you are just planning to use the binary release.
First, un-tar the release somewhere. You can put it in the same directory as the binary installation, or you can make a new directory for the sources.
# Go to a directory where you want to install
# the sources.
# For simpilicity, we let that be $SHROOT.
# If you use another directory, make the
# appropriate substitution for SHROOT in
# the next step.
set SRCDIR=$SHROOT
cd $SRCDIR
gunzip -c $TARDIR/shore.0.1.src.tar.gz | tar xvf -
(users of sh, ksh, etc. should omit the word ``set'').
This installs the $SRCDIR/config, $SRCDIR/tools, and $SRCDIR/src. The directions below tell you how to determine where the binaries will be installed when you make Shore from the sources.
Before you build Shore, you must give values to some configuration options. These options are located at the top of the file $SRCDIR/config/Project.tmpl.
vi $SRCDIR/config/Project.tmpl
For compilation to succeed you must set the values of TCL_DIR BISON_DIR, FLEX, and FLEXLIB, indicating where Tcl, Bison and Flex are installed at your site. The INSTALL_DIR specifies where the binaries will be installed when make install is executed.
Some of the configuration options control debugging support and optimization. They take one of the values ON and OFF. We describe them briefly here. More information about the effects of these options can be found by reading the comments prefaced by ``Compilation Options'' in config/Project.tmpl.
To build the system, gcc, perl, imake, make, and the normal Unix utilities must be in your path. The Makefiles are generated by Imake. They can be generated to work with GNU Make or with /bin/make, but not both. The steps below explain how to select which version of Make you use.
Here are the steps to compile Shore:
cd $SRCDIR
# if using Gnu Make, set the GNU_MAKE environment variable
setenv GNU_MAKE
# or, if you use a Bourne-style shell do this instead
GNU_MAKE= ; export GNU_MAKE
# if you are using /bin/make, do NOT set GNU_MAKE
# generate the Makefiles. NOTE: be sure to include the "."
tools/makemake .
# generate dependencies for Make
# (causes some compilation to be done)
tools/depend
# start compiling
cd $SRCDIR/src
make
The tools/makemake command generates Makefiles using Imake. The argument, ``.'' is important. Once Makefiles are generated, later changes to Imakefiles can be installed by running: make make in the src directory.
The tools/depend command generates dependencies. Making dependencies causes some other targets to be made in some directories. For example, rpcgen is built because it is needed to make the dependencies in the Shore Value-Added Server. Once tools/depend has been run, dependencies can be updated by running: make depend in the src directory.
The final make builds the system. You can ignore warnings about:
templates that are built with -fexternal-templates should be in ...
You can use make clean to remove all generated files.
The util/mount/sunos directory is skipped when making from the src directory (you will get a warning about this when make is run). This directory contains patches to SunOS sources that are used to build smount, (a program for mounting the Shore File System. If you have a SunOS source license, you can edit the mount/sunos/Imakefile to point to the sources and then build smount.
The Make target, install, installs the executable files in $INSTALL_DIR/bin, include files in $INSTALL_DIR/include, and other supporting files in $INSTALL_DIR/lib. It installs code and README files from src/examples and src/oo7 in $INSTALL_DIR/examples.
INSTALL_DIR is the macro set at the top of config/Project.tmpl. If you wish to change the it, you must change the macro and rerun tools/makemake, as described in the previous section, before you run make install.
To install:
# edit INSTALL_DIR config/Project.tmpl if you
# want to change the destination
cd $SRCDIR/src
make install
This section lists steps to test your installation. Included are instructions for running the Shore server, compiling and running some example programs, and mounting the Shore file system. Only brief explanations are provided. Pointers to relevant documents are given.
If you haven't already done so (while installing the software), do
set SHROOT=directory-in-which-shore-is-installed
(if you use a Bourne-style shell, omit the word ``set'').
Copy the configuration files to your home directory and modify a line in the .shoreconfig file to point to installation location:
sed -e "s,PUT-YOUR-INSTALLED-DIR-HERE,$SHROOT," \
$SHROOT/lib/alpha.options > ~/.shoreconfig
cp $SHROOT/lib/shore.rc ~
# in case you want to edit them later,
chmod u+w ~/.shoreconfig ~/shore.rc
Make a directory in which to run the Shore server. This directory will have subdirectories log and volumes. You must run the server while in this directory since the ~/.shoreconfig and /shore.rc files refer to ./log and ./volumes. The directory should be in a file system with at least 30MB of free space.
# create a directory for running the Shore server
mkdir shoreserver
cd shoreserver
mkdir log volumes
Now you can run the Shore server. The ~/shore.rc script initializes the Shore directory name space.
$SHROOT/bin/shore
You can safely ignore the warnings
Warning: This server is running under userid 1417, groupid 1417
Cannot serve ./volumes/miniroot
You must format it and try again../volumes/miniroot
Warning: Server is starting without a root directory.
The server has a command interpreter. Try these commands:
# list directories, registered objects, pools in root directory
ls
help
To shut down the server try any one of these:
# at the server prompt
q[uit]
bye
exit
ctrl-D
# or open another window and run this program
$SHROOT/bin/sshutdown
The document, Running a Shore Server, gives more information on configuring and running the Shore Server.
For the following examples, you must have a server running. If you don't, start one as described above.
This test uses one of the examples shipped in the documentation release. See pscan/README for details. For other examples, see the README in each of the examples directories.
mkdir pscan
cp $SHROOT/examples/pscan/* pscan
cd pscan
cp Makefile.template Makefile
chmod +w Makefile
Edit Makefile and change the value of the macro INSTALL_DIRto the value of $SHROOT.
make
build 10 testpool
pscan testpool
destroy testpool
The document Getting Started with Shore gives information about writing Shore applications, using $SHROOT/examples/stree as an example.
The Shore Server creates and manages a name space of objects, the Shore file system, that looks like a Unix file system. The Shore file system can be mounted as an NFS remote file system, allowing you to use standard commands such as ls to navigate it.
To mount the Shore file system you must have super-user (root) privileges on your machine.
# create a mount point (an empty Unix directory)
mkdir /shoremnt
$SHROOT/bin/mnt localhost /shoremnt $SHROOT/bin
To check the mount (you don't have to be super-user):
$SHROOT/bin/smount
# or use your system's mount command
/usr/etc/mount
# at the prompt from the shore server, type
ls /
# at a shell prompt, type
ls /shoremnt
# results should indicate the same directory
# contents, although the syntax differs
The document Running a Shore Server. gives more information on NFS-Mounting the Shore file system.