# System requirements

## Operating system

refdb was designed to run on as many platforms as possible and has positively been seen running on the following operating systems:

- GNU/Linux

- FreeBSD

- NetBSD

- OSX

- Solaris/SunOS

- Windows/Cygwin

Other Unix-like operating systems may work out of the box or with a minimum amount of tweaking. While this portability excludes fancy GUI bells and whistles, it makes it (most likely) possible to run refdb on the hardware and operating system that you happen to have. Both the clients and the application server should compile on all systems with a decent C compiler like gcc. There should be no problems to run refdb on heterogenous networks. For Windows users the free Cygwin tools are recommended. Cygwin is a POSIX layer on top of Win32 including a useful selection of the popular GNU tools.

To simplify the task of porting refdb to other operating systems the package uses autoconf and automake.

## Libraries necessary to build and run refdb

The following libraries are required on your system:

The version numbers in this list do not indicate that it is impossible to build refdb with any lower version number, except where indicated. The numbers just indicate the versions that were used successfully. Lower version numbers may work, higher version numbers are assumed to work in all cases.

Some operating systems/distributions use separate packages for the run-time libraries and the development libraries. In order to build refdb from the sources and run the resulting applications, you need both types of libraries.

### System libraries

These libraries should be offered by all operating systems if they are required on that particular system.

- libreadline (version 4.1 or later)

- libz (version 1.1.3 or later; not required on systems using glibc)

- libnsl, a standard library on Solaris, may be required on this platform.

- libdl, required on all systems that do not include the dl* functions for dealing with dynamic libraries in the standard C library.

- libiconv, required on all systems that do not include the character encoding conversion functions in the standard C library.

### Other libraries

- libdbi (version 0.8.x) and libdbi-drivers (version 0.8.x): a database abstraction layer framework and a set of database-specific drivers.

  libdbi provides the framework for the separately available database drivers. refdb currently supports the MySQL, PostgreSQL, SQLite, and SQLite3 drivers. When configuring the libdbi-drivers source package, please make sure to understand that you have to request the drivers you want to build with the `--with-mysql`, `--with-pgsql`, `--with-sqlite`, or `--with-sqlite3` options (you can specify as many drivers as you see fit).

- SQLite (version 2.8.x or 3.x.y): an embedded SQL engine which you can use instead of the external database servers MySQL or PostgreSQL.

- libexpat (version 1.95.1): a XML parser library.

- btparse (version 0.34; only required if you want to build the BibTeX import filter): a bibtex parser library.

## Perl modules

Some import filters and the SRU servers are implemented as Perl scripts or Perl modules. These require a couple of external Perl modules in order to run properly. Some of the modules are available at CPAN, the comprehensive Perl archive network, which allows you to search and download the modules by name. The refdb-specific modules are available as the refdb-perlmod and the refdb-perlsru packages on the refdb project page.

If you're not familiar with Perl modules, here's how almost all of them can be installed: After unpacking the archive, change into the top-level directory of the extracted module. First run `perl Makefile.PL` which will create a system-specific `Makefile`. Then run `make`, optionally followed by `make test` to check the functionality. Finally, run `make install` as root.

marc2ris

  - MARC::Record (CPAN)

  - MARC::Charset (CPAN)

  - refdb-perlmod

med2ris

  - XML::Parser (CPAN)

  - Text::Iconv (CPAN)

  - refdb-perlmod

en2ris

  - Text::Iconv (CPAN)

  - refdb-perlmod

refdbsru

  - CQL (CPAN)

  - CGI (CPAN)

  - XML::Writer (CPAN)

  - refdb-perlsru

  - refdb-perlmod

refdb-sruserver

  - CQL (CPAN)

  - CGI (CPAN)

  - XML::Writer (CPAN)

  - HTTP::Server::Simple (CPAN)

  - refdb-perlsru

  - refdb-perlmod

The `configure` script tests for the existence of the required Perl modules. If your system lacks some of the required scripts, you'll get a warning, but you'll still be able to make and make install refdb. You can install the modules at a later time without rebuilding refdb. In any case, the missing modules will only affect the Perl import filters, but not the core functionality of refdb. That is, if you don't require the Perl scripts, you don't have to install the modules either.

refdb also provides some support for Perl programmers. The RefDBClient module, also available at the refdb project page, implements Perl classes to directly communicate with refdbd. This allows to write custom clients that access the refdb databases and use the whole functionality implemented in refdbd. The `test.pl` script shipped with the module gives a basic idea how to write a custom client. See also the chapter about this module in the programmer's manual.

## External applications

refdb was designed with the fact in mind that good applications are out there for almost any purpose. Therefore it relies on a few external applications which have to be properly installed. The following list shows the applications which are absolutely required and some applications which will make your life easier.

SQL database server (required for all purposes)

  refdb uses libdbi as a database abstraction layer to access SQL database servers. refdb currently supports MySQL and PostgreSQL as external database engines. Both database servers run on a wide variety of Unix- and Unix-like operating systems as well as on Windows. Sources and precompiled binaries are available. MySQL should be at least version 4.1.x, PostgreSQL should be 7.1 or later.

  If you prefer not to run an external SQL database server, choose the SQLite based internal database engine as explained in the libraries section above.

