/usr/share/doc/refdb/refdb-manual/ch04s05.html is in refdb-doc 1.0.2-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 | <?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Installation on Windows NT/2000/XP</title><link rel="stylesheet" type="text/css" href="manual.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><link rel="home" href="index.html" title="RefDB handbook" /><link rel="up" href="ch04.html" title="Chapter 4. Installation" /><link rel="prev" href="ch04s04.html" title="Installation on Linux and other Unix variants" /><link rel="next" href="ch04s06.html" title="Installation on Windows 95/98/ME" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Installation on Windows NT/2000/XP</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch04s04.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Installation</th><td width="20%" align="right"> <a accesskey="n" href="ch04s06.html">Next</a></td></tr></table><hr /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="sect1-installation-windows"></a>Installation on Windows NT/2000/XP</h2></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="idp67460368"></a>Prerequisites</h3></div></div></div><p>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 <a class="link" href="ch04s05.html#sect2-install-cygwin-bin" title="Installation of prebuilt binaries">prebuilt binaries</a> that contain all non-standard libraries).</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="idp67462640"></a>External applications</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="ulink" href="http://www.cygwin.com" target="_top">Cygwin toolkit</a>, 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.</p></li><li class="listitem"><p>A SQL database engine. Currently you can choose between <a class="ulink" href="http://www.mysql.com" target="_top">MySQL</a> (version 3.23 or later), <a class="ulink" href="http://www.postgresql.org" target="_top">PostgreSQL</a> (version 7.1 or later), and <a class="ulink" href="http://www.sqlite.org" target="_top">SQLite/SQLite3</a> (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.</p><p>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 <a class="ulink" href="http://www.neuro.gatech.edu/users/cwilson/cygutils/cygipc/index.hml" target="_top">here</a>.</p><p>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.</p></li><li class="listitem"><p>If you want to import Pubmed or MARC datasets, please make sure to install the Perl interpreter available for Cygwin and get the <a class="ulink" href="http://sourceforge.net/projects/refdb" target="_top">refdb-perlmod</a> 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 <a class="ulink" href="http://www.cpan.org" target="_top">CPAN</a>.</p></li></ul></div><p>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.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a id="idp67474704"></a>Libraries</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The <a class="ulink" href="http://sourceforge.net/projects/libdbi" target="_top">libdbi library</a> and headers, along with the <a class="ulink" href="http://sourceforge.net/projects/libdbi-drivers" target="_top">libdbi-drivers</a> 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 <a class="ulink" href="http://libdbi.sourceforge.net/downloads/" target="_top">here</a>.</p></li><li class="listitem"><p>If you need the BibTeX import filter, you'll also want to have the <a class="ulink" href="http://www.ctan.org/tex-archive/biblio/bibtex/utils/btOOL/" target="_top">btparse</a> library. This builds out of the tarball on Cygwin.</p></li></ul></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="idp67481280"></a>Installation from the sources</h3></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Depending on the permission settings, you may have to run the installation steps proper (as opposed to the build steps) as an administrator.</p></div><div class="procedure"><ol class="procedure" type="1"><li class="step"><p>Unpack the sources in a convenient directory: <span class="command"><strong>tar -xzf refdb-x.y.z.tar.gz</strong></span> (the exact filename depends on the version).</p></li><li class="step"><p>If you do not want to build in the source directory, create an empty build directory.</p></li><li class="step"><p>Change into the new <code class="filename">refdb-x.y.z</code> source directory or into your separate build directory.</p></li><li class="step"><p>
<span class="command"><strong>./configure --help</strong></span>
</p><p>This command will display a list of things you can customize. If you build in a separate directory, use the relative path to <code class="filename">configure</code> in the source directory. Some important options are:</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>All paths and URLs in the following options should be entered without a trailing slash.</p></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">--prefix=PREFIX</span></dt><dd><p>By default, all files will be installed in the <code class="filename">/usr/local</code> tree. Use this option to use a different install root, e.g. <code class="filename">/usr</code> or <code class="filename">/opt</code>.</p></dd><dt><span class="term">--datadir=DIR</span></dt><dd><p>The data files will be installed in <code class="filename">/usr/local/share/refdb</code> unless you use this option. The data will be installed in the directory <code class="filename">DIR/refdb</code>. That is, specifying "--datadir=/usr/local/share" is equivalent to the default behaviour. The configuration variable <code class="varname">refdblib</code> (which will be automatically generated in the example configuration files) must point to the RefDB data directory.</p></dd><dt><span class="term">--sysconfdir=DIR</span></dt><dd><p>The global configuration files will be installed in <code class="filename">/usr/local/etc/refdb</code> unless you specify a different directory here.</p></dd><dt><span class="term">--with-libdbi-lib=DIR</span></dt><dd><p>Use this option to specify the directory that contains the libdbi library if it is not in the default library path.</p></dd><dt><span class="term">--with-expat-lib=DIR</span></dt><dd><p>Use this option to specify the directory that contains the expat library if it is not in the default library path.</p></dd><dt><span class="term">--with-btparse-lib=DIR</span></dt><dd><p>Use this option to specify the directory that contains the btparse library if it is not in the default library path.</p></dd><dt><span class="term">--with-sgml-declaration=PATH</span></dt><dd><p>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 <code class="filename">docbook.dcl</code> stolen from the DocBook DTD distribution. This SGML declaration also works for a variety of other DTDs.</p></dd><dt><span class="term">--with-xml-declaration=PATH</span></dt><dd><p>Specify the full path to <code class="filename">xml.dcl</code> which is the SGML declaration for XML files. If this option is not used, RefDB will use its own copy of <code class="filename">xml.dcl</code> which should work just fine.</p></dd><dt><span class="term">--with-docbook-xsl=PATH</span></dt><dd><p>Specify the full path to the root directory of the DocBook XSL stylesheets.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>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. <span class="command"><strong>configure</strong></span> 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.</p></div></dd><dt><span class="term">--with-docbook-xsl-ns=PATH</span></dt><dd><p>Specify the full path to the root directory of the DocBook XSL-NS (for DocBook V5.0 and later) stylesheets.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>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. <span class="command"><strong>configure</strong></span> 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.</p></div></dd><dt><span class="term">--with-tei-xsl=PATH</span></dt><dd><p>Specify the full path to the root directory of the TEI XSL stylesheets for P4.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>As mentioned above for the DocBook stylesheets, use this option only if your catalogs cannot resolve the public identifiers properly. The <a class="ulink" href="http://www.tei-c.org" target="_top">TEI Consortium</a> ships <a class="ulink" href="http://sourceforge.net/project/showfiles.php?group_id=106328&package_id=141124" target="_top">tei-xsl-5.2.9.zip</a> 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. <code class="filename">/usr/local/share/xsl/tei-xsl-5.2.9</code>.</p></div></dd><dt><span class="term">--with-tei-xsl-ns=PATH</span></dt><dd><p>Specify the full path to the root directory of the TEI XSL stylesheets for P5.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>As mentioned above for the DocBook stylesheets, use this option only if your catalogs cannot resolve the public identifiers properly. The <a class="ulink" href="http://www.tei-c.org" target="_top">TEI Consortium</a> ships <a class="ulink" href="http://sourceforge.net/project/showfiles.php?group_id=106328&package_id=141124" target="_top">tei-xsl-5.2.9.zip</a> 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. <code class="filename">/usr/local/share/xsl/tei-xsl-5.2.9</code>.</p></div></dd><dt><span class="term">--with-classpath-root=PATH</span></dt><dd><p>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.</p></dd><dt><span class="term">--with-var-dir=PATH</span></dt><dd><p>Use this option to specify a directory where refdbd can write its PID file (a file containing the process ID). By default, <code class="filename">/var/run</code> will be used.</p></dd><dt><span class="term">--with-log-dir=PATH</span></dt><dd><p>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, <code class="filename">/var/log</code> will be used.</p></dd><dt><span class="term">--with-main-db=dbname</span></dt><dd><p>RefDB uses one main database to store citation styles and other stuff. There is exactly one such database per installation with the default name <code class="filename">refdb</code>. 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 <code class="filename">refdbdrc</code> configuration file, as it allows the <a class="link" href="re09.html" title="refdb-init">refdb-init</a> script to use the proper database name.</p></dd><dt><span class="term">--with-db-dir</span></dt><dd><p>Selects the directory which holds SQLite/SQLite3 databases</p></dd><dt><span class="term">--with-trang-jar</span></dt><dd><p>Specifies the full path to the jar file of the <a class="ulink" href="http://www.thaiopensource.com/relaxng/trang.html" target="_top">trang</a> tool. You need this tool if you build RefDB from SVN sources, but not if you build from a tarball.</p></dd><dt><span class="term">--disable-docs</span></dt><dd><p>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.</p></dd><dt><span class="term">--disable-clients</span></dt><dd><p>Use this switch if you want to build and install only the application server <code class="filename">refdbd</code>. This is mainly targeted at package builders.</p></dd><dt><span class="term">--disable-server</span></dt><dd><p>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.</p></dd></dl></div><p>Finally, run <span class="command"><strong>./configure</strong></span> with any options that you need. If you build in a separate directory, use the relative path to <code class="filename">configure</code> in the source directory. A complete set of options might look like this if you use PostgreSQL:</p><pre class="screen">
<code class="prompt">$~ </code>
<strong class="userinput"><code>./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</code></strong>
</pre></li><li class="step"><p>Run <span class="command"><strong>make</strong></span>. This will create the executables and adapt scripts and other files to your local installation.</p></li><li class="step"><p><span class="command"><strong>make install</strong></span> will copy the application server and the clients to <code class="filename">/usr/local/bin</code> and the data files to <code class="filename">/usr/local/share/refdb</code> unless you chose different directories in the configure step.</p></li><li class="step"><p>To finish the installation, please follow the instructions in the section <a class="link" href="ch04s08.html" title="Finishing the RefDB installation">Finishing the RefDB installation</a> below.</p></li></ol></div><p>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:</p><div class="procedure"><a id="procedure-installservice"></a><ol class="procedure" type="1"><li class="step"><p>Install the service with the command <span class="command"><strong>cygrunsrv -I refdbd -p /usr/local/bin/refdbd -a '-s'</strong></span> (adapt the paths to your local installation if necessary).</p></li><li class="step"><p>Start the service with the command <span class="command"><strong>cygrunsrv -S refdbd</strong></span>. To stop the service, use the command <span class="command"><strong>cygrunsrv -E refdbd</strong></span>. 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 <span class="command"><strong>net start refdbd</strong></span> and <span class="command"><strong>net stop refdbd</strong></span>.</p></li></ol></div><p>With this setup, the service will be automatically started at system startup. See <span class="command"><strong>cygrunsrv --help</strong></span> for additional options.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="sect2-install-cygwin-bin"></a>Installation of prebuilt binaries</h3></div></div></div><p>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 <code class="filename">Readme</code> files as they may have newer or additional information.</p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p>Unpack the archive in the root directory (<code class="filename">/</code>) with the command <span class="command"><strong>tar -xzf refdb-cygwin-bin-x.y.z.tar.gz</strong></span> (the exact archive name depends on the version you use). This will extract the files into the <code class="filename">/usr/local</code> hierarchy. The binaries and scripts go to <code class="filename">/usr/local/bin</code>, the Document Type Definitions, stylesheets, styles and example configuration files go to <code class="filename">/usr/local/share/refdb</code> and its subdirectories.</p></li><li class="step"><p>Unpack the prebuilt binaries for both libdbi and libdbi-drivers, available <a class="ulink" href="http://libdbi.sourceforge.net/downloads/" target="_top">here</a>, in the very same way.</p></li><li class="step"><p>Add <code class="filename">/usr/local/share/refdb/refdb.cat</code> to your <code class="envar">SGML_CATALOG_FILES</code> environment variable.</p></li><li class="step"><p>Create the configuration files in <code class="filename">/usr/local/etc</code>. Sample configuration files with a <code class="filename">.example</code> extension are created in the same directory during the installation. Provide personalized copies for the user's home directories as needed.</p></li><li class="step"><p>To install refdbd as a service, follow the instructions <a class="link" href="ch04s05.html#procedure-installservice">above</a>.</p></li></ol></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch04s04.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch04.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch04s06.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Installation on Linux and other Unix variants </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Installation on Windows 95/98/ME</td></tr></table></div></body></html>
|