[BACK]Return to INSTALL CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / cvsweb

Annotation of cvsweb/INSTALL, Revision 4.5

4.5     ! schwarze    1: $Id: INSTALL,v 4.4 2019/11/11 13:15:09 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:
                     32:    Currently, you'll also need to have the GNU RCS utilities  'rlog',
3.17      scop       33:    'rcsdiff' installed (current version is 5.7).
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.9       scop       42:    Install GNU Enscript if you want syntax highlighting, and see (7) for
3.19      scop       43:    more info.  You'll need version 1.6.3 or newer.
3.9       scop       44:
3.29      scop       45:    Install CVSHistory if you want to use it with CVSweb, and see (8) for
                     46:    configuration notes.  You'll need version 2.0 or newer.
                     47:
3.17      scop       48: 2) Copy cvsweb.conf to a configuration directory, typically
                     49:    /usr/local/etc/cvsweb/cvsweb.conf.
                     50:    Edit cvsweb.conf to fit your needs, you'll probably need to tweak the
                     51:    CVS root(s) of the Repository(ies) you want to view.
3.26      scop       52:    See also the @command_path variable for the path where cvsweb.cgi
3.17      scop       53:    looks for the various external executables it interacts with.
3.26      scop       54:    The other cvsweb.conf-* files are example per-cvsroot configuration files,
                     55:    see commentary in cvsweb.conf for more information.
3.17      scop       56:
                     57: 3) Copy cvsweb.cgi to a directory of your web server where the execution
                     58:    of CGI scripts is allowed.  Edit it to make the variable $config
                     59:    (look for 'Configuration Area') point to your configuration file.
3.4       scop       60:    If your perl binary isn't located in /usr/bin you'll have to edit the
3.26      scop       61:    first line of the script as well.  For Apache web servers, there is an
                     62:    optional sample httpd.conf snippet in the samples/ directory.  Most
                     63:    setups do not need it though, it is only for advanced and/or mod_perl
                     64:    configurations.
3.1       knu        65:
3.4       scop       66: 4) If you do not have the dir.gif, text.gif and back.gif icons, copy
                     67:    them somewhere in your $DocumentRoot and edit the %ICONS hash
                     68:    in cvsweb.conf.  You won't need to do this if you have a stock
                     69:    Apache installed - they're located in the default icons directory.
3.1       knu        70:    The icons distributed with this cvsweb are in the public domain.
3.4       scop       71:    If you think that the default icons are too large, use the corresponding
                     72:    mini icons in the icons/ directory and change the %ICONS hash in
3.1       knu        73:    cvsweb.conf.
                     74:
3.6       scop       75: 5) Copy cvsweb.css from the css/ directory to a web server directory, and
                     76:    point the $cssurl variable in cvsweb.conf to it.
                     77:
3.9       scop       78: 7) GNU Enscript <http://www.iki.fi/~mtr/genscript/> can be used for syntax
3.27      scop       79:    highlighting.  To enable it, copy lang_cvsweb.st and lang_cvsweb_diff.st
                     80:    from the enscript/ dir to your Enscript "hl" directory (often eg.
                     81:    /usr/share/enscript/hl/) and enable $allow_enscript in cvsweb.conf.
                     82:    lang_cvsweb.st is used for generic colorization, and lang_cvsweb_diff.st
                     83:    for diffs.
3.9       scop       84:
3.29      scop       85: 8) CVSHistory <http://www.jamwt.com/CVSHistory/> can be used with this
                     86:    version of CVSweb.  See the $cvshistory_url configuration variable in
                     87:    cvsweb.conf.  For best results, configure CVSweb and CVSHistory to use
                     88:    the same "logical names" for CVS roots.
3.1       knu        89:
3.17      scop       90: 9) If you like you can add descriptions to be shown next to each directory
3.4       scop       91:    or module name.  These are read from CVSROOT/descriptions.
3.1       knu        92:
                     93:    - Check out a copy of your CVSROOT
                     94:    - edit checkoutlist and add a line that says
                     95:        descriptions
3.17      scop       96:    - Edit descriptions.  Add one line for each directory that you would like
3.1       knu        97:      to have a comment for.  You can have HTML in the descriptions.
                     98:      These lines are relative from the $CVSROOT.  Example:
3.22      scop       99:        JVote          An application to assist with <a href="http://www.irtc.org/">IRTC</a> voting
3.3       knu       100:        JVote/images   Store the images for JVote
                    101:        JVote/tools    Scripts to startup JVote
3.1       knu       102:    - cvs add descriptions
                    103:    - cvs commit
                    104:    - Set $use_descriptions to 1 in cvsweb.conf.
                    105:
