Return to INSTALL CVS log

Up to [cvsweb.bsd.lv] / cvsweb

Strict input checking and laundering, needed for running under Perl 5.8
with taint checks enabled.  Use the CGI module for input parsing.

PR:		52386

$FreeBSD$

1) To get cvsweb.cgi to work, make sure that you have Perl 5.005_03 or
   newer installed and a web server which is capable of executing CGI
   scripts.

   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.005_03 and newer.
   

      Module                Version  Ships with Perl      Type
      ----------------------------------------------------------
      CGI                                   N/A         required
      File::Spec::Functions   0.8+        5.6.0         required
      File::Temp                          5.8.0         required
      IPC::Run                              N/A         required
      MIME::Types                           N/A         optional
      String::Ediff                         N/A         optional

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

2) Copy cvsweb.conf to your configuration directory. If
   you've installed Apache, $ServerRoot/conf (or $ServerRoot/etc 
   with versions >= 1.3.0) makes sense.
   Edit cvsweb.conf to fit your needs, esp. set the CVS-Root(s)
   of the Repository(ies) you want to view. 
   If your RCS utilities are not in the $PATH of the cgi execution 
   environment you need to set it in the 'Misc' section as well.

3) Copy cvsweb.cgi to the cgi script location of your web server. 
   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. 
   If you want to run cvsweb.cgi on Windows NT, see (9).

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.  cvsweb.cgi will override some
   of the settings in the cvsgraph configuration file with command line
   options; the following in particular: map_branch_href, map_rev_href and
   map_diff_href so you won't have to tweak them for CVSWeb.  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 from the enscript/ dir
   to your Enscript "hl" directory (eg. /usr/share/enscript/hl/) and enable
   $allow_enscript in cvsweb.conf.

8) Have fun!

9) If you've Windows NT running, calling of external programs with parameters
   single quoted doesn't work (search for rcsdiff, rlog in
   cvsweb.cgi), you've to replace it with double quotes.  Thanks to
   Nick Brachet for pointing this out.
   I don't know if cvs-annotate works on NT.
   
   > From: Nick Brachet <nick@gradient.com>
   [...]
   > I'm running NT <g> and I had to patch a few things. For example,
   >   open(RCS, "co -p$rev '$fullname' 2>&1 |")
   > will fail on NT because the ' are not recognized. Using " will work
   > though.

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

--------------------

if you got PROBLEMS ..
----------------------

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 servers error.log

.. 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'...
   If you use annotation, the user needs to have write permissions
   to CVSROOT/history and to the directory the file is in in order
   to place the read-lock.
   If you don't want cvsweb to write into your CVSROOT/history, 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 - let
   cvsweb operate on a copy.
 o Does cvsweb find your RCS-utils/cvs-binary(annotate) ? ($ENV{PATH} in
   cvsweb.conf !)
 o cvsweb allows for compression now.  It is determined first, 
   if the browser accepts gzip-encoding.  But - no rule without
   exception - MSIE claims to understand gzip encoded content but
   displays garbage .. so 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 me (<zeller@think.de>)