Hooks

This training page provides some details about Client Side hooks, which are used to automate quality checks and metadata collection.

Hooks

Client Side hooks are scripts called at certain specific points of an IP's Lifecycle. A different script can be associated with each lifecycle event. Typical uses of Client Side hooks include initiating simulations or verification runs, or triggering continuous integration flows. Once scripts complete they may apply metadata back onto a new release, create a status widget, etc.

The hook scripts return a unix value of either '0' which PI interprets as a 'pass' or any non-zero integer which PI interprets as a 'fail'. Hooks can be triggered when an IP is loaded, updated or released, as well as pre and post integrate.

Hooks can be set either per IP, or on a Library, in which case all the IPs in that Library will by default inherit the Library hook configuration. Setting a hook at the IP level will override any Library level hook setting.

See Workspace Automation for more information. More information on a related concept, Server Side hooks is available on the Server Side Hooks page.

Managing Client Side hooks

Client side hooks are managed from the IP (or Library) template via the 'pi ip edit' command:

> pi lib edit mdx_tutorial


# Hooks are optional commands executed when certain events occur. These
# variables can be used as arguments to the hooks :
#     $IP     : IP name
#     $LIB    : Library name
#     $VER    : Version number
#               For pre-release hook, the old version number. For post-release
#               hook, the new version number.
#     $LINE   : Line name
#     $IPID   : Complete IP identifier (shorthand for $LIB.$IP@$VER.$LINE)
#     $IP_DIR : IP directory in the workspace
#     $ARGS   : Any arguments passed to the pi command with the --args argument
#               For instance, pi release lib.ip --args [arguments_for_hook]
[HOOKS]
# IP Permissions apply
pre-release = /mdx/verilog_checker.scr $IP_DIR
post-release = /mdx/verification.scr $IP $VER
post_load = 
post_update = 
pre_integrate = 
post_integrate =

Release hook example

Pre-release hook scripts are called before Perforce IPLM captures the new release, if they return 0 (success) the release proceeds, if they return something other than 0, the release is blocked. Pre-release hooks are typically used to run 'smoke' tests to be sure that the workspace is ready for release, lint checks or compilation checks are typical things evaluated by a pre-release hook.

Post-release hooks are called after the release is created by Perforce IPLM, they are typically used to run simulations, run verification, initiate Jenkins jobs, etc.

The below pre-release script example is called by passing the $IP_DIR value as an argument to it in the Library or IP template, i.e. 

[HOOKS]
pre-release = /mdx/verilog_checker.scr $IP_DIR

Below is the example of the pre release hook script.

#!/usr/bin/perl
use strict;
use warnings;


my $dir = $ARGV[0];
print "Running pre-release checks\n";
#sleep(2);
print "~~~~ Verilog Compile Check ~~~~\n";
my $res = `find . -name "*.v"`;
my @lines = split "\n", $res;
my $fail = 0;

foreach my $l (@lines) {

    #open the file, iterate across it, looking for the word ERROR.
    #if we find it, then say we failed.
    open(INFILE, "<$l");
    while (<INFILE>) {
        if (/ERROR/i) {
            $fail = 1;
            print "Compilation failed for $l\n";
            last;
        }
    }
    close(INFILE);

    print "$l\n";
    sleep (1);
}


if ($fail) {
    print "Release failed\n";
    exit 1;
} else {
    print "~~~~~~~~~~~~~~~\n";
    print "Compilation Successful!\n";
    print "~~~~~~~~~~~~~~~\n";
    exit 0;
}