Coral is an experimental logic-programming language implemented using bottom-up techniques. This document describes how to install and run Coral. The current release of Coral is available in executable form for a variety of architectures: coral-1.5.1.nobin.tar.gz :: contains src code for Coral, but no binaries coral-1.5.1.sun4bin.tar.gz :: contains SUN4 binaries for Coral coral-1.5.1.sun5bin.tar.gz :: contains SUN SOLARIS binaries for Coral coral-1.5.1.hpbin.tar.gz :: contains HP700 binaries for Coral coral-1.5.1.lnxbin.tar.gz :: contains LINUX binaries for Coral coral-1.5.1.sol386bin.tar.gz :: contains SOLARIS '386 binaries for Coral The source code is compatible with g++ and with AT&T CC. If you run into problems with Coral, send mail to coral@cs.wisc.edu. This document contains the following sections: Line 1) Installing Coral 38 2) Using Binaries 98 3) Changing Default Configurations 111 4) Using EXODUS for Persistence 128 5) Using RDB (Relational Database) for Sybase/Ingres 173 6) Options in Makefiles 201 7) Compiling Coral 240 8) Space Requirements 254 9) Running Test Scripts 280 10) Using EXPLAIN 314 11) Other Software Needed 330 If you are installing only the binary version of Coral, you can skip sections 3 through 8. For installing Coral using the source code, skip section 2. 1) Installing Coral -------------------- The first thing to do is to get access to the Coral system code. If you are reading this, it is most probable that you already do have the code too. However, just in case you bought this installation document in its bestselling paperback edition from your local bookstore :-), you should know that Coral is available by anonymous ftp from ftp.cs.wisc.edu. Change directory to 'coral' once you get there. If you're wondering whether there's a new release of Coral out, you might want to check Coral's homepage at: http://www.cs.wisc.edu/coral/ The file that you download is a 'tar' file called coral-1.5.yy.tar.gz. Where xx is the version, and yy is your architecture type or 'nobin' for the source code only. To set up Coral on your machine, you need to store the tar file in an appropriate directory, and then do the following : ``gunzip coral-1.5.yy.tar.gz''. ``tar xvf coral-1.5.yy.tar''. If you do not have gzip/gunzip available, when you get the tar file from the ftp site (ftp.cs.wisc.edu) leave off the '.gz' extension and the file will be unzipped as you download it. Now a whole directory system should have been created with the root of the system called `coral-1.5'. If your tar file contained the Coral src code, all the directories listed below will have been created : coral-1.5 coral-1.5/bin coral-1.5/doc coral-1.5/include coral-1.5/lib coral-1.5/programs coral-1.5/src coral-1.5/tutorial The directory `coral-1.5' is the root of the Coral system, and there should be an environment variable called CORALROOT which has the value of this root directory. For example, CORALROOT=/usr/coral-1.5 At this stage, you should add this to your environment using `setenv', and also make the change to your .cshrc file so that it gets done automatically in the future. Also, $CORALROOT/bin should be added to your PATH variable. This is very important, since all the Coral executables reside in the coral/bin directory or have links in it. There are a couple of startup files that can be used with Coral. One is .coralrc, which is read and processed initially by the Coral interpreter. It can contain any Coral commands, but we recommend that you put in your favorite Coral alias definitions in this file. The other file is .sm_config which is used to configure the EXODUS storage manager. Both these files should be placed in your HOME directory. There is an example of a .sm_config file in the $CORALROOT directory. 2) Using Binaries ------------------- If you do not wish to recompile Coral, and would simply like to use the binaries in the release, here's what you need to do: cd $CORALROOT make binary_setup Coral is now ready to use. After this you can ignore most of this installation document, skip to section 9 (Space requirements) to continue from here. 3) Changing default configurations ----------------------------------- The default configuration of the Coral system is controlled by a set of default definitions in the file src/coral/global/Config.h. It is remotely possible that you might want to change certain parameters before compiling. However, we recommend that before you attempt to do so, you understand the use of the defaults in the code, and the effects of modifying them. It should not be necessary to modify any of these values unless you intend to extend the system to some significant degree. In any case, most of these defaults can be changed from the Coral prompt, and commands to change them can be included in your startup .coralrc file. Once you have Coral up and running, you can type 'help(defaults).' to get information on how to change the default values. 4) Using EXODUS for persistence -------------------------------- At this stage, you should be aware that Coral can be used with or without persistent relations. The conditional compilation can be controlled by setting some flags in the makefiles (see next subsection). The persistence is built on top of the EXODUS storage manager, which is a separate piece of software, also available from UW-Madison at ftp.cs.wisc.edu. However it is your responsibility to obtain and install the EXODUS storage manager Version 3.*. The following five files are needed: sm_client.h lib_smclient.a formatvol sm_server diskrw Look at the options in $CORALROOT/CONFIG. Two variables deal with EXODUS. EXODUS_LIB_DIR is used to specify the directory in which lib_smclient.a resides, and EXODUS_INCLUDE_DIR is used to specify where sm_client.h resides. We have provided a .sm_config file that provides a sample EXODUS config file for Coral. You will need to modify it as required (refer to the EXODUS Installation Manual for details). For starters, make sure that the machine names, port ids and file names used in the file are valid. The default .sm_config file uses a data "disk", a log "disk" and a temporary "disk". The very first time around, you will need to use formatvol to initialize these "disks". For the default .sm_config, this involves executing "formatvol -volume 9000; formatvol -volume 8000; formatvol -volume 7000". After that, you need to open a separate window and run sm_server, which is the EXODUS Storage Manager. If the Storage Manager is up and running, the Coral interpreter will automatically connect to it, provided it has been compiled to support persistent relations, and provided it is invoked with the -e flag (type "coral -help" to see the various command line flags that Coral supports). Within Coral, type "help(persistence)." to get information on how to use persistent relations. The binary versions of Coral are compiled _without_ the persistence option!! If you need to use persistence, you will have to obtain the Coral sources (if you don't already have them) and compile it in. 5) Using RDB (Relational Database) for Sybase/Ingres ----------------------------------------------------- Coral version 1.2 can access data stored in relational databases via the network. Currently the two types of relational databases supported are Sybase and Ingres. To compile in RDB, you need to set either DO_SYBASE and/or DO_INGRES to `yes' in $CORALROOT/CONFIG. There are more options specific to RDB available in: $CORALROOT/src/class/rdb/CONFIG.RDB If you compile with either of the above flags set, the RDB library librdb.a will be created as well as being compiled into Coral. You should at least read CONFIG.RDB before compiling, there are many configurable options there. Note: Sybase or Ingres should be installed according to the directions provided with their instructions. Both of these Databases are commerical products; the words Sybase and Ingres are undoubtably trademarked. Note: This code is still beta, please let us know if you have any trouble with it. This code was developed using Sybase Version 4.6, Sybase Open Client DB-Library/C Version 4.6.2 and Ingres 6.2. 6) Options in Makefiles ------------------------ In order to specify options to any makefiles, you only need to modify $CORALROOT/CONFIG. This file is included in all the other makefiles. The $CORALROOT/CONFIG file contains comments explaining the use of every flag and makefile variable. One important point to note is that Coral can be compiled with or without persistence. You also need to indicate where you have various utilites installed by setting different make variables. If you do not have all of the needed software please see section 11. The variables and their purpose: ARCH : The architecture being compiled on (hp, sun4, etc) CPLUS : The c++ compiler to use. CC : The c compiler to use. FLEX : Where the Flex scanner is installed. READLINEROOT : Where the Gnu Readline library is. TCL_HOME_DIR : Where Tk and Tcl are located (TkX/TclX are no longer required.) Other packages needed for installing: Perl - `perl' must be installed on your system, and be in your path for the Coral test suites to be setup correctly. Perl is also needed for a `multiple architecture' setup. Gnu Make - You must have the Gnu Version of Make and it should be in your path before the regular version. Gnu Bison - Previous releases allowed either Yacc or Bison, Coral has since been switched to using a re-entrant parser, so Bison is now required. 7) Compiling Coral ------------------- Once you have got to this point, all that remains is to install the system. To do this, cd to the $CORALROOT, and type `make install'. This will start a compilation of the entire Coral system (which will take quite a while : approx. 40 minutes on a DECStation 5000). When it completes, Coral will be compiled and ready to run. If an error occurs and you would like to return to a "just out of the box" state, you can run `make pack', which cleans off everything it can to prepare for being tarred up. 8) Space Requirements ---------------------- The approximate size of the tar files when unzipped and untarred is: sources only : 30 M with stripped binaries: 45 M After you compile Coral successfully, you can use `make clean' to remove all the objects files and unneeded libraries. (This has already been done for the binary versions of Coral). If you do not expect to recompile Coral until the next release, you may remove the entire $CORALROOT/src directory, though this will only save about 3M. The following paragraph applies only for the version with the source files. When you start compilation using the source files, the entire system can grow to around 70 M, if compiled without the -g flag (as is the default), and can grow to about 150 M if compiled with the -g flag. However, much of this space is occupied by .o files that can be deleted once the compilation finishes. Also, the executables can be stripped to reduce space utilization. This has been done in all of the binary versions of the release. 9) Running Test Scripts ------------------------ At this stage, we recommend you run the test suites that sit in the $CORALROOT/programs/regression directory. These are run by typing the commands: cd $CORALROOT/programs/regression test_suite accept1 accept2 These tests might generate some warning messages, but there should be no error messages. The entire `test_suite' should run in under an hour. The script allows up to 20 minutes for _each_ suite in a suite to run, after which it stops it and moves onto the next. This is a sufficient amount of time for each suite on a Sun Sparc 10. If you recieve a timeout message and would like to extend the time allowed to finish use the '-t' option followed by the number of minutes timeout for _each_ suite. For example: test_suite -t 50 accept1 accept2 Allows each suite (about 80 programs) 50 minutes to run to completion. Note that you must have `perl' to use the testing script, please see section 11 for more information. If you run into any problems in reaching this point, send mail to coral@cs.wisc.edu, and we'll try to fix it asap. Otherwise, the Coral manual and overview documents should carry you on from here. 10) Using EXPLAIN ------------------ This release of Coral is accompanied by an 'Explanation Tool' called simply `Explain'. This tool allows you to graphically observe the execution of a Coral program. It uses Tk/Tcl to provide its graphic user interface (see section 12 for more information). For more information on the explain tool, type `help(explain)' from within coral. Note: If you do _not_ wish to use the explanation facility, you may remove the definition of DO_EXPLAIN from the CONFIG file. This is not suggested, as the resulting decrease in code size is negliable. 11) Other Software Needed -------------------------- If you require the use of persistent data, you will need to get the Exodus Storage Manager v3.*, which is freely available from ftp.cs.wisc.edu. 1) gcc/g++, Flex, gnuMake, and the gnu readline library are available by anonymous ftp from 'prep.ai.mit.edu'. 2) You will also need nawk, which is a variant of awk to process testscripts and table data. If you do not have nawk, make a link to awk in your $CORALROOT/bin directory and call it nawk. 3) Most of the Coral scripts use perl. 4) The explanation tool Explain, and the Coral GUI use Tcl and Tk, you will need the libraries for these items (libtcl.a available to compile the Tcl Shell (coralsh) used by Explain and the Coral GUI. These programs also use TkTree and parts of Jed, but these things are included with this Coral release. Perl - `perl' must be installed on your system, and be in your path for the Coral test suites to be setup correctly. Perl is also needed for a `multiple architecture' setup. Gnu Make - You must have the Gnu Version of Make and it should be in your path before the regular version. Gnu Bison - Previous releases allowed either Yacc or Bison, Coral has since been switched to using a re-entrant parser, so Bison is now required. If you're using Linux, the minimum package requirement is: (Many thanks go to Salvatore Labonia, for creating this list.) Disk set A & AP: standard installation with support of shared library Disk set D: binutils bison flex gcc263 gmake include libc libgxx lx128_2 perl Disk set N: netcfg and tcpip Disk set TCL: (note: tclx is no longer required for version 1.5) tcl tk Disk set X: Standard installation + xinclude Disk set XV: Standard installation Disk set XD: xstatic.tgz We hope you enjoy using Coral; your feedback would be appreciated. If you extend Coral, and want to make your changes available to the world, get in touch with Raghu Ramakrishnan or mail coral@cs.wisc.edu.