The Java Platform Reliability Testing (JPRT) System

How To Guide

JPRT is a build/test/putback system that at the highest level can be viewed as a very smart Teamware 'putback' command or Source Code Management (SCM) commit operation. For those of you unfamiliar with Teamware, a 'putback' is the step that is taken to send changes back (commit them) into the parent or upper-level repository. Basically you submit changes from your formal source tree (teamware workspace) into JPRT and you will be given a job ID and your job will be placed in the queue for processing.

FIXME: Create separate 'how-to' section for integrators and developers (-stree). FIXME: Document the necessary commands needed in path (tar, teamware, etc.)

The source trees accepted by JPRT need to have been configured for JPRT. This involves 3 basic items:


So if your source tree does not contain the above items, you need to do a bringover from the parent source tree, or talk to the primary or parent source tree owners about getting it configured for use with JPRT.

The JPRT system is composed of a driver machine which you will communicate with via the jprt_* user commands, and a set of client machines that perform the build and testing of all the platforms. The JPRT user need never access these client machines.

The status of the system, including who is in the job queue can be inspected with the command 'jprt_status' or 'jprt_status -v' for more verbose status information.

The jprt commands are located in the sfbay domain at /java/svc/jprt/dist/bin or /net/jprt-web.sfbay/jprt/dist/bin. The help information for these commans is available by running the commands with the -help option or viewing the help results in the helpdocs directory.

Jobs are submitted with the command 'jprt_submit', which works very much like the Teamware putback command, but has many more options to control what is built, what is tested, and whether the changes need to be sync'd with the parent source tree, or putback to the parent source tree if everything passes. (It does much more than a putback command of course). The JPRT system uses a separate source tree to putback the changes, creating a sibling source tree from the files you have specified in your submit command and from your own source tree.

Then when your job gets to the head of the queue, it will make sure the sibling source tree is sync'd with the parent source tree (bringover of all parent files). If there are conflicts, you will get an email and roughly 60 minutes to resolve the conflicts, otherwise your job is killed. Normally this doesn't happen, but you should be prepared. Any time you have a job in the JPRT queue, you need to be at least keeping an eye on it occasionally. The state of the job will show up with 'jprt_status'. Once your job is sync'd, the sources are bundles and sent to the various client machines for building. Once a platform is done building, it will start any tests that have been specified. By default, if ANY build or test fails, all other tasks are killed and the system is freed up so that the next job can start. On success, the email sent to you should include a path to where the binary build results are, and any test results.

If the parent source tree has the name '*baseline' special rules kick in with regards to the format of the comment, requiring the standard JDK putback form for CR numbers fixed, etc.

Examples

Details on all options can be seen by using the -help option of any of the tools, especially 'jprt_submit'. This may be best explained with some examples (in all these examples I assume you have done a 'cd' into your source tree):

The source tree itself defines what the default list of build targets and test targets are (see the files make/jprt* in the source tree).

If you have requests for better examples, please let me know.