Using the Build Hooks in the Release Manager System

Last modified: 7/20/99 5:01 PM

The purpose of the build-hooks functionality within the Release Manager System is to provide to projects a means by which they can effect reasonable alterations to their product base at the four steps of the development process. These steps (for the sake of clarification and definition) are considered to be:

The hook interface as it currently stands is designed to provide simple functionality using available tools and techniques.

Using Make Rules and Actions

The base tool for providing this functionality is the UNIX utility called make. It is almost ubiquitous across UNIX platforms, and a freely obtainable version exists should it be necessary for supporting a machine that lacks the utility. The syntax and semantics are generally already a part of a developer’s set of skills.

For each of the four stages itemized above, the tool used to perform the action (which shares its name with the action) will look for the existence of a file named "Makefile" in the top-most directory of the project. If that file is present, The make utility will be invoked, with a target rule of the same name (checkout, release, etc.). If that rule does not exist, the error condition is quietly ignored. If the resultant error is due to a cause other than lack of a given rule, the full error message will be presented to the user running the tool for diagnosis.

In terms of the make utility, a rule is a construct with two parts, the second of which may be empty. The first part is the target, or name. The target need not be unique. If the target appears more than once in the Makefile, then each rule by that name is executed in sequence. The second part of the rule is the action, and it is expressed as a sequence of one or more lines of shell script code (which defaults to the Bourne shell or Korn shell, but can be coerced into using the C shell). The lines may have no blank lines separating them (the blank line is considered a separator by make), and each must be indented with at least one hard tab stop (a sequence of eight space characters is not sufficient). For more detail on how to maximize the usefulness of make and developing Makefiles, consult the book, "Managing Projects with Make", available from O’Reilly and Associates.

A rule’s action may also be empty. It is strongly recommended that if a Makefile is added to a project to enable hooks for only one or two of the stages, that the file include rules with empty actions for the remaining targets. This will not only leave the file prepared for future enhancement, but it will bring consistency to the Makefile itself and save processing effort by eliminating "missing rule" errors from make (which are subsequently ignored). Ideally, a prototypical Makefile would start out looking like this:

checkout::

populate::

stage::

prerelease::

release::

The doubled colon characters allow for multiple rules to be defined under the same name. In addition, these rules are empty, bypassing error conditions from make. From here, additional instances of rules may be defined for those rules that need actions assigned to them. At the same time, those rules that still require no action remain present.

Mechanics of the Hook Execution

The hooks for make are only attempted if the presence of a Makefile is detected. This file must be in the root directory of the project, where it will eventually be deployed into the document area of the web server during the release operation. At the end of each of the four defined steps, the tool executing that step tests for this file. When it is found, the make command is executed with the step name as the target. The command is executed from within the directory that the Makefile resides in. Any relative file paths will be relative to this directory. For example, the populate step on the machine webdev currently uses the directory /opt/ims/htdocs as the web server documents root, appending the project name for the complete path. For project "phoenix", the full path would be /opt/ims/htdocs/phoenix, and in the presence of a Makefile, the command "make populate" would be run with a working directory of /opt/ims/htdocs/phoenix.

In addition to specifying a target to make, the tool executing the command provides three variable definitions on the command line. These variables and their values are:

HTDOCS

The full path of the document directory with regards to the current step. This will be an absolute path.

CGIBIN

The full path the CGI directory for this project’s executable content. On some steps, the CGI area is a sub-directory of the document area. For other steps, it may be a sibling. This too is an absolute path.

STEP

The name of the step being executed. This is exactly the same as the rule being invoked, but is also provided as a make variable for the convenience of any project that needs to use the value within execution of the rule.

The intent is to spare the project the need of hard-coding or guessing at the values of those directory paths. These variables can be assigned default values in the Makefile itself; make will give run-time precedence to the command line values over the hard-coded ones.

NOTE: This functionality does not yet exist on the "release" step, even though that step does currently support the Makefile functionality in general.

If an error is reported by the make utility, it is either ignored or reported back to the same list of e-mail addresses that would receive any other error notification. The only error message that is ignored is the message informing the user that no such rule exists. To avoid saddling projects with the necessity of defining all rules, whether needed or not, these errors are discarded, as are diagnostic messages warning that the executed rule had no actions. Any other content (message text from make) is included in the summary message sent upon completion. For the release step, this is electronic mail. For the other steps, it is simply displayed on the terminal.

As a final note, the release step alone removes (unlinks) the Makefile upon completion of the command. This is to prevent the file being accessed via the web server. The unlink step is not done for any other steps.