========================================================================= ACEDB: A C.elegans Database R. Durbin and J. Thierry-Mieg (supporting cast: Ed Griffiths, Simon Kelley, John Sturdy) Last updated: 23 Avril 2001. ========================================================================= ------------------------------------------------------------------------- List of distribution files README brief list/description of files NOTES this file INSTALL first time installation script ACEDB-BuildVersion.shtml machine generated file summarsing build details for this release. All other files are tar'd/gzip'd files files with the common file suffix of .V_RU.tar.gz where V = AceDB version, R = AceDB release and U = AceDB update level, e.g. .4_9a.tar.gz ACEDB-binaryXXXXX.V_RU.tar.gz executables for various platforms including Dec ALPHA, Intel LINUX, Silicon Graphics SGI and Sun SOLARIS. (Other ports can be compiled by getting the source code and compiling.) Also contains documentation, tools and other useful stuff. ACEDB-serverXXXXX.V_RU.tar.gz server executables for various platforms including Dec ALPHA, Intel LINUX, Silicon Graphics SGI and Sun SOLARIS. (Other ports can be compiled by getting the source code and compiling.) Also contains documentation, tools and other useful stuff. (see comments below for explanation of "STATIC" binaries) ACEDB-demo.4_9a.tar.gz ACEDB-demo.4_9a.exe a demonstration database, based on the C. elegans database for you to try out. (The .exe file is for easy installation on Windows) ACEDB-doc.4_9a.tar.gz various documentation files, in particular WRITE_ACCESS, which explains about how to manage write access for multiple users. ACEDB-help.4_9a.tar.gz all of the online help files available from xace. ACEDB-source.4_9a.tar.gz a complete build tree for all AceDB programs including the makefile + variations for different platforms. ACEDB-tools.4_9a.tar.gz a collection of shell, perl, python programs for working with AceDB. ACEDB-windows.4_9a.exe The AceDB for Microsoft windows installer. This includes everything in the binary, server, doc, help and tools files above. All files except NOTES, README and INSTALL and the windows .exes are tar.gz files. They will be uncompressed and untarred automatically by the INSTALL script if you are using it to install, which is recommended. Note that the binary files come in two flavours, STATIC and non-static versions. The acedb programs make use of the following GNU Software libraries: readline, Glib, GDK, GTK. If you know your system already has these installed then you can download the non-static versions which are smaller and quicker to download. If your system does not have these libraries installed then you can either: - download the static binaries which include these libraries and then you can just run the programs - or you can install readline, Glib, GDK & GTK on your system and then download the non-static binaries. If you are uncertain about this then you should contact your system administrator, or if you don't have one you can: ask on the acedb newsgroup (send mail to bionet-software-acedb@net.bio.net) ask the acedb developers (send mail to acedb@sanger.ac.uk) ******* IMPORTANT ******* When downloading code/help files for an existing database, the Version number of what you are downloading should match the Version number of your database. You can find out the version of your database using the "Program Status" item of the "Admin" menu button on the xace main window. If this is not so, you will need to dump your database into ace files and then rebuild it using the new code. ******* IMPORTANT ******* ------------------------------------------------------------------------- Current state of the system The current release, is 4_9a. This new release is fully compatible with 4_7 & 4_8. The new release also includes a windows version. There is a new client/server package which makes use of TCP sockets rather than RPC and so is portable to Windows. The new client/server also uses a user/passwd system to give users access to the database rather than the previous system of shared files. This means that users on remote sites can be given controlled access to the server and database. The RPC server is not available in 4_9. The new release also incorporates the new AQL query language that allows much finer grained and more complex queries than the existing query language. Thus, we strongly urge you to upgrade from 4_7 or 4_8 to the new 4_9. Note that this software comes under the GNU General Public License, this means that its free and that you can do lots of things with it but that you should not try to make money from it. See the file wdoc/GNU_GENERAL_PUBLIC_LICENSE in this distribution or go to http://www.uk.gnu.org/ to see the original copy. Note especially that this software does not come with any guarantee of any kind. ------------------------------------------------------------------------- How to get the latest release 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. You can get the latest version in several ways: 1) Visit the downloads pages at the AceDB web site: http://www.acedb.org/Software/Downloads/ 2) Visit one of several ftp sites on public servers. In each case log in as user "anonymous" and give your userid as password. - ncbi.nih.gov (130.14.20.1) in the USA, in repository/acedb - ftp.sanger.ac.uk in England, in pub/acedb Under each of these there should be archives for binaries, tools, source code, help files, documentation. An example session would be: # comments ftp ncbi.nlm.nih.gov login: anonymous password: your user id or email address cd repository/acedb # change to relevant directoy binary # IMPORTANT dir # display files in this directory get README get NOTES get INSTALL get ACEDB-help.4_9a.tar.gz # get help files archive quit ------------------------------------------------------------------------- How to install AceDB on UNIX If installing for the first time, make a new home directory for AceDB and place all the .tar.Z files you need plus INSTALL into this directory. The INSTALL script will install packages in your current working directory, it will install the package as a sub-directory of the current directory. If such a directory exists you will be given a chance to not install that package or abort the install altogether. Since all packages are installed in sub-directories you should not INSTALL In our default configuration the AceDB database can only be updated by the user who installed it. If you want other people than the installer to be able to edit AceDB, please read the document WRITE_ACCESS (in doc/). IMPORTANT: DO NOT INSTALL AS ROOT: this would create a security loophole. ------------------------------------------------------------------------- How to build AceDB on UNIX You need to install the source code on your system (see above). From 4_8 onwards, AceDB makes use of the following GNU software: readline, Glib (all AceDB programs) GDK, GTK (graphical programs only) If these are not already installed on your system then either you can get and install them, or you can use private copies which come with the AceDB source (they are in the w3rdparty subdirectory). The latter option is simpler if you just need these libraries for AceDB, but if you might need then for anything else it is better to install a shared copy. If you want to install the libraries you can down load the single GTK+ package from from www.gtk.org which includes Glib, GDK and GTK. Note that AceDB needs the 1.2.x version, where x is the latest release. You can get readline from ftp://ftp.gnu.org/gnu/readline, make sure you get readline 4.x. (If you are running linux, your distribution will certainly have packages for all of these, don't forget to install the -dev packages as well as the run-time ones.) Building AceDB with the private copies of the GNU software: ----------------------------------------------------------- > cd directory_where_you_installed_source_code > setenv ACEDB_MACHINE something_like_ALPHA_4 (see available files in wmake/) > make all_static Building AceDB with the system wide copies of the GNU software: --------------------------------------------------------------- The system wide copies will have been put in directories that the compiler searches by default so you can build AceDB more simply: > cd directory_where_you_installed_source_code > setenv ACEDB_MACHINE something_like_ALPHA_4 (see available files in wmake/) > make all If the above descriptions, "make all" & "make all_static" will make all the executables for AceDB. If you want to build single programs then you should do the following (the example builds tace and xace but you could select any combination of the acedb programs): Building single programs with the private copies of the GNU software: --------------------------------------------------------------------- > cd directory_where_you_installed_source_code > setenv ACEDB_MACHINE something_like_ALPHA_4 (see available files in wmake/) > make gnulibs > make tace xace Building single programs with the system wide copies of the GNU software: ------------------------------------------------------------------------- The system wide copies will have been put in directories that the compiler searches by default so you can build AceDB more simply: > cd directory_where_you_installed_source_code > setenv ACEDB_MACHINE something_like_ALPHA_4 (see available files in wmake/) > make tace xace The above examples assume that you either want to build using the private copies of the GNU software of the system wide copies. If you want to switch from doing one to doing the other you should first "clean" out existing binaries/libraries by doing this: > make clean ------------------------------------------------------------------------- How to install AceDB on MicroSoft-Windows The installation of AceDB on Microsoft Windows is very simple. Download the installer from http://www.acedb.org/Software/Downloads/ and run it. The simplest way to so this is probably to download the installer onto the desktop, and then double-click on its icon. You will then be launched into a standard windows installshield-type interactive installation which will install all the AceDB files and make entries for AceDB in your start menu. AceDB has been tested on Windows 95, 95, and NT by us. It is known to be functional as well in W2k and Windows ME. ------------------------------------------------------------------------- Macintosh version *** No New Version *** The Macintosh version has not been updated for a least 3-4 years, we hope to produce a fully compatible version once the new Unix-like version of the OS-X operating system is stable. This may initially only be the command line versions of the program, e.g. tace, giface, client/server. The older version of AceDB is still available from the ftp site, look in the /pub/acedb/macace directory. You need a Macintosh with absolute mimimum 16Mb of memory and a decent monitor. You also need some way of obtaining the files from an ftp site (e.g. Mosaic, Netscape, NCSA telnet, Versaterm Pro...). Please note that this version is totally unsupported. ------------------------------------------------------------------------- Directory structure You will typically have $ACEDB (the home directory) layed out something like as follows: acedb # executable script to be moved in /usr/local/bin textace # executable script to be moved in /usr/local/bin database/ ACEDB.wrm # little file needed for AceDB to run block1.wrm # the database block2.wrm etc. "" database.map # info on all the block* files log.wrm # log file # all these files in database/ are only created after # running AceDB the first time bin/ # the executable(s) xace # X graphics version (usual interface) tace # command line version acediff # for comparing two ace files wspec/ # database dependent specification files. GraphPackage # X resources file - not needed cachesize.wrm # You may want to edit this file copyright options.wrm # You may want to edit this file database.wrm # specifies chunk sizes to split the database into displays.wrm # You may want to edit this file models.wrm # database schema help.wrm # help passwd.wrm # User access control - see doc/WRITE_ACCESS server.wrm # control file for server/client version subclasses.wrm # subclass schema information xfonts.wrm # Edit this to change screen fonts psfonts.wrm # Edit this file to change printing fonts rawdata/ update files The minimal requirements for running AceDB are that the database/ and wspec/ directories exist, and wspec/ contains cachesize, options, displays, models, passwd. The files in database/ will be made as necessary by the program - do not try to edit them yourself. For update files to load properly they must be in $ACEDB/rawdata. The executables can be somewhere other than $ACEDB/bin. Sites with multiple AceDB databases can use the same executables for all of them. Conversely, the same database files can be read by executables for multiple machine types (at least within Unix systems), which will require some reorganising of directories and/or file names. To run the program you must either set the environment variable ACEDB to the absolute path to the ACEDB home directory (by e.g. "setenv ACEDB ~acedb"), or make the home directory the first argument of xace or tace on the command line (e.g. "xace ~acedb"). Of course xace must be in your path. All this is done most easily by moving the shell scripts acedb and textace prepared by the INSTALL script into /usr/local/bin, where they are set up for any user, who can then type "acedb" or "textace" to run the X or command line versions, respectively. ------------------------------------------------------------------------- Help system The help system has been revised. We know have an in-lined html viewer for local files. It is much fatser than Mosaic, and defaults to Mosaic (or netscape as defined in wscripts/Mosaic) on http references. The help pages will be searched 1) in $ACEDB/whelp/*.html, 2) in wspec/help.wrm. In case 1, we use the Prilusky system so you can register help to a particualr class or tag in trre displays for axemple wdir/Tree_Author_Paper.html, gives help oon tag paper in class Author in Tree display. ------------------------------------------------------------------------- Server Client AceDB now has a socket version of the server client which is much better integrated with AcePerl. The new version also offers proper user id/password facilities so that the client/server can be used for controlled access across the internet. You can download the server/client separately using the ACEDB-serverXXXXX.V_RU.tar.gz archives. There is a user guide to setting up/using the new socket server in: wdoc/SOCKET_aceserver.html and a programmers guide to how to communicate with the socket server in: wdoc/SOCKET_interface.html You should read the former if you want to run saceserver and saceclient, and the latter if you want to write a client of your own. ------------------------------------------------------------------------- X-client in test There is also a sockets version of the X-client in test. This gives a graphical AceDB, without loading all the data. To use it, you must first compile it (setenv ACEDB_SRC `pwd` ; setenv ACEDB_MACHINE ..) then (make xclient). Then you initialise a database on the current source code distribution models with xace, but do not load any data. Then you start xclient. Because that address is given in wspec/server.wrm, you will automatically download data from Montpellier. If you then save and run xace, you will work locally with the same data. But each time you start xclient, you load again from the network. I would lie to know a) if it works at all, b) if it is useful, c) how it should be improved. ------------------------------------------------------------------------- WWW interface There are now several ways to serve the web: For Perl based AceDB web serving see AcePerl/AceBrowser at http://stein.cshl.org/AcePerl/ http://stein.cshl.org/AcePerl/AceBrowser/ For Java based AceDB see jadex at http://stein.cshl.org/ ------------------------------------------------------------------------- Known problems: ALPHA builds ------------ If you running on an alpha which has operating system vervion 4.0, update 1229 or later you may find that acesocket.c will not compile, the compiler will complain about not being able to find the type "socklen_t". This is because DEC have decided to change the way this type is included in /usr/include/sys/socket.h. You need to do your make like this: make USEROPTS='-D_POSIX_PII_SOCKET' saceserver sgifaceserver saceclient and then these programs (which are the only ones that require acesocket.c) should compile. You get the operating system version like this: adnah[edgrif]46: uname -a OSF1 adnah V4.0 1229 alpha Lock file problems ------------------ On some machines the lock file mechanism does not appear to work correctly, so that no data can be read in (not even enough to bootstrap initialisation). You will see a message "Don't-know-who (session 0) already has write access" even before the database exists. To defeat the file locking mechanism, set the environment variable ACEDB_NO_LOCK before starting the program (e.g. "setenv ACEDB_NO_LOCK"). Of course if you do this you are responsible for making sure that two people do not try to update or edit the database at the same time. Alternatively, create a fake user "NOLOCK" in the wspec/passwd.wrm file. ------------------------------------------------------------------------- Additional Information An on line help file is contained in ${ACEDB}/wspec/help.wrm and is activated by the help option in the menu, or by function key F1 or F10, or, on a Sun under twm, the help key. Some documentation files are available in the doc/ subdirectory of the distribution. Amongst these, the nicest general user guide is angistute, which was written by Bruno Gaeta of the Australian National Genome Information Service, and is available as a compressed Unix postscript file (angistute.ps.Z) and a Macintosh Word binhex/stuffit compressed file (angistute.sit.hqx). Although written for version 2 AceDB, this is still very relevant for most uses. Further information is available in files in the wdoc/ subdirectory of the source distribution, and via the AceDB website at: http://www.acedb.org/ ========================= end of file ===================================