acedb --- A C. elegans Database
II. Installation guide

Richard Durbin
MRC Laboratory for Molecular Biology
Hills Road, Cambridge, CB2 2QH, UK
Email: rd@mrc-lmba.cam.ac.uk

Jean Thierry-Mieg
CNRS--CRBM
Route de Mende, BP 5051, 34033 Montpellier, France
Email: mieg@crbm1.cnusc.fr

January 15, 1993

Contents

1 Installation Guide

 The user installing the acedb program will henceforth be called the administrator. He will be the only user allowed to reorganize the database and will have to grant write access to the other users. For this purpose, we recommend the creation on your machine of a new login name, acedb, but this is not mandatory. You must NOT be root when you install acedb, because the programs runs in setuid mode, so if installed as root it would run with root priviledge.

1.1 Automatic installation of the database

a) Login as administrator.

b) Choose a disk drive with sufficient free space to hold the whole database. As of Octobre 1992, we need around 50 Megabytes for the nematode data. There is no hard limit, and the program asks permission and increases the disk file size if needed.

c) On this disk, create a new directory, henceforth called $ACEDB.

d) Copy in this directory the acedb tar-compressed files, exactly as you received them on tape or via ftp. Explanations on how to run an ftp session are given in a separate section further down.

e) Keep only the file bin.machine.version.N_n.Z corresponding to your machine (where N_n is the release number). As of Octobre 1992, we can provide executables for SUN , DEC , Next, Silicon Graphics, Alliant and Convex running Unix and X11. We have near working versions on the Alliant and IBM risc. We no longer support the Sunview version, contact us if you badly need it.

f) Run the installation script by typing the command:

% INSTALL
or possibly

% source INSTALL
if INSTALL is not directly executable on your machine after ftp or untarring. If you miss that file, a copy is kept in doc/INSTALL, you will find it if you untar yourself the file doc.N_n.tar.Z.

g) If other users than the administrator need to have write access, add their login names, one per line, in the file wspec/passwd.wrm. Line starting by a pair of slash // are comments. Note that the INSTALL script should already have added in the administrator. On some machine, the unix call getlogin() fails. In such a case, acedb issues a message and you can circumvent the problem by uncommenting the fake user name getLoginFailed in the file passwrd.wrm. However, everybody will then have write access.

h) If possible, su to root, and copy in /usr/local/bin the shell scripts acedb and textace created by INSTALL. In this way, they will be in everybody's path. Otherwise, in every user's .login or .cshrc file, add the 2 lines:

setenv ACEDB fullPathToAcedbIntallationDirectory
set path = ($path $ACEDB/bin)
i) Skip to section: "Initialising the database"

1.2 Automatic installation of a new release

 Login as administrator. Ftp in the $ACEDB directory the recent data update files: update.N-n.tar.Z and the most recent source and/or binaries: source.N_p.tar.Z, bin.machine.N_p.tar.Z The main number N must match for the code and update files, the second number does not. All these tar files contain a copy of wspec. Therefore if you untar update.1-1 after source.1_8 you would have a problem to recompile, but not to execute on data 1-1, because you would be missing the tags relative to more recent data.

Then run the INSTALL script, this will save and restore your password and semaphore files and install the latest code release and update file. The first time you run, use Update button from the main menu.

1.3 Hand installation

If for some reason the INSTALL script fails, or you want to change the security scheme, here are the details of what INSTALL is supposed to do.

Perform steps a) through e) as above.

f') Tar the distribution file(s). e.g.

% zcat *.tar.Z | tar xvf -
or

