99.1 Perforce p4 User Guide: Scripting Daemons & Triggers

Perforce 99.1 p4 User's Guide


<< Previous Chapter Job Tracking	Table of Contents Index Perforce on the Web	Next Chapter >> Reporting

Chapter 11
Scripting Perforce: Daemons & Triggers

User-written scripts can greatly enhance Perforce's functionality. There are three primary methods of scripting Perforce:

Wrappers are scripts that call Perforce commands.

Daemons run at predetermined times, looking for changes to the Perforce metadata. When a daemon determines that the state of the depot has changed in some useful way, it runs other commands. For example, a daemon might look for newly submitted changelists and send email to users who have previously updated the files that were submitted in those changelists. Perforce provides a number of tools that make daemon-writing easier.

Pre-submit triggers are scripts that Perforce has been told to run whenever particular files are submitted. A trigger script returns a value to Perforce that determines whether or not the submit should be performed. For example, you might write a script that watches for a particular executable file to be submitted; when this file is submitted, the trigger script might tell the submit to fail if the release notes file has not been updated within the same changelist.

This chapter assumes that you know how to write scripts. Since Perforce provides nothing in particular to help you write wrappers, wrappers are not discussed here.

Using Triggers

! Warning !

Although Perforce commands that only read data from the depot can be called in a trigger script, running Perforce commands that write data to the depot is dangerous and should be avoided! In particular, do not run p4 submit from within the trigger script.

A pre-submit trigger is a script called by Perforce when files that you've specified have been submitted. If the script returns a value of 0, the submit continues. If it returns any other value, the submit fails. Triggers might be used for any of the following:

to validate submits above and beyond the Perforce protections mechanism; for example, it might ensure that Ed isn't allowed to submit file foo until Courtney has submitted file bar.
to tell the submit to fail if file foo is not submitted in the same changelist as file bar.
to ensure that every submit to a particular codeline fixes at least one job.

Triggers are created and edited with p4 triggers; only the Perforce superuser can run this command. The p4 triggers form looks like this:


`Triggers:` `relnotes_check //depot/bld/... "perl relcheck.pl %user%"` `verify_jobs //depot/... "python /usr/bin/job.py %change%"`

Each line in the trigger table has three fields:


Field	Meaning
Trigger Name	The name of the trigger. The name can be any arbitrary string.
File Specification	A file specification in depot syntax. If a changelist contains any files that match this specification, the script will be run. Multiple file specifications can be linked to the same trigger by listing the trigger multiple times in the trigger table.
Script	The command that Perforce should run when a matching file is submitted. This command should be quoted, and can take any or all of a number of variables as parameters. The most useful of these variables are: `%user%,` which provides the Perforce name of the user who submitted the changelist; `%changelist%`, the number of the changelist that's being submitted; and `%client%`, the name of the client workspace from which the submit was run. The submit will continue if the trigger script returns a 0, and fail otherwise.

The script must be specified in a way that allows the p4d server account to find the file. You can place the directory of the script in the p4d server's path, or specify the full path name of the script within the trigger table.

Example

Creating triggers

The development group wants to make sure that whenever a .exe file is submitted to the depot that the release notes for the program are submitted at the same time. Ed is assigned to write a trigger script that does this. He writes a script that takes a changelist number as its only argument, does a p4 opened on the changelist, parses the results to find the files included in the changelist, and ensures that for every executable file that's been submitted, a RELNOTES file in the same directory has been submitted. If this is true, the script exits 0; otherwise it exits 1. He then adds this trigger script to the trigger table:

Triggers: relnotes //depot/....exe /usr/bin/relnotestest.pl %change%

Whenever an .exe file is submitted, this trigger is run. If Ed's script fails, it returns a non-0 value to Perforce, and the submit is aborted.

The triggers are run in the order entered in the triggers table. If multiple filepatterns are meant to trigger the same script, you should create multiple triggers with the same name, the same script, and different filepatterns.

Some trigger scripts will need to know which files are included in the changelist. Since p4d can only pass 1K of data to a trigger script, the file list can't be passed via the trigger. Use p4 opened -ac changelist# in your trigger scripts to get the list of files for the changelist number provided as an argument. The actual contents of the files are not accessible from within the trigger script, since the files are not stored in the depot until the submit completes.

