Annotation of cvsweb/INSTALL, Revision 3.16
3.3 knu 1: $FreeBSD$
3.2 knu 2:
3.16 ! scop 3: 1) To get cvsweb.cgi to work, make sure that you have Perl 5.6.0 or
3.7 scop 4: newer installed and a web server which is capable of executing CGI
5: scripts.
6:
3.10 scop 7: CVSweb uses the following Perl modules. Chances are that some of
3.7 scop 8: these are already installed with your Perl distribution. The oldest
9: Perl distributions, if any, that already ship with these modules have
10: been marked below. If your Perl doesn't have some of the modules,
11: you can get them from CPAN, <http://www.cpan.org/>. Be sure to
12: install also the prerequisites these modules may have. Note that
13: this list contains only modules that aren't already part of Perl
3.16 ! scop 14: 5.6.0 and newer.
3.7 scop 15:
16:
3.11 scop 17: Module Version Ships with Perl Type
18: ----------------------------------------------------------
19: File::Temp 5.8.0 required
3.12 scop 20: IPC::Run N/A required
3.11 scop 21: MIME::Types N/A optional
3.13 scop 22: String::Ediff N/A optional
3.15 scop 23: URI N/A required
3.1 knu 24:
3.4 scop 25: Surprisingly enough, you need to have cvs installed. The recommended
26: version of cvs is 1.11 or newer. Older cvs versions may work with
27: more or less quirks, YMMV.
28:
29: Currently, you'll also need to have the GNU RCS utilities 'rlog',
3.1 knu 30: 'rcsdiff' installed (current version is 5.7).
31:
3.6 scop 32: This may change if cvs will be able to serve these functions without
33: having a working directory [see TODO].
3.1 knu 34:
3.6 scop 35: Note that the cvsweb.cgi script needs to have physical access to the
36: repository (or a copy of it) therefore; rsh, ssh or pserver access
37: doesn't work yet.
38:
39: Install CvsGraph if you want to use it with CVSWeb, and see (6) for
3.8 scop 40: configuration notes. CvsGraph 1.4.0 or newer is required.
3.5 scop 41:
3.9 scop 42: Install GNU Enscript if you want syntax highlighting, and see (7) for
43: more info. You'll need version 1.6.2 or newer.
44:
3.4 scop 45: 2) Copy cvsweb.conf to your configuration directory. If
3.1 knu 46: you've installed Apache, $ServerRoot/conf (or $ServerRoot/etc
47: with versions >= 1.3.0) makes sense.
48: Edit cvsweb.conf to fit your needs, esp. set the CVS-Root(s)
49: of the Repository(ies) you want to view.
50: If your RCS utilities are not in the $PATH of the cgi execution
51: environment you need to set it in the 'Misc' section as well.
52:
3.4 scop 53: 3) Copy cvsweb.cgi to the cgi script location of your web server.
3.1 knu 54: Edit it to make the variable $config (look for 'Configuration Area')
55: point to your configuration file.
3.4 scop 56: If your perl binary isn't located in /usr/bin you'll have to edit the
3.1 knu 57: first line of the script as well.
3.9 scop 58: If you want to run cvsweb.cgi on Windows NT, see (9).
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:
72: 6) CvsGraph <http://www.akhphd.au.dk/~bertho/cvsgraph/> can be used with
3.5 scop 73: this version of CVSWeb. See the $allow_cvsgraph and $cvsgraph_config
74: configuration variables in cvsweb.conf. cvsweb.cgi will override some
75: of the settings in the cvsgraph configuration file with command line
76: options; the following in particular: map_branch_href, map_rev_href and
77: map_diff_href so you won't have to tweak them for CVSWeb. Note (and
78: install) also the cvsgraph.png icon in the icons/ directory.
79:
3.9 scop 80: 7) GNU Enscript <http://www.iki.fi/~mtr/genscript/> can be used for syntax
81: highlighting. To enable it, copy lang_cvsweb.st from the enscript/ dir
82: to your Enscript "hl" directory (eg. /usr/share/enscript/hl/) and enable
83: $allow_enscript in cvsweb.conf.
84:
85: 8) Have fun!
3.1 knu 86:
3.9 scop 87: 9) If you've Windows NT running, calling of external programs with parameters
3.1 knu 88: single quoted doesn't work (search for rcsdiff, rlog in
3.4 scop 89: cvsweb.cgi), you've to replace it with double quotes. Thanks to
90: Nick Brachet for pointing this out.
3.1 knu 91: I don't know if cvs-annotate works on NT.
92:
93: > From: Nick Brachet <nick@gradient.com>
94: [...]
95: > I'm running NT <g> and I had to patch a few things. For example,
96: > open(RCS, "co -p$rev '$fullname' 2>&1 |")
97: > will fail on NT because the ' are not recognized. Using " will work
98: > though.
99:
3.9 scop 100: 10) If you like you can add descriptions to be shown next to each directory
3.4 scop 101: or module name. These are read from CVSROOT/descriptions.
3.1 knu 102:
103: - Check out a copy of your CVSROOT
104: - edit checkoutlist and add a line that says
105: descriptions
106: - edit descriptions. Add one line for each directory that you would like
107: to have a comment for. You can have HTML in the descriptions.
108: These lines are relative from the $CVSROOT. Example:
3.3 knu 109: JVote An application to assist with <A HREF="http://www.irtc.org/">IRTC</A> voting
110: JVote/images Store the images for JVote
111: JVote/tools Scripts to startup JVote
3.1 knu 112: - cvs add descriptions
113: - cvs commit
114: - Set $use_descriptions to 1 in cvsweb.conf.
115:
116: --------------------
117:
118: if you got PROBLEMS ..
119: ----------------------
120:
121: If you've trouble to make cvsweb.cgi work ...
122: .. if nothing seems to work:
3.4 scop 123: o Check if you can execute CGI-scripts (Apache needs to have an
124: ScriptAlias /cgi-bin or cgi-script Handler defined). Try to
125: execute a simple CGI script that often comes with the distribution
126: of the web server; locate the log files and try to find hints
127: which explain the malfunction.
128: o View the entries in the web servers error.log
3.1 knu 129:
130: .. If cvsweb seems to work but doesn't show the expected result
131: (Typical error: you can't see any files)
3.4 scop 132: o Check whether the CGI script has read permissions to your
133: CVS-Repository. The CGI script often runs as the user 'nobody'
134: or 'httpd'...
135: If you use annotation, the user needs to have write permissions
3.1 knu 136: to CVSROOT/history and to the directory the file is in in order
137: to place the read-lock.
3.4 scop 138: If you don't want cvsweb to write into your CVSROOT/history, build
3.1 knu 139: a fake cvsroot with symlinks to the 'real' CVS-directories and make
140: a fake CVSROOT/history as symbolic link to /dev/null.
3.4 scop 141: If you don't want cvs called from cvsweb to place read-locks - let
3.1 knu 142: cvsweb operate on a copy.
3.4 scop 143: o Does cvsweb find your RCS-utils/cvs-binary(annotate) ? ($ENV{PATH} in
3.1 knu 144: cvsweb.conf !)
3.4 scop 145: o cvsweb allows for compression now. It is determined first,
146: if the browser accepts gzip-encoding. But - no rule without
3.1 knu 147: exception - MSIE claims to understand gzip encoded content but
3.4 scop 148: displays garbage .. so MSIE is disabled now. Maybe you find another
3.1 knu 149: Browser with this problem, then you should disable compression
3.4 scop 150: ($allow_compress=0 in cvsweb.conf) and
3.1 knu 151: report it to me (<zeller@think.de>)
CVSweb