- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
DESCRIPTION

This file contains special instructions for setting up ViewCVS on Windows. It
will take you through a basic installation and tell you how to set up optional
features like code colorizing and the MySQL commit database.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
REQUIREMENTS

ViewCVS requires the Python interpreter which you can download from

  http://python.org/

and the Python for Windows Extensions which are at

  http://starship.python.net/crew/mhammond/win32/

ViewCVS also requires that the CVSNT client (cvs.exe) OR the RCS tools
(rlog.exe, rcsdiff.exe, and co.exe) be installed on your computer. CVSNT is
available from

  http://www.cvsnt.org/

and RCS can be obtained from:

  http://www.cs.purdue.edu/homes/trinkle/RCS/

Once you've got Python and CVSNT or RCS installed, you can test out ViewCVS
before you install it by running:

  python standalone.py -r <PATH_TO_REPOSITORY>

The standalone server has a number of features (including a GUI interface)
which you can find out about by running

  python standalone.py --help

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
BASIC INSTALLATION

Run the ViewCVS install script with

  python viewcvs-install

The script will copy the source files into an installation directory that you
specify, store some path information, and compile the ViewCVS library files
into Python bytecode.

After the installation is finished you will need to edit the viewcvs.conf file
in the folder you installed to. The comments in that file tell you exactly what
to do.

With the config file set up you should be able to double-click standalone.py
and access your repository with a web browser.

See the sections below for information on setting up optional features and
troubleshooting. From here on <PYTHON_DIR> will stand for the Python root
directory (usually something like C:\Python22) and <VIEWCVS_INSTALL_DIR> will
represent the directory where ViewCVS has been installed to (default is
C:\Program Files\viewcvs-1.0-dev).

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
SERVER CONFIGURATION

If you want to make ViewCVS available to a network (rather than using it on a
standalone machine), you will need to configure a web server to host it. This
section includes instructions for setting up ViewCVS on two commonly used
Windows web servers, IIS and Apache.

With IIS, you can run ViewCVS in CGI mode or ASP mode (or both modes). ASP mode
gives better performance (faster page loads), but is harder to set up and may
be less stable. CGI mode is stable and easy to set up but slower.

On Apache, you can use CGI mode or Mod_Python mode or both modes at once.
Mod_Python mode is faster than CGI mode.

CGI Mode On IIS

  1) Copy viewcvs.cgi and query.cgi from <VIEWCVS_INSTALL_DIR>\www\cgi to a
  folder that is accessible through your web server.

  2) Start up the IIS "Internet Services Manager" and right click a virtual
  server or virtual directory that contains the files you just copied. Choose
  "Properties" from the context menu that appears.

  3) On the properties dialog that appears, navigate to [Home | Virtual]
  Directory -> Application Settings -> Configuration. This will bring up
  another dialog box called "Application Configuration".

  4) On the "App Mappings" tab choose "Add". Fill in the following information

                 Executable:  <PYTHON_DIR>\python.exe "%s"
                  Extension:  cgi
              Script Engine:  checked
     Check that file exists:  unchecked

  That is all. Assuming you've set up viewcvs.conf to point to your
  repositories, the CGI pages should run. See the Troubleshooting section below
  if there are any problems.

ASP Mode On IIS

  In order to run ViewCVS with ASP, you will need to enable Python ActiveX
  scripting and to install the included Aspfool ISAPI filter on whatever
  virtual server is being used to serve the viewcvs pages. Step by step
  instructions follow below. Aspfool is located in the windows\aspfool folder.

  To set up ASP mode, follow these steps:

  1) Run <PYTHON_DIR>\Lib\site-packages\win32comext\axscript\client\pyscript.py
  to register Python as an ASP scripting language. (More documentation on this
  is at http://www.python.org/windows/win32com/ActiveXScripting.html)

  2) Copy the viewcvs.asp and query.asp files from
  <VIEWCVS_INSTALL_DIR>\www\asp to a folder that is accessible through your web
  server.

  3) Start up the IIS "Internet Services Manager" and right click on the
  virtual server that contains the files you just copied. Choose "Properties"
  from the context menu that appears.

  4) On the properties dialog that appears, click the "ISAPI Filters" tab.
  Click the "add" button and enter the following information:

     Filter Name:  aspfool
      Executable:  aspfool.dll

  After you save these changes, the ViewCVS ASP pages should begin to work.

