NAME

DESCRIPTION

GENERAL FORM

build_command =
    "cook project=${project} change=${change}";

Substitutions may take several forms:

$name

This is the same as saying "${name}". The name must start with an alphabetic, and be followed by zero or more alphanumerics.

${name}

The name in this form may contain any non‐blank characters, and it may be subject to substitution.

${name arg...}

The name and the arguments in this form may contain any non‐blank characters, and it may be subject to further substitution. Within the braces ({ and }) pairs of single quote characters ('blah blah') may be used to insulate spaces and other special characters, or you may use the back quote (\) to escape a single character.

$$

This is replaced by a single $ character. It avoid RCS expansions, you can also use ${$}.

%%

This is replaced by a single % character. Percent (%) followed by anything else is illegal.

$#...\n

This is a comment, usually found in template files read in using the ${read_file} substitution. It consumes all characters up to and including the next newline. (See also ${comment}, below.)

As another example, the dirname substitution is replaced by the directory name of the argument, rather like the dirname(1) command. In the command

history_query_command =
    "get -t -g ${Dirname $History}/s.${Basename $History}";

ABBREVIATIONS

The above example could be abbreviated to

history_query_command =
    "get -t -g ${d $h}/s.${b $h}";

Ambiguous abbreviations will result in a fatal error message.

SUBSTITUTIONS

The following lists contains those substitutions which are always understood:

Active_Directory

The absolute path of the change's development directory, if the change is between the being developed and awaiting integration states. The absolute path of the change's integration directory, if the change is in the being integrated state. Not available when the change is in the awaiting development or completed states. This rather like the default behaviour of the aecd(1) command.

Add_Path_Suffix

This substitution may be used to add a suffix to each element of a colon‐separated path list. The first argument is the suffix to use, the second and subsequent arguments are the colon‐separated paths to work on. The result is a single colon separated path. Often used in combination with the ${search_path} substitution, below.

Administrator_List

Space separated list of the project's administrators. Takes an optional argument in the same form as the user substitution.

ARCHitecture

This substitution is replaced by the architecture name appropriate for the current execution environment. Requires no arguments. See the architecture field of aepconf(5) for more information. When used in commands, you may need to surround this substitution with the quote substitution (see below), if any of your architecture names contain shell special characters.

BaseLine

Absolute path of the the project's baseline.

Basename

This substitution takes one argument, a pathname. The value of the substitution will be the last element of the pathname. This is similar to the basename(1) command.

BAse_RElative

This substitution takes at least one pathname. The value of the substitution is the base‐relative filenames, with any change‐specific or project baseline specific leading path removed. The file does not have to be a project source file. (This is almost the inverse of the $source substitution, below.)

BINary_DIRectory

The absolute path of Aegis' architecture‐specific binary (executables) directory. This corresponds to the “./configure --bindir” option when Aegis was built. This is where most of the Aegis executable programs are installed.

CAPitalize

This substitution takes at least one argument. The value of the substitution will be the arguments with the first letter of each word forced to upper case and the rest forced to lower case.

Change

Change_Attribute

Change_Files

Change_Developer_List

Space separated list of all the change's developers. Note that this is different than the Developer_List substitution.

Change_Reviewer_List

Space separated list of the change's reviewers since the last develop end. Note that this is different than the Reviewer_List substitution. Bt using the review_policy_command field of the project configuration file this value can have more than one reviewer, because this allows a project to require a change to need to be reviewed more than once before it can be integrated.

COMment

Inserts exactly nothing; any and all arguments are ignored. Another form of comment is “$#” which extends to the end of the current line.

Copyright_Years

DATa_DIRectory

The absolute path of Aegis' architecture‐neutral library directory. This corresponds to the “./configure --datadir” option when Aegis was built. This is where most of the scripts included with Aegis are installed.

DAte

With no arguments, the output is the current date. If there are arguments, they form a format string. This is similar to the date(1) command on many UNIX systems. For a description of the date formats, see the DATE section, below.

DELta

The delta number of the change. This is only available when the change is in the being integrated state or the completed state.

DEVeloper

The name of the developer. Takes an optional argument in the same form as the user substitution.

DEVeloper_List

Space separated list of the project's developers. Takes an optional argument in the same form as the user substitution. Note that this is different than the Change_DeveloperList substitution.

