**************************************************************************
* Copyright 1995, 1998 Perforce Software.  
*
* This file is part of WebKeeper, a perforce client apache module.
*
* License is hereby granted to use this software and distribute it
* freely, as long as this copyright notice is retained and modifications
* are clearly marked.
*
* ALL WARRANTIES ARE HEREBY DISCLAIMED.
*
* Last updated: December 24, 1998
*
* $Id: //guest/kyle_vanderbeek/webkeeper/README.WEBKEEP#3 $
*
**************************************************************************

PERFORCE SOFTWARE WEBKEEPER NOTES

    Warning: This is a demo, not a product.

WHAT THIS IS

    As it stands, WebKeeper is not a very useful thing.  What it does
    allow you to do is "Alias" a section of your web server URI space
    into a running perforce server.  Simply put, you can make it so that
    /someurl/foo.html maps to //depot/somedir/foo.html .  Nothing more.

    It DOES NOT provide any interesting repository functions like
    browsing or changelist viewing.  If you are interested in these
    things, check out p4web.

    The idea is that you could extend this minimal functionality to
    serve some purpose in your enterprise.

    This version of WebKeeper is intended to work with 1.3 series of
    web servers from Apache.  It has been tested on a Linux system.

WHAT YOU HAVE

    This directory contains the generic componentry to build an Apache
    Web Server with a Perforce WebKeeper module.  This directory includes:

	Jamfile		a description file for 'jam'
	Makefile	a basic traditional Unix make file
	README.WEBKEEP	this file
	mod_webkeep.c	the WebKeeper Apache module, C half
	mod_webkeep2.cc	the WebKeeper Apache module, C++ half
	mod_webkeep.h	glue between the C and C++ halves

    You will also need a Perforce header file and link libraries and
    for your platform.  They can be found at:

	ftp.perforce.com/pub/perforce/r??.?/bin.*/p4api.tar

    If you want to build the Apache server with jam, a make(1) alternative
    program, it is available from http://www.perforce.com/jam.html.  If
    you wish to use plain old make(1), you'll need to edit the Makefile
    and modules.c.

BUILDING mod_webkeep.so

    1) Unpack the Perforce libraries.

	% mkdir p4api
	% cd perforce
	% tar xvf /path/to/p4api.tar

       Note that there are source files in the p4api.tar ball
       that are not related to webkeeper.

    2) Get the WebKeeper files from Perforce and put them in some
       directory.  cd into that directory

    3) Edit the WebKeeper Makefile and change the first four definitions
       to be appropriate for your installation.

	% vi Makefile config.c

       Note, the apxs program is a module compilation helper program from
       Apache.  It should have been installed when you installed Apache
       (On many RPM-based Linux systems, this is a part of a separate
       apache-devel RPM).  Compilation has only been tested on a Linux
       system using CC=gcc and CPP=g++ (the defaults in the Makefile).

    4) Run make

	% make

    You should now have a mod_webkeep.so file!  Copy it to the directory
    where Apache is keeping its loadable modules.

TO USE WEBKEEPER

    1)  Do the necessary steps to get a Perforce server running.  See
    	the admin section of the Perforce manual.

    2)	Edit the Apache httpd.conf file to add module definitions so that
        mod_webkeep is loaded.  You'll need:

		LoadModule webkeep_module    modules/mod_webkeep.so
		AddModule mod_webkeep.c

        Look at the other modules as examples.  Maintain the order of
        the module loadings.

    3)  Add WebKeeper directives to your httpd.conf.  These are the
        available directives:

		WebKeepPort host:port

		    Gives the address of the Perforce server.  
		    Default is $P4PORT or host 'perforce', port 1666.

		WebKeepUser username

		    Gives the Perforce user name.  
		    Default is $P4USER or $USERNAME.

		WebKeepPasswd password

		    Gives the user's password.
		    No default.

		WebKeepClient clientname

		    Gives the Perforce client name.
		    Default is $P4CLIENT or hostname.

		WebKeepAlias uri perforcePath

		    If the URI begins with uri, strips the intial uri,
		    replaces it with perforcePath, and then treats the
		    URI as a WebKeeper request.

	For example:

		WebKeepAlias /$ //depot/index.html
		WebKeepAlias / //depot

	Maps the URI / to //depot/index.html and the rest of the web
	namespace into the corresponding Perforce namespace under //depot.
	The $ is necessary to distinguish between initial substring 
	mactches and exact matches.

	You can also use //client/ where client is the name of your
	client.  If you use //client/, it will map the name through your
	client view.  You don't have to map the whole namespace.  You
	could say:

		WebKeepAlias /foo/ //depot/

	To map only files under /foo/... to the Perforce namespace.

	You can have multiple alias lines.

Notes:

    Directory indexing is still not yet supported.