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:
MySQL version 3.22 or later. This does not have to physically run on the box(es) where you plan to install refdb, it is sufficient if the MySQL server is accessible through the network.
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) and the mysqlclient library and headers. You can either get the sources (at www.mysql.com) and build the library yourself or you pick the precompiled library and the development files from your OS distribution, if available. 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 plan to use the refdb web interface, you'll also need a web server like Apache. Again, this may be running on some other box in your network.
MySQL and Apache (as well as a variety of other web servers) are available as source, .tar.gz archive, and as rpm and deb packages, so one of these should work on your system.
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, the binaries and the data files will be installed in the /usr/local tree. Use this option to install the stuff somewhere else, e.g. in /usr or in /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) or the environment variable REFDBLIB must point to the refdb data directory.
The global configuration files will be installed in /usr/local/etc unless you specify a different directory here.
Use this option to specify the directory that contains the MySQL client 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. In the case of DocBook documents, use docbook.dcl which is part of 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. This file is part of the Jade and OpenJade distributions.
Specify the full path to the root directory of the DocBook XSL stylesheets.
Specify the full path to the root directory of the TEI XSL stylesheets.
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 where the HTML files will be installed. This should be a string like "http://www.mycomp.com/refdb".
Note: This URL affects only the links in the HTML files. You will still have to install the HTML files manually into that location (the web server might run on a different computer).
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.
The last eight 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 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
Note: The autotools-generated Makefiles apparently prefer (or require?) GNU make. If make results in spurious error messages about a 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).
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". 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.
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 (the line was split into several lines for the sake of clarity; type everything on one line and skip the backslashes):
#~ CFLAGS=-I/usr/local/include ./configure --with-mysqlclient-lib=/usr/local/lib/mysql \ --with-expat-lib=/usr/local/lib --with-sgml-declaration=/usr/local/share/sgml/docbook/4.1/docbook.dcl \ --with-xml-declaration=/usr/local/share/sgml/docbook/dsssl/modular/dtds/decls/xml.dcl \ --with-docbook-xsl=/usr/local/share/xsl/docbook --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.
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.
Both the standard C compiler and the standard make program will not give the desired results when building refdb. Use gcc and gmake instead.
configure needs a little help to recognize this fairly new operating system properly. To this end, copy config.guess and config.sub from /usr/libexec to the refdb/conf directory. Use fink to conveniently install all the additional software needed. Finally, 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].