3.29      scop      106: 10) Have fun!
3.1       knu       107:
3.17      scop      108: Troubleshooting
                    109: ---------------
3.1       knu       110:
                    111: If you've trouble to make cvsweb.cgi work ...
                    112: .. if nothing seems to work:
3.17      scop      113:  o Check if you can execute CGI scripts (Apache needs to have an
                    114:    ScriptAlias /cgi-bin or cgi-script Handler defined).  Try to
3.4       scop      115:    execute a simple CGI script that often comes with the distribution
                    116:    of the web server; locate the log files and try to find hints
                    117:    which explain the malfunction.
3.32      scop      118: o  View the entries in the web server's error.log.  Set $DEBUG to 1 in
                    119:    cvsweb.conf to get more error output.
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
4.1       schwarze  140:    compression ($allow_compress=0 in cvsweb.conf).
3.17      scop      141:
3.31      scop      142: Upgrade instructions
                    143: --------------------
                    144:
4.4       schwarze  145: List of things to pay attention to when upgrading CVSweb from
3.34      scop      146: earlier versions follows.  Lack of instructions for a particular
                    147: version means that there are no special things to pay attention to.
3.31      scop      148:
3.36      scop      149: Upgrading to 3.0.5
3.35      scop      150: ------------------
                    151:
                    152: The following configuration variables in cvsweb.conf have changed:
                    153:
                    154:   $allow_mailtos is new, and optional.  See comments in cvsweb.conf.
                    155:
3.34      scop      156: Upgrading to 3.0.3
                    157: ------------------
                    158:
                    159: The following configuration variables in cvsweb.conf have changed:
                    160:
                    161:   $DEBUG is new, and optional.  See comments in cvsweb.conf.
                    162:
                    163: Upgrading to 3.0.1
                    164: ------------------
3.29      scop      165:
                    166: The following configuration variables in cvsweb.conf have changed:
                    167:
                    168:    $cvshistory_url is new, and optional.  See comments in cvsweb.conf.
3.17      scop      169:
3.34      scop      170: Upgrading to 3.0.0
                    171: ------------------
3.17      scop      172:
                    173: Make sure that the dependencies are met, see 1) above.
                    174:
                    175: The following configuration variables in cvsweb.conf have changed:
                    176:
3.24      scop      177:    $command_path has been changed to @command_path, ie. a list.
                    178:
3.25      scop      179:    @HideModules has been removed.  It had nothing to do with actual
                    180:    modules in CVS terminology, and the implementation was broken.
                    181:    @ForbiddenFiles has been enhanced to affect directories as well.
                    182:
3.17      scop      183:    $cvstreedefault is now optional.  If unset, the first one in
                    184:    @CVSrepositories is used.
                    185:
                    186:    %DEFAULTVALUE for "f" (default diff format) now understands the values
3.22      scop      187:    "uc", "cc" and "sc" for enscript-colored diffs (unified, context and
                    188:    side-by-side respectively).
3.17      scop      189:
                    190:    %DEFAULTVALUE for "ln" can now be set to a boolean indicating whether
                    191:    line numbers in markup views should be shown or not.  The default is off.
                    192:
3.20      scop      193:    The following parameters have been removed, use CSS instead:
3.17      scop      194:    $body_tag, $body_tag_for_src, $navigationHeaderColor, $dirtable,
                    195:    @tabcolors, $columnHeaderColorDefault, $columnHeaderColorSorted,
                    196:    $tableBorderColor, $diffcolorHeading, $diffcolorEmpty, $diffcolorRemove,
                    197:    $diffcolorChange, $diffcolorAdd, $diffcolorDarkChange, $difffontface,
                    198:    $difffontsize, $markupLogColor.
3.20      scop      199:
                    200:    The following parameters have been removed, with no replacement:
3.21      scop      201:    $open_extern_window, $extern_window_height, $extern_window_width,
                    202:    $checkout_magic.
3.17      scop      203:
                    204:    $allow_enscript, @enscript_options and %enscript_types control the use
                    205:    and behavior of enscript(1).
                    206:
                    207:    $file_list_len can be set to work around problems with rlog(1) and dirs
                    208:    with lots of files.
                    209:
                    210:    $cssurl contains the absolute URI to the CSS file to use.
                    211:
4.5     ! schwarze  212:    %ICONS has a new entry: binfile for binary files (-kb keyword
        !           213:    substitution).
3.23      scop      214:
                    215:    %DIFF_COMMANDS is new, it is used to configure external per file type
                    216:    diff commands.

CVSweb