Before p4 submit calls the trigger script, it creates the changelist, assigns it a number, and locks the files in the changelist. After the trigger script is run, p4 submit may run subsequent trigger scripts that cause the submit to fail. For this reason, trigger scripts should not take any actions that assume the submit will succeed. Trigger scripts are meant primarily for changelist validation; if you need to take particular actions based on the success of a submit, use a daemon.

Using Daemons

Daemons are scripts that are called by the server OS at preset times. Daemons that utilize Perforce usually work by examining the server metadata as often as needed and taking action as often as necessary. At Perforce Software, we use three daemons:

The change review daemon wakes up every ten minutes to see if any changelists have been submitted to our production depot. If any changelists have been submitted, the daemon sends email to those users who have `subscribed' to any of the files included in those changelists. The message informs them that the files they're interested in have changed.
Our jobs daemon generates a report at the end of each day to create a report on open jobs; it tells us how many jobs there are in each category, their severity, and more. The report is mailed to all interested users.
The Web daemon looks for changes to files in a particular depot subdirectory. If new file revisions are found there, they are synced to a client workspace that contains our live web pages.

Daemons can be used for almost any task that needs to occur when Perforce metadata has changed. Unlike triggers, which are used primarily for submission validiation, daemons can be used to write information to a depot.

Perforce's Review Daemon

The change review daemon and the jobs daemon described above are included in a single script that can be downloaded from http://www.perforce.com/perforce/loadsupp.html . This script runs under Python, which can be retrieved from http://www.python.org/. Before running the script, please be sure to read and follow the configuration instructions included the script itself.

The change review portion of the daemon looks at the files included in each newly-submittted changelist and emails those users who have `subscribed' to any of the files included in the changelist, letting those users know that the file(s) they're interested in have changed. Users subscribe to files by calling p4 user and entering filepatterns on the resulting form:


`User: sarahm` `Email: [email protected]` `Update: 04/29/1997 11:52:08` `Access: 04/29/1997 11:52:08` `FullName: Sarah MacLonnogan` `Reviews:` `//depot/doc/...` `//depot.../README`

An interested user should enter her email address in the Email: field, and enter any number of filepatterns corresponding to the files she's interested in into the Reviews: field.

The change review portion of the change daemon implements the following scheme:

p4 counter is used to read and change a variable, called a counter, in the Perforce metadata. The counter used by this daemon, review, stores the number of the latest changelist that's been reviewed.
The Perforce depot is polled for submitted, unreviewed changelists with the command p4 review countervalue;
p4 reviews is used to generate a list of reviewers for each of these changelists;
The Python mail module is used to email the p4 describe changelist description to each reviewer;
The first three steps are repeated every ten minutes; this value can be changed when the review daemon is installed.

The commands used in step 4, p4 describe, is a straightforward reporting command. The other commands used here, p4 review, p4 reviews, and p4 counter, are used almost exclusively by review daemons. These commands, and other commands used by review daemons, are discussed in detail in the next section.

! Warning !

The review counter names journal, job, and change are used internally by Perforce; use of any of these three names as review counters could corrupt the Perforce database!

Reference

Access levels are covered in Chapter 14.

Daemon Commands

Certain Perforce commands will be used almost exclusively by review daemons. These commands are:


Command	Usage
`p4 counter name [value]`	When the value argument is not included, `p4 counter` will return the value of the variable name. When the value argument appears, `p4 counter` sets the value of the variable name to value. Requires at least review access to run.
`p4 counters`	List all counters and their values.
`p4 review changelist#`	For all changelists between changelist# and the latest submitted changelist, this command lists the changelists' numbers, creators, and creators' email addresses. Requires at least review access to run.
`p4 reviews -c changelist# filespec`	Lists all users who have subscribed to review the named files or any files in the specified changelist. It is hard to imagine any use for this command outside of our own change review daemon.

Creating Other Daemons

You can use p4review.py as a starting point to create your own daemons, changing it as needed. As an example, another daemon might upload Perforce job information into an external bug tracking system after changelist submission. It would use the p4 review command with a new review counter to list new changelists, and use p4 fixes to get the list of jobs fixed by the newly submitted changelists. This information might then be fed to the external system, notifying it that certain jobs have been completed.

If you do write a daemon of your own, and would like to share it with other users, you can submit it to the Perforce Public Depot.

Perforce 99.1 p4 User's Guide


<< Previous Chapter Job Tracking	Table of Contents Index Perforce on the Web	Next Chapter >> Reporting