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:
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.
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):
jprt_submit -m commentFile .
The file 'commentFile' contains the putback message and the '.' signifies this is a putback of ALL the changed files in your source tree. This is the simpliest example, but is often overkill and will cause the jprt_submit command to create a complete sibling source tree on the spot in the JPRT system with ALL the files of your entire source tree, which will take a long time, maybe over an hour. If you have an idea of the part of the source tree that you have changed or the specific file, try specifying those filenames or directory names instead of the '.', this allows the jprt_submit to complete quicker and lets the JPRT system get the rest of the files from the parent source tree. If you don't know what files you have changed, try 'putback -n .'.
jprt_submit -c "your comments" make/Makefile
First a sibling source tree is created with only the file make/Makefile in it. The job is submitted rather quickly, e.g. jprt_submit returns quickly, and you can watch your job with jprt_status right away. The initializing of this job when it gets to the head of the queue will take a long time, because most of the source tree files will need to be created at job initializing time.
jprt_submit -n -m comment_file .
This job is a non-putback job (-n), and the comment is in a file called "comment_file". The '.' specification means that all files in the source tree should be used to create the sibling source tree, so this jprt_submit command will take a long time in creating a complete source tree before it ever returns to the user. On the other hand, once the job gets to the head of the queue, it will initialize faster because the sync with the parent will not need to copy over quite as many files.
jprt_submit -onlytargets '.*product.*' -n -c src/share/classes
This is a non-putback job where we are only interested in the product build and tests, and we know that we only changed files in the 'src/share/classes' directory of the 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.