Installation on Linux and other Unix variants
Prev | Chapter 4. Installation | Next

## Installation on Linux and other Unix variants

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.

### Generic instructions

#### Prerequisites

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.

#### Installation from the sources

### Note

The installation steps proper (as opposed to the build steps) should be run with root privileges.

1. Unpack the archive in a convenient directory: tar -xzf refdb-x.y.z.tar.gz (the actual filename depends on the version).

2. If you do not want to build in the source directory, create an empty build directory.

3. cd into the new `refdb-x.y.z` source directory or into your separate build directory

4. 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.

   --prefix=PREFIX

     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`.

   --datadir=DIR

     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.

   --sysconfdir=DIR

     The global configuration files will be installed in `/usr/local/etc/refdb` unless you specify a different directory here.

   --with-libdbi-lib=DIR

     Use this option to specify the directory that contains the libdbi library if it is not in the default library path.

   --with-expat-lib=DIR

     Use this option to specify the directory that contains the expat library if it is not in the default library path.

   --with-btparse-lib=DIR

     Use this option to specify the directory that contains the btparse library if it is not in the default library path.

   --with-sgml-declaration=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.

   --with-xml-declaration=PATH

     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.

   --with-docbook-xsl=PATH

     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.

   --with-docbook-xsl-ns=PATH

     Specify the full path to the root directory of the DocBook XSL-NS (for DocBook V5.0 and later) 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.

   --with-tei-xsl=PATH

     Specify the full path to the root directory of the TEI XSL stylesheets for P4.

     ### Note

     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`.

   --with-tei-xsl-ns=PATH

     Specify the full path to the root directory of the TEI XSL stylesheets for P5.

     ### Note

     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`.

   --with-classpath-root=PATH

     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.

   --with-var-dir=PATH

     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.

   --with-log-dir=PATH

     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.

   --with-main-db=dbname

     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.

   --with-db-dir

     Selects the directory which holds SQLite/SQLite3 databases.

   --with-trang-jar

     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.

   --disable-docs

     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.

   --disable-clients

     Use this switch if you want to build and install only the application server `refdbd`. This is mainly targeted at package builders.

   --disable-server

     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.

   ### 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.

5. 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.

6. 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.

7. 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).

#### Living on the bleeding edge: installing a SVN version

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:

1. Change into a suitable directory. SVN will create a subdirectory called `refdb` during the following steps

2. Run the following command (adapt this accordingly if you use some graphical CVS frontend instead of the command line tool):

       	      $~/build
       	      svn 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:

       	      $~/build
       	      svn co --revision 324 https://svn.sourceforge.net/svnroot/refdb/refdb/trunk refdb-324
       	      svn co https://svn.sourceforge.net/svnroot/refdb/refdb/tags/Release-0.9.7 refdb-0.9.7
       	      svn co https://svn.sourceforge.net/svnroot/refdb/refdb/branches/back-to-a-1-branch refdb-a1-branch

3. 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/refdb
       	      svn update

   Consider subscribing to the refdb-cvs mailing list as you'll be notified about each SVN checkin.

4. 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

   ### 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 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.

5. 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

6. 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.

#### Installation of refdbd as a daemon

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).

##### SysV-style

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.

1. 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).

2. Copy the script `refdb` to `/etc/init.d/` and make sure it is executable: chmod 755 /etc/init.d/refdb.

3. 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).

4. 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

5. 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.

##### BSD-style

The following procedure describes the installation on a FreeBSD system. Other systems might differ somewhat, but you should get the idea.

1. 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.

2. 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.

3. 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.

### OS-specific hints

This section contains a few hints about the installation on some popular Unix-like operating systems.

#### Linux

The generic instructions should work out of the box for most if not all Linux distributions.

##### Debian GNU/Linux

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

#### FreeBSD

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`.

#### NetBSD

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`.

#### Solaris

Both the standard C compiler and the standard make program will not give the desired results when building RefDB. Use gcc and gmake instead.

#### OSX

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].

Prev | Up | Next
Things to know before you start | Home | Installation on Windows NT/2000/XP