Development_Directory

The absolute path of the change's development directory. Only available when the change is between the being developed state and the being integrated state.

DIFF

The absolute path of the diff command, as discovered when Aegis was built. It tries to locate GNU Diff at build time to provide maximum functionality.

Dirname

This substitution takes at least one argument, a pathname. The value of the substitution will be everything but the last element of the pathname. This is similar to the dirname(1) command.

Dirname_RELative

This substitution takes at least one argument, a pathname. The value of the substitution will be everything but the last element of the pathname. This is similar to the dirname substitution, except that if there are no directory components, it returns dot (“.”).

DownCase

This substitution takes at least one argument. The value of the substitution will be the argument with any upper case letters mapped to lower case.

EMail_Address

ENVironment

This substitution takes at least one argument. The value of the substitution is the value of the corresponding environment variable, or empty of undefined.

ERrno

This substitution takes no arguments. The value of the substitution will be the value if the errno variable provided by the system, as mapped through the strerror function. Thus you may give the users informative system error messages.

EXpression

This substitution evaluates simple arithmetic expressions. Addition, subtraction, division, multiplication, modulo and negation are understood. The 6 basic comparison operators are available. The usual C syntax and precedence are used. The arguments must constitute a valid expression, white space and word boundaries are ignored.

History_Directory

This substitution takes zero arguments. It is replaced by the absolute path of the history directory of the project.

History_Path

This substitution takes one argument, the name of a source file. It is replaced by the absolute path of the history file for that source file. Note that you may beed to massage the file name a little for you proticular history tool, just as the history commands in the aegis.conf file do.
This substitution takes zero arguments. It is replaced by the absolute path of the history directory of the project.

IDentifier

This substitution takes at least one argument. The value of the substitution will be the argument with all characters but alpha numerics mapped into an underscore (_), so as to form a legal C identifier.

INTegration_Directory

The absolute path of the change's integration directory. Only available when the change is in the being integrated state.

INTegrator

The name of the change's integrator. Only available when the change is in the being integrated state or the completed state. Takes an optional argument in the same form as the user substitution.

INTegrator_List

Space separated list of the project's integrators. Takes an optional argument in the same form as the user substitution.

LEFt

This substitution extracts the left hand side of strings. It takes two arguments: the first is the string, the second is the number of characters.

LENgth

This substitution determines the length of strings, the result is a number. It takes one argument: the string to be measured.

LIBrary

The absolute path of Aegis' library directory. This corresponds to the “./configure --datadir” option when Aegis was built. This substitution is deprecated - please use ${datadir} instead.

LIBrary_DIRectory

The absolute path of Aegis' architecture‐specific library directory. This corresponds to the “./configure --libdir” option when Aegis was built.

Name_Maximum

This substitution is used to get the maximum file name length within a file system. It takes at least one argument: the name of a directory within the file system. Frequently used with ${left} to crop filenames to the file system maximum.

PAth_Reduce

This function requires at least one argument. It is used to remove duplicates from a command search path, such as may be found in the PATH environment variable. If more than one argument is given, all are included in the results, as if they were separated by colons.

PERL

This function requires zero arguments. It is replaced by the absolute path of a Perl interpreter.

PLural

This function requires 2 or 3 arguments. The first argument is evaluated as a number, if it is plural (not equal to 1) the second argument is the result, otherwise the third argument is the result (or empty if not given). This is mostly used to pluralize sentences in Germainic error messages.

PLural_Forms

Project

Project_Specific

This substitution takes exactly one argument. This argument is a name to be found in the project configuration file's project_specific field (see aepconf(5) for more information). This returns the value listed in the project configuration file. Unknown attributes will be replaced with the empty string.

QUote

This substitution may be used to quote shell special characters. If no quoting is required, not quotes will be inserted. This is used to insulate shell special characters in filenames when forming commands.

Read_File

Read a file and substitute the contents of the file. Requires exactly one argument, the pathname of the file to be read. If the pathname is a project source file, you will need to use the source substitution to resolve the path. It is a fatal error if the file does not exist, or is not readable. It is a fatal error if the pathname is not absolute (because the current directory is undefined).

Read_File_Simple

Read a file and without substituting the contents of the file. Requires exactly one argument, the pathname of the file to be read. If the pathname is a project source file, you will need to use the source substitution to resolve the path. It is a fatal error if the file does not exist, or is not readable. It is a fatal error if the pathname is not absolute (because the current directory is undefined).

