This is version 1.70 of AcePerl, a Perl interface for the ACEDB object-oriented database. Designed specifically for use in genome sequencing projects, ACEDB provides powerful modeling and management services for biological and laboratory data. For others, it is a good open source introduction to the world of object-oriented databases See the ChangeLog for important notices, including recent user interfaces changes. Please see DISCLAIMER.txt for disclaimers of warranty. INSTALLATION: AcePerl comes with all the code needed to communicate with a remote ACEDB server. No additional software is required. However, if you wish to communicate with your own ACEDB database, you must use ACEDB version 4.7c or higher, available from this location: ftp://ncbi.nlm.nih.gov/repository/acedb/ However, to take full advantage of the sequence annotation features in the Ace::Sequence and Ace::Sequence::Feature classes, you will need version 4.8c or higher. It can be obtained from the Sanger FTP site at ftp.sanger.ac.uk. Version 4.8 of Aceserver adds support for Berkeley sockets. It is highly recommended that you use it if you are not already reliant on an earlier version of the server. This release of AcePerl fully supports the new socket interface. This advice only applies to the aceserver, gifaceserver and tace applications. You may use older versions of the graphical xace application freely, as this does not interact with AcePerl. If you wish to use AcePerl in a client-server fashion, you must get gifaceserver up and running. Some hints on installing the gifaceserver application are given later in this README. Follow these steps to unpack, build and install AcePerl: 1. Unpack the AcePerl distribution with this command: gunzip -c AcePerl-X.XX.tar.gz | tar xvf - Replace X.XX with the current version number of AcePerl. 2. cd AcePerl-X.XX 3. perl Makefile.PL Among other things, the Makefile.PL script will attempt to guess the type of your machine and its operating system. This information is needed to select the correct makefile in the ACEDB library directory, AcePerl-X.XX/ace/. If AcePerl fails to make correctly later in the process, it may be because the script guessed wrong. You can override this guess by setting the machine type using the ACEDB_MACHINE environment variable. On a C-shell or TC-shell machine, use a command like this one: setenv ACEDB_MACHINE ALPHA_4_GCC; perl Makefile.PL On a Bourne-shell or Korn-shell system, use: ACEDB_MACHINE=ALPHA_4_GCC; export ACEDB_MACHINE perl Makefile.PL You can find a list of machine definitions in AcePerl-X.XX/ace/wmake. There are lots of them, but only one or two per operating system, so it's usually pretty easy to choose the right one. The definitions have names like ALPHA_4_GCC_DEF. Before setting the corresponding environment variable, remove the "_DEF" from the end of the name. In case you're wondering the "4" stands for version 4 of the ACEDB server. Please drop me a line to let me know what you had to do to get the ACEDB libraries to compile. I'll fix up the Makefile so that it works correctly for the next person who tries it. 4. make This will build the ACEDB client library, libaceperl.a, in the ace subdirectory. It will then link in the Perl client subs. 5. make test (optional) You may "make test" to test the system. It will attempt to open a connection to a database at beta.crbm.cnrs-mop.fr:20000100. You may change these defaults by setting the environment variables ACEDB_HOST and ACEDB_PORT, or by defining them on the command line, as in: make test ACEDB_HOST=localhost ACEDB_PORT=200005 However, since some of the tests are dependent on specific values in the database, this may cause some tests to fail. Do not be alarmed if a handful of tests fail. Do be alarmed if all of the tests fail. 6. make install This will install AcePerl into your perl5 library directory. You may need to be root (superuser) in order to "make install". This is because Perl will want to install the newly-built files into its library tree, /usr/local/lib/perl5/site_perl (or something similar), and this tree is usually not writable by mere mortals. Do not despair: see the next section. INSTALLING ACEPERL IN A NON-STANDARD LOCATION By default, Perl will install AcePerl's library files within the site-specific subdirectory of its library tree, usually /usr/local/lib/perl5/site_perl. If you wish, you can install the library files elsewhere. Simply change to the AcePerl distribution directory and run the Makefile.PL script with the INSTALLSITELIB switch set to the full path of the directory you want to install into: perl Makefile.PL INSTALLSITELIB=/path/to/library Then "make" and "make install" as described before. You will now have to tell Perl where to find AcePerl. You can do this on a script-by-script basis, or by defining an environment variable that will affect all scripts. To tell a single script where to find AcePerl, add a "use lib" line to your script. Put it _before_ the "use Ace" line: use lib /path/to/library; use Ace; To change Perl's library search path so that it finds AcePerl automatically, define the PERL5LIB environment variable in your .login, .cshrc or .profile script. PERL5LIB is a colon-delimited list of directories in which Perl will search for included libraries. For example: setenv PERL5LIB "/path/to/library"; If AcePerl was built as part of the main Ace distribution, you will want to define PERL5LIB to be the location of the machine-specific build directory. For example: setenv PERL5LIB $HOME/ace/bin.LINUX_4_OPT Or you could reinstall AcePerl in the main Perl library tree just by entering the wperl/ subdirectory, and rerunning "perl Makefile.PL" without defining INSTALLSITELIB. See ACEDB.HOWTO in the docs/ subdirectory for instructions on obtaining and setting up the ACeDB database. You'll find other hints here too. USING ACEPERL A. Read the copious documentation perldoc Ace B. Review the examples A few useful examples can be found in the "examples" subdirectory. Among these is a script called "ace.pl", which implements a text interface to any local or remote ace database. If you have the Perl Term::readline module installed, it gives you command-line editing, completion, and history. The script "dump_cdna.pl" shows you how to dump out all spliced cDNAs from wormbase.org. Other dump scripts show similar tricks. You can use these as templates for doing other biologically interesting tricks. There is also family of CGI scripts that run on top of AcePerl to give a WebAce-like interface to Ace (it is not as feature-full as WebAce, but it is probably easier to set up and run). You can find the package at this URL: http://stein.cshl.org/AcePerl/AceBrowser Lincoln Stein lstein@cshl.org