Annotation of cvsweb/INSTALL, Revision 3.3.2.3
3.3.2.3 ! schwarze 1: $Id$
! 2: $knu: INSTALL,v 1.3.2.1 2002/07/30 19:35:42 scop
3.2 knu 3:
3.1 knu 4: 1) To get cvsweb.cgi to work, make sure that you
3.3.2.1 scop 5: have Perl 5 installed and a web server which is capable
6: of executing cgi-scripts.
3.1 knu 7:
3.3.2.1 scop 8: Surprisingly enough, you need to have cvs installed. The recommended
9: version of cvs is 1.11 or newer. Older cvs versions may work with
10: more or less quirks, YMMV.
11:
12: Currently, you'll also need to have the GNU RCS utilities 'rlog',
3.1 knu 13: 'rcsdiff' installed (current version is 5.7).
14:
15: This will change if cvs will be able
16: to serve these functions without having a working directory
17: [see TODO]
3.3.2.1 scop 18: Note that the cvsweb.cgi script needs to have physical
3.1 knu 19: access to the repository (or a copy of it) therefore;
20: rsh/ssh or pserver access doesn't work yet.
21:
3.3.2.1 scop 22: 2) Copy cvsweb.conf to your configuration directory. If
3.1 knu 23: you've installed Apache, $ServerRoot/conf (or $ServerRoot/etc
24: with versions >= 1.3.0) makes sense.
25: Edit cvsweb.conf to fit your needs, esp. set the CVS-Root(s)
26: of the Repository(ies) you want to view.
27: If your RCS utilities are not in the $PATH of the cgi execution
28: environment you need to set it in the 'Misc' section as well.
29:
3.3.2.1 scop 30: 3) Copy cvsweb.cgi to the cgi script location of your web server.
3.1 knu 31: Edit it to make the variable $config (look for 'Configuration Area')
32: point to your configuration file.
3.3.2.1 scop 33: If your perl binary isn't located in /usr/bin you'll have to edit the
3.1 knu 34: first line of the script as well.
3.3.2.1 scop 35: If you want to run cvsweb.cgi on Windows NT, see (6).
3.1 knu 36:
3.3.2.1 scop 37: 4) If you do not have the dir.gif, text.gif and back.gif icons, copy
38: them somewhere in your $DocumentRoot and edit the %ICONS hash
39: in cvsweb.conf. You won't need to do this if you have a stock
40: Apache installed - they're located in the default icons directory.
3.1 knu 41: The icons distributed with this cvsweb are in the public domain.
3.3.2.1 scop 42: If you think that the default icons are too large, use the corresponding
43: mini icons in the icons/ directory and change the %ICONS hash in
3.1 knu 44: cvsweb.conf.
45:
3.3.2.1 scop 46: 5) Have fun!
3.1 knu 47:
3.2 knu 48: 6) If you've Windows NT running, calling of external programs with parameters
3.1 knu 49: single quoted doesn't work (search for rcsdiff, rlog in
3.3.2.1 scop 50: cvsweb.cgi), you've to replace it with double quotes. Thanks to
51: Nick Brachet for pointing this out.
3.1 knu 52: I don't know if cvs-annotate works on NT.
53:
54: > From: Nick Brachet <nick@gradient.com>
55: [...]
56: > I'm running NT <g> and I had to patch a few things. For example,
57: > open(RCS, "co -p$rev '$fullname' 2>&1 |")
58: > will fail on NT because the ' are not recognized. Using " will work
59: > though.
60:
3.2 knu 61: 7) If you like you can add descriptions to be shown next to each directory
3.3.2.1 scop 62: or module name. These are read from CVSROOT/descriptions.
3.1 knu 63:
64: - Check out a copy of your CVSROOT
65: - edit checkoutlist and add a line that says
66: descriptions
67: - edit descriptions. Add one line for each directory that you would like
68: to have a comment for. You can have HTML in the descriptions.
69: These lines are relative from the $CVSROOT. Example:
3.3 knu 70: JVote An application to assist with <A HREF="http://www.irtc.org/">IRTC</A> voting
71: JVote/images Store the images for JVote
72: JVote/tools Scripts to startup JVote
3.1 knu 73: - cvs add descriptions
74: - cvs commit
75: - Set $use_descriptions to 1 in cvsweb.conf.
76:
77: --------------------
78:
79: if you got PROBLEMS ..
80: ----------------------
81:
82: If you've trouble to make cvsweb.cgi work ...
83: .. if nothing seems to work:
3.3.2.1 scop 84: o Check if you can execute CGI-scripts (Apache needs to have an
85: ScriptAlias /cgi-bin or cgi-script Handler defined). Try to
86: execute a simple CGI script that often comes with the distribution
87: of the web server; locate the log files and try to find hints
88: which explain the malfunction.
89: o View the entries in the web servers error.log
3.1 knu 90:
91: .. If cvsweb seems to work but doesn't show the expected result
92: (Typical error: you can't see any files)
3.3.2.1 scop 93: o Check whether the CGI script has read permissions to your
94: CVS-Repository. The CGI script often runs as the user 'nobody'
95: or 'httpd'...
96: If you use annotation, the user needs to have write permissions
3.1 knu 97: to CVSROOT/history and to the directory the file is in in order
98: to place the read-lock.
3.3.2.1 scop 99: If you don't want cvsweb to write into your CVSROOT/history, build
3.1 knu 100: a fake cvsroot with symlinks to the 'real' CVS-directories and make
101: a fake CVSROOT/history as symbolic link to /dev/null.
3.3.2.1 scop 102: If you don't want cvs called from cvsweb to place read-locks - let
3.1 knu 103: cvsweb operate on a copy.
3.3.2.1 scop 104: o Does cvsweb find your RCS-utils/cvs-binary(annotate) ? ($ENV{PATH} in
3.1 knu 105: cvsweb.conf !)
3.3.2.1 scop 106: o cvsweb allows for compression now. It is determined first,
107: if the browser accepts gzip-encoding. But - no rule without
3.1 knu 108: exception - MSIE claims to understand gzip encoded content but
3.3.2.1 scop 109: displays garbage .. so MSIE is disabled now. Maybe you find another
3.1 knu 110: Browser with this problem, then you should disable compression
3.3.2.2 schwarze 111: ($allow_compress=0 in cvsweb.conf).
CVSweb