A developers README for P4DB

Introduction

Abstract

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, this sw package. You can read it anyway if you like but you will probably do quite well without.

More introduction

P4DB (P4 Depot Browser) was created to present information about the contents in the p4 depot in a nice way. Some CGI's also 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 and the needs for our project leaders (and most important, of course, the needs 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 was developed for and runs 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.

Current version of P4DB (0.99f) requires Perforce p4 98.2 (or newer).

History

The application was developed from 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. Some code from perlbrowse.perl remains in P4DB but most parts are completely changed.

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

The reason I started to do this was that 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).

Diff 0.99d to 0.99f:

Diff 0.99a to 0.99d:

WARNING:
Release 0.99d P4DB does not work with p4 97.3 or earlier.

Installation

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 the server. The main reasons are that it improves response time and reduces load on network.

One argument against this may be that you want to keep the server clear from other apps that might create problems. Personally I don't think this is a very good one but this is up to you.

How to install

You obviously got to this README. Together with README.html file you got a file "install.pl".
Type "perl install.pl" To install all scripts. This is the theory, at least. I have not tested it on many systems

Install will first find out if you have CGI.pm installed and if not a copy will be unpacked. Second it will find out the path to perl, unpack all cgi scripts and modify the first line to contain the local path to perl.

For more details, see the comments inside the install.pl script.

How to configure

You will need to configure the scripts. The basic configuration file is called config. To create a configuration file copy the file config.org to config and modify it.
The configuration file is a perl script but very little knowledge of perl should be required to configure it.

To make some handy shortcuts available for the users there is a file called CODELINES. See the sample file CODELINES.sample.

P4DB will let you view some file types using the browser rather than just as text. 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.

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.

Known Bugs

  • Deleted files can't be viewed
  • A serious case of feature bloat
  • Should probably be written in Java or some other language
  • Sometimes slow.....

    • Missing features or "Why these silly version numbers?"

    There are some features that I feel is missing. This is why I can not bring myself over the psycological barrier to announce version 1.0 of P4DB.

    Some missing features and improvements are:

    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 a) useful or b) defines some common "look and feel" or c) 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
    NOTE! The P4CGI.pm module "knows" if it is used in a cgi script or a regular perl script by checking for .cgi extension.

    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). On my target system it was not available so I included a copy with the rest of the script.

    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.

    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.
    chb.cgi
    Change browser

    View list of changes for selected part of depot
    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......
    chv.cgi
    Change viewer
    View a change by number
    dnld.cgi
    Download
    Used to download files
    dtb.cgi
    Depot tree browser
    Walk around in the depot file tree
    fdv.cgi
    File diff viewer
    View diff between two files or two revisions
    flv.cgi
    File log viewer
    View file history
    fv.cgi
    File  viewer
    View a file
    jdtb.cgi
    Java depot browser cgi
    Provides data for java part of depot browser
    lab.cgi
    List all branches
    Show a list of all branches
    lal.cgi
    List all labels
    Display a list of all labels
    lau.cgi
    List all users
    Display a list of all users
    ldv.cgi
    Label diff viewer
    View diff between two labels
    lu.cgi
    List user
    List info about a p4 user
    lv.cgi
    Label view
    View info about a label
    p4race.cgi
    The p4 submit race
    sff.cgi
    Search for file
    Search depot for files matching spec
    sfv.cgi
    Special file viewer
    Special file viewer for HTML, JPEG, GIF , MS-Word, MS-Powerpoint, RTF, and PDF file types.
    CGI.pm
    CGI/Carp.pm
    CGI.pm package (unpacked only if the installation script does not find the CGI.pm package already installed)
    p4jdb/P4DirTreeApplet.java
    p4jdb/P4DirTree.java
    p4jdb/P4File.java

    p4jdb/P4Folder.java
    p4jdb/TreeDisplay.java
    Java source code for the graphic depot tree browser.
    Makefile
    Make file for java classes (GNU make)
    p4jdb/P4DirTree$1.class
    p4jdb/P4DirTree$2.class
    p4jdb/P4DirTree$3.class
    p4jdb/P4DirTree$Manager.class
    p4jdb/P4DirTree.class
    p4jdb/P4DirTreeApplet$1.class
    p4jdb/P4DirTreeApplet.class
    p4jdb/P4File$1.class
    p4jdb/P4File.class
    p4jdb/P4Folder$1.class
    p4jdb/P4Folder.class
    p4jdb/TreeDisplay$1.class
    p4jdb/TreeDisplay$Data.class
    p4jdb/TreeDisplay$DataManager.class
    p4jdb/TreeDisplay$LineData.class
    p4jdb/TreeDisplay$MyPanel.class
    p4jdb/TreeDisplay.class
    Java files (compiled from the .java files above)