-h

Help, show usage information.

-H

Help, show usage plus all helpful comment information.

-a

run on Any machine (normally only IntegrationHost)

-s

run remote operations via ssh (default rsh)

-n

No action, just tell what would be done.

-k

Keep the scripts and report files.

-K

Keep the temp file even if integration passes.

-loop

Loop to process more changes if they become available before completes. It will stop when there is nothing more to be done.

-M list

Minimum, run given changes -minimum

-P list

Precious, do not IFail changes in list, just stop.

-R list

Ready , specify order and subset, e.g. -R 29,45

-S stage

Pick up at given stage (diff|build|test|integrate)

-c change-number

specify Change to integrate at Stage

-p project-name

specify single Project name

NOTE: if custom options such as -P -R -S -c -p are given only a single project may be integrated since the options would be meaningless to the next project given.

Some options are present only for testing and investigation. Note that options are rarely required for normal operations.

The following options are available for special needs. They control the order and disposition of each change awaiting_integration in a given project.

-R[eady] number1,number2...

This option is used to specify order or subset to integrate. Only those changes listed will be attempted, and in exactly the order given. This applies to queue looping if -loop is given. In particular note unless the list includes future changes, future loops will not integrate them.

Useful if a particular change must go in before another for some reason. Or if only integrating one or two changes when several are awaiting_integration in the given project. A single change may also be specified with the -c[hange] number option, which is common for other aegis commands. However the -R option allows a list and if given will override any -c given.

-P[recious] number1,number2...

-P[recious] all

This option is used to specify that a particular change or subset of changes should be considered precious. It neither implies order nor limits the queue run to that subset; it only means that the changes should be considered precious. Note that at least one number (or the keyword all) must be given.

The concept of precious means that if the given change were to fail anywhere in the integration process, then the process simply stops and leaves the problem change in the delta directory. The -IFail would not actually be executed. This is sometimes useful to diagnose a problem which only occurs during integrations. It is also useful if the failure is due to a transient problem such as unreliable machines on the network. In such a case the integration can be resumed after fixing the problem. See the stage options below.

If, on the other hand, a precious change makes it through the integration process successfully, the option has no effect.

-M[inimum] number1,number2... or all

Integrate the given change[s] with the -minimum option. Such changes will be put on the end of the queue so that the last integrations of a run will be a minimum. This feature allows practical use of minimum integrations without requiring -minimum on each and every integration. See the section below on Minimum integrations for more information. If -loop is given any change[s] specified as minimum will run at the end of the loop in which they are ready, they will not be pushed to the final loop.

The following options allow [re]starting an integration which has already progressed through some stages. This is useful to deal with failed (precious) integrations, or to finish automatically an integration begun by hand.

-S[tage] diff

-S[tage] build

-S[tage] test

-S[tage] integrate

Pick up the integration at the given stage. Requires -c[hange] number option to specify the change number.

There are a set of hooks available which are run, if present, before and after each stage of the integration. They can be used to help ensure that the integrator actually gets some sleep while managing large projects.

These hooks are searched for in the directory $HOME/integration_hooks. None need exist; will only pay attention to any that do exist. Hooks may be any form of executable (script, etc) and are called with 2 arguments: project-name change-number. They run as the integrator on the machine from which was started. They are named using the project name along with a suffix according to what place in the integration process you want them to run.

Note that if a hook for project foo exists it is also used for any branches under that project. For example, if you have provided foo.pre_ip, it will be run for foo.1 and foo.1.0 as well. If for some reason you want different (or no) action for project foo.1.0, then you would provide foo.1.0.pre_ip which does what you wish, including nothing, effectively overriding foo.pre_ip.

Here is how to map particular places in the integration process to hook suffixes. center,box,tab(;); l l. run at time;extension _ before attempting -Integrate_Begin;.pre_ib after -Integrate_Begin completes;.ib before attempting -Diff;.pre_d after -Diff completes;.d before attempting -Build;.pre_b after -Build completes;.b before attempting -Build on <arch>;.pre_<arch>b after -Build on <arch> completes;.<arch>b before attempting -Test;.pre_t after -Test completes;.t before attempting -IPass;.pre_ip after -IPass completes;.ip before attempting -IFail;.pre_if after -IFail completes;.if

The hook program should exit with 0 if successful or 1 if not. A non-zero exit causes the change being integrated to fail immediately unless it was marked precious.

Note that in most cases anything done via an .ip hook should probably be done instead by the ipass_notify command in the project attributes file (see aepattr(5) for more information), or the build_%time_%adjust_%notify_%command in the project configuration file (see aepconf(5) for more information), but the hook can provide a temporary way to keep going until the permanent solution can be implemented.

In addition two special hooks, aeintegratq.end and aeintegratq.fail, are recognized. They are called when aeintegratq finishes a queue run. They are called with 2 arguments like any other hook (project-name change-number) although both the project-name and change-number given are of the last change integrated and may be less than useful.

The .end hook is called if/when the queue run is finished and was successful. Note that this does not mean that no changes failed, only that no queue errors occurred. This hook might be used to invoke another queue run on a different project/branch, or possibly even on the same project, if other changes may have been ended and/or reviewed while the first run was in progress. These conditions arise quite often with flex time engineers. Another use of the .end hook is to automatically build a new package using the newly integrated project as source.

If queue errors were encountered, or a change failed that was marked precious, then the .fail hook is called. An obvious use of that hook would be an e-mailed page to the integrator.

Sometimes a persistent build problem will plague integrations. This can be very annoying if it ruins an overnight run, especially if the cure is simple when it happens. Examples of this can be timeouts due to a busy data server or other transient errors. Note that this applies only to -Build related problems.

To deal with such problems the integrator may provide a strategy script specific to a project. An executable program should be found in $HOME/strategy.<project_name>. The program will be run as the integrator with the delta directory as current directory. The program may do any commands necessary to clean up and/or diagnose the error. If the script finds the problem to be transient and fix-able, it exits successfully (with 0 status) and will re-launch the -Build and log the re-try. Otherwise the script should exit with a 1 and the change will fail.