History
Originally there was Perfbrowse (if there was anything before that,
I don't know of it). It's not clear who the original author of
perfbrowse.pl was, but the comments at the top of the script show it
as having been "Updated by Jeff Marshall at Paragon Software, Inc.
(jam@paragon-software.com)". However, given all the things he lists
as having added in his "update", it looks like he comes awfully
close to being able to be called the author of it.
Fredric Fredriksson (fredric@mydata.se) took Perfbrowse and transformed it
into his P4DB (see his readme file, //public/perforce/utils/p4db/README.html).
I started with his P4DB at version 0.99f (I believe his is now [2/7/00] at
0.99h, but I'm not sure what changed in the "g" and "h" versions, since I
stayed with what I started with, having already diverged enough from 0.99f
by the time "g" and "h" came along that it seemed best to just stick with
what I had.)
Where I Came In
My original reason for working with P4DB was just to get it to work on NT.
I knew almost nothing about NTs, only a little HTML, barely enough Perl
to print out the ubiquitous "Hello, world", and less than nothing about
CGI apps, web servers, cookies, etc. (but hey, why let a little thing
like that stop me, right? :)
Since my knowledge was so lacking, I originally started changing the Perl
code itself to try and get it to work on NT (and actually did manage to get
an awful lot of it to work that way -- which I later realized was pretty
miraculous, given what the real answer was). In the process, I also couldn't
stop myself from changing just a little something here and a little something
there. Of course, all those little somethings had started to add up, and
by the time I figured out what I actually needed to do to get it all to
work on NT (namely, add an environment variable to the CONFIG file that
sets $SHELL to be a Unix-type shell [in my case, the MKS korn shell]),
I'd come pretty close to changing at least something about almost
everything -- so I figured I might as well just have at it. :)
What's New
I suppose the most noticable change is the difference in the way the
top-level page is laid out -- for one thing, it no longer emphasizes
the changes-by-codeline thing. Instead, it presents a number of options
(including a List Changes by Branch option, which presents the list of
branches you can click on to see a branch's changes), along with the
forms that were there before and one new one (which allows for the
option of pointing to a different repository), and a Get Help option
(which brings up a help-file window).
There is one difference in one of the forms from before -- the "View
change number" form now contains the latest change number as its default
value.
The new "Browse a different repository" form allows the user to enter
either a new hostname or a new port number, or both, to switch to browsing
a different repository. This allows each user who's accessing the application
to browse whatever repository they want, instead of being tied to a single
one for everybody. So, if you have more than one p4 server in-house and
want to switch to a different one from the default, or if you want to browse,
say, the public one over at Perforce, you can do that, without it affecting
what repository anyone else is browsing.
Another change is the way the "Browse Depot Tree" presents its pages.
If the respository has more than one depot, it will display the depots
under "Depots" (from there, you go through a depot to display the
subdirs/files) -- if the repository has only one depot, it will display
the top-level directories under "Subdirs". (Files are displayed under "Files".)
I also changed the way things get printed across the window -- I did it
so that it gets printed out in 3 columns. And I added a "Back To" line
that allows the user to go directly back up to whatever level in the tree
they want.
I added an option to restrict certain files from being displayed -- which
ones are specified, either by directory or file name, in the CONFIG file
(see the comments in the CONFIG file for more detail). This is handy in case
you have people who can access the browser, but who aren't supposed to have
access to certain files (e.g., cryptography files). I was going to implement
the restriction by IP_ADDR, but I decided to just do it for everyone so it's
more secure (if people who are allowed access to the files need to see the
file contents, they can always just do it directly through P4). The P4DB
restriction doesn't stop anyone from seeing file meta-data -- just the
actual file contents.
Other changes include:
New index-page options:
- List Changes by Branch (includes a refinement option for
branch changes by user)
- List Opened Files (includes a refinement option by client)
- List Changes by User
- Get Help (for a help-page window)
- The "Change <chg_no>" page now includes the option of going up or
down to the next or previous change.
- Clicking on an "add" Action now displays the contents of the file as
the diff output.
- Clicking on the little line-numbers in the diff output to go to that
line in the file now works.
- The output of the 'p4pr.pl' utility is now presented as a Legend option
("View line-by-line history trace").
- Page titles are more general, with the specific information that used
to be in some of them presented in the page body instead.
- Pages that display things like Change, Action, Rev, etc., now all do
that in a consistent order (as does the Legend for those pages).
- The label-diff output table is more consistent and has more link options.
- The CONFIG file allows you to specify a link to return to from the
index page.
- The CONFIG file allows you to specify an intranet site, which is then
used to translate relative links (e.g., "../../index.html") in HTML files
that are being viewed through the browser (see "About Links..." on the
File View page Legend for more detail).
- The User Info page allows for getting a list of the user's clients.
(Note: this is an option rather than just doing it by default because
as of now the 'p4 clients' command doesn't include the owner in the
output [which I've mentioned to the people at Perforce, who've said
they'll ask to have that changed] so it's pretty slow at this point
to get the list.)
- Pages that include a client name now have those names as links to view
the client info.
- A mailto link is included for a P4DB admin.
There are probably other miscellaneous changes I'm forgetting, but hopefully
the Help page covers everything.
I haven't implemented any Jobs stuff yet, since I haven't yet dealt with
Perforce Jobs, but I intend to add it in the near future.
One thing I took out was the Java applet -- I couldn't see that it really
did much (but maybe I just never got it to work right -- in any case, it's
gone from this version).
I believe I've commented the CONFIG file enough to explain what needs to
be done to get it working on your system.
I've now run it successfully on NT, FreeBSD, and AIX, with only the CONFIG
file being different between them. Okay, that's not completely true -- I did
have to tweak some things to get it to run on the ISP's machine, but that's
just because they have things set up differently there than on a machine
where you just have the Apache server to yourself. See the "How To Install
It" section below for details.
In all cases, I've used an Apache server, so I can only verify it works
with Apache.
Oh yes -- one other change...unlike Fredric (who must be even more of
a perfectionist than I am), I'm willing to call my version of P4DB
Version 1.0 :)
Where to See It
I've installed it on an ISP, with the default repository it's pointing to
the one at public.perforce.com:1666. Since it's running on a machine that's
not inside your network, if you try to point it to your own P4 server,
it's pretty likely it will fail (I'd hope it would anyway), but you can
change the one it's pointing to to be at host perforce.com (at port 1666) --
that'll just point you at the same repository, but you'll at least be able to
see it change for you, while staying the default for someone else. The link
is:
http://www.tsoft.com/~dianeh/cgi-bin/index.cgi
Where to Get It
I've bundled up the *.cgi/*.pm/*.pl files, the help file, and the icons
I used into a straight tar file. I didn't compress it, because a) it's not
all that big uncompressed, and b) I've been bitten too many times lately by
not having the tools I need to deal with uncompressing compressed tar-files,
so I didn't want anyone else running into that wall.
You can either download the tar-file by going through the source browser
available through the above URL, and entering:
//guest/diane_holt/p4db/p4db.tar
in the "Search for file" form on the top-level page, then clicking on the Rev
to get to the File View page, and selecting the "Download file" option in the
Legend at the top of the page.
Or, if you have client access to the Perforce guest depot, you can just use
'p4 sync' to get it.
Which One To Get
The p4db.tar file (and the Perl files) at rev 1 are suitable for running with
the 98.2 release of P4.
The p4db.tar file (and the Perl files) at rev 2 are suitable for running with
the 99.2 release of P4. I also changed one little thing on the File Log page
("Opened by", and the "Client:..." Legend item only print out if in fact the
file is opened by someone).
How To Install It
If you pick up the tar-file, and you're running an Apache server, you should
just be able to un-tar it in the directory where the cgi-bin, htdocs, and
icons directories live (assuming you have write permission there). It's
unlikely that there would be any files named the same, but you should probably
do a table-of-contents tar first, just to make sure.
If you have things set up differently, un-tar the file into some holding
place, then move the files around accordingly.
NOTE: There were a couple of things I needed to do to get it to run on the
ISP's machine:
- The hash-bang's at the top point to /usr/local/bin/perl5 rather than
just /usr/local/bin/perl.
- I needed to add a "use lib '/usr/local/lib/perl5/site_perl;" statement
to the P4CGI.pm file.
- The href's to the help doc and the icons needed to be done relatively
(i.e., with ../'s) rather than just, for example, "/icons/uarrw.gif".
You might need to change some or all of those things.
Other than that, you should be able to just modify the CONFIG file according
to your needs.
The Qualifiers
Since I didn't really know Perl going into it, I'm sure the Perl code could
be better written (one place in particular I know is embarrassing, just from
a general programming standpoint -- but it was expeditious and my brain was
tired that day). Any suggestions for improvements will be gladly accepted.
All other comments/bug-reports are also welcome: holtdl@yahoo.com
And of course, no warranty, expressed or implied, etc., etc.