viewvc-4intranet/INSTALL

CONTENTS
--------
  TO THE IMPATIENT
  INSTALLING VIEWCVS
  UPGRADING VIEWCVS
  SQL CHECKIN DATABASE
  ENSCRIPT CONFIGURATION
  CVSGRAPH CONFIGURATION
  IF YOU HAVE PROBLEMS...


TO THE IMPATIENT
----------------
Congratulations on getting this far. :-)

Prerequisites: Python 1.5 or later
                 (http://www.python.org/)
               RCS, Revision Control System
                 (http://www.cs.purdue.edu/homes/trinkle/RCS/)
               read-only, physical access to a CVS repository
                 (See http://www.cvshome.org/ for more information)

Optional:      a web server capable of running CGI programs
                 (for example, Apache at http://httpd.apache.org/)
               GNU-diff to replace broken diff implementations
                 (http://www.gnu.org/software/diffutils/diffutils.html)
               MySQL to create and query a commit database
                 (http://www.mysql.com/)
                 (http://sourceforge.net/projects/mysql-python)
		 (and Python 1.5.2 or later)
               Enscript to colorize code displayed from the CVS repository
                 (http://people.ssh.com/mtr/genscript/)
               CvsGraph for a graphical representation of the CVS revisions
                 (http://www.akhphd.au.dk/~bertho/cvsgraph/)

  GUI Operation:

    If you just want to see what your CVS repository looks like with
    ViewCVS, type "./standalone.py -g -r /PATH/TO/CVS/ROOT".  This
    will start a tiny webserver serving at http://localhost:7467/.

  Standard operation:

    To start installing right away (on UNIX): type "./viewcvs-install"
    in the current directory and answer the prompts.  When it
    finishes, edit the file viewcvs.conf in the installation directory
    to tell viewcvs the paths to your CVS repositories. Next,
    configure your web server to run <INSTALL>/cgi/viewcvs.cgi, as
    appropriate for your web server.  The section `INSTALLING VIEWCVS'
    below is still recommended reading.


INSTALLING VIEWCVS
------------------

1) To get viewcvs.cgi to work, make sure that you have Python 1.5 or
   greater installed and a webserver which is capable of executing
   CGI scripts (either based on the .cgi extension, or by placing the
   script within a specific directory).

   You need to have RCS installed. Specifically, "rlog", "rcsdiff",
   and "co". This script was tested against RedHat's rcs-5.7-10.rpm

   Note, that the viewcvs.cgi script needs to have READ-ONLY, physical
   access to the CVS repository (or a copy of it).  Therefore, rsh/ssh or
   pserver access to the repository will not work.

   For the more human readable diff formats you need a modern diff utility.
   If you are using Linux, this is no problem.  But on commercial unices
   you might want to install GNU-diff to be able to use unified or 
   side-by-side diffs.

   If you want to use cvsgraph, you have to obtain and install this
   separately.  See below.  This was tested with cvsgraph-1.1.2.

   For the checkin database to work, you will need MySQL >= 3.22, 
   and the Python DBAPI 2.0 module, MySQLdb.  This was tested with
   MySQLdb 0.9.1.

2) Installation is handled by the ./viewcvs-install script.  Run this
   script and you will be prompted for a installation root path.
   The default is /usr/local/viewcvs-VERSION, where VERSION is
   the version of this ViewCVS release.  The installer sets the install 
   path in some of the files, and ViewCVS cannot be moved to a 
   different path after the install.

   Note: while 'root' is usually required to create /usr/local/viewcvs,
   ViewCVS does not have to be installed as root, nor does it run as root.
   It is just as valid to place ViewCVS in a home directory, too.

   Note: viewcvs-install will create directories if needed. It will
   prompt before overwriting files that may have been modified (such
   as viewcvs.conf), thus making it safe to install over the top of
   a previous installation. It will always overwrite program files,
   however.

3) Edit <VIEWCVS_INSTALLATION_DIRECTORY>/viewcvs.conf for your specific 
   configuration.  In particular, examine the following configuration options:

      cvs_roots
      default_root
      rcs_path
      mime_types_file

   There are some other options that are usually nice to change. See
   viewcvs.conf for more information.  ViewCVS provides a working,
   default look. However, if you want to customize the look of ViewCVS
   then edit the files in <VIEWCVS_INSTALLATION_DIRECTORY>/templates.
   You need knowledge about HTML to edit the templates.

4) The CGI programs are in <VIEWCVS_INSTALLATION_DIRECTORY>/cgi/.  You can 
   symlink to this directory from somewhere in your published HTTP server 
   path if your webserver is configured to follow symbolic links.  You can 
   also copy the installed <VIEWCVS_INSTALLATION_DIRECTORY>/cgi/*.cgi scripts 
   after the install (unlike the other files in ViewCVS, the CGI scripts can 
   be moved).

   If you are using Apache, then the ScriptAlias directive is very
   useful for pointing directly to the viwecvs.cgi script.

   NOTE: for security reasons, it is not advisable to install ViewCVS
   directly into your published HTTP directory tree (due to the MySQL
   passwords in viewcvs.conf).

5) That's it for repository browsing.  Instructions for getting the
   SQL checkin database working are below.


WARNING: ViewCVS has not been tested on web servers operating on the
         Win32 platform.


UPGRADING VIEWCVS
-----------------

Please read the file upgrading.html in the website subdirectory or
at <http://viewcvs.sourceforge.net/upgrading.html>.


SQL CHECKIN DATABASE
--------------------

This feature is a clone of the Mozilla Project's Bonsai database.  It
catalogs every commit in the CVS repository into a SQL database.  In fact,
the databases are 100% compatible.

Various queries can be performed on the database.  After installing ViewCVS,
there are some additional steps required to get the database working.

1) You need MySQL >= 3.22, and the Python module MySQLdb 0.9.0 installed.
   Python 1.5.2 is REQUIRED by MySQLdb, therefore to use this part of
   ViewCVS you must be using Python 1.5.2.  Additionally you will need the
   mxDateTime extension.  I've tested with version 1.3.0

2) You need to create a MySQL user who has permission to create databases.
   Optionally, you can create a second user with read-only access to the
   database.

3) Run the <VIEWCVS_INSTALLATION_DIRECTORY>/make-database script.  It will 
   prompt you for your MySQL user, password, and the name of database you 
   want to create.  The database name defaults to "ViewCVS".  This script 
   creates the database and sets up the empty tables.  If you run this on a 
   existing ViewCVS database, you will lose all your data!

4) Edit your <VIEWCVS_INSTALLATION_DIRECTORY>/viewcvs.conf file.  
   There is a [cvsdb] section.  You will need to set:
     
      
      host =             # MySQL database server host
      database_name =    # the name of the database you created with
                         # make-database
      user =             # the read/write database user
      passwd =           # password for read/write database user
      readonly_user =    # the readonly database user -- it's pretty 
                         # safe to use the read/write user here
      readonly_passwd =  # password for the readonly user

5) Two programs are provided for updating the checkin database, 
   cvsdbadmin and loginfo-handler.  They serve two different purposes.
   The cvsdbadmin program walks through your CVS repository and adds
   every commit in every file.  This is commonly used for initializing
   the database from a repository which has been in use.  The 
   loginfo-handler script is executed by the CVS server's CVSROOT/loginfo 
   system upon each commit.  It makes real-time updates to the checkin
   database as commits are made to the repository.

   To build a database of all the commits in the CVS repository /home/cvs,
   invoke: "./cvsdbadmin rebuild /home/cvs".  If you want to update
   the checkin database, invoke: "./cvsdbadmin update /home/cvs".  The
   update mode checks to see if a commit is already in the database,
   and only adds it if it is absent.

   To get real-time updates, you'll want to checkout the CVSROOT module
   from your CVS repository and edit CVSROOT/loginfo.  Add the line:

     ALL (echo %{sVv}; cat) | <VIEWCVS_INSTALLATION_DIRECTORY>/loginfo-handler

   If you have other scripts invoked by CVSROOT/loginfo, you will want
   to make sure to change any running under the "DEFAULT" keyword to
   "ALL" like the loginfo handler, and probably carefully read the
   execution rules for CVSROOT/loginfo from the CVS manual.

6) You may want to modify the HTML template file:

      <VIEWCVS_INSTALLATION_DIRECTORY>/templates/query.ezt

   This is used by the query.cgi script to generate part of its HTML output.  
   At some point the currently hardcoded table output will also vanish.

7) You should be ready to go.  Load up the query.cgi script and give 
   it a try.


ENSCRIPT CONFIGURATION
----------------------

Enscript is program that can colorize sourcecode of a lot of languages.
Linux distributions like for example SuSE Linux from at least 7.0
up to the recently released 7.3 already contain a precompiled and
configured enscript 1.6.2 package.

1) Download genscript from http://people.ssh.com/mtr/genscript/

2) Configure and compile per instructions with enscript.
   (I 've not done this, since I'm using the precompiled package
   delivered with SuSE Linux)

3) Set the 'use_enscript' option in viewcvs.conf to 1.

4) That's it!

5) If you want to colorize exotic languages, you might have to 
   patch 'lib/viewcvs.py' and add a new highlighting file to enscript.
   I've done this for Modula-2 and submitted the file to the 
   enscript maintainer long ago.  If interested in this patch for
   enscript mailto:pefu@sourceforge.net


CVSGRAPH CONFIGURATION
----------------------

CvsGraph is a program that can display a clickable, graphical tree
of files in a CVS repository.

WARNING: Under certain circumstances (many revisions of a file
or many branches or both) cvsgraph can generate very huge images.
Especially on thin clients these images may crash the Web-Browser.
Currently there is no known way to avoid this behavior of cvsgraph.
So you have been warned!  

Nevertheless cvsgraph can be quite helpful on repositories with 
a reasonable number of revisions and branches.

1) Install viewcvs according to instructions in 'INSTALLING
   VIEWCVS' section above.  The installation directory is where
   the 'viewcvs-install' script copied and configured the viewcvs
   programs.

2) Download CvsGraph from http://www.akhphd.au.dk/~bertho/cvsgraph/

3) Configure and compile per instructions with CvsGraph.  I had
   problems with 'configure' finding the gd library.  Had to create
   a link from libgd.so to libgd.do.4.0.0.   On Solaris you might
   want to edit the link command line and add the option -R if 
   you have you libraries at non-standard location.

4) Place the 'cvsgraph' executable into a directory readable by the
   userid running the web server. (default is '/usr/local/bin' if
   you simply type 'make install' in the cvsgraph directory).

5) Check the setting of the 'cvsgraph_path' option in viewcvs.conf:
   /usr/local/bin/ is most often NOT contained in $PATH of the
   webserver process (e.g. Apache), so you will have to edit this.  
   Set the 'use_cvsgraph' option in viewcvs.conf to 1.

6) That's it!

7) There is a file <VIEWCVS_INSTALLATION_DIRECTORY>/cvsgraph.conf that
   you may want to edit if desired to set color and font characteristics.
   See the cvsgraph.conf documentation.  No edits are required in
   cvsgraph.conf for operation with viewcvs.


IF YOU HAVE PROBLEMS ...
------------------------

If you've trouble to make viewcvs.cgi work:

=== If nothing seems to work:

 o check if you can execute CGI-scripts (Apache needs to have an
   ScriptAlias /cgi-bin or cgi-script Handler defined). Try to 
   execute a simple CGI-script that often comes with the distribution
   of the webserver; locate the logfiles and try to find hints
   which explain the malfunction

 o view the entries in the webserver's error.log
 
 o make sure there is a trailing slash on the URL. for example:
 
     http://www.example.com/cgi-bin/viewcvs.cgi/
     
   (ViewCVS should perform a redirection to ensure this, but a report
    has indicated that it doesn't always do this... please send more
    of these bug reports if you run into this)

=== If viewcvs seems to work but doesn't show the expected result
    (Typical error: you can't see any files)

 o check whether the CGI-script has read-permissions to your
   CVS-Repository. The CGI-script often runs as the user 'nobody' 
   or 'httpd' ..

 o does viewcvs find your RCS utilities? (edit rcs_path)

=== If something else happens or you can't get it to work:

 o check the ViewCVS home page:

     http://viewcvs.sourceforge.net/

 o review the ViewCVS mailing list archive to see if somebody else had
   the same problem, and it was solved:

     http://mailman.lyra.org/pipermail/viewcvs/

 o send mail to the ViewCVS mailing list: viewcvs@lyra.org

   NOTE: make sure you provide an accurate description of the problem
         and any relevant tracebacks or error logs.