This is version 1.54 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 one of these two locations:
ftp://ncbi.nlm.nih.gov/repository/acedb/
There are numerous performance enhancements and bug fixes in version
4.7 of ACEDB. Use of older versions of ACEDB is not recommended.
However 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 defintions have names
like ALPHA_4_GCC_DEF. Before setting the corresponding
environment variable, remove the "_DEF" from the end of the name.
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.
HINTS ON INSTALLING AN ACE SERVER
ACEDB comes with two servers called "aceserver" and "gifaceserver".
The difference between the two is that gifaceserver has the ability to
serve graphical pictures. Aceserver is text-only. In general, you
will want to use gifaceserver unless you know you will never need to
serve pictures.
A full description of installing (gif)aceserver is given in the ACEDB
distribution subdirectory wrpc/, in the file SERVER.INSTALLATION.
In order to get the server to start up automatically when it's needed,
you must modify two system files, /etc/rpc, and /etc/inetd.conf.
Here's my configuration:
* /etc/rpc:
... lots of existing entries...
elegans 200005
* /etc/inetd.conf:
... lots of existing entries...
elegans/1 stream rpc/tcp wait acedb /usr/local/bin/gifaceserver
aceserver /local/db/elegans 200005 1200:1200:0
The line has been wrapped to fit on the page. All inetd.conf entries
should be on a single line. Replace /usr/local/bin/gifaceserver with
the location of your aceserver binary, and /local/db/elegans with the
location of your ACE database.
You may need to kill the inetd daemon completely and restart it in
order to have the server come up correctly the first time. At least I
did. After that it will come up whenever it is needed and exit after
it has idled for the timeout period specified on the command line.
(gif)aceserver has a problem on many Solaris systems. The symptom of
this problem is that the server launches, but fails to respond to
requests. The solution to this problem is to install the binary
distribution of ACEDB for solaris, or to follow the directions given
in the SERVER.INSTALLATION file.
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.
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
January 21, 1999