522 lines
22 KiB
Plaintext
522 lines
22 KiB
Plaintext
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
DESCRIPTION
|
||
|
||
This file contains special instructions for setting up ViewVC 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
|
||
|
||
ViewVC requires the Python interpreter which you can download from
|
||
|
||
http://python.org/
|
||
|
||
and the Python for Windows Extensions which are at
|
||
|
||
http://sourceforge.net/projects/pywin32/
|
||
|
||
For CVS support, ViewVC 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/wiki
|
||
|
||
and RCS can be obtained from:
|
||
|
||
http://www.cs.purdue.edu/homes/trinkle/RCS/
|
||
|
||
For Subversion support, 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
|
||
|
||
Note that if you use binaries, you have to be running the same version
|
||
of python as the binaries were built for. For example, you cannot use
|
||
Subversion bindings built for Python 2.3 with Python 2.4. Instructions
|
||
for building the binaries from source are available here:
|
||
|
||
http://svn.collab.net/repos/svn/trunk/subversion/bindings/swig/INSTALL
|
||
|
||
The Subversion bindings also require you 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 you've got Python and CVSNT or RCS or the Subversion bindings
|
||
installed, you can test out ViewVC before you install it by running:
|
||
|
||
python bin\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 bin\standalone.py --help
|
||
|
||
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
BASIC INSTALLATION
|
||
|
||
Run the ViewVC install script with
|
||
|
||
python viewvc-install
|
||
|
||
The script will copy the source files into an installation directory
|
||
that you specify, store some path information, and compile the ViewVC
|
||
library files into Python bytecode.
|
||
|
||
After the installation is finished you will need to edit the
|
||
viewvc.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 <PY_DIR> will stand for the Python
|
||
root directory (usually something like C:\Python22) and
|
||
<VIEWVC_INSTALL_DIR> will represent the directory where ViewVC has
|
||
been installed to (default is C:\Program Files\viewvc-VERSION).
|
||
|
||
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
SERVER CONFIGURATION
|
||
|
||
If you want to make ViewVC 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 ViewVC
|
||
on two commonly used Windows web servers, IIS and Apache.
|
||
|
||
With IIS, you can run ViewVC 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 viewvc.cgi and query.cgi from <VIEWVC_INSTALL_DIR>\bin\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: <PY_DIR>\python.exe "%s"
|
||
Extension: cgi
|
||
Script Engine: checked
|
||
Check that file exists: unchecked
|
||
|
||
That is all. Assuming you've set up viewvc.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 ViewVC 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 viewvc
|
||
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 <PY_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 viewvc.asp and query.asp files from
|
||
<VIEWVC_INSTALL_DIR>\bin\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 ViewVC ASP pages should begin to
|
||
work.
|
||
|
||
CGI Mode on Apache
|
||
|
||
Follow the instructions under "Apache Configuration" in the ViewVC
|
||
INSTALL file.
|
||
|
||
Mod_Python Mode on Apache
|
||
|
||
There are probably ten thousand different ways to set up Apache,
|
||
mod_python, and ViewVC 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 viewvc.py, query.py, handler.py, and .htaccess from
|
||
<VIEWVC_INSTALL_DIR>\bin\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
|
||
ViewVC 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 ViewVC.
|
||
|
||
1) Open a command prompt and type these commands:
|
||
|
||
cd /d <VIEWVC_INSTALL_DIR>
|
||
python bin\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 "ViewVC" 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 <VIEWVC_INSTALL_DIR>\viewvc.conf file.
|
||
|
||
3) At the command prompt run
|
||
|
||
python bin\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 "<VIEWVC_INSTALL_DIR>\bin\loginfo-handler" %{sVv}
|
||
|
||
If you decide not to enable dynamic updates, you can periodically
|
||
refresh the database with "python bin\cvsdbadmin update <REPOSITORY>"
|
||
|
||
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
CVSGRAPH
|
||
|
||
To use CvsGraph with ViewVC, just put cvsgraph.exe in a directory on
|
||
your system PATH and set the use_cvsgraph option to 1 in your
|
||
viewvc.conf file.
|
||
|
||
The CvsGraph home page is http://www.akhphd.au.dk/~bertho/cvsgraph/.
|
||
|
||
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
DOCROOT OPTIMIZATION
|
||
|
||
By default ViewVC serves up image and stylesheet files in
|
||
<VIEWVC_INSTALL_DIR>\templates\docroot\ on its own instead of relying
|
||
on the webserver to deliver them. This simplifies web server
|
||
configuration, but is inefficient because it means the Python
|
||
interpreter has to run each time one of these files is
|
||
downloaded. This causes ViewVC pages to load more slowly, especially
|
||
when ViewVC is running under CGI on Windows.
|
||
|
||
To make things more efficient, you can make the
|
||
<VIEWVC_INSTALL_DIR>\templates\docroot directory available on your web
|
||
server and then set the "docroot" value in viewvc.conf to point to the
|
||
web address of the directory.
|
||
|
||
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
TROUBLESHOOTING
|
||
|
||
- By far the most common cause of errors in ViewVC is failure to
|
||
successfully execute the programs it depends on (cvs, rlog, rcsdiff,
|
||
co, enscript, sed, and cvsgraph). To help deal with this problem,
|
||
ViewVC 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
|
||
<VIEWVC_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.
|
||
|
||
- If you see the following error:
|
||
|
||
error: (2, 'CreateProcess', The system cannot find the file specified.')
|
||
|
||
it means that a program ViewVC has tried to execute could not be
|
||
found by Windows. The fix to this is usually to install the program
|
||
if it isn't already installed or to update the path to the program
|
||
in viewvc.conf. Enabling the SHOW_CHILD_PROCESSES mode as described
|
||
above can provide helpful diagnostic information such as the command
|
||
line ViewVC is using to invoke the program and the value of the PATH
|
||
environment variable in the environment ViewVC is running under.
|
||
|
||
- 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 ViewVC 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 ViewVC 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, ViewVC source files and the
|
||
ViewVC 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 | ViewVC | ViewVC |
|
||
| | 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(viewvc) in stub |
|
||
+----------------+----------------+----------------+-------------------------+
|
||
| asp mode under | reboot | restart IIS | restart IIS |
|
||
| IIS | computer | OR | OR |
|
||
| | | Unload ASP App | Unload ASP App |
|
||
| | | | OR |
|
||
| | | | reload(viewvc) 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 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 <VIEWVC_INSTALL_DIR>\lib
|
||
|
||
To "Unload ASP App", go to the IIS properties dialog for the
|
||
application directory containing the ViewVC .asp files (in Internet
|
||
Services Manager). Switch to the [Home] | [Virtual] Directory tab
|
||
and click the "Unload" button under "Application Settings".
|
||
|
||
To "reload(viewvc) in stub", put these lines in one of the ASP or
|
||
Mod_Python stub scripts:
|
||
|
||
import viewvc
|
||
reload (viewvc)
|
||
|
||
then load the page in a web browser.
|
||
|
||
- If you have problems getting ViewVC 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 ViewVC 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 an "rlog error: unknown expand mode u" error message in
|
||
ViewVC directory listings. To work around this, you can set up
|
||
ViewVC 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. ViewVC
|
||
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 ViewVC .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://sourceforge.net/projects/pywin32/
|
||
|
||
- ViewVC can't convert timestamps on diff pages to local time when it
|
||
is used with CVSNT. This is caused by a CVSNT bug, which is
|
||
described at
|
||
http://www.cvsnt.org/mantis/bug_view_page.php?bug_id=0000110
|
||
|
||
- Old versions of CVSNT (2.0.11 and earlier) have a bug in their rlog
|
||
emulation which causes them to output truncated paths to RCS
|
||
files. In ViewVC, this causes errors like
|
||
|
||
Error parsing rlog output. Expected RCS file
|
||
"c:\cvsroot\dir\file,v", found "file,v"
|
||
|
||
- Old versions of CVSNT (2.0.11 and earlier) have a bug in their
|
||
standalone RCS tools (rlog.exe, co.exe, and rcsdiff.exe) which
|
||
causes them not to properly interpret arguments with spaces. This
|
||
can result in ViewVC errors in repositories that have spaces in file
|
||
or directory names. This bug only occurs when ViewVC is configured
|
||
to use the standalone utilities, not when it uses cvs.exe directly
|
||
as it does by default.
|
||
|
||
- Old versions of CVSNT (1.11.1.3-76 and earlier) don't have any RCS
|
||
emulation, so they can't be used as RCS parsers for ViewVC.
|
||
|
||
- Very old versions of CVSNT (1.11.1.3-57g and earlier) won't work
|
||
reliably with our loginfo handler because they have a bug which
|
||
makes them escape spaces and other special characters in filenames
|
||
twice. This bug can result in loginfo errors or invalid data being
|
||
inserted into the database.
|
||
|
||
- Old versions of Highlight (2.4.3 and earlier) will not show line
|
||
numbers for .txt files or files of unknown type even when the
|
||
"highlight_line_numbers" option is enabled.
|
||
|
||
- Highlight versions 2.4.2 and 2.4.3 start line numbering for all file
|
||
types at 0 instead of 1 by default. A workaround is to make ViewVC
|
||
pass an explicit --line-number-start=1 option to Highlight
|
||
|
||
- Highlight version 2.4.4 starts line numbering for .txt files at 0
|
||
instead of 1. It also misinterprets the --line-number-start option
|
||
for those files, starting numbering one number before whatever
|
||
number is specified. Since this behavior does not affect unknown
|
||
file types, a simple workaround is just to not pass a --syntax
|
||
option to Highlight for plain text files (instead of passing
|
||
--syntax=txt).
|
||
|
||
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
||
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 viewvc 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.
|