$FreeBSD: projects/cvsweb/INSTALL,v 1.36 2005/01/22 12:43:55 scop Exp $

For notes on upgrading between FreeBSD-CVSweb releases, see the bottom
of this document.

1) To get cvsweb.cgi to work, make sure that you have Perl 5.6.0 or
   newer installed and a web server which is capable of executing CGI
   scripts.  See also samples/cvsweb-httpd.conf.

   CVSweb uses the following Perl modules.  Chances are that some of
   these are already installed with your Perl distribution.  The oldest
   Perl distributions, if any, that already ship with these modules have
   been marked below.  If your Perl doesn't have some of the modules,
   you can get them from CPAN, <http://www.cpan.org/>.  Be sure to
   install also the prerequisites these modules may have.  Note that
   this list contains only modules that aren't already part of Perl
   5.6.0 and newer.


      Module                Version  Ships with Perl      Type
      ----------------------------------------------------------
      File::Temp                          5.8.0         required
      IPC::Run                              N/A         required
      MIME::Types                           N/A         optional
      String::Ediff                         N/A         optional
      URI                                   N/A         required

   Surprisingly enough, you need to have cvs installed.  The recommended
   version of cvs is 1.11 or newer.  Older cvs versions may work with
   more or less quirks, YMMV.

   Currently, you'll also need to have the GNU RCS utilities  'rlog',
   'rcsdiff' installed (current version is 5.7).

   This may change if cvs will be able to serve these functions without
   having a working directory [see TODO].

   Note that the cvsweb.cgi script needs to have physical access to the
   repository (or a copy of it) therefore; rsh, ssh or pserver access
   doesn't work yet.

   Install CvsGraph if you want to use it with CVSweb, and see (6) for
   configuration notes.  CvsGraph 1.4.0 or newer is required.

   Install GNU Enscript if you want syntax highlighting, and see (7) for
   more info.  You'll need version 1.6.3 or newer.

   Install CVSHistory if you want to use it with CVSweb, and see (8) for
   configuration notes.  You'll need version 2.0 or newer.

2) Copy cvsweb.conf to a configuration directory, typically
   /usr/local/etc/cvsweb/cvsweb.conf.
   Edit cvsweb.conf to fit your needs, you'll probably need to tweak the
   CVS root(s) of the Repository(ies) you want to view.
   See also the @command_path variable for the path where cvsweb.cgi
   looks for the various external executables it interacts with.
   The other cvsweb.conf-* files are example per-cvsroot configuration files,
   see commentary in cvsweb.conf for more information.

3) Copy cvsweb.cgi to a directory of your web server where the execution
   of CGI scripts is allowed.  Edit it to make the variable $config
   (look for 'Configuration Area') point to your configuration file.
   If your perl binary isn't located in /usr/bin you'll have to edit the
   first line of the script as well.  For Apache web servers, there is an
   optional sample httpd.conf snippet in the samples/ directory.  Most
   setups do not need it though, it is only for advanced and/or mod_perl
   configurations.

4) If you do not have the dir.gif, text.gif and back.gif icons, copy
   them somewhere in your $DocumentRoot and edit the %ICONS hash
   in cvsweb.conf.  You won't need to do this if you have a stock
   Apache installed - they're located in the default icons directory.
   The icons distributed with this cvsweb are in the public domain.
   If you think that the default icons are too large, use the corresponding
   mini icons in the icons/ directory and change the %ICONS hash in
   cvsweb.conf.

5) Copy cvsweb.css from the css/ directory to a web server directory, and
   point the $cssurl variable in cvsweb.conf to it.

6) CvsGraph <http://www.akhphd.au.dk/~bertho/cvsgraph/> can be used with
   this version of CVSweb.  See the $allow_cvsgraph and $cvsgraph_config
   configuration variables in cvsweb.conf.  Note (and install) also the
   cvsgraph.png icon in the icons/ directory.

7) GNU Enscript <http://www.iki.fi/~mtr/genscript/> can be used for syntax
   highlighting.  To enable it, copy lang_cvsweb.st and lang_cvsweb_diff.st
   from the enscript/ dir to your Enscript "hl" directory (often eg.
   /usr/share/enscript/hl/) and enable $allow_enscript in cvsweb.conf.
   lang_cvsweb.st is used for generic colorization, and lang_cvsweb_diff.st
   for diffs.

8) CVSHistory <http://www.jamwt.com/CVSHistory/> can be used with this
   version of CVSweb.  See the $cvshistory_url configuration variable in
   cvsweb.conf.  For best results, configure CVSweb and CVSHistory to use
   the same "logical names" for CVS roots.