CGI Mode on Apache

  Follow the instructions under "Apache Configuration" in the ViewCVS INSTALL
  file.

Mod_Python Mode on Apache

  There are probably ten thousand different ways to set up Apache, mod_python,
  and ViewCVS together. Here are some instructions that work for me using
  Mod_Python 3.0.3 and Apache 2.0.46. If any Apache gurus want to contribute
  better instructions, I'd be happy to include them here.

  1) Run the win32 mod_python installer from www.modpython.org.

  2) Add the following line to the "Global Environment" section of httpd.conf

     LoadModule python_module modules/mod_python.so

  3) Copy viewcvs.py, query.py, and .htaccess from
  <VIEWCVS_INSTALL_DIR>\www\mod_python to a folder being served by apache. Make
  sure overrides are allowed in this folder. The relevant parent directory in
  httpd.conf should have "AllowOverride All" set, or at least "AllowOverride
  FileInfo Options".

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ENSCRIPT HIGHLIGHTING

To use enscript, you'll have to install the enscript, libintl, libiconv, and
sed packages from the gnuwin32 project (http://gnuwin32.sourceforge.net/).
Detailed instructions are on their site, but here is the basic procedure.

1) Extract all packages to a folder on your hard drive, for example c:\gnuwin32

2) Add "c:\gnuwin32\bin" to the system "PATH" environment variable. If ViewCVS
is running as part of a system service like IIS you will need to reboot the
computer so it is able to see the value. See the "Troubleshooting" section
below for specific information on when a reboot is neccessary.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
BONSAI-LIKE CHECKIN DATABASE

To use the checkin database, you'll need to install MySQL and the MySQL-Python
interface. MySQL can be downloaded from www.mysql.com. The MySql-Python adapter
is available from http://sf.net/projects/mysql-python/. Make sure to grab the
the latest version from the "Files" section. (The "Home Page" link takes you to
an outdated page that only links to very old versions.) Both packages come with
GUI installers. Once you have MySQL running and set up with a username and
password, follow these instructions to set up ViewCVS.

1) Open a command prompt and type these commands:

   cd /d <VIEWCVS_INSTALL_DIR>
   python make-database

The script that comes up will prompt you for the MySQL username and password
(you should have created these during the MySQL installation), and the name of
the database to create. The default database name "ViewCVS" should be fine
unless for some reason a database with that name already exists.

2) Enter the username, password, and database name into the [cvsdb] section of
the <VIEWCVS_INSTALL_DIR>\viewcvs.conf file.

3) At the command prompt run

   python cvsdbadmin rebuild <repository>

where <repository> is the path to your CVS repository.

4) If you want the checkin database to be dynamically updated with every
checkin, add the following line to your CVSROOT/loginfo file:

   ALL python "<VIEWCVS_INSTALL_DIR>\loginfo-handler" %{sVv}

If you decide not to enable dynamic updates, you can periodically refresh the
database with "python cvsdbadmin update <repository>"

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CVSGRAPH

To use CvsGraph with ViewCVS, just put cvsgraph.exe in a directory on your
system PATH and set the use_cvsgraph option to 1 in your viewcvs.conf file.

The CvsGraph home page is http://www.akhphd.au.dk/~bertho/cvsgraph/.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
SUBVERSION SUPPORT

To use ViewCVS with Subversion, you'll need to have the Subversion Python
bindings installed. Binaries are available from the Subversion website at:

  http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91

Or to build from source you can use the instructions here:

  http://svn.collab.net/repos/svn/trunk/subversion/bindings/swig/INSTALL

You'll also need to have diff.exe installed in a directory on your system PATH.
diff.exe is available as part of the GnuWin32 project's DiffUtils package at
http://gnuwin32.sf.net/.

Once the Python bindings and diff are installed, you just need to set the
svn_roots option in viewcvs.conf to point to your repositories.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ICONS FOR IIS

