Annotation of cvsweb/INSTALL, Revision 4.9
4.9 ! schwarze 1: $Id: INSTALL,v 4.8 2019/11/26 12:04:55 schwarze Exp $
4.2 schwarze 2: $knu: INSTALL,v 1.36 2005/01/22 12:43:55 scop
3.2 knu 3:
4.4 schwarze 4: For notes on upgrading between CVSweb releases, see the bottom
3.29 scop 5: of this document.
3.17 scop 6:
3.16 scop 7: 1) To get cvsweb.cgi to work, make sure that you have Perl 5.6.0 or
3.7 scop 8: newer installed and a web server which is capable of executing CGI
3.18 scop 9: scripts. See also samples/cvsweb-httpd.conf.
3.7 scop 10:
3.10 scop 11: CVSweb uses the following Perl modules. Chances are that some of
3.7 scop 12: these are already installed with your Perl distribution. The oldest
13: Perl distributions, if any, that already ship with these modules have
14: been marked below. If your Perl doesn't have some of the modules,
15: you can get them from CPAN, <http://www.cpan.org/>. Be sure to
16: install also the prerequisites these modules may have. Note that
17: this list contains only modules that aren't already part of Perl
3.16 scop 18: 5.6.0 and newer.
3.17 scop 19:
3.7 scop 20:
3.11 scop 21: Module Version Ships with Perl Type
22: ----------------------------------------------------------
23: File::Temp 5.8.0 required
3.12 scop 24: IPC::Run N/A required
3.11 scop 25: MIME::Types N/A optional
3.15 scop 26: URI N/A required
3.1 knu 27:
3.4 scop 28: Surprisingly enough, you need to have cvs installed. The recommended
29: version of cvs is 1.11 or newer. Older cvs versions may work with
30: more or less quirks, YMMV.
31:
4.9 ! schwarze 32: Currently, you'll also need to have the RCS utilities rlog(1) and
! 33: rcsdiff(1) installed.
3.1 knu 34:
3.6 scop 35: This may change if cvs will be able to serve these functions without
36: having a working directory [see TODO].
3.1 knu 37:
3.6 scop 38: Note that the cvsweb.cgi script needs to have physical access to the
39: repository (or a copy of it) therefore; rsh, ssh or pserver access
40: doesn't work yet.
41:
3.17 scop 42: 2) Copy cvsweb.conf to a configuration directory, typically
43: /usr/local/etc/cvsweb/cvsweb.conf.
44: Edit cvsweb.conf to fit your needs, you'll probably need to tweak the
45: CVS root(s) of the Repository(ies) you want to view.
3.26 scop 46: See also the @command_path variable for the path where cvsweb.cgi
3.17 scop 47: looks for the various external executables it interacts with.
3.26 scop 48: The other cvsweb.conf-* files are example per-cvsroot configuration files,
49: see commentary in cvsweb.conf for more information.
3.17 scop 50:
51: 3) Copy cvsweb.cgi to a directory of your web server where the execution
52: of CGI scripts is allowed. Edit it to make the variable $config
53: (look for 'Configuration Area') point to your configuration file.
3.4 scop 54: If your perl binary isn't located in /usr/bin you'll have to edit the
3.26 scop 55: first line of the script as well. For Apache web servers, there is an
56: optional sample httpd.conf snippet in the samples/ directory. Most
57: setups do not need it though, it is only for advanced and/or mod_perl
58: configurations.
3.1 knu 59:
3.4 scop 60: 4) If you do not have the dir.gif, text.gif and back.gif icons, copy
61: them somewhere in your $DocumentRoot and edit the %ICONS hash
62: in cvsweb.conf. You won't need to do this if you have a stock
63: Apache installed - they're located in the default icons directory.
3.1 knu 64: The icons distributed with this cvsweb are in the public domain.
3.4 scop 65: If you think that the default icons are too large, use the corresponding
66: mini icons in the icons/ directory and change the %ICONS hash in
3.1 knu 67: cvsweb.conf.
68:
3.6 scop 69: 5) Copy cvsweb.css from the css/ directory to a web server directory, and
70: point the $cssurl variable in cvsweb.conf to it.
71:
3.17 scop 72: 9) If you like you can add descriptions to be shown next to each directory
3.4 scop 73: or module name. These are read from CVSROOT/descriptions.
3.1 knu 74:
75: - Check out a copy of your CVSROOT
76: - edit checkoutlist and add a line that says
77: descriptions
3.17 scop 78: - Edit descriptions. Add one line for each directory that you would like
3.1 knu 79: to have a comment for. You can have HTML in the descriptions.
80: These lines are relative from the $CVSROOT. Example:
3.22 scop 81: JVote An application to assist with <a href="http://www.irtc.org/">IRTC</a> voting
3.3 knu 82: JVote/images Store the images for JVote
83: JVote/tools Scripts to startup JVote
3.1 knu 84: - cvs add descriptions
85: - cvs commit
86: - Set $use_descriptions to 1 in cvsweb.conf.
87:
3.29 scop 88: 10) Have fun!
3.1 knu 89:
3.17 scop 90: Troubleshooting
91: ---------------
3.1 knu 92:
93: If you've trouble to make cvsweb.cgi work ...
94: .. if nothing seems to work:
3.17 scop 95: o Check if you can execute CGI scripts (Apache needs to have an
96: ScriptAlias /cgi-bin or cgi-script Handler defined). Try to
3.4 scop 97: execute a simple CGI script that often comes with the distribution
98: of the web server; locate the log files and try to find hints
99: which explain the malfunction.
3.32 scop 100: o View the entries in the web server's error.log. Set $DEBUG to 1 in
101: cvsweb.conf to get more error output.
3.1 knu 102:
103: .. If cvsweb seems to work but doesn't show the expected result
104: (Typical error: you can't see any files)
3.4 scop 105: o Check whether the CGI script has read permissions to your
3.17 scop 106: CVS repository. The CGI script often runs as the user 'nobody'
107: or 'httpd'.
108: o If you use annotation, see @annotate_options in cvsweb.conf.
109: o See CVSROOT/config for various options controlling what gets written
110: into CVSROOT/history, where lock files are placed etc. You can also
111: build a fake cvsroot with symlinks to the 'real' CVS directories and make
3.1 knu 112: a fake CVSROOT/history as symbolic link to /dev/null.
3.17 scop 113: If you don't want cvs called from cvsweb to place read locks at all, let
3.1 knu 114: cvsweb operate on a copy.
3.17 scop 115: o Does cvsweb find your RCS utils/cvs binary(annotate)?
116: See $command_path in in cvsweb.conf.
117: o cvsweb allows for compression now. It is determined first if the
118: browser accepts gzip encoding. But - no rule without exception - some
119: versions of MSIE claim to understand gzip encoded content but
120: display garbage .. so compression for MSIE is disabled now. Maybe you
121: find another browser with this problem, then you should disable
4.1 schwarze 122: compression ($allow_compress=0 in cvsweb.conf).
3.17 scop 123:
3.31 scop 124: Upgrade instructions
125: --------------------
126:
4.4 schwarze 127: List of things to pay attention to when upgrading CVSweb from
3.34 scop 128: earlier versions follows. Lack of instructions for a particular
129: version means that there are no special things to pay attention to.
3.31 scop 130:
3.36 scop 131: Upgrading to 3.0.5
3.35 scop 132: ------------------
133:
134: The following configuration variables in cvsweb.conf have changed:
135:
136: $allow_mailtos is new, and optional. See comments in cvsweb.conf.
137:
3.34 scop 138: Upgrading to 3.0.3
139: ------------------
140:
141: The following configuration variables in cvsweb.conf have changed:
142:
143: $DEBUG is new, and optional. See comments in cvsweb.conf.
3.17 scop 144:
3.34 scop 145: Upgrading to 3.0.0
146: ------------------
3.17 scop 147:
148: Make sure that the dependencies are met, see 1) above.
149:
150: The following configuration variables in cvsweb.conf have changed:
151:
3.24 scop 152: $command_path has been changed to @command_path, ie. a list.
153:
3.25 scop 154: @HideModules has been removed. It had nothing to do with actual
155: modules in CVS terminology, and the implementation was broken.
156: @ForbiddenFiles has been enhanced to affect directories as well.
3.17 scop 157:
158: %DEFAULTVALUE for "ln" can now be set to a boolean indicating whether
159: line numbers in markup views should be shown or not. The default is off.
160:
3.20 scop 161: The following parameters have been removed, use CSS instead:
3.17 scop 162: $body_tag, $body_tag_for_src, $navigationHeaderColor, $dirtable,
163: @tabcolors, $columnHeaderColorDefault, $columnHeaderColorSorted,
164: $tableBorderColor, $diffcolorHeading, $diffcolorEmpty, $diffcolorRemove,
165: $diffcolorChange, $diffcolorAdd, $diffcolorDarkChange, $difffontface,
166: $difffontsize, $markupLogColor.
3.20 scop 167:
168: The following parameters have been removed, with no replacement:
3.21 scop 169: $open_extern_window, $extern_window_height, $extern_window_width,
170: $checkout_magic.
3.17 scop 171:
172: $file_list_len can be set to work around problems with rlog(1) and dirs
173: with lots of files.
174:
175: $cssurl contains the absolute URI to the CSS file to use.
176:
4.5 schwarze 177: %ICONS has a new entry: binfile for binary files (-kb keyword
178: substitution).
3.23 scop 179:
180: %DIFF_COMMANDS is new, it is used to configure external per file type
181: diff commands.
CVSweb