Perforce 2005.1 System Administrator's Guide
<< Previous Chapter
Customizing Perforce:
Job Specifications

Table of Contents
Index
Perforce on the Web
Next Chapter >>
Tuning Perforce for Performance

Chapter 6
Scripting Perforce:
Triggers and Daemons

There are two primary methods of scripting Perforce:

This chapter assumes that you know how to write scripts.

Triggers

Triggers can be useful in many situations. Consider the following common uses:

The trigger table

After you have written a trigger script, create the trigger by issuing the p4 triggers command. The p4 triggers form looks like this:

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

You must be a Perforce superuser to run p4 triggers.

Trigger table fields

Each line in the trigger table has four fields:

Field
Meaning

name

The user-defined name of the trigger.

type

There are seven trigger types. The first three trigger types (submit, content, and commit) are fired when users submit changelists, and are referred to as changelist submission triggers. The remaining trigger types (save, out, in, and delete) are fired when users generate or modify form specifications, and are referred to as specification triggers.

  • submit: Execute a changelist trigger after changelist creation, but before file transfer. Trigger may not access file contents.
  • content: Execute a changelist trigger after changelist creation and file transfer, but before file commit.
To obtain file contents, use commands such as p4 diff2, p4 files, p4 fstat, and p4 print with the revision specifier @=change, where change is the changelist number of the pending changelist as passed to the script in the %changelist% variable.
  • commit: Execute a changelist trigger after changelist creation, file transfer, and changelist commit.
  • save: Execute specification trigger after its contents are parsed, but before its contents are stored in the Perforce database. Trigger may not modify form specified in %formfile% variable.
  • out: Execute specification trigger upon generation of form to end user. Trigger may modify form.
  • in: Execute specification trigger on edited form before contents are parsed and validated by the Perforce server. Trigger may modify form.
  • delete: Execute specification trigger after its contents are parsed, but before the specification is deleted from the Perforce database. Trigger may not modify form.

path

For changelist submission triggers (submit, content, or commit), a file pattern in depot syntax. When a user submits a changelist that contains any files that match this file pattern, the script linked to this trigger is run. Use exclusionary mappings to prevent triggers from running on specified files.

For specification triggers (save, out, in, or delete), the name of the type of form, such as branch, client, and so on. Triggers that fire on the p4 triggers command are ignored.

command

The command for the Perforce server to run when a matching path applies for the trigger type. Specify the command in a way that allows the Perforce server account to locate and run the command. The command must be quoted, and can take the variables specified in "Trigger script variables" on page 96 as arguments.

For submit and content triggers, changelist submission continues if the trigger script exits with 0, or fails if the script exits with a nonzero value. For commit triggers, changelist submission succeeds regardless of the trigger script's exit code, but subsequent commit triggers do not fire if the script exits with a nonzero value.

For in, out, save, and delete triggers, the data in the specification becomes part of the Perforce database if the script exits with 0. Otherwise, the database is not updated.

Trigger script variables

Use the following variables in the command field to pass data to a trigger script:

Argument
Description
Available for type

%changelist%

The number of the changelist being submitted. (The abbreviated form %change% is equivalent.)

submit, content, commit

%client%

Triggering user's client workspace name.

all

%clienthost%

Hostname of the client.

all

%clientip%

The IP address of the client.

all

%serverhost%

Hostname of the Perforce server.

all

%serverip%

The IP address of the server.

all

%serverport%

The IP address and port of the Perforce server, in the format ip_address:port.

all

%serverroot%

The P4ROOT directory of the Perforce server.

all

%user%

Perforce username of the triggering user.

all

%formfile%

Path to temporary specification file. To modify the form from an in or out trigger, overwrite this file. The file is read-only for triggers of type save and delete.

save, out, in, delete

%formname%

Name of form (for instance, a branch name or a changelist number).

save, out, in, delete

%formtype%

Type of form (for instance, branch, change, and so on).

save, out, in, delete

Triggering on changelists

To configure Perforce to run trigger scripts when users submit changelists, use changelist submission triggers: these are triggers of type submit, content, and commit.

For changelist submission triggers, the path column of each trigger line is a file pattern in depot syntax. If a changelist being submitted contains any files in this path, the trigger fires. To prevent changes to a file from firing a trigger, use an exclusionary mapping in the path.