The default templates supplied with ViewCVS rely on icons that come with
apache. As a replacement for them on IIS, you can use the ones in the
windows/icons folder. Just copy the folder to your web server's root directory
to use them.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TROUBLESHOOTING

- By far the most common cause of errors in ViewCVS is failure to successfully
  execute the programs it depends on (cvs, rlog, rcsdiff, co, enscript, sed,
  and cvsgraph). To help deal with this problem, ViewCVS includes a special
  debugging mode that displays output from the programs it executes on every
  web page. This allows you to see error messages and other information that
  isn't normally visible. To enable the debugging mode, change line 23 of
  <VIEWCVS_INSTALL_DIR>\lib\debug.py from:

    SHOW_CHILD_PROCESSES = 0

  to:

    SHOW_CHILD_PROCESSES = 1

  Important: You may need to restart your web server before this change takes
  effect. See "Changes made to..." later in this section.

- A common cause of server errors under IIS is permissions problems. You need
  to make sure that the virtual directory containing the CGI or ASP files has
  script execution enabled. You also need to make sure that the web server user
  accounts (IUSR_machine_name and IWAM_machine_name, where machine_name is your
  computer name) have read and execute access to the .asp or .cgi stub scripts,
  the ViewCVS lib/ folder, the paths where external tools like cvs, rcs,
  enscript, sed, and cvsgraph live, and the CVS repositories. NTFS auditing
  makes it very easy to track down permissions problems. Also look for IIS
  messages in the event log.

