refdb was designed with portability in mind. Thanks to the GNU autotools installation on many Unix variants is straightforward, others need only a little tweaking. The following instructions provide a guideline for all Unix-like systems. Please see also the hints for specific operating systems at the end of this section.
These instructions assume that the following software is installed and functional on your computer or on your network before you start:
A SQL database engine. For an external database server, choose between MySQL (version 3.23 or later) or PostgreSQL (version 7.1 or later). The database server does not have to physically run on the box(es) where you plan to install refdb, it is sufficient if it is accessible through the network.
If you prefer an embedded database engine, please use SQLite instead.
As far as non-standard libraries and header files are concerned, you'll need the readline library and headers (available at the GNU FTP site). Database access requires the libdbi library and headers as well as the libdbi-drivers package. Furthermore, you`ll need the expat library. If you need the BibTeX import filter, you'll also want to have the btparse library.
Note: Some operating systems/distributions use separate packages for the run-time libraries (ususally .so files) and for the development libraries (usually .a files). In order to build and run refdb, you need both packages for each library.
If you want to import Pubmed or MARC datasets, please get the refdb-perlmod package. This collection of Perl modules is required to run the Pubmed and MARC import filters shipped with refdb. These Perl modules in turn depend on MARC::Record, MARC::Charset, XML::Parser, and Text::Iconv, available at CPAN.
Note: The installation steps proper (as opposed to the build steps) should be run with root privileges.
Unpack the archive in a convenient directory: tar -xzf refdb-x.y.z.tar.gz (the actual filename depends on the version).
If you do not want to build in the source directory, create an empty build directory.
cd into the new refdb-x.y.z source directory or into your separate build directory
Use ./configure --help to see a list of things you can customize. If you use a separate build directory, use the relative path to configure in the source directory. Some important options are:
Note: All paths and URLs in the following options should be entered without a trailing slash.
By default, all files will be installed in the /usr/local tree. Use this option to use a different install root, e.g. /usr or /opt.
The data files will be installed in /usr/local/share/refdb unless you use this option. The data will be installed in the directory DIR/refdb. That is, specifying "--datadir=/usr/local/share" is equivalent to the default behaviour. The configuration variable refdblib (which will be automatically generated in the example configuration files) must point to the refdb data directory.
The global configuration files will be installed in /usr/local/etc/refdb unless you specify a different directory here.
Use this option to specify the directory that contains the libdbi library if it is not in the default library path.
Use this option to specify the directory that contains the expat library if it is not in the default library path.
Use this option to specify the directory that contains the btparse library if it is not in the default library path.
Specify the full path to a suitable SGML declaration for your SGML files. If this option is not used, refdb will use its own copy of docbook.dcl stolen from the DocBook DTD distribution. This SGML declaration also works for a variety of other DTDs.
Specify the full path to xml.dcl which is the SGML declaration for XML files. If this option is not used, refdb will use its own copy of xml.dcl which should work just fine.
Specify the full path to the root directory of the DocBook XSL stylesheets.
Note: This option is required only on systems that do not maintain XML catalogs. If your system is set up properly to resolve public identifiers like those in the XSL stylesheets by XML catalogs, leave out this option. configure checks whether the required stylesheets are accessible, so watch out for error messages. If the stylesheets can't be found, either install them, fix your catalogs, or use this option to hardcode the path.
Specify the full path to the root directory of the TEI XSL stylesheets.
Note: The TEI Consortium ships tei-xsl-5.2.9.zip which contains the stylesheets for both p4 and p5. The root directory which you want to specify here is the directory which contains the p4 and p5 subdirectories, e.g. /usr/local/share/xsl/tei-xsl-5.2.9.
The refdbxml script assumes that all Java classes for the Java parsers and xslt engines are stored in a class repository, i.e. all in the same directory. Specify this directory with this option. If you keep the relevant Java classes in different directories, either create symlinks or customize refdbxml manually.
The HTML files and templates for the web interface require absolute URLs matching your web server setup. Specify the URL of the directory that contains the refdb HTML files. If you follow the Apache setup instructions in this manual, this will be a string like "http://www.mycomp.com/refdb", where "www.mycomp.com" is the hostname of your computer running Apache and "refdb" is the directory alias used for the refdb web pages.
Note: This URL affects the links in the HTML files and templates. A wrong or missing value of this URL will break the navigation as well as the access to stylesheets and javascript files.
Use this option to specify a directory where refdbd can write its PID file (a file containing the process ID). By default, /var/run will be used.
Use this option to specify a directory where refdb programs can write log files to, if logging is directed to a custom file. By default, /var/log will be used.
By default, all configuration files are preconfigured for use with the MySQL database server. Use this option to preconfigure the configuration files for a different database server (currently mysql, pgsql, and sqlite are recognized as values for DBS).
Note: This option does not modify the binaries that you will create. These will work with all supported database engines regardless of what you select here. The only things affected by this option are a few settings in the refdbdrc configuration file. You can change them after the installation anytime.
refdb uses one main database to store citation styles and other stuff. There is exactly one such database per installation with the default name refdb. The only reason to change this name is if you want to run this and an older, incompatible version of refdb in parallel.
Some of these options are used to customize the shell scripts, XSL stylesheets, example configuration files, and HTML files which are part of refdb. If you do not specify these options now, you can still build and install the package, but you will have to customize the scripts and stylesheets manually in order to make them work. Doing it now is much easier. You've been warned.
Start the configuration with the command ./configure, specifying any additional options as you may need. Use the relative path to configure in the source directory if you build in a separate directory.
Note: If your system keeps non-system header files in odd places, it may be necessary to set the
CFLAGSenvironment variable before you run configure. E.g. if headers like expat.h are stored in /usr/local/include, you should run CFLAGS="-I/usr/local/include" ./configure instead, specifying additional options as necessary.
make
Note: The autotools-generated Makefiles apparently prefer (or require?) GNU make. If make results in spurious error messages about the Makefile syntax, try to run gmake instead as your regular make is apparently not the GNU version.
make install
This will install the binaries and scripts in /usr/local/bin and the data in /usr/local/share/refdb unless you chose different directories in the configure step. Again, run gmake install instead if your regular make is not the GNU version.
To finish the installation, please follow the instructions in the section Finishing the refdb installation below.
If this procedure results in strange error messages, you probably use a platform that is not supported yet. The author appreciates a porting effort or a description of the problem (in this particular order).
While the official release versions of refdb are your best bet to get a stable installation, you may be interested to test the latest developments "in statu nascendi". The CVS version is guaranteed to compile on the author's development platform (currently FreeBSD 5.4), but may fail on other platforms. Known bugs may have been fixed, but new ones may have crept in as well. New features may be implemented, but might not be without problems. You've been warned. If you still want to go ahead, this is what you need to do:
Change into a suitable directory. CVS will create a subdirectory called refdb during the following steps
Run the following command (adapt this accordingly if you use some graphical CVS frontend instead of the command line tool):
$~/build cvs -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/refdb login |
Just press enter if you're asked for a password. This login is required only once as CVS will remember the required information for all later accesses.
Check out the latest refdb sources with this command:
$~/build cvs -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/refdb -z3 checkout refdb |
This will retrieve the HEAD code which is pretty much experimental and unlikely to work at the moment. The more usable stable branch, which receives most of the current development work, can be retrieved with this command:
$~/build cvs -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/refdb -z3 checkout -r Release_0_9_5_stable refdb |
Other interesting modules to check out are perlmod (the Perl modules and the Perl client library), makestyle (the Perl script to write bibliography styles from scratch), and elisp (the Emacs support files).
If you are interested in a particular release or branch, use a command along the lines of this example instead:
$~/build cvs -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/refdb -z3 checkout -r Release_0_9_4 refdb |
If you want to keep track of the latest developments, you'll have to update your CVS version once in a while. Run this command from within the top-level source directory:
$~/build/refdb cvs update |
Consider subscribing to the refdb-cvs mailing list as you'll be notified about each cvs checkin.
The CVS version lacks all autotool-generated files. You'll have to create them with your local autotools. refdb contains a small script called autogen.sh in its top-level directory which performs all necessary steps.
$~/build/refdb ./autogen.sh |
Note: The autotools can cause severe headaches at times. If the above command causes errors, read autogen.sh and run the commands manually, substituting different versions as appropriate. E.g. substitute automake with automake-1.8 if this gives better results. The native autotools shipped with FreeBSD 5.4 are unusable for our purposes, you have to install the gnu-autotools package instead. You have to modify your
PATHto pick up the latter, and fiddle with the m4 macro paths in order to see the light.
The CVS version also lacks a few other things which are included in the source tarballs. To rectify this, you may have to use the following additional ./configure switches:
The CVS sources contain the DTDs from which you have to build the RelaxNG schema files if you need them. Pass the full path of trang.jar to this option. If not specified, the .rng files will be mere copies of the DTD files.
The refdb manual is not built by default. Use this switch to generate the documentation from the sources. In order to successfully build the docs, you need the following tools installed:
OpenJade: the DSSSL engine used to transform the sources
JadeTeX: a TeX macro package used to generate printable output
TeX: the typesetting engine used to generate printable output
Batik SVG Rasterizer: an image converter used to create the images from the SVG sources. The Makefile calls a script in your path called batik-rasterizer which is supposed to run this Java application appropriately.
dtdparse: A Perl script (which in turn depends on a few Perl modules, see the installation instuctions) which generates the DTD documentation.
Finally you're ready to build refdb like you would with a released version.
There is also a neat shell script available on the refdb download page which helps you to keep a CVS version up to date with a minimum number of keystrokes.
This is all it takes to run refdb from the command line. If you want to start refdbd as a daemon at system startup, a few more steps are necessary. The exact procedure varies greatly between operating systems and distributions. First we'll look at SysV-style systems (most Linux distributions), then at BSD-style systems (BSD-derived Unices and the Slackware Linux distribution).
The following procedure describes the setup on a Debian GNU/Linux 2.2 system. With a little help of your system handbook you should be able to adapt this to your system. On many systems /etc/init.d/README contains just what you need to know or at least it points you to the correct resources.
Review the parameters in the script refdb in the scripts directory of the source distribution (this file is not automatically installed). If necessary, change the paths and names to your needs and adapt the following steps. Make sure the BSDSTYLE variable is set to "NO" (this is the default value).
Copy the script refdb to /etc/init.d/ and make sure it is executable: chmod 755 /etc/init.d/refdb.
Create symbolic links from every runlevel directory that should start refdbd to /etc/init.d/refdb, e.g. ln -s /etc/init.d/refdb /etc/rc2.d/S93refdb. The numbers in the link names are a convenient and simple way to determine the sequence of daemon starts. As most likely no other daemons rely on refdb, you can choose as high a number as you want (the daemons are started in lexicographical order).
In analogy to the previous step, generate symbolic links in every runlevel directory that should stop the daemon. Usually these are the runlevels 0 (system halt) and 6 (reboot):
ln -s /etc/init.d/refdb /etc/rc0.d/K20refdb
ln -s /etc/init.d/refdb /etc/rc6.d/K20refdb
Review the settings in the script refdbctl which by default is installed in /usr/local/bin/. Most likely the script was properly customized for your system in the build step so you don't have to change anything.
When you boot, halt, or reboot the system you should see messages on the screen telling you that the daemon has been started or stopped successfully. If you don't, please check again all paths in the scripts, the file permissions, and the runlevels you're looking at. Try to run the control script from the command line, e.g. refdbctl start, to distinguish between general setup problems and init-related setup problems.
The following procedure describes the installation on a FreeBSD 4.3 system. Other systems might differ somewhat, but you should get the idea.
Review the parameters in the script refdb in the scripts directory of the source distribution (this file is not automatically installed). Set the value of the script variable BSDSTYLE to "YES" (the sole purpose of this variable is to make the boot message blend in seamlessly, if you happen to care for aesthetics). If necessary, change the paths and names to your needs and adapt the following steps.
Copy the script refdb to /usr/local/etc/rc.d/refdb.sh and make sure it is executable: chmod 755 /usr/local/etc/rc.d/refdb.sh.
Note: The suffix .sh is mandatory on BSD-style systems.
Review the settings in the script refdbctl which by default is installed in /usr/local/bin/. Most likely the script was properly customized for your system in the build step so you don't have to change anything.
When you boot, halt, or reboot the system you should see messages on the screen telling you that the daemon has been started or stopped. If you don't, please check again all paths in the scripts and the file permissions. Try to run the control script from the command line, e.g. refdbctl start, to distinguish between general setup problems and system-related setup problems.
This section contains a few hints about the installation on some popular Unix-like operating systems.
The generic instructions should work out of the box for most if not all Linux distributions.
Debian keeps all configuration files in /etc and subdirectories thereof which makes backing up the configuration of the whole box a breeze. To support this nice feature, you want to add --sysconfdir=/etc to your configure options. The configuration files will then be in /etc/refdb. The following is an example of a complete configure call that works on Debian 3.0 (the line was split into several lines for the sake of clarity; type everything on one line and skip the backslashes):
#~ ./configure --sysconfdir=/etc \ --with-docbook-xsl=/usr/share/sgml/docbook/stylesheet/xsl/nwalsh \ --with-tei-xsl=/usr/local/lib/sgml/stylesheet/xsl \ --with-refdb-url=http://localhost/refdb |
The BSD version of make cannot handle the autotools-generated Makefiles correctly. Use gmake instead, and set CFLAGS=-I/usr/local/include during the configuration step. The full configure command, using the default installation paths for the accessory files and programs, looks like this:
#~ CFLAGS=-I/usr/local/include ./configure --with-expat-lib=/usr/local/lib \ --with-classpath-root=/usr/local/share/java/classes --with-refdb-url=http://localhost/refdb |
The shared data end up in /usr/local/share/refdb, the configuration files will be in /usr/local/etc/refdb.
The BSD version of make cannot handle the autotools-generated Makefiles correctly. Use gmake instead, and set the following environment variables before running ./configure:
#~ setenv CFLAGS "-I/usr/pkg/include -I/usr/local/include -L/usr/pkg/lib" |
#~ setenv LDFLAGS "-L/usr/pkg/lib -R/usr/pkg/lib -R/usr/pkg/lib/mysql" |
#~ ./configure --with-mysqlclient-lib=/usr/pkg/lib/mysql --with-btparse-lib=/usr/local/lib --with-refdb-url=http://localhost/refdb --prefix=/usr/pkg |
Use additional options as needed. The shared data will end up in /usr/pkg/share/refdb, the configuration files go to /usr/pkg/etc/refdb.
Both the standard C compiler and the standard make program will not give the desired results when building refdb. Use gcc and gmake instead.
Use fink to conveniently install all the additional software needed. Then help configure find the fink-installed packages in /sw by setting the following environment variables: CFLAGS="-I/sw/include" LDFLAGS="-L/sw/lib" ./configure [your_options].