Submit triggers

Use the submit trigger type to create triggers that fire after changelist creation, but before files are transferred to the server. Because submit triggers fire before files are transferred to the server, submit triggers cannot access file contents. Submit triggers are useful for integration with reporting tools or systems that do not require access to file contents.

Content triggers

Use the content trigger type to create triggers that fire after changelist creation and file transfer, but prior to committing the submit to the database. Content triggers can access file contents by using the p4 diff2, p4 files, p4 fstat, and p4 print commands with the @=change revision specifier, where change is the number of the pending changelist as passed to the trigger script in the %changelist% variable.

Use content triggers to validate file contents as part of changelist submission, and to abort changelist submission if the validation fails.

Commit triggers

Use the commit trigger type to create triggers that fire after changelist creation, file transfer, and changelist commission to the database. Use commit triggers for processes that assume (or require) the successful submission of a changelist.

Triggering on specifications

To configure Perforce to run trigger scripts when users edit specifications, use specification triggers: these are triggers of type save, in, out, and delete.

Use specification triggers to generate customized specifications for users, validate customized specifications, to notify other users of attempted changes to specification forms, and to otherwise interact with process control and management tools.

Save triggers

Save triggers are called when users send changed specifications to the server, and are called after the specification has been parsed by the server, but before the changed specification is stored in the Perforce metadata.

Out triggers

Out triggers are called whenever the Perforce Server generates a specification for display to the user. For example, the command p4 job -o fires an out trigger on the job path.

Warning!

Never use a Perforce command in an out trigger that fires the same out trigger, or infinite recursion will result. For example, never run p4 job -o from within an out trigger script that fires on job specifications.

In triggers

In triggers are called when users submit specifications, and before the specification is parsed by the Perforce server.

Delete triggers

Delete triggers are called when users attempt to delete a specification, after the specification is parsed by the Perforce server, but before the specification is deleted from the Perforce database.

Using multiple triggers

Triggers are run in the order in which they appear in the triggers table. If you have multiple triggers of the same type that fire on the same path, each is run in the order in which it appears in the triggers table. If one of these triggers fails, no further triggers are executed.

To link multiple file specifications to the same trigger (and trigger type), list the trigger multiple times in the trigger table.

Multiple changelist submission triggers of different types that fire on the same path fire in the following order:

  1. submit (fired on changelist submission, before file transmission)

  2. content triggers (after changelist submission and file transmission)

  3. commit triggers (fired any automatic changelist renumbering by the server).

Similarly, specification triggers of different types are fired in the following order

  1. out (form generation)

  2. in (changed form is transmitted to the server)

  3. save (validated form is ready for storage in the Perforce database).

  4. delete (validated form is already stored in the Perforce database).

Writing triggers to support multiple Perforce Servers

To call the same trigger script from more than one Perforce Server, use the %serverhost%, %serverip%, and %serverport% variables to make your trigger script more portable.

For instance, if you have a script that uses hardcoded port numbers and addresses...

#!/bin/sh
# Usage: jobcheck.sh changelist
CHANGE=$1
P4CMD="/usr/local/bin/p4 -p 192.168.0.12:1666"
$P4CMD describe -s $1 | grep "Jobs fixed...\n\n\t" > /dev/null

...and you call it with the following line in the trigger table...

sample1  submit //depot/qa/... "jobcheck.sh %change%"

...you can improve portability by changing the script as follows...

#!/bin/sh
# Usage: jobcheck.sh changelist server:port
CHANGE=$1
P4PORT=$2
P4CMD="/usr/local/bin/p4 -p $P4PORT"
$P4CMD describe -s $1 | grep "Jobs fixed...\n\n\t" > /dev/null

...and passing the server-specific data as an argument to the trigger script:

sample2  submit //depot/qa/... "jobcheck.sh %change% %serverport%"

For a complete list of variables that apply for each trigger type, see "Trigger script variables" on page 96.

Triggers and security

Warning!

Because triggers are spawned by the p4d process, never run p4d as root on UNIX systems.

Triggers and Windows

By default, the Perforce service runs under the Windows local System account.