Jade/OpenJade and SP/OSP-based tools (required for DocBook SGML bibliographies, import of DocBook bibliography data)

  Jade is a freely available and well-proven DSSSL engine which is based on the SP parser. The Jade package contains a few more SP-based tools, e.g. the nsgmls validator and the sgmlnorm normalizer. refdb uses Jade both to extract the IDs of the references which are cited in SGML documents and to transform SGML documents using DSSSL stylesheets. sgmlnorm is required to preprocess multipart documents using the short notation for refdb citations. The Jade/SP package is available on James Clarks homepage. Prebuilt binaries are available for some platforms, and it builds out of the box on quite a number of platforms. Jade has seen some further development by an independent group of programmers. These newer versions were released as OpenJade/OpenSP and are available at the OpenJade homepage.

  OpenJade has some advantages over Jade for our purposes. If it is possible to obtain or compile OpenJade on your platform, you should go for it. Both Jade and OpenJade can be installed on the same machine without conflicts. The configure script will look for both OpenJade and Jade and will use the former as the default DSSSL engine in the shell script customizations if it is available.

XSLT and FO processors (required for DocBook and TEI XML documents)

  If you're working with XML documents and want to transform them using the XSL stylesheets, you'll need some sort of XSL processing machinery. Popular choices are Xalan, Saxon, and xsltproc. The latter is checked for in the configure script and will be used as the default processor if available. The Java-based tools among these need the Java Virtual Machine installed, of course. Generating printable output from FO seems to work best with FOP.

Stylesheets (required for SGML or XML bibliographies)

  refdb ships with DSSSL stylesheet driver files for DocBook SGML documents, XSL stylesheet driver files for DocBook XML documents, and XSL stylesheet driver files for TEI XML documents. All of these rely on the respective stylesheets by Norm Walsh and Sebastian Rahtz. These must be installed on your system if you want to transform DocBook or TEI documents.

TeX (required for LaTeX bibliographies and recommended for printable output from SGML and XML documents)

  Donald Knuth's famous typesetting system is available on almost any platform. You need a TeX system to generate LaTeX bibliographies. It is also convenient to generate nice-looking printable output from SGML and XML documents.

Unix-style text editor (required for all purposes)

  This is nothing to worry about if you use some flavour of Unix or Linux: anything that lets you edit texts will do. However, if you have to use Windows, you should be aware that many run-of-the-mill Windows text editors are not suitable for use with refdb as they are not able to handle the Unix-style line endings (LF instead of CR/LF) properly. The standard Windows editors Notepad, WordPad, and MS Word will not work unless you use a DOS to Unix conversion filter like refdb_dos2unix. These line endings are important in almost all cases, especially when adding and editing references. Some freeware or shareware text-editors for programmers have an option to read and write Unix-style line endings. A few popular Unix text editors are available as Windows ports. Among them are vi clones like vim which is available as a native Windows application and as a Cygwin version, as well as Emacs. GNU Emacs is available as a native Windows application and also as a Cygwin package (even for the Cygwin XFree86 port if you wish). XEmacs can both be built as a native application and as a Cygwin program.

SGML/XML editor (recommended, but not mandatory)

  If you plan to create bibliographies, you may need a SGML/XML editor for two reasons. First, the bibliography style specifications have to be written as XML documents (unless someone else has contributed such a file). Second, if you want to create bibliographies for DocBook documents, you want to use a SGML/XML editor anyway. But SGML is plain text after all, so SGML/XML editors make your life easier, but they are not strictly necessary to get something done.

  Emacs/XEmacs and the PSGML mode for DTD-based SGML and XML documents or the nxml mode for RELAX NG-based XML documents are an excellent choice.

Web browser (recommended, but not mandatory)

  Most likely you will not have a hard time to find some kind of web browser on your system. A web browser may be more pleasant to view the query results than the standard output on stdout or a pager. If you use refdb to manage a collection of PDF or Postscript files, the paths to these files will be displayed in the HTML output and you can open the files with one mouseclick. A web browser is of course also required to use the PHP interface, and it is also useful to interactively retrieve references through the SRU interface.

Perl (import of MARC datasets, import of Pubmed XML datasets, import of EndNote RIS datasets, post-processing BibTeX import files, SRU interfaces)

  The Perl interpreter is available for almost any platform. refdb currently uses Perl for two purposes: the first are the MARC and Pubmed XML import filters, the other is a non-mandatory post-processing step of bibliography data that you import from BibTeX `.bib` files. The MARC import filter requires at least Perl version 5.6.0 and the Perl modules MARC::Record and MARC::Charset. The Pubmed XML import filter requires the Perl modules XML::Parser and Text::Iconv. The latter is also required for the Endnote import filter. Both the standalone and the CGI version of the SRU services are also implemented in Perl. All things Perl are available at CPAN.

Z39.50 client

  In order to retrieve datasets from one of the countless libraries offering their contents through the Z39.50 protocol you'll need a client. The free YAZ toolkit includes a sample client which should be sufficient for general use. The toolkit is available as source, RPM and Debian binaries, and as a Windows binary package.

## Related Software

Please visit the RefDB web page for further information about the following tools which extend the capabilities of RefDB but are not included in the sources:

- ris-mode, an Emacs major mode for RIS datasets

- refdb-mode, an Emacs frontend for RefDB

- A package providing RefDB support for vim, the improved vi editor

- refdb-perlmod, a package containing several Perl support modules for the Perl scripts shipped with RefDB

- RefDB::Client, a Perl module implementing an object-oriented access to RefDB for Perl programmers

- RefDB::SRU and RefDB::SRUserver, the Perl modules that implement the SRU access to RefDB

- A Ruby client library (partially implemented and currently unmaintained!)