% zcat path/*.tar.Z | tar xvf -
if the tar.Z files are elsewhere.(The isolated | is meant to be the pipe symbol). This should create a number of subdirectories.

wspec
wspec must contain at least the files sysclass.wrm, systags.wrm, classes.wrm, tags.wrm, models.wrm, mandatory at run time; the files passwd.wrm and semkey.wrm necessary to gain write access; and the file help.wrm which contains the online help. To compile you also need a file quovadis.wrm that specifies the main menu, and allows a programmer to add in hooks to his own display and analysis code. The only change you should make to these, unless you are designing your own database, is to make sure that the user name of the person who will apply the updates (normally administrator) is in the file passwd.wrm; if not, then edit it.
database
If tar did not produce this directory, make it:

% mkdir database
The program itself will create there a set of files the first time it runs. blocks.wrm is the main database file (30 MegaBytes or more for C. elegans data) and 2 tiny files ACEDB.wrm and lock.wrm. lock is used for concurrency control. If you remove ACEDB.wrm, the database will be reinitialised.
PS
If tar did not produce this directory, make it:

% mkdir PS ; chmod 777 PS
The directory PS will contain the various output files created by the users. It is thus better if everybody has write access to it, hence the chmod 777.

wquery
wquery contains examples query command files.
wmake
wmake is needed to recompile. It should contain the files makefile and truemake, and a collection of files MACHINE_DEF (see Recompilation below).
doc
doc contains various documentation files, including at least the present guide. Some files are in ascii and can be printed directly. Those with a tex ending are written in latex. They are human readable but it is best, when posible, to process them. For this, you need to have latex available on your system (probably in /usr/local/bin). If you do then you can issue the following commands:

% latex xxx.tex
% dvi2ps xxx.dvi | lpr
If not, then you may be lucky and find a postscipt version, xxx.PS, or possibly compressed as xxx.PS.Z.

The users guide should be useful to all users. The installation guide is just needed when installing a new release. The configuration guide is useful if you plan to enter your own data in the system, at last the programmers guide is needed only if you want to modify or extend the code. Note that we will only support the worm canonical database (official updates etc.) when used with the program as it comes from us. However, we would welcome your collaboration if we can plan things together in advance.

bin
bin contains the object modules and the executables. Do not edit any of the files contained in bin. If they are wrong or obsolete, just delete them, the makefile will resucitate them. If you wish to support a multiple architecture, simply rename bin, say mv bin sparc, and recompile on a second machine.

rawdata
rawdata contains the raw data (update files, ace files, asn files).
wh
wh contains the include files, it is needed only at compile time. If the standard X library on your machine is not the one you need, put in wh a link to the correct one. We do this in particular on the DEC to compile under X11mit rather than X11dec. By the way, on the DEC, you must arrange the X-fonts-path so that the standard mit fonts 8x13, 6x10 etc. are reachable by the X-server.

w1-9
These directories contain the source code. More or less accurately, w1 contains tools useful in general C programs, w2 contains our portable graphics library, w3 manages the network, w4-5-6 manage the database kernel, w7 contains the graphic applications, w8, associated less graphic tools, w9 a few miscellaneous. If you wish to add new code of yours , we suggest that you create a new set of directories.

g') Create a file logbook.wrm and adjust the authorizations with the commands:

% `date` $>$! logbook.wrm
% chmod 644 logbook,wrm
% chmod 755 bin w*	# so everybody can read the source code etc
% chmod 644 w*/* 
% chmod 755 INSTALL 	# so someone else can INSTALL again 
% chmod 755 doc/INSTALL 
% chmod 777 PS 		# so every body can touch the  files in PS 
% chmod 755 bin/tace    # read only line mode acedb 
% chmod 4755 bin/xace   # note the 4, setuid.
Setuid on xace is necessary, it sets the effective user id of anyone executing the program to administrator. Without it, nobody else will be able to write. Do NOT setuid on tace, since this executable is readonly but may fork interactive cshells with the same authorizations.

1.4 Granting Authorizations

The acedb program relies on the read/write authorisations set in the ACEDB directory to guarantee its security and integrity. We propose 2 alternative schemes.

a)If you install the system with the INSTALL script provided, then, the authorizations will be set up as detailed in item g') of the preceeding section.

