Compiling and Administrating Aesop

1 Quick Summary

The Aesop distribution consists of a customized Tcl interpreter called "fcl" and a lot of Tcl code defining a database system and user interface. It comes in two distributions, the "small" one consists of only our C and Tcl code, while the "big" one consists of our code plus all the external packages that we use: Exodus, Tcl/Tk, Expect, and BLT.

Here is a quick summary of how to build Fcl:

Pick a directory to be the root of the source tree, call this ROOT.
Make sure you have the GNU C and the GNU C++ compilers. Exodus will not build easily with compilers other than g++.
If you picked up the "big" distribution, unpack the able.tar.gz file. This file includes the sources for Exodus and all the tcl/tk stuff. Go into those directories and follow their directions for building the supporting software.
If you have the "small" distribution, go get Exodus, Tcl/Tk, Expect and BLT and build them.Exodus is at ftp.cs.wisc.edu and the Tcl/Tk and related tools are available at ftp.aud.alcatel.com.
Read the Exodus document and set up a couple of data volumes and a log volume. Don't put these in AFS! Put them in the local file system of the machine where the server will run.
To build Fcl, go to the directory $ROOT/fcl and edit the Makefile to reflect your choice of the ROOT directory and fix up all the library and include paths.
Type "make depend; make." Curse me when it doesn't work.
Now set up your environment (see Section 3) and see if anything works.

If the make worked, you should get a Fcl, a bare event system client, and the event system server. Now we'll go over these steps in more detail, and then we'll see how to set up the generic system after having compiled all this stuff.

2 Where stuff goes.

Here is what the source tree should look like for Fcl and its related extensions:

Note that it is important that you at least have the Tcl and Tk sources in the right place because Fcl uses some of their private include files to implement something that can't be done correctly without them.

Everything under the $ROOT directory has to be in the correct place because all of the default load paths are relative to "..". This will change to some more rational spot as the system matures. When Fcl is installed, all of its utility scripts go into the directory
/afs/cs/project/able/lib/fcl, and some auxiliary binaries go into
/afs/cs/project/able/lib/fcl/tools.
At CMU, the Tcl code repository must be accessible using the path
/afs/cs/project/able/lib/fcl/ABLE_CODE_REPOSITORY/. In the tape distribution, this directory is duplicated in the main source tree. You can set an environment variable and place this whereever you like. See the next section for details.

Eventually, all of the UI and style libraries will install into
/afs/cs/project/able/lib/fcl/ as well. Right now they are not stable enough to make it worthwhile.

3 Environment Variables

These definitions come from the script /afs/cs/project/able/bin/ablesteup.csh. I'll describe what they are for so you can update them correctly if the configuration of the development machines ever changes. Here the variable ROOT is the root of your development tree. In the ABLE project, this is /afs/cs/project/able/sunos

setenv EVOLID 3001

This is the default data volume for Fcl to use to store persistent objects.

setenv CVSROOT $ROOT/cvs

This is the root of our CVS repository tree. Must be set if you want to check the code out from CVS. Not needed if you got the code from tape or something. Note that Tcl, Tk, Expect, BLT and Exodus are not stored in the CVS tree.

setenv PATH ${PATH}:$ROOT/bin

This way we can find the binaries for the ESM server and utilities.

setenv PATH /usr/misc/.X11/bin:${PATH}

X11 binaries.

setenv PATH /afs/cs/project/able/bin:${PATH}

Our local binaries. Tcl, Tk, etc.

unsetenv CPATH
unsetenv LPATH

Make sure no CMU brain damage leaks in.

setenv MANPATH /usr/man:/usr/local/man:/afs/cs/project/able/man

To find man local man pages.

setenv RMDIR /afs/cs/project/able/sunos/sys/RMTool

For Notikin's stuff. This is strictly for local use at CMU.

setenv ABLEROOT /afs/cs/project/able/sunos

Same as $ROOT.

setenv FCL_LIBRARY /afs/cs/project/able/lib/fcl

Default place to find Fcl related Tcl code.

setenv MSG_LIBRARY /afs/cs/project/able/lib/fcl/msg

Default place to find the message server/client Tcl libraries.

setenv MESSAGE_SERVER rojen.sp.cs.cmu.edu:9001

Default host and port of the event server

setenv ABLE_REPOSITORY \
/afs/cs/project/able/lib/fcl/ABLE_CODE_REPOSITORY/alpha

Where the Tcl code repository lives.

setenv FDRHOME /afs/cs/misc/se-support/sun4c_411/omega/fdr.1.4

For running FDR. This is also for local use at CMU only.

if (${?DISPLAY} == "0") then
 xset fp+ /afs/cs/project/able/lib/fcl/sgen/fonts
 xrdb -merge /afs/cs/project/able/lib/fcl/sgen/sgen.Xdefaults
endif

This sets up X so it can find special Synthesizer Generator fonts.