Because Windows requires a real account name and password to access files on a network drive, if the trigger script resides on a network drive, you must configure the service to use a real userid and password to access the script.

For details, see "Installing the Perforce service on a network drive" on page 129.

Daemons

Daemons are processes that are called periodically or run continuously in the background. Daemons that use Perforce usually work by examining the server metadata as often as needed and taking action as often as necessary.

Typical daemon applications include:

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 validation, daemons can also be used to write information (that is, submit files) to a depot.

Perforce's change review daemon

The Perforce change review daemon (p4review.py) is available from the Perforce Supporting Programs page:

The review daemon runs under Python, available at http://www.python.org/. Before running the review daemon, please be sure to read and follow the configuration instructions included in the daemon itself.

Users subscribe to files by calling p4 user, entering their email addresses in the Email: field, and entering any number of file patterns corresponding to files in which they're interested in to the Reviews: field.

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

The change review daemon monitors the files were included in each newly submitted changelist and emails all users who have subscribed to any files included in a changelist, letting those users know that the file(s) in question have changed.

By including the special path //depot/jobs in the Reviews: field, users can also receive mail from the Perforce change review daemon whenever job data is updated.

The change review daemon implements the following scheme:

  1. 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.

  2. The Perforce depot is polled for submitted, unreviewed changelists with the p4 review -t review command.

  3. p4 reviews generates a list of reviewers for each of these changelists.

  4. The Python mail module mails the p4 describe changelist description to each reviewer.

  5. The first three steps are repeated every three minutes, or at some other interval configured the time of installation.

The command used in the fourth step (p4 describe) is a straightforward reporting command. The other commands (p4 review, p4 reviews, and p4 counter) are used almost exclusively by review daemons.

Creating other daemons

You can use p4review.py (see "Perforce's change review daemon" on page 106) 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 write a daemon of your own and would like to share it with other users, you can submit it into the Perforce Public Depot. For more information, go to http://www.perforce.com and follow the "Perforce Public Depot" link.

Commands used by daemons

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

Command
Usage

p4 review -c change#

For all changelists between change# 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 change# filespec

Lists all users who have subscribed to review the named files or any files in the specified changelist.

p4 counter name [value]

To create a new counter or set the value of an existing counter, you must have review access or greater. To display a counter's value, you must have list access or greater.

If a value argument is not included, p4 counter returns the value of name, or 0 if the counter does not exist.

If a value argument is included, p4 counter sets the value of the name to value. If the counter name does not exist, it is created.

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

Counters are represented internally as signed ints.  For most platforms, the largest value that can be stored in a counter is 231 - 1, or 2147483647. A server running on a 64-bit platform can store counters up to 263 - 1, or 9223372036854775807

p4 counters

List all counters and their values.

p4 changes -m 1 -s submitted

Output a single line showing the changelist number of the last submitted changelist, as opposed to the highest changelist number known to the Perforce server.

Daemons and counters

If you're writing a change review daemon or other daemon that deals with submitted changelists, you may also wish to keep track of the changelist number of the last submitted changelist, which is the second field in the output of a p4 changes -m 1 -s submitted command.

This is not the same as the output of p4 counter change. The last changelist number known to the Perforce server (the output of p4 counter change) includes pending changelists created by users, but not yet submitted to the depot.

Scripting and buffering

Depending on your platform, the output of individual p4 commands may be fully-buffered (output flushed only after a given number of bytes generated), line-buffered (as on a tty, one line sent per linefeed), or unbuffered.

In general, stdout to a file or pipe is fully-buffered, and stdout to a tty is line-buffered. If your trigger or daemon requires line-buffering (or no buffering), you can disable buffering by supplying the -v0 debug flag to the p4 command in question.

If you're using pipes to transfer standard output from a Perforce command (with or without the -v0 flag), you may also experience buffering issues introduced by the kernel, as the -v0 flag can only unbuffer the output of the command itself.


Perforce 2005.1 System Administrator's Guide
<< Previous Chapter
Customizing Perforce:
Job Specifications

Table of Contents
Index
Perforce on the Web
Next Chapter >>
Tuning Perforce for Performance
Please send comments and questions about this manual to [email protected].
Copyright 1999-2005 Perforce Software. All rights reserved.
Last updated: 05/12/05