Debugging Triggers

PROBLEM

How do I debug triggers?

SOLUTION

This article provides a quick explanation of how triggers work, and outlines a few common usage pitfalls. The definitive reference for triggers is the Triggers and Daemons chapter of the Perforce System Administrator's Guide.

Perforce triggers are superuser defined rules that activate specialized scripts whenever certain client operations are performed. Triggers come in three distinct varieties:

• changelist submission triggers
• specification triggers
• external authentication triggers
  

Changelist submission triggers can be further identified as 'submit', 'content', or 'commit' triggers. The following examples are situations in which changelist submission triggers are commonly employed:

• validate text in a change description, such as requiring bug number
• require that related files be submitted together
• start build processes after successful changelist submission
• ensure that every submit to a particular branch fixes at least one job

Specification triggers can also be recognized as 'save', 'out', 'in', or 'delete' triggers. Examples of procedures suited to specification trigger use are:

• to validate specifications
• to provide customized versions of Perforce specifications
• notifying other users of attempts to change or delete specifications

External authentication triggers are either 'set' or 'check' triggers. External authentication triggers run a script that invokes another authentication application such as LDAP or Active Directory to either validate an existing password or set a password.

For examples of triggers, check the Public Depot.

Trigger debugging basics

First, check that your trigger script runs correctly outside the context of Perforce. This step is required. Run the script from the command line as the same operating system user that runs Perforce.

If the trigger script runs outside of Perforce but fails when called as a Perforce trigger, check the following:

In the p4 triggers form...

• Is the full pathname to the trigger script specified?
• Is the full pathname to the calling program (perl.exe, for example) specified?
• Does the triggers form have two triggers with the same name?

Within the trigger script...

• Are your environment variables correct?
  
• The trigger script typically needs to specify the Perforce user, client workspace and password for all Perforce commands.

Special note for Windows NT/2000 services

If you are running Perforce as a Windows service, note that by default, Perforce runs as the unpriviliged LocalSystem user that does not have access to network drives. If your trigger needs access to network drives, run the Perforce service as a user with network privileges; otherwise, such triggers fail.

Generating error output

Output to the Perforce user

If a trigger script command fails, the command's standard output (not error output) is used as the text of the trigger failure error message. For releases up to, and including, 2007.2, if a trigger script command succeeds (and therefore returns error code 0), then standard output is not shown. In 2007.3 a trigger success is sent back to the client app.

Not all failed commands generate error messages, however. If your trigger shows the default error output when it fails, then either no error message is being issued when a command fails, or no message is being written to standard output (STDOUT). The trigger script itself must write errors to STDOUT (which is normally your display) in order for users to get information. Capturing error output might require forcing a 'failed' exit code by running a bogus command.

Below is an example of a trivial trigger. You will  see the "Always succeeds" output from this trigger because it always succeeds. Note that the trigger name is not on the leftmost column; it starts with a space or tab.

     triggerTest change-submit //depot/... "echo Always succeeds."

Now, put some commands in a batch file and examine how a failing trigger generates output. Using the following trigger:

     triggerTest2 change-submit //depot/... "d:\perforce\triggers\fail.bat"

where the contents of "fail.bat" are:

@echo off
boguscommand

you see output similar to the following, when this trigger runs:

Change 1850 created with 1 open file(s).
Submitting change 1850.
Locking 1 files ...
Submit validation failed -- fix problems then use 'p4 submit -c 1850'.
'triggerTest2' validation failed: no error message

To display an error message to the user, you must write to STDOUT prior to running the failed command. For example:

@echo off
echo This trigger always fails!
boguscommand

Now, our modified "fail.bat" script displays an error message to the user:

Change 1851 created with 1 open file(s).
Submitting change 1851.
Locking 1 files ...
Submit validation failed -- fix problems then use 'p4 submit -c 1851'.
Submit check 'triggerTest2' failed: This trigger always fails!

Output to a file

If you require further troubleshooting, you can further modify "fail.bat" to redirect errors to a file. On Bourne shell and Windows scripts, the greater than sign (>) will redirect output to a file, and the 2>&1 notation sends errors to the file as well. In the following example the "boguscommand" line is modified to redirect error messages:

@echo off
echo This trigger always fails!
boguscommand > errorlog.txt 2>&1

The error from the script is captured in a file, errorlog.txt.

'boguscommand' is not recognized as an internal or external command,
operable program or batch file.

If you have problems with triggers, try the examples above. Again, for more meaningful trigger examples, check the Public Depot.