=================================================================== RCS file: /cvs/cvsweb/INSTALL,v retrieving revision 3.4 retrieving revision 4.6 diff -u -p -r3.4 -r4.6 --- cvsweb/INSTALL 2002/07/30 19:42:26 3.4 +++ cvsweb/INSTALL 2019/11/11 14:56:27 4.6 @@ -1,37 +1,64 @@ -$FreeBSD$ +$Id: INSTALL,v 4.6 2019/11/11 14:56:27 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). + 'rcsdiff' installed (current version is 5.7). - 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. + 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. - 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 +69,131 @@ $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. +8) 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. -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.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 "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.