Reviewer

The name of the change's reviewer. Only available when the change is between the awaiting integration state and the completed state. Takes an optional argument in the same form as the user substitution.

Reviewer_List

Space separated list of the project's reviewers. Takes an optional argument in the same form as the user substitution. Note that this is different than the Change_Reviewer_List substitution.

RIght

This substitution extracts the right hand side of strings. It takes two arguments: the first is the string, the second is the number of characters.

Search_Path

The Search_Path substitution is replaced by a colon separated list of absolute paths to search when building a change, it will point from a change to its branch and so on up to the project trunk.

Search_Path_Executable

The Search_Path_Executable substitution is usually the same as the Search_Path substitution. However, during an “aegis -Test -BaseLine” command, it contains the baseline as the first element, rather then the development directory or the integration directory. This is of most use when looking for executables and executable support files while running tests.

SHell

The absolute path of a Bourne shell which understands functions. Requires exactly zero arguments.

Source

Resolve the argument filename into a pathname. It is an error if the file is not a source file. An optional second argument may be "Absolute" or "Relative", and may be abbreviated. Relative will attempt to provide a development‐directory‐relative pathname whenever possible, absolute will always result in an absolute path. The default is "Relative". (For the inverse mapping, see ${BAse_RElative}, above.)

SPLit

This substitution may be used to split strings are specified separators. The first argument is the separator character to be used, subsequent arguments are strings to be split. The result is the collection is split strings of the second a follwoing arguments, separated by spaces.

STate

The state the current change is in. It is an error if the substitution does not refer to a change.

SUBSTitute

Regular expression substitution. The first argument is the pattern to match, the second argument is the replacement string. The third and subsequent arguments are modified as specified by the first two arguments. The search is not anchored, and the replacement will happen as many times as possible. Use “^” to match the beginning, and “$” to match the end.

SUBSTRing

This substitution extracts a substring from the middle of strings. It takes three arguments: the first is the string, the second is the star character (counting from zero), the third is the number of characters.

SWitch

Select amongst a set of values. The first argument is expected to be a number. If the number is zero, the second argument is used; if the number is one, the third argument is used; etc. If the number is negative, or exceeds the available arguments, the last argument is used.

Trim_DIRectory

This substitution takes one or two arguments. If given one argument, one directory component (if present) is removed from the argument, which is assumed to be a file name. If two arguments are present, the first is a directory count; at most this many directory components (if present) will be removed. The base file name is always left.

Trim_EXTension

This substitution takes one argument. Any file name extension (a dot characters and the characters following) will be removed from the final filename section of the argument.

UNSplit

This substitution may be used to reverse the effects of the split substitution. The first arguments is a seaparator character, the second and following arguments are strings to be joined together using the separator character. The result is a single string.

UpCase

This substitution takes at least one argument. The value of the substitution will be the argument with any lower case letters mapped to upper case.

USer

Version

Zero_Pad

This substitution is used to zero pad a string on the left. It takes two arguments: the first is the string to be padded, the second is the minimum string width.

DATE

%%

The percent character (%)

%a

the abbreviated weekday name

%A

the full weekday name

%b

the abbreviated month name

%B

the full month name

%c

the date and time

%d

the day of the month, zero padded

%H

the hour of the 24‐hour day

%I

the hour of the 12‐hour day

%j

the day number of year, zero padded, one based

%m

the month of the year, zero padded, one based

%M

the minute of the hour, zero padded

%p

meridian indicator, AM or PM as appropriate

%S

the second of the minute

%U

the Sunday week of the year

%w

the day of the week, Sunday is 0

%W

the Monday week of the year

%x

the date, as mmm dd yyyy

%X

the time, as hh:mm:ss

%y

the year of the century

%Y

the year including the century

%Z

time zone abbreviation

Using an undefined format specifier will produce random results, depending on the version of UNIX you are on.

SEE ALSO

aesub(1)

Substitute and print strings.

COPYRIGHT

The aegis program comes with ABSOLUTELY NO WARRANTY; for details use the 'aegis -VERSion License' command. This is free software and you are welcome to redistribute it under certain conditions; for details use the 'aegis -VERSion License' command.

AUTHOR