Installing the package

The files comprising SCB should be obtained and installed into the Starlink tree in more or less the usual way. There are some environment variables which affect the installation, determining for instance the locations of the indexes and temporary directories. All default to sensible values, but you can tailor them to your requirements by setting them at installation time. Additionally, the install-time values can be overridden by setting the same environment variables at run time. These variables are as follows:

SCB_SOURCES

The directory containing the Starlink source code. This directory should contain only Starlink source packages, each of which must be either in a directory named after the package or in a tar file named package.tar, optionally compressed using compress or gzip (and named with a suffix .Z or .gz respectively). The former of these is the usual format if the sources are in their usual location, /star/sources. If undefined at install time and run time, SCB_SOURCES defaults to $STARLINK/sources.

SCB_INDEX

The directory containing the index files (around 5-10 Mbyte for the full Starlink source collection). If undefined at install time and run time, SCB_INDEX defaults to $INSTALL/etc/scb.

SCB_BROWSER_TMP

The directory used by the browser program to store temporary files. If undefined at install time and run time, SCB_BROWSER_TMP defaults to /usr/tmp/scb.

SCB_INDEXER_TMP

The directory used by the indexer program to store temporary files. If undefined at install time and run time, SCB_INDEXER_TMP defaults to /usr/tmp/scb.

HTX_SERVER

The URL of an HTTP server which will provide HTX versions of the Starlink documents (see SUN/188). In fact this does not have to be a proper HTX server; as long as it can serve the documents it will not need to resolve xref_-type cross-references. Thus if the /star/docs directory is being served, the URL of the top of that tree will do. If undefined at build time, HTX_SERVER defaults to http://star-www.rl.ac.uk/cgi-bin/htxserver/.

It is possible to change the defaults from the installed values by modifying the file $SCB_DIR/Scb.pm.

An example site installation from source files might go as follows:

% zcat scb.tar.Z | tar xf -
% mk build
    ...
% setenv SCB_BROWSER_TMP /scratch/scb/browser
% setenv SCB_INDEXER_TMP /scratch/scb/indexer
% setenv INSTALL /star
% mk install
    ...
% mk test
    ...
*** Installation test for the SCB package has been run

The program uses a DBM file to store the indexes on disk. There will always be at least one library available on your system which Perl can use to do this, and there may be several -- different implementations each have their own pros and cons. SCB will try to find the BSD DB library or the Gnu DBM library. If these are not available then it will use one of the implementations that is. For most purposes this will work without any problems, but these other implementations often impose limits which interfere slightly with SCB's operation. In practice, the only effect of this is likely to be that the makefile entry for a few of the packages cannot be written -- if this is the case, then warning messages like

!!! Failed to write makefile => package#makefile (block size limit?)

will be written by scbindex.pl. This is not a very serious handicap, but can be fixed by installing GDBM or BSD DB, which are available in the public domain. Typically, BSD DB will be installed on a Linux or Digital Unix system, but a Solaris system may lack all of the preferred implementations.