In this way, everybody will be able to read the configuration and documentation files but only the administrator will be allowed to rename or alter them, and only the users listed in wspec/passwd.wrm will have write access. If you chmod 755 bin/xace, only the administrator will have write access.

b) Tighter scheme :

Create a new user group called acedb containing the administrator and all users to whom you want to grant write access. To do this get your system administrator to add into the file /etc/group a line of the form

acedb::100:acedb,durbin,mieg
where acedb stands for the user id of the acedb administrator, 100 stands from a new group number and durbin,mieg stand for the list of write-authorized users.

Then edit the file wspec/passwd.wrm as above and run the following commands in $ACEDB 

% chmod 750 * 
% chmod 640 */* 
% chmod 4750 bin/xace ; chmod 750 bin/tace 
% chmod 600 wspec/passwd.wrm 
% if (! -d PS) mkdir PS 
% chmod 770 PS  
% if (! -e logbook.worm) echo Installed, `date` $>$ logbook.wrm 
% chmod 640 logbook.wrm
the last two commands give group write access to the postscript directory and the log file.

Then only the administrator and the group members listed in wspec/passwd.wrm will have write access to the database and only the other members of his UNIX group will have permission to read the data.

1.5 Initialising the database

If your database directory is empty you must initialise the database. To do this, you must log in as administrator and own the database. If you want to reinitialise even when there is something there then remove the file ACEDB.wrm in the database directory, in which case next time you run it will reinitialise the whole database.

If possible, acedb uses semaphores to avoid write access conflicts. As of release 1_8, we use it only on the SUN (flag IPC in wmake/SUN_DEF). To see if this option is available on your own machine, type the command ipcs. If this command is recognized, the answer looks like this: 

% ipcs
IPC status from kaa as of Thu Mar 12 13:05:26 1992
T     ID     KEY        MODE       OWNER    GROUP
Message Queues:
Shared Memory:
Semaphores:
s      0 0x00000005 --ra-ra-r--     mieg    acedb
s      1 0x00000007 --ra-ra-r--     mieg    acedb
This means that semaphores 5 and 7 are beeing used. The limit is machine dependent, often 50. Then edit the file wspec/semkey.wrm. The format of semkey.wrm is comment lines starting with symbol # followed by a single line

SEM  = 7
Edit this seven to a small value not yet used, or to zero if ipcs is not recognized.

Run the system. The system should politely complain about some missing files, ask for a few confirmations, create some files, read in the models and ask if you want to quit. You can then exit and verify that the file permissions are set correctly according to whatever scheme you chose for granting authorisation (see above), or simply continue and chose the ``add update'' option of the main menu to read in all the official data.

1.6 Using acedb on several organisms

If you want to run ACEDB on several organisms, the best solution is to prepare in /usr/local/bin a collection of shell scripts with different name. The executable acedb prepared by the INSTALL script reads on my machine:

#!/bin/csh
setenv ACEDB /home2/mieg/worm
echo -n "ACEDB home directory : "
echo \$ACEDB
echo
/home2/mieg/worm/bin/acedb
To run on the arabidopsis data, I have a second script /usr/local/bin/aatdb which reads:

#!/bin/csh 
setenv ACEDB /home2/mieg/arabidopsis
echo -n "ACEDB home directory : "
echo \$ACEDB
echo
/home2/mieg/worm/bin/acedb
I run the same executable on the two sets of data. The 2 directories worm and arabidopsis each contain their own subdirectories database and wspec. It is essential that wspec/semkey.wrm specifies a different semaphore value (or zero) for each dataset.

1.7 Recompilation

 To recompile, you need to set 2 environment variables.

ACEDB_SRC must indicate the full path to the source directory, the (symbolic) parent of w1-9, wh, wspec, wmake, bin). Go to the directory where you have actually installed the code and type:

% setenv ACEDB_SRC ` pwd` # Note the back single quotes.
The second variable ACEDB_MACHINE must be such that wmake contains the file $(ACEDB_MACHINE)_DEF. That file contains specifications about the options you choose, the compiler, the libraries. Study the provided _DEF files and read the explanations at the beginning of the file wmake/truemake

We use ANSI C function prototyping, if possible, we use the GNU C compiler (gcc), and explicitly specify GNU's object library in the LIBS parameter of the _DEF file. Ours is in /usr/local/lib/gcc-gnulib.

The usual Sun C compiler is non-ANSI, but we use it for the final link to benefit from shared libraries. On Next, Silicon and Alliant, we use the native C. On IBM-6000 we use xlc. We compiled under the recent SUN ANSI-C compiler.

The options: IPC, WCS etc are explained in truemake. In particular, you may at compile time enable or disable the semaphore system. Removing -DIPC will disable it. This is needed on some machines where the semaphores have not been installed in the Unix Kernel. The point of IPC is that it absolutely guarantees that two different users can't gain write access to the database simultaneously. We use other approaches to try to ensure this doesn't happen, so it is extremely unlikely to be a problem, but only the IPC system is provably correct.

To actually recompile, go to the ACEDB home directory and make a symbolic link

% ln -s wmake/makefile makefile
Type make sunace to get the sunview version of the database program, make xace or simply make to get the X11 version, make tace to get the vt100 version. makefile itself is pretty small. It merely checks that the executable and database directories exist (see above), copies wmake/truemake into bin/makefile, changes directory to bin, and starts a new make with the same arguments it was called with. To support several architectures, mv bin elsewhere and make again after changing the environment variable ACEDB_MACHINE.

Notes if you are trying to cross-compile on another Unix X11 system:

We have compiled now on a number of systems. The instructions at the top of wmake/truemake should give a list of what has been tested and the problems we have met. You will need the standard X11-R4 libraries, including Xt and Xaw and a compiler that accepts ANSI C prototypes (ideally gcc, which is ported to many systems). If you have problems then please contact us. We may be able to provide an executable, or at any rate some help. In principle, you must write your own MACHINE_DEF file, edit wh/mystdlib.h to prototype correctly the system calls, edit mydirent.h because this file is not very standard accross Unix machines and hopefully touch nothing else. Note however that some compilers are more touchy than gcc about macros. So far, we only had a difficulty with IBM's xlc for the push and pop macros in array.h. If you met this problem add your machine name aside IBM in that file. On several machines, Silicon, IBM, the make command is less powerful than on the Sun. It happens that the source file are not transferrred as thy should from w1-9 to bin. In these situations, try the following:

% rm bin/*
% cp w*/*.c bin
% cp wmake/truemake bin/makefile
% cd bin
%make
Remember in the wh file to use the machine name as set by the variable NAME in the _DEF file, not as set by the environment variable ACEDB_MACHINE, which is just used to select the relevant _DEF file.

On a non Unix machine, you will probably have to edit w4/session.c On a non X11 platform, you must write your own graphic interface in w2. We provide X11, an obsolete Sunview, PostScript and Macintosh.

If you manage to port, please let us know.

1.8 How to get the latest release via ftp.

You are welcome to copy acedb from a friend, but if you have access to internet then it may be best to get your own version to be sure it is up to date. The latest version of this program is available by ftp from several public file servers.

In each case log in as user "anonymous" and give a user identifier as password. An example session would be:

% ftp crim.crim.fr
login: anonymous
password: your user id or email address
ftp> cd pub/acedb
ftp> binary
ftp> ls
ftp> get bin.sparc.1_8.tar.Z
ftp> get update.1-12.tar.Z
ftp quit
Notes on possible email corruptions:

If you receive code by email then known corruption problems are (i) tildas (~ signs, used for logical not in C) can change to something else (e.g. `c' when going from France to Stanford), (ii) sometimes long lines get cut. We try to keep lines under 80 chars long, but be warned (especially check models.wrm, which has some lines unavoidably longer than 80 chars).