Developers README file for P4DB
Author: fredric@mydata.se
Description: Information on how to install and maintain P4DB

# Administrators README for P4DB Version 2.01

## Introduction

This is a README for P4DB, a CGI based p4 depot browser written by Fredric Fredricson (fredric@mydata.se) (One part is written by Bob Sidebotham, no email available). The README is intended for administrators and others that want to install, maintain, and possibly contribute to, P4DB.

## Table Of Contents

##

About

P4DB is designed to provide a user friendly and intuitive interface to the p4 depot. Information is presented using a web browser and most pages combine output from two or more p4 commands.
The driving force behind the development has been my needs as a manager for a software team, the needs for our project leaders to document changes in the code line and the need for our programmers to analyze changes in the code line (and most important, of course, the need for me as a frustrated software engineer promoted to my level of incompetence to get my hands on a nice little programming project).

The browser is written in perl and developed on a Linux/Apache system and has been tested mainly with Netscape 4 although some of our users use MS Explorer and no problems has been reported.

### Why P4DB?

P4DB is inspired by a depot browser, perfbrowse.perl, made available by Perforce at http://www.perforce.com/perforce/loadsupp.html#browse Perfbrowse.perl is written in perl and the author is unknown to me.

The idea is also stolen so I can't claim that one.

To view file a script by Bob Sidebotham called `p4pr.perl` is used. This script is also made available by Perforce at http://www.perforce.com/perforce/loadsupp.html#util (but I made some minor changes and one bug fix).

I liked perfbrowse.perl very much but wanted just a little more functionality. I started to add functionality and it quickly got out of hand. Soon I had a huuuge perl script that I could no longer maintain. Once I realized that I can write a perl script that is about 2-4 times the size of the script that I can maintain I decided to rewrite it all from the start as a set of small, maintainable, perl scripts. I leave to others to judge if I succeeded in my mission.
(Maybe I should mention that it took much more time than I anticipated).

##

Software requirements

P4DB version 2.01 requires:

- Perl 5.004 or newer with the CGI.pm modules installed. The CGI.pm module can be downloaded from http://www.cpan.org/ (link to CGI.pm).
- A http server that supports CGI:s. Apache will do just fine.
- P4 99.2 or later (98.2 will also work but some features will be missing, 97.3 and older... forget it!).
  P4DB has been tested with 2000.2beta.

##

Supported platforms and compatibility

There is no real "list of supported platforms" simply because there is no real "support" for P4DB. I just write it, test it, and release it.

Http server:
P4DB is developed on a Linux box running Suse 6.3 and Apache 1.3.9 , runs in production on RedHat 6.2/Apache 1.3.9, and has been reported to run on SUN/Solaris and NT/IIS platforms as well. The NT platform require MKS toolkit or similar and some tweaking, though.

Browser:
All development work is done using Netscape 4.7 but I perform some basic testing with MS-Explorer. I expect P4DB to work reasonably well with any GUI browser like Mozilla or Opera. because P4DB use almost only plain HTML and just a little CSS (Cascaded Style Sheets). P4DB is not designed for character mode browsers such as Lynx.
And, by the way, the browser should support cookies.

##

Installation and configuration

NOTE: This installation description assumes that the reader is familiar with http servers, cgi scripts and, to a small degree, perl.

### First: Where to install

Other than the obvious, that is somewhere in a http servers CGI path, I recommend you to set up a http server on your p4 server and run P4DB on that server. The main reasons are that it improves response time and reduce network load.

### How to install

1. You obviously got to this README. Together with README.html file you got:
   - `install.pl`
   - `cgi_files.tar`
   - `P4CGI.html`
   - `P4DB.shortcuts.txt`
   - `P4DB.shortcuts2.txt`
   - `P4DB.conf.txt`
   Move all these files together with `README.html` to the cgi-bin directory used by the web server or wherever you want P4DB installed. Or you could just move the original tarball and unpack it.
2. Type "`perl install.pl`" To install all scripts.
   Install.pl will unpack all cgi scripts and modifies the first line to contain the path to perl.
   For details, see the `install.pl` script.
3. The file `index.cgi` is the start page for P4DB. Create your links to it..

This is the theory, at least. I have not tested it on many systems

#### Installation without `install.pl`

If `install.pl` don't work for you here is what it does that you need to do manually:

1. Verify that perl and the perl module CGI.pm is available
2. Unpack cgi_file.tar (`tar -xf cgi_files.tar`)
3. Find path to perl
4. Change first line of every file with extension ".cgi", ".pl" or ".perl" to contain correct path to perl

### How to configure

#### Basic configuration

The basic configuration file is named P4DB.conf. The file is not included in the package but a sample configuration file called `P4DB.conf.txt` is.

Copy the file P4DB.conf.txt to P4DB.conf and modify it. The instructions are included in the file.

Security Note 1: Since the DEPOT field in the configuration file may contain passwords for p4 users it may be wise to move the file outside the file tree reachable by the web server. The path to the configuration file is specified at the top of `P4CGI.pm`.

Security Note 2 P4DB does not provide any access protection or other security. It is not possible to modify the depot using P4DB so poorly trained or inexperienced operators should not be able to damage the depot. If this security is not enough you have to rely on the authentication provided by the web server.

You must specify a p4 user for P4DB. If I understand Perforce Licensing policies correctly you should not have to use a separate user license for this user, but this is just my interpretation and I recommend that you verify this with Perforce.

#### Shortcut files

It is possible to add a set of links to the P4DB index page using a "shortcut file". The idea is to add links that function as shortcuts into P4DB for the users. There can be more than one shortcut file and the user can select his/her favorite in the "set preferences" page.

#### Shortcut file format:

The shortcut file is format is HTML plus some extra tags and comment syntax added by P4DB. The HTML code is inserted into the P4DB index page. There are no limits imposed by P4DB to the HTML code but there are an infinite number of bad ideas to avoid (like, for example, inserting a `</BODY>` tag in the shortcut file). Ill-formed HTML will probably break the index page.

##### Difference from HTML

Perl style comments
  Lines starting with '#' are ignored.
Extra tag `<P4DB>`text`</P4DB>`
  This tag will make "text" a link to a function in P4DB.

  Syntax | `<P4DB>....</P4DB>`
  Attribute specifications | `TYPE=`link_type (mandatory) link_type is one of: `CHANGELIST` - display list of changes `BROWSE` - browse depot `JOBLIST` - list jobs FSPC=depot_file_spec (valid for types `CHANGELIST` and `BROWSE`) depot_file_spec is a file spec in depot format. A typical file spec would be "//..." to view changes for or the whole depot or browse starting at the top of the depot. For CHANGELIST more than one file spec can be listed. The file specifications should be separated by "+". For example "`//...*.c+//...*.h`" would list changes for all .c and .h files. USER=user_list (valid for CHANGELIST). user_list is a comma separated list of users that the changes should be listed for. GROUP=group_list (valid for CHANGELIST). group_list is a comma separated list of groups that the changes should be listed for. JOB_FIELD=data (valid for JOBLIST) JOB_FIELD is the field name for any field in the job spec for the depot. Data is the data that this field should contain. Typical use would be: `<P4DB type=joblist status=open>list open jobs</P4DB>.` These are the most important attribute specifications. More can be found if you study the URLs generated when you browse around in P4DB. The attributes corresponds more or less directly to the URL parameters. The one exception is the job list where field names are translated to field codes in the URL.

Two sample shortcut files are included with the distribution: `P4DB.shortcuts.txt` and `P4DB.shortcuts2.txt`.

#### Configure file types (for viewers)

P4DB will let users view some file types using applications like MS-Word for Word-file etc. This can be configured in a file viewConfig.pm. Default will let you view HTML, gif, jpeg, MS-Word, MS-Powerpoint, and Acrobat (PDF) formats. See file viewConfig.pm for details.

##

Known bugs

- A serious case of Feature Bloat.

##

Diffs between versions

#### New to P4DB 2.01:

Works for p4 2000.2beta
  The jobspec command was changed and now P4DB understands both 2000.2beta as well as 2000.1 thru 98.2.
Works for p4 2000.1
  The depot statistics did not work properly for p4 release 2000.1
Made easier to port
  The configuration file now contains fields for command to redirect to null device and command to redirect to stdout. This makes it easier to port P4DB to NT that thinks /dev/null is called NUL:.

  Configuration file for 2.0 not compatible with 2.01

Java GUI browser improved
  Can now handle filenames containing spaces
Label diff view rewritten
  The old code was buggy and difficult to maintain
Made some code more maintainable
  Modified client view and label view code to make it more maintainable.

#### Diff earlier version of P4DB to 2.0:

The difference is so huge that I do not care to list it. P4DB 2.0 can simply do much more than earlier versions.

##

Licensing

There is no license for P4DB. You are free to use, modify, resell, repackage, make money from (ha!), P4DB. Your conscience is the limit ;-).
I might decide to apply GPL to it some time in the future but I doubt that I will bother....

##

Warranty

If you get any problems because of these scripts I promise to feel sorry for you. Other than that you are on your own.

Please note for the record that I do not even claim that P4DB can be used to browse the P4 depot. I will also inform you that even though the intention is that P4DB should not in any way modify the depot status I can make no promises that this is can not happen.
And please remember that it would be easy for someone to grab the P4DB code, insert a few malicious lines of code, and "release" it with this "Trojan Horse".

##

Would you like to contribute?

If you would like to contribute changes/improvements/new functions feel free to do so and mail them to me and I will add them to the next "release" (flames and flattery are also welcome).

