In order to run RefDB you'll need a few external apps. The most important thing are the Cygwin tools which provide a Unix-like environment on the otherwise incompatible Windows platform. Additionally you'll have to build or obtain prebuilt versions of a few libraries which are not part of the standard Cygwin distribution (unless you use prebuilt binaries that contain all non-standard libraries).
Cygwin toolkit, DLL version 1.5.0 or later (the current version as of this writing, 1.5.12, has serious problems with PostgreSQL, though). The Cygwin distribution uses individual packages for the various parts. In addition to what is installed automatically (the base distribution), please make sure to select the following packages: libxml2, libxslt, expat, Perl, and a full TeX installation if you wish to create Postscript or PDF files.
A SQL database engine. Currently you can choose between MySQL (version 3.23 or later), PostgreSQL (version 7.1 or later), and SQLite/SQLite3 (versions 2.8.x or later; 3.0.x 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.
Cygwin offers a prepackaged version of PostgreSQL (7.3.3 as of this writing) which used to be the most convenient way to run a database server on your Cygwin box, but as stated above it may be broke when you try. Please follow the instructions in the readme shipped with the package to install and initialize the database server. It is crucial that you install and run the separately available cygipc package, available only here.
SQLite does build on Cygwin, but all filename/path handling code uses the Windows conventions. You will have to use the Windows-style path when setting the database directory.
If you want to import Pubmed or MARC datasets, please make sure to install the Perl interpreter available for Cygwin and 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, available at CPAN.
The mentioned websites offer plenty of support as web documents or with mailing lists, so it should be possible to figure out how to do a basic install for these suites.
The libdbi library and headers, along with the libdbi-drivers package. Please follow the Cygwin-specific instructions that accompany both packages to build and install the software. Prebuilt binaries for both libdbi and libdbi-drivers are available here.
If you need the BibTeX import filter, you'll also want to have the btparse library. This builds out of the tarball on Cygwin.
Depending on the permission settings, you may have to run the installation steps proper (as opposed to the build steps) as an administrator.
Unpack the sources in a convenient directory: tar -xzf refdb-x.y.z.tar.gz (the exact filename depends on the version).
If you do not want to build in the source directory, create an empty build directory.
Change into the new refdb-x.y.z source directory or into your separate build directory.
./configure --help
This command will display a list of things you can customize. If you build in a separate 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.
Finally, run ./configure with any options that you need. If you build in a separate directory, use the relative path to configure in the source directory. A complete set of options might look like this if you use PostgreSQL:
$~./configure --with-refdb-url=http://yourbox.com/refdb --with-db-server=pgsql --with-var-dir=/var/run \ --with-log-dir=/var/log --with-libdbi-dir=/uar/local/lib --with-docbook-xsl=/usr/local/share/sgml/stylesheets/docbook \ --with-tei-xsl=/usr/local/share/xsl/tei
Run make. This will create the executables and adapt scripts and other files to your local installation.
make install will copy the application server and the clients to /usr/local/bin and the data files to /usr/local/share/refdb unless you chose different directories in the configure step.
To finish the installation, please follow the instructions in the section Finishing the RefDB installation below.
Now you have everything in place to use the RefDB clients and the application server from the command line. To install the application server as a service, the following additional steps are necessary:
Install the service with the command cygrunsrv -I refdbd -p /usr/local/bin/refdbd -a '-s' (adapt the paths to your local installation if necessary).
Start the service with the command cygrunsrv -S refdbd. To stop the service, use the command cygrunsrv -E refdbd. If you prefer, you can also start and stop the service with Windows' own tools: Either use the system control panel or use the commands net start refdbd and net stop refdbd.
With this setup, the service will be automatically started at system startup. See cygrunsrv --help for additional options.
If you decide to grab the prebuilt binaries, the installation will be a little bit faster. The binaries are accompanied by a copy of libexpat. Please make sure to read the aptly named Readme files as they may have newer or additional information.
Unpack the archive in the root directory (/) with the command tar -xzf refdb-cygwin-bin-x.y.z.tar.gz (the exact archive name depends on the version you use). This will extract the files into the /usr/local hierarchy. The binaries and scripts go to /usr/local/bin, the Document Type Definitions, stylesheets, styles and example configuration files go to /usr/local/share/refdb and its subdirectories.
Unpack the prebuilt binaries for both libdbi and libdbi-drivers, available here, in the very same way.
Add /usr/local/share/refdb/refdb.cat to your SGML_CATALOG_FILES environment variable.
Create the configuration files in /usr/local/etc. Sample configuration files with a .example extension are created in the same directory during the installation. Provide personalized copies for the user's home directories as needed.
To install refdbd as a service, follow the instructions above.