9) If you like you can add descriptions to be shown next to each directory
   or module name.  These are read from CVSROOT/descriptions.

   - Check out a copy of your CVSROOT
   - edit checkoutlist and add a line that says
       descriptions
   - Edit descriptions.  Add one line for each directory that you would like
     to have a comment for.  You can have HTML in the descriptions.
     These lines are relative from the $CVSROOT.  Example:
       JVote          An application to assist with <a href="http://www.irtc.org/">IRTC</a> voting
       JVote/images   Store the images for JVote
       JVote/tools    Scripts to startup JVote
   - cvs add descriptions
   - cvs commit
   - Set $use_descriptions to 1 in cvsweb.conf.

10) Have fun!

Troubleshooting
---------------

If you've trouble to make cvsweb.cgi work ...
.. if nothing seems to work:
 o Check if you can execute CGI scripts (Apache needs to have an
   ScriptAlias /cgi-bin or cgi-script Handler defined).  Try to
   execute a simple CGI script that often comes with the distribution
   of the web server; locate the log files and try to find hints
   which explain the malfunction.
o  View the entries in the web server's error.log.  Set $DEBUG to 1 in
   cvsweb.conf to get more error output.

.. If cvsweb seems to work but doesn't show the expected result
  (Typical error: you can't see any files)
 o Check whether the CGI script has read permissions to your
   CVS repository.  The CGI script often runs as the user 'nobody'
   or 'httpd'.
 o If you use annotation, see @annotate_options in cvsweb.conf.
 o See CVSROOT/config for various options controlling what gets written
   into CVSROOT/history, where lock files are placed etc.  You can also
   build a fake cvsroot with symlinks to the 'real' CVS directories and make
   a fake CVSROOT/history as symbolic link to /dev/null.
   If you don't want cvs called from cvsweb to place read locks at all, let
   cvsweb operate on a copy.
 o Does cvsweb find your RCS utils/cvs binary(annotate)?
   See $command_path in in cvsweb.conf.
 o cvsweb allows for compression now.  It is determined first if the
   browser accepts gzip encoding.  But - no rule without exception - some
   versions of MSIE claim to understand gzip encoded content but
   display garbage .. so compression for MSIE is disabled now.  Maybe you
   find another browser with this problem, then you should disable
   compression ($allow_compress=0 in cvsweb.conf) and report it to
   <freebsd-cvsweb@freebsd.org>.

Upgrade instructions
--------------------

List of things to pay attention to when upgrading FreeBSD-CVSweb from
earlier versions follows.  Lack of instructions for a particular
version means that there are no special things to pay attention to.

Upgrading to 3.0.5
------------------

The following configuration variables in cvsweb.conf have changed:

  $allow_mailtos is new, and optional.  See comments in cvsweb.conf.

Upgrading to 3.0.3
------------------

The following configuration variables in cvsweb.conf have changed:

  $DEBUG is new, and optional.  See comments in cvsweb.conf.

Upgrading to 3.0.1
------------------

The following configuration variables in cvsweb.conf have changed:

   $cvshistory_url is new, and optional.  See comments in cvsweb.conf.

Upgrading to 3.0.0
------------------

Make sure that the dependencies are met, see 1) above.

The following configuration variables in cvsweb.conf have changed:

   $command_path has been changed to @command_path, ie. a list.

   @HideModules has been removed.  It had nothing to do with actual
   modules in CVS terminology, and the implementation was broken.
   @ForbiddenFiles has been enhanced to affect directories as well.

   $cvstreedefault is now optional.  If unset, the first one in
   @CVSrepositories is used.

   %DEFAULTVALUE for "f" (default diff format) now understands the values
   "uc", "cc" and "sc" for enscript-colored diffs (unified, context and
   side-by-side respectively).

   %DEFAULTVALUE for "ln" can now be set to a boolean indicating whether
   line numbers in markup views should be shown or not.  The default is off.

   The following parameters have been removed, use CSS instead:
   $body_tag, $body_tag_for_src, $navigationHeaderColor, $dirtable,
   @tabcolors, $columnHeaderColorDefault, $columnHeaderColorSorted,
   $tableBorderColor, $diffcolorHeading, $diffcolorEmpty, $diffcolorRemove,
   $diffcolorChange, $diffcolorAdd, $diffcolorDarkChange, $difffontface,
   $difffontsize, $markupLogColor.

   The following parameters have been removed, with no replacement:
   $open_extern_window, $extern_window_height, $extern_window_width,
   $checkout_magic.

   $allow_enscript, @enscript_options and %enscript_types control the use
   and behavior of enscript(1).

   $allow_cvsgraph and $cvsgraph_config control the use and behavior of
   cvsgraph(1).

   $file_list_len can be set to work around problems with rlog(1) and dirs
   with lots of files.

   $cssurl contains the absolute URI to the CSS file to use.

   %ICONS has two new entries: binfile for binary files (-kb keyword
   substitution) and graph for the cvsgraph icon.

   %DIFF_COMMANDS is new, it is used to configure external per file type
   diff commands.
