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