- Certain Apache configurations may hide some environment variables from the
  ViewCVS CGI scripts and the programs they launch. You can see whether an
  environment variable is visible from the CGI environment by enabling the
  SHOW_CHILD_PROCESSES debug mode described above. You can force Apache to let
  variables through with the PassEnv directive
  (http://httpd.apache.org/docs/mod/mod_env.html#passenv).

- Changes made to environment variables, ViewCVS source files and the ViewCVS
  configuration file do not always take effect immediately. The table below
  shows what actions you need to take after changing any of these things before
  they will have an effect.

+----------------+----------------+----------------+-------------------------+
|                | Environment    | ViewCVS        | ViewCVS                 |
|                | Variables      | Source         | Configuration           |
+----------------+----------------+----------------+-------------------------+
| Standalone     | restart        | restart        | restart                 |
| Server         | standalone.py* | standalone.py  | standalone.py           |
+----------------+----------------+----------------+-------------------------+
| CGI mode under | reboot         | nothing        | nothing                 |
| apache or IIS  | computer       |                |                         |
+----------------+----------------+----------------+-------------------------+
| mod_python or  | reboot         | restart Apache | restart Apache          |
| under apache   | computer       |                | OR                      |
|                |                |                | reload(viewcvs) in stub |
+----------------+----------------+----------------+-------------------------+
| asp mode under | reboot         | restart IIS    | restart IIS             |
| IIS            | computer       | OR             | OR                      |
|                |                | Unload ASP App | Unload ASP App          |
|                |                |                | OR                      |
|                |                |                | reload(viewcvs) in stub |
+----------------+----------------+----------------+-------------------------+
  * If standalone.py was launched from a command prompt and you set the
  environment variable through the control panel, you'll need to open a new
  command prompt.

  Notes:

  Under mod_python and ASP, changes made to the stub scripts inside the web
  root do take effect immediately, you only need to take additional action when
  you make changes to the main source files in <VIEWCVS_INSTALL_DIR>\lib

  To "Unload ASP App", go to the IIS properties dialog for the application
  directory containing the ViewCVS .asp files (in Internet Services Manager).
  Switch to the [Home] | [Virtual] Directory tab and click the "Unload" button
  under "Application Settings".

  To "reload(viewcvs) in stub", put these lines in one of the ASP or Mod_Python
  stub scripts:

    import viewcvs
    reload (viewcvs)

  then load the page one or more times in a web browser.

- If you have problems getting ViewCVS to work with mod_python, you can first
  make sure mod_python works standalone with the testing instructions at
  http://www.modpython.org/live/current/doc-html/inst-testing.html.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
KNOWN ISSUES

- If you see ViewCVS errors like

    Error parsing rlog output. Expected RCS file "c:\cvsroot\dir\file,v", found
    "c:\cvsroot\dir\RCS/file,v"

  it's because your RCS utilities don't recognize the RCS file suffix and are
  treating all files specified on the command line like working copies even
  when they end in ",v". You can fix this by including the following string in
  your RCSINIT environment variable:

    -x,v

  Important: You may need to reboot your computer before the environment
  variable has an effect. See "Changes made to..." in the TROUBLESHOOTING
  section.

- The GNU RCS utilities won't work with repository files that use CVSNT's
  unicode expansion mode (-ku). Files that use this mode will show up with the
  "CVS information is unreadable" error message in ViewCVS directory listings.
  To work around this, you can set up ViewCVS to use the CVSNT executable
  (cvs.exe) or CVSNT RCS tools (co.exe, rlog.exe, and rcsdiff.exe) instead of
  the GNU tools.

- The standalone server will not run under Cygwin Python because it does not
  support threads. ASP pages can't be run with Cygwin Python because it does
  not support ActiveX. To use either of these features you should install a
  native Python interpreter.

- On Windows XP and Windows 2003 Server under IIS, enscript might give an error
  like:

    enscript: couldn't open input filter "states -f
    "K:/gnuwin32/share/enscript/hl/enscript.st" -p
    "C://.enscript;K:/gnuwin32/share/enscript/hl" -shtml -Dcolor=1
    -Dstyle=emacs -Dlanguage=html -Dnum_input_files=1
    -Ddocument_title="Enscript Output" -Dtoc=0 -" for file "": No error
    no output generated

  The solution is to give read & execute permissions on cmd.exe to the
  IUSR_computername and IWAM_computername user accounts. (Enscript uses cmd.exe
  internally to launch its little helper program, states.exe).

- By default, ASP will set session cookies at each page load. ViewCVS does not
  use these cookies and they can be safely disabled. You can do this by opening
  the IIS properties dialog for the application directory containing the
  ViewCVS .asp files. Go to the [Home] | [Virtual] Directory tab and click the
  "Configuration" button under "Application Settings". On the dialog that comes
  up, uncheck "Enable Session State" under "App Options" -> "Application
  Configuration".

- Python support for ASP can be a little flaky. If you get strange errors, it
  can sometimes help to uninstall and reinstall it with pyscript.py. A number
  of people have also encountered a problem in ActivePython 2.2 where the first
  loads of any Python ASP page would work, but subsequent loads of the same
  page would always return nothing (leaving the screen blank). There were a
  number of workarounds for this problem, but the fix is to download and
  install the latest python win32 extensions from
  http://starship.python.net/crew/mhammond/win32/Downloads.html

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
THANKS

- Bryan T. Vold for improving the original ViewCVS patch by adding support for
  enscript and tarball generation.
- David Resnick for tracking down the cause of re_search failures in
  repositories with non-rcs files and for bringing a bug in
  sapi.AspFile.header() to my attention
- Matt Bunch for finding a better way to address the ASP blank page problem,
  and Keith D. Zimmerman for finding another workaround.
- Rüdiger Koch for reporting a bug in viewcvs PATH_INFO parsing code with
  Apache for Windows as well as Jelle Ouwerkerk and Steffen Yount for providing
  fixes.
- Nick Minutello and Rüdiger Koch for providing workarounds for setting
  enscript_library environment variable with apache. David Duminy for providing
  the first bug report on this.
- Gyula Faller and Tony Cook for independently coming up with CVSNT loginfo
  handlers that accept spaces and don't rely on unix-style echo commands. Tony
  Cook's patch also eliminated the dependency on cat.exe.
- Mathieu Mazerolle for making the unix loginfo handler handle spaces in
  filenames
- Paul Russell for analyzing problems with new fields in CVSNT RCS files.
  Terry.Ninnis@pgen.com for coming up with a partial solution
- Bo Berglund for tracking down the cause of a case-sensitivity issue that
  could lead to problems in the commit database and for patiently working with
  me to finally fix the CVSNT RCS fields problem and another problem with
  enscript.
- Ivo Roessling for finding and fixing a bug in the query page's commit
  grouping code.
- Keith D. Zimmerman for experimenting with enscript and finding some new ways
  to make it work.