===================================================================
RCS file: /cvs/cvsweb/INSTALL,v
retrieving revision 3.3
retrieving revision 4.8
diff -u -p -r3.3 -r4.8
--- cvsweb/INSTALL 2002/04/05 11:12:41 3.3
+++ cvsweb/INSTALL 2019/11/26 12:04:55 4.8
@@ -1,108 +1,181 @@
-$FreeBSD$
+$Id: INSTALL,v 4.8 2019/11/26 12:04:55 schwarze Exp $
+$knu: INSTALL,v 1.36 2005/01/22 12:43:55 scop
-1) To get cvsweb.cgi to work, make sure that you
- have Perl 5 installed and a webserver which is capable
- to execute cgi-scripts.
+For notes on upgrading between CVSweb releases, see the bottom
+of this document.
- Currently, you need to have the GNU RCS utilities 'rlog',
- 'rcsdiff' installed (current version is 5.7).
+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.
- This will 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.
+ 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, . 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.
-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 have to edit the
- first line of the script as well.
- If you want to let cvsweb.cgi run on WinNT running see (7).
+ Module Version Ships with Perl Type
+ ----------------------------------------------------------
+ File::Temp 5.8.0 required
+ IPC::Run N/A required
+ MIME::Types N/A optional
+ URI N/A required
-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-Hashtable
- in cvsweb.conf. You won't need to do this if you have a stock
- Apache installed .. the're located in the default icons-directory.
+ 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.
+
+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 to large, use the corresponding
- miniicons in the icons-directory and change the %ICONS-Hashtable in
+ 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) have fun
+5) Copy cvsweb.css from the css/ directory to a web server directory, and
+ point the $cssurl variable in cvsweb.conf to it.
-6) 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 to point this out.
- I don't know if cvs-annotate works on NT.
-
- > From: Nick Brachet
- [...]
- > I'm running NT 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.
+9) If you like you can add descriptions to be shown next to each directory
+ or module name. These are read from CVSROOT/descriptions.
-7) 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
+ - 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 IRTC voting
+ JVote An application to assist with IRTC 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!
-if you got PROBLEMS ..
-----------------------
+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 webserver; locate the logfiles and try to find hints
- which explain the malfunction
-o view the entries in the webservers error.log
+ 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' ..
- 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 like cvsweb to write into your CVSROOT/history, build
- a fake cvsroot with symlinks to the 'real' CVS-directories and make
+ 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 like cvs, called from cvsweb, to place read-locks - let
+ 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) ? ($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
- ($allo_compress=0 in cvsweb.conf) and
- report it to me ()
+ 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).
+Upgrade instructions
+--------------------
+
+List of things to pay attention to when upgrading 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.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.
+
+ %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.
+
+ $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 a new entry: binfile for binary files (-kb keyword
+ substitution).
+
+ %DIFF_COMMANDS is new, it is used to configure external per file type
+ diff commands.