Route de Mende, BP 5051, 34033 Montpellier, France
January 15, 1993
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:
% INSTALLor possibly
% source INSTALLif 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"
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.
% mkdir databaseThe 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.
% mkdir PS ; chmod 777 PSThe 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.
% latex xxx.tex % dvi2ps xxx.dvi | lprIf 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.
% `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,miegwhere 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.wrmthe 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
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 acedbThis 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 = 7Edit 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
#!/bin/csh setenv ACEDB /home2/mieg/worm echo -n "ACEDB home directory : " echo \$ACEDB echo /home2/mieg/worm/bin/acedbTo 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/acedbI 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.
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 makefileType 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 %makeRemember 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.
% 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 quitNotes 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).