4 Building all the External Stuff

Building Tcl, Tk and its friends isn't hard. You go and get all the tar files from the Tcl repository, unpack them, auto-configure the source code and type "make." That's pretty much it. You have to play around a bit to make shared libraries, but there are instructions on how to do that in the Tcl FAQ, I think. Exodus builds smoothly as long as you use g++, which we do. Its tougher to make it work with AT&T C++, due to problems with the way cfront handles templates in libraries. Don't even try it.

This is all I'll say about this, since saying any more would just duplicate the documentation that comes with Tcl, Tk and the other tools.

5 Building and Running Fcl

Once everything is set up correctly, building Fcl is easy. Just edit the Makefile to specify where the Exodus and Tcl sources live, run make depend and then run make to build all the binaries. Some problems that occur:

Weird compiler error messages are usually caused by gcc not finding its include files correctly. Use gcc -v to make sure gcc is reading the right headers.
Link errors happen either because libraries are not in the right places, or gcc's linker search path is wrong. Again, run gcc -v to see where gcc is looking for libraries, and check the Makefile.
If you think the resulting binaries are too bloated, follow the directions in the Tcl FAQ for building shared libraries for Tcl and Tk.
Steve Fink has experience building this code. Ask him what to do.

After make runs, you get three executables: fcl is the main fcl interpreter, msgClient is a bare event service client for debugging, and msgServer is the event server you should run along with the Exodus server.

The system can't run without the servers, and the servers do not start up automatically. That kind of magic is a bit too complicated, so starting the servers by hand is the best thing to do. To set up the Exodus server, first follow the directions in the Exodus documentation on how to set up a configuration file for the client and the server. Each user of the system must have such a file, called .sm_config, in their home directory. The file we use is shown below:

# config file for Exodus.
# client info
client*bufpages: 300
client*mount: 3001 9000@rojen.sp.cs.cmu.edu
client*mount: 3002 9000@rojen.sp.cs.cmu.edu
#
server*diskproc: /afs/cs/project/able/sunos/esm/bin/diskrw
server*bufpages: 300 
server*verbose: yes
server.sm_server.portname: 9000
server.SM_server.portname: 9000
# the log
[sf]*logformat: /rojen/usr0/psu/esm-vols/log 3000 1 1 1000 8
# data 
[sf]*dataformat: /rojen/usr0/psu/esm-vols/vol3001 3001 1 1 4000
[sf]*dataformat: /rojen/usr0/psu/esm-vols/vol3002 3002 1 1 2000
# tell the server where the log is
server.sm_server.logvolume: 3000
server.SM_server.logvolume: 3000

Next, log on to the machines named in the Exodus configuration fileand run the sm_server binary. Finally, log on to the machine named in the the MSG_SERVER environment variable and run the msgServer binary. In the ABLE project, we use the same machine,
rojen.sp.cs.cmu.edu, for both servers.

Finally, if you can run the screen program, its useful to run the servers in a screen session that can be detached and then resumed from anywhere. The screen program is available for ftp and comes with loads of documentation. At CMU, you can find it in /afs/cs/project/cmt/bin/screen and in the Andrew contrib area. Todd Kaufman (toad) builds lots of neat things like this. Ask him for help and advice once in a while. Look at ~psu/.screenrc for an example screen setup file.

6 Setting up the Database

Now that you have Fcl running, you need to set up a data area so you can really do something with the system. This is pretty easy to do. First, follow the directions in the Exodus documentation for creating a bare data volume and a bare log volume. Then, having installed Fcl, take the following steps:

% fcl
fcl> __famInitDatabase
=> _OBJ(xxx,yyyy,zzzz,wwww)
fcl> exit

Now run Fcl again to make sure the data area is really there:

% fcl
fcl> set root [ trans { persist getroot }]
fcl> set root
_OBJ(xxx,yyyy,zzzz,wwww)
fcl> exit

You should get back exactly the same object handle as you got before.

Now the DB is ready to handle the code in the user interface. You can now run the UI as described in its manual and create some sample designs in the three pre-defined styles.

7 Running the UI

The UI makes up the bulk of the generic design environment. "Styles" in the current system are just extensions to this generic environment that are loaded into the Fcl interpreter at run time. Currently, in addition to the generic environment (called the "UI") there are three styles: pf, unix-pf, and msg. Each lives in its own directory at the same level of the source tree as the Fcl directory.

Right now, you can only run one style at a time. This is changing however, since the code itself only has this limitation in a few places. To run the UI in a particular style, say pf, type the following at the shell:

% cd $ROOT/pf
% fcl
fcl> source main.tcl

At this point, the main box with four buttons will come up, and if you haven't got a tool server around, the tool server will start also. This startup sequence is identical for all styles.

If you want to configure your system so different things happen at startup, for now, the best way is just to edit main.tcl. Eventually, we'll provide something smarter.