- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
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 a Python interpreter. The best one to use for Windows is ActiveState's ActivePython ( http://aspn.activestate.com/ASPN/Python ).
ViewCVS also requires that the RCS tools be installed on your computer. If you are using ViewCVS with CVSNT, you should use the RCS utilities that come with CVSNT (they aren't installed by default). Otherwise you can find RCS binaries at
http://ftp.cvshome.org/rcs/
and more information at
http://www.cvshome.org/cyclic/cyclic-pages/rcs.html
Once you've got Python and 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
Once python is installed you can 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:\python2.2) 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. CGI mode is slower but more likely to work, while the Mod_Python mode is faster but a little harder to get working.
CGI Mode On IIS
1) Copy viewcvs.cgi and query.cgi from <VIEWCVS_INSTALL_DIR>\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.asp page. Step by step instructions are given below. Information and source code for Aspfool can be found in the windows\aspfool folder and there is a precompiled version of aspfool.dll in the windows\binaries folder.
To install ASP 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>\windows 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've saved 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 and query.py from <VIEWCVS_INSTALL_DIR>\windows to a folder being served by apache.
4) Create a new .htaccess file in the folder where you put viewcvs.py and query.py (or edit an existing .htaccess file there) and paste in the contents of <VIEWCVS_INSTALL_DIR>\windows\htaccess-mod_python. Make sure overrides are allowed in this folder. The relevant virtual 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 check-in, 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>"
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CVS Graph
To use CVS Graph, you can either use the precompiled binary that I provided (windows/binaries/cvsgraph.exe, version 1.2.0) or build the source which is available from http://www.akhphd.au.dk/~bertho/cvsgraph/
To build the source, you will need to have a C compiler like Mingw or Visual C++ installed on your system and these libraries:
gd 1.x - http://www.boutell.com/gd
libpng - http://www.libpng.org/pub/png/
zlib - http://www.gzip.org/zlib/
Build instructions for Mingw can be found at http://www.cvsnt.org/wiki/CvsGraphMingw
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
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 (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 20 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 option takes effect. See "Changes made to..." later in this section.
- A common cause of server errors under IIS are 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 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
- In ViewCVS, if you can browse directories but see messages like "NOTE: There are 11 files, but none match the current tag" with empty file listings, your RCS utilities might not be set up correctly. One particular problem is that they sometimes do not recognize the extensions on RCS files, treating all files specified on the command line like working copies even if they end in ",v". As a result, when the ViewCVS gives commands like
rlog C:/CVSROOT/myproject/main.cpp,v
rlog replies:
rlog: C:/CVSROOT/myproject/RCS/main.cpp,v: No such file or directory
and the files do not show up in the directory listing because the script does not have any information about them. You can test for this by entering commands like the one above on the command line. 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 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 ActiveState Python. Activestate and Cygwin coexist nicely, so they can be installed side by side.
- On 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 for IUSR_computername and IWAM_computername users. (Enscript uses cmd.exe internally to launch it's 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.
76657fb8ad