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.
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.
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:
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.
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 DocBook XSL-NS (for DocBook V5.0 and later) stylesheets.
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 for P4.
As mentioned above for the DocBook stylesheets, use this option only if your catalogs cannot resolve the public identifiers properly. 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.
Specify the full path to the root directory of the TEI XSL stylesheets for P5.
As mentioned above for the DocBook stylesheets, use this option only if your catalogs cannot resolve the public identifiers properly. 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.
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.
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. You may have to change this name if you want to run two different versions of RefDB in parallel, or if you're not free to choose your database name. Although the main database name is configurable at runtime, you should use this option to initialize your refdbdrc configuration file, as it allows the refdb-init script to use the proper database name.
Selects the directory which holds SQLite/SQLite3 databases.
Specifies the full path to the jar file of the trang tool. You need this tool if you build RefDB from SVN sources, but not if you build from a tarball.
RefDB ships with prebuilt docs. However, if you build a SVN version, or if the documentation is otherwise screwed up, you may have to build them. Building the docs from the sources requires a couple of extra tools. You can use this configure switch to build the rest of RefDB without having to install these tools.
Use this switch if you want to build and install only the application server refdbd. This is mainly targeted at package builders.
Use this switch if you want to build and install only the clients but not the application server. This is mainly targeted at package builders.
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.
If your system keeps non-system header files in odd places, it may be necessary to set the CFLAGS environment 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
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 SVN version is guaranteed to compile on the author's development platform (currently FreeBSD 6.1), 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. SVN 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):
$~/buildsvn co https://svn.sourceforge.net/svnroot/refdb/refdb/trunk refdb
Other interesting modules to check out are perlmod (the Perl modules and the Perl client library) and elisp (the Emacs support files).
If you are interested in a particular repository version, release, or branch, use commands along these lines:
$~/buildsvn co --revision 324 https://svn.sourceforge.net/svnroot/refdb/refdb/trunk refdb-324svn co https://svn.sourceforge.net/svnroot/refdb/refdb/tags/Release-0.9.7 refdb-0.9.7svn co https://svn.sourceforge.net/svnroot/refdb/refdb/branches/back-to-a-1-branch refdb-a1-branch
If you want to keep track of the latest developments, you'll have to update your SVN working copy once in a while. Run this command from within the top-level source directory:
$~/build/refdbsvn update
Consider subscribing to the refdb-cvs mailing list as you'll be notified about each SVN checkin.
The SVN 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
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 and later are unusable for our purposes, you have to install the gnu-autotools package instead. You have to modify your PATH to pick up the latter, and fiddle with the m4 macro paths in order to see the light.
The SVN version also lacks a few other things which are included in the source tarballs. In order to create the missing stuff, you'll need the following additional tools:
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.
trang: a tool required to turn the RefDB DTDs into RelaxNG schemas.
To work around problems, you may want to use the following ./configure switches:
--with-trang-jar=PATH
--disable-docs
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 SVN 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 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 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.
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
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
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 --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].