=================================================================== RCS file: /cvs/cvsweb/INSTALL,v retrieving revision 3.3.2.1 retrieving revision 4.10 diff -u -p -r3.3.2.1 -r4.10 --- cvsweb/INSTALL 2002/07/30 19:35:42 3.3.2.1 +++ cvsweb/INSTALL 2019/11/29 18:50:15 4.10 @@ -1,37 +1,61 @@ -$FreeBSD$ +$Id: INSTALL,v 4.10 2019/11/29 18:50:15 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 web server which is capable - of executing cgi-scripts. +For notes on upgrading between 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, . 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 + 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). + Currently, you'll also need to have the RCS utilities rlog(1) and + rcsdiff(1) installed. - 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. + This may change if cvs will be able to serve these functions without + having a working directory [see TODO]. -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. + 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. -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. +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. - If you want to run cvsweb.cgi on Windows NT, see (6). + 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 @@ -42,70 +66,113 @@ $FreeBSD$ 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 for pointing 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. - -7) If you like you can add descriptions to be shown next to each directory +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 + - 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 + 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 +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 want cvsweb to write into your CVSROOT/history, build - a fake cvsroot with symlinks to the 'real' CVS-directories and make + 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 - 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 - ($allow_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).