============================ CORAL FILES LAYOUT UNDER AFS ============================ Name: /p/coral/admin/file.layout Author: wei Date: July 14, 1994 Last update: Feb 7, 1995 I. Directory structure: All files related to CORAL stored on AFS in /p/coral. This directory is accessible via AFS as "/p/coral" on the other computers. The following sections detail the contents of each of the subdirectories of /p/coral. a. bin Executables used in installing and compiling CORAL. These are grouped by architecture: hp, sun4 and mips. This directory (e.g., "/p/coral/bin/hp") should be inserted into the user's path directly after "." and "~/bin" and before any other directories. This allows us control over which versions of GNU make, flex, etc. are used to make CORAL. Note that a number of the executables are simply links to the appropriate versions of the executables in /usr/psup/bin; these links could be replaced with actual executables if a different version were required. Under the architecture directory(e.g. hp), there is a lib/ to store the latest version of the coral libraries. There is also a perl subdirectory containing scripts to assist in programming in coral (srcchk, rcs_status, etc). There are links in each of the architecture directories to these files, so this directory does not need to be in your path. b. demos This directory is a copy of the original CORAL demos directory. c. dev The root directory for the restructured CORAL and its RCS files. See part II for descriptions of these directories. d. misc Miscellaneous text files. "Bugs" contains a list of reported, but not yet fixed, bugs. "CoralUsers" (and "CoralUsers.old") lists the e-mail addresses of people interested in CORAL. "coraloverview.tar" contains an overview to CORAL written by Praveen. The "explain" directory contains the original Explain source code and the files Jeff changed. e. original Contains the original CORAL RCS directories and related files. f. public Contains a version of flex, IV, readline, and a few other public domain items used by coral. These items (if we are using them) are expected to be on a machine that Coral will be installed on, and we do not ship them with the Coral releases. The "flex" directory contains the binaries for GNU flex version 2.4.6. This directory should be deleted as we are now using CS's version of flex. The "iv" directories contain the source and binaries for the latest version of InterViews. Interviews is no longer being used in coral, so these directories can be deleted at some point as well. Finally, "makedep" contains the source for the makedep utility; binaries for it are installed in /p/coral/bin. g. releases Source and binaries for each coral release, organized by release date. The Makefile in "apr94" was used to create the latest release. This Makefile will need to be modified to work with the restructured coral when it is to be released to the ftp site. h. ftp The ftp site for the rest of the world. Only user coral has full right to this directory. II. The Restructured CORAL The restructured coral and its corresponding RCS directories reside in /p/coral/dev/. To create a development environment in your home directory you need to: Create a "coral" directory. Change into the coral directory. do "setenv CORALROOT `pwd`" (This directory should also be set in your .cshrc file, and $CORALROOT/bin should be added to your path) Change the AFS permissions on the coral directory to have full permission (except administor, for user coral) The command to do this is "fs setacl ~/coral coral write". This will give user coral these rights on all directories created in this one, and will allow you to check-out files. do "rcs_status -t -co" (Note: One of /p/coral/bin/(hp/sun/mips) must be in your path already) The rcs_status program builds the coral tree with RCS links back to /p/coral/dev and checks out a copy of each of the coral files. Currently, $CORALROOT/src/coral/obj/CONFIG needs to be edited so that ARCH is set to your proper architecture (sun4, hp, or mips). Hopefully, we will be eliminating this soon. do a "make setup" at the top level to create the links for the include files and create configuration files. This is architecture dependent (for coralsh, the graphical coral interface), so you should do it on the platform you intend to use coral on most. Don't forget, add this stuff to your .cshrc: # For coral setenv CORALROOT $HOME/coral (Modify the above to indicate the location of the top of your coral directory tree.) Add this to the path area (modify for your architecture, hp shown): (Note that this adds these directories to the _front_ of your path, this allows us to override the system defaults for programs like make, etc) set path = ( /p/coral/bin/hp $CORALROOT/bin $path ) Once installed, the files and subdirectories of ~/coral will be as follows: Makefile Makefile for setting up the coral system. bin CORAL binaries (just links unless you install). examples CORAL example programs. includes Links to the CORAL header files. lib coral.help, tcl files, and installation directory for libcoral.a src All CORAL source code. tutorial CORAL programs used in the Tutorial. Within the src directory is a Makefile and the directories "clients", "class","coral" and "tools". The clients directory contains the source for some client programs that use coral. The tools directory contains source for programs that are generally required by coral itself, or other coral programs. The tools directory currently contains exist, exodus, magic and the C++/CORAL translator. The "coral" directory in "src" contains the CORAL source code, the regression and timing directories and the object ("obj") files directory. Generally, to compile coral you will issue a 'make' within the obj directory, the makefile will cd to the appropriate architecture and re-issue the make command. The Makefile actually used is "obj/Makefile.template". Note that source code is located via GNU make's vpath directive. If you want to use coral with EXODUS, see install.chap in misc directory for details. For a description of the CORAL source directories see section IV. III. Debugging the Restructured Coral Since the object files are no longer stored with the source files, when debugging CORAL you need to tell gdb where to look for the source files. This can be accomplished by creating a ~/.gdbinit file that contains the following (one) line: directory $cdir:$cwd:~/coral/src/coral/src/arg:~/coral/src/coral/src/bin ding:~/coral/src/coral/src/bitvector:~/coral/src/coral/src/builtin:~/cor al/src/coral/src/compile:~/coral/src/coral/src/global:~/coral/src/coral/ src/hashtable:~/coral/src/coral/src/index:~/coral/src/coral/src/misc:~/c oral/src/coral/src/parser:~/coral/src/coral/src/pipelined:~/coral/src/co ral/src/relation:~/coral/src/coral/src/rule:~/coral/src/coral/src/scc:~/ coral/src/coral/src/sm:~/coral/src/coral/src/symboltable:~/coral/src/cor al/src/tuple This line contains a list of all the CORAL source directories. (A copy of the gdbinit file can be found in /p/coral/misc/gdbinit.) Another option is to create a directory 'tmp' at $CORALROOT/src/coral/src, cd into it and execute the following: ln -s ../*/*.[Chc] . ln -s $CORALROOT/bin/* . You will then be able to use gdb from this directory. IV. CORAL Source Directories CORAL source files are located in $(CORALROOT)/src/coral/src. The source files and their corresponding header files are grouped in directories according to function as follows: arg Arg class and all its subclasses with the exception of the Relation class and its subclasses. binding Unification and binding environments. bitvector Bitvector class. builtin Builtin relations, solvers and supporting code. compile Implementation of backtracking plus code for compiling and executing. global Global variables and functions. hashtable Hashtable implementation. index GenericIndex class and its subclasses. misc Miscellaneous support functions. parser Parser, parser environment, scanner and unparser. pipelined Implementation of pipelining. relation Relation class, its subclasses and related classes. rule Classes and structures that define rules. scc Module environment and data and SCC code. sm Support classes for the EXODUS storage manager. socket Code for coral server interface and eventually socket relations (socketRel's). symboltable SymbolTable implementation. tuple Tuple, TupleIterator and Term. One big advantage of the restructured CORAL is that the source code for each class is contained in a separate file named after the class. For example, in the original CORAL the majority of the source for the Arg class and all its subclasses was stored in the files Arg.C and Arg.h; the remainder was scattered throughout in files such as grouping.C, symbol.C, aggreg-arg.h, etc. In many cases methods for one class were scattered amongst a number of different files. By collecting the methods and definitions for each class into its own header and source files the integrity of a single class can be maintained. (Although for true class integrity more of the methods and class variables need to be made private; at present nearly everything is declared public.) V. ArgList (note: This is probably hopelessly out of date since the addition of the CArg class - Shaun) As part of the restructuring the ArgList class and all code that used it was rewritten. Previously the ArgList class did not have a constructor; instead a procedure was called to malloc space for it. This made it possible to use the first Arg pointer in the ArgList as a typecast integer length. Unfortunately, all code that used ArgList was written to use pointer arithmetic to extract the appropriate data element from the class. In the restructured CORAL this is no longer the case. ArgList is a true class with a constructor and destructor and the array of pointers are stored separately from the length of the list. Furthermore, data elements are accessed via the array operator '[]'. The only exception to this rule is the method "first()", which returns a pointer to the first element in the list. This method is only used in calls to CopyArgs(). In creating CoralArgList, this method must be removed; once CopyArgs is modified to accept two ArgLists instead of two Arg pointers the removal should be trivial. (Note: SimpleCopyArgs() must not be modified to accept ArgLists, since it uses RuleInfo's private implementation of ArgLists. Either that or RuleInfo must be changed to use the ArgList class.) VI. Literal A rewrite similar to that of the ArgList class was performed on the Literal class, which lacked a constructor and was allocated instead by a call to AllocLiteral(). (The reason for this was that a Literal contained an ArgList and since an ArgList had to be specially allocated so did a Literal.) VII. Bug fixes and other changes. Other bug fixes and modifications are detailed in the RCS logs. A checkpoint ("Release 1.2") marks a stable revision. These checkpoints need to be done more frequently. VII. CoralArg and CoralArgList Source for a prototype CoralArg and CoralArgList can be found in /p/coral/misc. For a sketch of what CoralArg will look like with inlined data see the file /p/coral/misc/CoralArg-inlined.h. VIII. access rights under /p/coral a. all the files and directory under /p/coral except the private dirs(under people/) should be owned by coral. b. every member in the group is able to read and put file into any of the directories, but no one except user coral is able to overwrite or delete any files from the directories. If you want to check out (with a RCS lock) or check in a file via RCS, send mail to the coral coordinator (currently Shaun [flisakow@cs]). c. all files and directories are read-only to the world. IX. Documents Under /p/coral/doc: This directory contains our "external" documentation for Coral, we are currently working on expanding it. coral.impl.guide : A must-read hacking book by Wei Xiao. inside/ : praveen- The original programmer's ultimate guide. make.doc: Explains current recursive setup of makefile (only 6 targets) parsing: Talks about the scanning and parsing used in Coral test.suite: A discussion of the re-done test suites. file.layout: The file you are currently reading. client_server: Discussion of the coral client/server changes See Also: client.README - quick overview of programs and usage. client.protocol - the protocol used to comminicate. client_programmer_guide: