Administrators README for P4DB Version 4.0

Introduction

This is a README for P4DB, a CGI based p4 depot browser written by Fredric Fredricson (fredric@mydata.se)

The graphic "Branch Relationships" page is written by Todd Short (see Todd's readme file).
More credits at the end.

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 Firefox 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.

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 4.0 requires:

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 a little, and release it.

Http server:
P4DB is developed on a Linux box running Fedora Core 3 and Apache, runs in production on RedHat 7.2/Apache, 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 FireFox version 1.0 (preview) but I usually perform some basic testing with MS-Explorer and sometimes Netscape. P4DB should work with a recent browser with reasonable support for CSS (Cascaded Style Sheets) and javascript.
P4DB is not designed for character mode browsers such as Lynx.
And, by the way, the P4DB use cookies. Without cookies enabled you will not even be able to log in to P4DB.

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

If you use Linux and downloaded the tarball (that is, not the zip-file) you can follow the instructions below. If not, go to "Installation without install.pl"

  1. You obviously got to this README. Together with README.html file you got: 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 or zip archive 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) or cgi_file.zip
  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.

Each p4 user that should be able to use P4DB must have at least read access from the machine that P4DB runs on to the parts of the depot he/she should have access to through P4DB. P4 groups may come in handy here.

Security Note 1:
P4DB asks for a p4 user to access the depot. It is wise to give users read priviliges only on the P4DB host. This protects the depot from errors in P4DB that might affect the depot status.

Security Note 2:
P4DB does not provide any strong 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.

Security Note 3:
During the login procedure the p4 user name and password are transmitted unencrypted over the network. If this is not acceptable you should use the SSL (Secure Sockets Layer) and TLS (Transport Layer Security) protocols. Unfortunately I am not an expert in these matters and can not give you any help here other than point you to the mod_ssl module documentation in Apache.

I also recommend that you read the Warranty-paragraph.

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

Diffs between versions

New to P4DB 4.0:

Added a login page
P4DB now requires the user to log in and supply a p4 user and a password. See also Security Note 3
Require 2004.2
P4DB require both the client and server to be of version 2004.2 or newer. The reason for this is that P4DB use the ticket based authentication introduced in this release.

New to P4DB 3.1:

P4DB 3.1 is a frame-less version of 3.0. The frame stuff was not appreciated by the users at all. The main problem was that it made it difficult to take the URL and slap it in an email to another developer to point something out, something the users do frequently.

Another thing that really killed the frame based solution was the (wonderful!) tabs in Netscape 7 and other Mozilla-based browsers. No doubt the next version of MS-Explorer will have some similar feature if they have the slightest clue in Redmond. With frames the "open in new tab"-feature became somewhat awkward.

Apart from the above the follwing things have changed:

The "p4 annotate" command is used to view files.
The "annotate" command provides a nice view of a complete file history. Previous versions of P4DB did part of this using the p4pr.perl script written by Bob Sidebotham, but the "p4 annotate" provides more info. Thank you, Perforce.
The header comes in two flavours, pulldown menues and buttons.
The pulldown menues or buttons are used to select page. The pulldown menu use less space but Explorer does not display all menu options (you have to scroll) and this makes buttons more convenient. The user selects in the User Preferences page.
The user can specify start page.
The script "index.cgi" does not really display anything, it only forwards the user to the start page. Default is "intro.cgi" but the user can modify this using a button in the page header.
A few other small improvements..
I have made some small improvements to the branch and label views and to quite a few other pages as well.

New to P4DB 3.0:

P4DB is, again, completley rewritten (well.. almost) only this time I did not add much functionality other than a completley different user interface that I hope will be more efficient.

NOTE! Configuration file for 2.1 not compatible with 3.0.

Here are a few of the changes:

User defined "shortcuts"
A user can define her own personal "shortcuts". Pretty much like browser bookmarks/favorites only bookmarks can not really be used for a frame-based web applications.
Graphic "Branch Relationships" page.
Displays branch relationships in a graph. Contributed by Todd Short. Requires the GD.pm perl module.
Next and previous keys in change view
When you view a change there are next and previous links that displays next and previous changes. If you entered the page asking for changes for a specific path in the depot the next and previous links will follow this path.
(Almost) all formatting done in CSS
Output formatting is specified in a CSS file (P4DB.css).
Full descriptions are always shown
Change descriptions are never displayed in a truncated form (in 2.1 displaying a full change description was sometimes an option).
Removed "shortcut files"
P4DB 2.1 had some optional "shortcut files" that the administrator could specify. They are gone. I never liked the idea myself (even though it was mine).
Java browswer no longer part of P4BD
The Java browser was optional and never really well integrated with P4DB.

New to P4DB 2.1:

Better support for jobs and fixes
Works for p4 2001.1
There is a nice feature in 2001.1 that P4DB use to make label cross reference in file log page much, much faster.
Warning levels for unused users and clients in P4 Users and groups page configurable
The warning level are set in the configuration file
"#include" in c-files links to file search
The colorC.pl script makes #includes links to file search cgi. (Silly feature that was easy to implement)
Warning level for unused users and clients configurable.
The user and client lists will print a warning next to users and clients that has not been accessed for a number of weeks. This number is now configurable in P4DB.conf.

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 it for any purpose.
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 the best way is to become a registered user at the Perforce Public Depot, branch from //guest/fredric_fredricson/P4DB/main/..., make the changes and send me a email.
I can of course not promise that I will like your changes and immediately integrate them to P4DB but if not you can always start you own competing version of P4DB, I do not mind.

If Perforce Public Depot does not work for you you can just send me an email and describe the changes.

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.

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.

Credits

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

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