Installation on Windows NT/2000/XP
Prev | Chapter 4. Installation | Next

## Installation on Windows NT/2000/XP

### Prerequisites

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

#### External applications

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

#### Libraries

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

### Installation from the sources

### Note

Depending on the permission settings, you may have to run the installation steps proper (as opposed to the build steps) as an administrator.

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

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

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

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

   ### 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-tei-xsl=PATH

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

     ### Note

     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.

   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

5. Run make. This will create the executables and adapt scripts and other files to your local installation.

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

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

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

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

### Installation of prebuilt binaries

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.

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

2. Unpack the prebuilt binaries for both libdbi and libdbi-drivers, available here, in the very same way.

3. Add `/usr/local/share/refdb/refdb.cat` to your `SGML_CATALOG_FILES` environment variable.

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

5. To install refdbd as a service, follow the instructions above.

Prev | Up | Next
Installation on Linux and other Unix variants | Home | Installation on Windows 95/98/ME