Shore Software Installation Manual
Version 0.1

The Shore Project Group
Computer Sciences Department
Madison, WI

Thu Nov 3 14:11:49 CST 1994


1 Introduction

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.

2 Requirements

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 or

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 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

3 Installing the Documentation Release

    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.

4 Installing the Binary Release

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.

5 Compiling and Installing the Source Release

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.
    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.

5.0.1 Setting Configuration Options

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.

controls whether auditing and assert checking code is generated. For development and testing purposes we strongly suggest setting this to ON. Turning it on seems to slow things down by a factor of two, at least.

controls the -g compiler flag.

controls compiler flags related to optimization. When OPTIMIZE is OFF and you are compiling with gcc, gcc is called with -O because this seems to avoid gcc bugs (at least in earlier versions of gcc).

5.1 Compilation Steps

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)

    # start compiling
    cd $SRCDIR/src

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.

5.2 Installing the Compiled Files

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

6 Testing Your Installation

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.

6.1 Running the Shore Server

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:

         $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.

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 

To shut down the server try any one of these:

    # at the server prompt

    # or open another window and run this program 

The document, Running a Shore Server, gives more information on configuring and running the Shore Server.

6.2 Compiling and Running an Application

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.

    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.

6.3 NFS-Mounting the Shore File System

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):

    # or use your system's mount command

    # 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.
Thu Nov 3 14:11:45 CST 1994