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

Annotation of cvsweb/INSTALL, Revision 3.19

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:
                     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.
                     51:    See also the $command_path variable for the path where cvsweb.cgi
                     52:    looks for the various external executables it interacts with.
                     53:
                     54: 3) Copy cvsweb.cgi to a directory of your web server where the execution
                     55:    of CGI scripts is allowed.  Edit it to make the variable $config
                     56:    (look for 'Configuration Area') point to your configuration file.
3.4       scop       57:    If your perl binary isn't located in /usr/bin you'll have to edit the
3.17      scop       58:    first line of the script as well.
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.17      scop       87: 9) If you like you can add descriptions to be shown next to each directory
3.4       scop       88:    or module name.  These are read from CVSROOT/descriptions.
3.1       knu        89:
                     90:    - Check out a copy of your CVSROOT
                     91:    - edit checkoutlist and add a line that says
                     92:        descriptions
3.17      scop       93:    - Edit descriptions.  Add one line for each directory that you would like
3.1       knu        94:      to have a comment for.  You can have HTML in the descriptions.
                     95:      These lines are relative from the $CVSROOT.  Example:
3.17      scop       96:        JVote          An application to assist with <a href="http://www.irtc.org/">IRTC</A> voting
3.3       knu        97:        JVote/images   Store the images for JVote
                     98:        JVote/tools    Scripts to startup JVote
3.1       knu        99:    - cvs add descriptions
                    100:    - cvs commit
                    101:    - Set $use_descriptions to 1 in cvsweb.conf.
                    102:
                    103:
3.17      scop      104: Troubleshooting
                    105: ---------------
3.1       knu       106:
                    107: If you've trouble to make cvsweb.cgi work ...
                    108: .. if nothing seems to work:
3.17      scop      109:  o Check if you can execute CGI scripts (Apache needs to have an
                    110:    ScriptAlias /cgi-bin or cgi-script Handler defined).  Try to
3.4       scop      111:    execute a simple CGI script that often comes with the distribution
                    112:    of the web server; locate the log files and try to find hints
                    113:    which explain the malfunction.
3.17      scop      114: o  View the entries in the web server's error.log.
3.1       knu       115:
                    116: .. If cvsweb seems to work but doesn't show the expected result
                    117:   (Typical error: you can't see any files)
3.4       scop      118:  o Check whether the CGI script has read permissions to your
3.17      scop      119:    CVS repository.  The CGI script often runs as the user 'nobody'
                    120:    or 'httpd'.
                    121:  o If you use annotation, see @annotate_options in cvsweb.conf.
                    122:  o See CVSROOT/config for various options controlling what gets written
                    123:    into CVSROOT/history, where lock files are placed etc.  You can also
                    124:    build a fake cvsroot with symlinks to the 'real' CVS directories and make
3.1       knu       125:    a fake CVSROOT/history as symbolic link to /dev/null.
3.17      scop      126:    If you don't want cvs called from cvsweb to place read locks at all, let
3.1       knu       127:    cvsweb operate on a copy.
3.17      scop      128:  o Does cvsweb find your RCS utils/cvs binary(annotate)?
                    129:    See $command_path in in cvsweb.conf.
                    130:  o cvsweb allows for compression now.  It is determined first if the
                    131:    browser accepts gzip encoding.  But - no rule without exception - some
                    132:    versions of MSIE claim to understand gzip encoded content but
                    133:    display garbage .. so compression for MSIE is disabled now.  Maybe you
                    134:    find another browser with this problem, then you should disable
                    135:    compression ($allow_compress=0 in cvsweb.conf) and report it to
                    136:    <freebsd-cvsweb@freebsd.org>.
                    137:
                    138:
                    139: Upgrading from FreeBSD-CVSweb 2.0.x to 3.x
                    140: ------------------------------------------
                    141:
                    142: Make sure that the dependencies are met, see 1) above.
                    143:
                    144: The following configuration variables in cvsweb.conf have changed:
                    145:
                    146:    $cvstreedefault is now optional.  If unset, the first one in
                    147:    @CVSrepositories is used.
                    148:
                    149:    %DEFAULTVALUE for "f" (default diff format) now understands the values
                    150:    uc, cc and sc for enscript-colored diffs.
                    151:
                    152:    %DEFAULTVALUE for "ln" can now be set to a boolean indicating whether
                    153:    line numbers in markup views should be shown or not.  The default is off.
                    154:
                    155:    The following parameter have been removed, use CSS instead:
                    156:    $body_tag, $body_tag_for_src, $navigationHeaderColor, $dirtable,
                    157:    @tabcolors, $columnHeaderColorDefault, $columnHeaderColorSorted,
                    158:    $tableBorderColor, $diffcolorHeading, $diffcolorEmpty, $diffcolorRemove,
                    159:    $diffcolorChange, $diffcolorAdd, $diffcolorDarkChange, $difffontface,
                    160:    $difffontsize, $markupLogColor.
                    161:
                    162:    $allow_enscript, @enscript_options and %enscript_types control the use
                    163:    and behavior of enscript(1).
                    164:
                    165:    $allow_cvsgraph and $cvsgraph_config control the use and behavior of
                    166:    cvsgraph(1).
                    167:
                    168:    $file_list_len can be set to work around problems with rlog(1) and dirs
                    169:    with lots of files.
                    170:
                    171:    $cssurl contains the absolute URI to the CSS file to use.
                    172:
                    173:    %ICONS has two new entries: binfile for binary files (-kb keyword
                    174:    substitution) and graph for the cvsgraph icon.

CVSweb