Disclaimer: I may grow tired of this project or change job or die or something in which case my promise above probably expires.

### What would be a contribution?

I will be glad for any kind of contributions ranging from corrections of my bad English to new interesting functionality. Nice letters are also welcome.

##

Design documentation

The most important documentation is in the P4CGI.pm module. This modules is used by all scripts and contains a set of common functions that are useful or defines some common "look and feel" or both.

The P4CGI.pm module is documented using perlpod (see perlpod man page). To get a HTML page containing documentation type:
`pod2html P4CGI.pm >P4CGI.html` (There is one distributed with P4DB, for convenience)

For other files: more often than not the code is commented.

There are three different files 'types' in the design:

P4CGI.pm
  - A perl module containing functions that I find useful and all other scripts use
*.cgi
  - A set of cgi scripts that are used as ...eh.. cgi-scripts.
p4pr.perl
  - The script by Bob Sidebotham I mentioner earlier

The code also uses the CGI.pm perl module. This module should be part of the "standard distribution" of perl (if there is such a thing). If you do not have the module it is available for download at www.cpan.org.

As a part of my personal religion the -w flag is always turned on and 'use strict' flag is also set. I have never had any reason to regret this particular peculiarity of mine but it might cause some warning messages that will be printed to the browsers error log.

Performance has not been a great issue. I assume that these cgi's will not have thousands of hits each day and the design has focused on ease of development rather than speed.

### List Of Files:

`P4CGI.pm` | A perl package that contains common functions
`index.cgi` | Entry point or "main" cgi
`SetPreferences.cgi` | Set user preferences User preferences are stored in a cookie. If cookies are not enabled the user can not modify the user preferences and the default setting will be used.
`branchList.cgi` | List branches
`branchView.cgi` | View information about a branch
`changeByUsers.cgi` | Select a set of users and groups to view changes for. Calls changeList.cgi to do the job.
`changeList.cgi` | List changes NOTE: Even if I said earlier that my goal was to create a set of small, maintainable, scripts this script stands out as a blazing proof of my failure. It may not be huge but it is certainly not maintainable. Some day I might rewrite it...... And to 2.0 I finally rewrote it.
`changeView.cgi` | View a change
`clientList.cgi` | List clients
`clientView.cgi` | View a client spec.
`colorView.pm` | Perl module used by fileViewer.cgi to handle color display of some file types.
`colorC.pl colorHtml.pl colorPerl.pl` | Special designed filters that adds colors to C/C++ (colorC.pl), HTML code (colorHtml.pl) and perl (colorPerl.pl). The filters are quick hacks and more like demo examples.
`depotStats.cgi` | View depot statistics
`depotTreeBrowser.cgi` | Browse the depot file tree
`fileDiffView.cgi` | View diff between two files or two revisions
`fileDownLoad.cgi` | Download files
`fileLogView.cgi` | View file history
`fileOpen.cgi` | List open files
`fileSearch.cgi` | Search for file matching file spec
`fileViewer.cgi` | View a file
`filesChangedSince.cgi` | List recently modified files
`groupView.cgi` | View a group
`htmlFileView.cgi` | "Smart" html file viewer that translates relative links to links into the depot
`javaDataView.cgi` | Java depot browser cgi Provides data for java part of depot browser
`jobList.cgi` | List jobs
`jobView.cgi` | View info about a job
`labelDiffView.cgi` | Label diff viewer View diff between two labels
`labelList.cgi` | Display a list of all labels
`labelView.cgi` | List info about a label
`p4race.cgi` | The p4 submit race
`searchPattern.cgi` | Specify a search for a pattern in description field in changes. Calls changeList.cgi to do the actual job.
`specialFileView.cgi` | Special file viewer Special file viewer for HTML, JPEG, GIF , MS-Word, MS-Powerpoint, RTF, and PDF file types. Downloads files with the appropriate Content-Type
`userList.cgi` | Display a list of all users
`userView.cgi` | View info about a user
`p4jdb/P4DirTreeApplet.java p4jdb/P4DirTree.java P4Jdb/P4File.java p4jdb/P4Folder.java p4jdb/TreeDisplay.java` | Java source code for the GUI depot tree browser.
`Makefile` | Make file for java classes (GNU make)
`p4jdb/*.class` | Java files compiled from the .java files above

##

Credits

An incomplete list of people that has contributed to P4DB in different ways:

- Diane Holt - Diane has also released her own version of P4DB adapted to NT. I think it's available in Perforce Public Depot.
- Lawrence You
- Ron Shalhoup
- Rob Chandhok
- Carl Martinsson - A colleague of mine that use P4DB a lot and contributed a lot of ideas for new functions.
- Eric Engberg - Provided valuable information on how to facilitate ports to NT/Apache.
- Lee Marzke - For valuable bug reporting

There are more but these are the only names I found in my records.