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).
MySQL version 3.22 or later. This is the SQL database which provides the database services for refdb. 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.
Cygwin toolkit, preferably one of the recent net releases with a DLL version 1.3.10 or later. The Cygwin distribution uses individual packages for the various parts. If you are not sure what to pick, you should install everything, just to be on the safe side. refdb has been ported to (or rather co-developed on) Win32 using this fine collection of GNU tools.
If you plan to use the web interface of refdb, you also need a web server. If this happens to be a different Windows box in your network, please keep in mind that you will have to install one of the refdb clients as a CGI application, so this box must run Cygwin as well. If you don't have big bucks to spend: there is a Cygwin port of Apache and a native Win32 version, either of which may suit your needs.
Both the MySQL and the Cygwin 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 readline library and headers are available at the GNU FTP site. This library builds out of the box. Recent versions of Cygwin come with a prebuilt library anyway.
The mysqlclient library and headers. Build instructions for Cygwin are available in the MySQL mailing list archive and in the Cygwin mailing list archive. For the most recent MySQL versions it is apparently sufficient to configure for clients only and then run make and make install.
The expat library and headers are available at the expat homepage. This library builds cleanly on recent Cygwin versions (./configure --with-gnu-ld --enable-shared --enable-static).
If you need the BibTeX import filter, you'll also want to have the btparse library. This builds out of the tarball on Cygwin.
Note: 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:
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 something 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.
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.
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.
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' -e 'REFDBLIB=/usr/local/share/refdb' (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 NT's own tools: Either use the NT system control panel or use the NT 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 statically linked with libmysqlclient and are accompanied by a copy of libexpat, so you do not have to get or build these libraries yourself.
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.
Add the following line to your /etc/profile:
export REFDBLIB=/usr/local/share/refdb
|
Add /usr/local/share/refdb/dtd/catalog and /usr/local/share/refdb/dsssl/catalog to your SGML_CATALOG_FILES environment variable.
Create the configuration files in /etc. Sample configuration files with a .example extension are installed in /usr/local/share/refdb. Provide personalized copies for the user's home directories as needed.
To install refdbd as a service, follow the instructions above.