<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Mozilla/4.5 [en] (X11; I; Linux 2.0.35 i686) [Netscape]">
<meta name="Author" content="fredric@mydata.se">
<meta name="Description" content="Information on how to install andmaintain P4DB">
<title>Developers README file for P4DB</title>
</head>
<body>
<center>
<h1>
A developers README for P4DB</h1></center>
<h2>
Introduction</h2>
<h3>
Abstract</h3>
This is a README for P4DB, a CGI based p4 depot browser written by Fredric
Fredricson (<a href="mailto:fredric@mydata.se">fredric@mydata.se</a>) (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.
<h3>
More introduction</h3>
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).
<p>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.
<p>Current version of P4DB (0.99f) requires Perforce p4 98.2 (or newer).
<h3>
History</h3>
The application was developed from a depot browser, perfbrowse.perl, made
available by <a href="http://www.perforce.com">Perforce</a> at <a href="http://www.perforce.com/perforce/loadsupp.html#browse">http://www.perforce.com/perforce/loadsupp.html#browse</a>
<p>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.
<p>The idea is also stolen so I can't claim that one.
<p>To view file a script by Bob Sidebotham called <tt><a href="p4pr.perl">p4pr.perl</a></tt>
is used. This script is also made available by Perforce at <a href="http://www.perforce.com/perforce/loadsupp.html#util">http://www.perforce.com/perforce/loadsupp.html#util</a>
(but I made some minor changes and one bug fix).
<p>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.
<br><i>(Maybe I should mention that it took much more time than I
anticipated).</i>
<h4>Diff 0.99d to 0.99f:</h4>
<ul>
<li> Depot browser only worked with a single depot named "depot".<br>
Fix supplied by Mike Dixon. </li>
<li> Install script now more portable.<br>
Problem pointed out by Jeffrey A. Marshall.</li>
<li> P4CGI now runs with Solaris 2.7/perl5.005_02.<br>
Thanks Ron Shalhoup for reporting and testing.</li>
<li> Somewhat improved error handling
(inspired by idea from Ron Shalhoup).</li>
<li> Bugfix: Change browser can view jobs again</li>
<li> Added a "smart" html viewer that changes relative links to point
to files in depot. (Maybe to smart).<br>
This was implemented in response to a problem reported by
Laura Wingerd at Perforce.
</li>
<li> As a result of the "smart" html viewer the special file viewers
are controlled by a new file "viewConfig.pm". This file makes
it easier to associae file extensions with mime types.</li>
<li> Added line numbers to file viewer</li>
<li> Converts tabs to spaces in file viewer</li>
<li> Improved diff viewer:<ul>
<li>Lists line numbers for file
<li>Possible to get more context (up to whole file)
<li>Links to file viewer</li></ul>
</ul>
<h4>Diff 0.99a to 0.99d:</h4>
<ul>
<li> Handles 98.2 file lists better
</li>
<li>
Changed colors a little (looks nicer)
</li>
<li>
Improved file viewer and added a "download file" link
</li>
<li>
Improved "special file viewer" (downloads MS-Word etc
for view)
</li>
<li>
Added a graphic depot browser using a java applet
</li>
<li>
Improved "Browse depot tree". Uses features in 98.2
to avoid the use of temporary files.
</li>
<li>
Fixed bug in label cross reference function in
file log view
</li>
<li>
Added "list files in label" to label view
</li>
<li>
Fixed bug triggered by newer versions of CGI.pm package
</li>
<li>
Change log will only show 100 changes at the time
</ul>
<B>WARNING:</b><br> Release 0.99d P4DB does not work with p4 97.3
or earlier.
<h2>
Installation</h2>
<h3>
First: Where to install</h3>
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.
<p>One argument against this may be that you want to keep the server clear
from other apps that <u>might</u> create problems. Personally I don't think
this is a very good one but this is up to you.
<h3>
How to install</h3>
You obviously got to this README. Together with README.html file you got
a file "install.pl".
<br>Type "<tt>perl install.pl</tt>" To install all scripts. This is the
theory, at least. I have not tested it on many systems
<p>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.
<p>For more details, see the comments inside the <a href="install.pl">install.pl</a>
script.
<h3>
How to configure</h3>
You will need to configure the scripts. The basic configuration file is
called <tt>config</tt>. To create a configuration file copy the file
<tt>
<a href="config.org">config.org</a></tt>
to <tt>config</tt> and modify it.
<br>The configuration file is a perl script but very little knowledge of
perl should be required to configure it.
<p>To make some handy shortcuts available for the users there is a file
called <tt>CODELINES</tt>. See the sample file <tt><a href="CODELINES.sample">CODELINES.sample</a></tt>.
<p>P4DB will let you view some file types using the browser rather
than just as text. This can be configured in a file
<A href="viewConfig.pm">viewConfig.pm</A>. Default will let you view
HTML, gif, jpeg, MS-Word, MS-Powerpoint, and Acrobat (PDF) formats.
<h2>
Warranty</h2>
If you get any problems because of these scripts I promise to feel sorry
for you. Other than that you are on your own.
<h2>
Known Bugs</h2>
<li>
Deleted files can't be viewed</li>
<li>
A serious case of feature bloat</li>
<li>
Should probably be written in Java or some other language</li>
<li>
Sometimes slow.....</li>
<h2>
Missing features or "Why these silly version numbers?"</h2>
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.
<p>
Some missing features and improvements are:
<UL>
<LI> Better branch viewer. The current is not very good.
</LI>
<LI> List opened files for all users.
</LI>
<LI> A more complete file history listing that includes branches and
integration of changes. This not a trivial thing to do but interesting.
</LI>
<LI> More complete user information including client information.
</LI>
<LI> View jobs<B>!</B>
</LI>
</UL>
<h2>
Would you like to contribute?</h2>
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).
<p><b>Disclaimer</b>: I may grow tired of this project or change job or
die or something in which case my promise above probably expires.
<h3>
What would be a contribution?</h3>
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.
<h2>
Design documentation</h2>
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.
<p>The P4CGI.pm module is documented using perlpod (see perlpod man page).
To get a HTML page containing documentation type:
<br><tt>pod2html P4CGI.pm ><a href="P4CGI.html">P4CGI.html</a></tt>
(There is one distributed with P4DB, for convenience)
<p>For other files: more often than not the code is commented.
<p>There are three different files 'types' in the design:
<dl COMPACT>
<dt>
P4CGI.pm</dt>
<dd>
- A perl module containing functions that I find useful and all other scripts
use</dd>
<dt>
*.cgi</dt>
<dd>
- A set of cgi scripts that are used as ...eh.. cgi-scripts.</dd>
<dt>
p4pr.perl</dt>
<dd>
- The script by Bob Sidebotham I mentioner earlier</dd>
</dl>
NOTE! The P4CGI.pm module "knows" if it is used in a cgi script or a regular
perl script by checking for .cgi extension.
<p>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.
<p>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.
<p>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.
<h3>
List Of Files:</h3>
<dl>
<dt>
<b><tt>P4CGI.pm</tt></b></dt>
<dd>
A perl package that contains common functions.</dd>
<dt>
<b><tt>index.cgi</tt></b></dt>
<dd>
Entry point or "main" cgi.</dd>
<dt>
<b><tt>chb.cgi</tt></b></dt>
<dd>
Change browser</dd>
<br>View list of changes for selected part of depot
<br>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......
<dt>
<b><tt>chv.cgi</tt></b></dt>
<dd>
Change viewer<br>
View a change by number</dd>
<dt>
<b><tt>dnld.cgi</tt></b></dt>
<dd>
Download<br>
Used to download files</dd>
<dt>
<b><tt>dtb.cgi</tt></b></dt>
<dd>
Depot tree browser<br>
Walk around in the depot file tree</dd>
<dt>
<b><tt>fdv.cgi</tt></b></dt>
<dd>
File diff viewer<br>
View diff between two files or two revisions</dd>
<dt>
<b><tt>flv.cgi</tt></b></dt>
<dd>
File log viewer<br>
View file history</dd>
<dt>
<b><tt>fv.cgi</tt></b></dt>
<dd>
File viewer<br>
View a file</dd>
<dt>
<b><tt>jdtb.cgi</tt></b></dt>
<dd>
Java depot browser cgi<br>
Provides data for java part of depot browser</dd>
<dt>
<b><tt>lab.cgi</tt></b></dt>
<dd>
List all branches<br>
Show a list of all branches</dd>
<dt>
<b><tt>lal.cgi</tt></b></dt>
<dd>
List all labels<br>
Display a list of all labels</dd>
<dt>
<b><tt>lau.cgi</tt></b></dt>
<dd>
List all users<br>
Display a list of all users</dd>
<dt>
<b><tt>ldv.cgi</tt></b></dt>
<dd>
Label diff viewer<br>
View diff between two labels</dd>
<dt>
<b><tt>lu.cgi</tt></b></dt>
<dd>
List user<br>
List info about a p4 user</dd>
<dt>
<b><tt>lv.cgi</tt></b></dt>
<dd>
Label view<br>
View info about a label</dd>
<dt>
<b><tt>p4race.cgi</tt></b></dt>
<dd>
The p4 submit race</dd>
<dt>
<b><tt>sff.cgi</tt></b></dt>
<dd>
Search for file<br>
Search depot for files matching spec</dd>
<dt>
<b><tt>sfv.cgi</tt></b></dt>
<dd>
Special file viewer<br>
Special file viewer for HTML, JPEG, GIF , MS-Word, MS-Powerpoint, RTF,
and PDF file types.</dd>
<dt>
<b><tt>CGI.pm<br>
CGI/Carp.pm</tt></b></dt>
<dd>
CGI.pm package (unpacked only if the installation script does not find
the <tt>CGI.pm</tt> package already installed)</dd>
<dt>
<b><tt>p4jdb/P4DirTreeApplet.java<br>
p4jdb/P4DirTree.java<br>
p4jdb/P4File.java</tt></b></dt>
<br><b><tt>p4jdb/P4Folder.java<br>
p4jdb/TreeDisplay.java</tt></b>
<dd>
Java source code for the graphic depot tree browser.</dd>
<dt>
<b><tt>Makefile</tt></b></dt>
<dd>
Make file for java classes (GNU make)</dd>
<dt>
<b><tt>p4jdb/P4DirTree$1.class<br>
p4jdb/P4DirTree$2.class<br>
p4jdb/P4DirTree$3.class<br>
p4jdb/P4DirTree$Manager.class<br>
p4jdb/P4DirTree.class<br>
p4jdb/P4DirTreeApplet$1.class<br>
p4jdb/P4DirTreeApplet.class<br>
p4jdb/P4File$1.class<br>
p4jdb/P4File.class<br>
p4jdb/P4Folder$1.class<br>
p4jdb/P4Folder.class<br>
p4jdb/TreeDisplay$1.class<br>
p4jdb/TreeDisplay$Data.class<br>
p4jdb/TreeDisplay$DataManager.class<br>
p4jdb/TreeDisplay$LineData.class<br>
p4jdb/TreeDisplay$MyPanel.class<br>
p4jdb/TreeDisplay.class</tt></b></dt>
<dd>
Java files (compiled from the .java files above)</dd>
</dl>
</body>
</html>
| # | Change | User | Description | Committed | |
|---|---|---|---|---|---|
| #2 | 382 | heather_van_steenburgh | Bring up to 0.99f level | ||
| #1 | 381 | heather_van_steenburgh |
The version of P4DB in the public depot isn't 0.99f. Branch for 0.99f |
||
| //guest/heather_van_steenburgh/perforce/utils/p4db/README.html | |||||
| #1 | 380 | heather_van_steenburgh | P4DB baseline | ||
| //guest/perforce_software/utils/p4db/README.html | |||||
| #1 | 11 | Perforce maintenance | Add Fredric Fredricson's depot browser, P4DB. | ||