Getting Started

Documentation

Glish

Learn More

Programming

Contact Us

Version 1.9 Build 1556

News	FAQ
Search	Home

Subsections

• Synopsis
• Description
• Options
• Notes
• Diagnostics
• Examples
• Bugs
• See also
• Author

ai

AIPS++ source code checkin utility.

Synopsis

ai [-ae] [-af] [

options for

ci] file1 [file2,...]

Description

ai checks in source files from the current directory into the AIPS++ master RCS repository. It is a front-end for the RCS ci command.

ai assumes that you are working within a private directory tree which shadows that of the AIPS++ master source code tree, see mktree (p). The filename arguments specified to ai must be simple filenames without path or RCS ,v suffix. ai determines the corresponding master directory from the current working directory.

Directories may also be created on the master by ``checking them in''. In this case any options for ci are ignored. RCS subdirectories are explicitly excluded from directory checkin.

If an AIPS++ copyright notice exists in the file to be checked in ai will ensure that it is kept up-to-date for the current year (unless the -oc option is specified, see below).

If the -au option is specified, then after checking the code into the master, ai copies the RCS version file back to the local slave RCS repository (if it exists), giving it a file ownership defined by the owner of ai (aips2mgr at the local site), which must itself be setuid. If this completed successfully, ai then checks out a plain-text copy of the code from the slave RCS repository into the corresponding code directory.

ai updates the master AIPS++ RCS repository by executing $MSTRETCD/ai_master, where $AIPSMSTR is expected to be NFS mounted from the AIPS++ master host (see §1.1.4). Programmers who have an account on the AIPS++ master host, aips2.nrao.edu, may instead use a related utility, rai (p), which invokes ai remotely on the master host via ssh.

Options

-ae

For each file to be checked in, invoke ae (p) to delete any pre-existing RCS semaphore file.

-af

ai normally verifies that a file to be checked in does exist and will skip it if it doesn't on the assumption that the filename may have been misspelt. This behaviour may be overridden via the -af option which forces the creation of an empty RCS version file on the master. It is mainly for use by the AIPS++ ``code cops'' to allow the true author of a file to check in the initial version.

-au

Update the slave repository after the checkin as explained above.

-oc

Override the automatic update of the copyright notice. Automatic copyright updating can also be defeated en masse by creating an empty file called ``.oc'' in the master directory.

-I | -l | -r | -u | -wlogin

These options (without revision number) are passed directly to ci, check the manual page for ci for an explanation. All other ci options are defeated.

Notes

• Checkins by aips2mgr are explicitly defeated to discourage anonymous changes.

• Code checked into the master repository will have the file ownership defined by the owner of $MSTRETCD/ai_master (aips2adm). This script must have the setuid bit set (see chmod).

• While mktree (p) creates RCS symbolic links in the programmer directory hierarchy, these are not used by ai. Their main function is to allow gmake (p) to automatically check out the makefile for a directory. They also allow RCS utilities such as rlog to be applied readily to the slave RCS repository. ai does not make use of these RCS symbolic links but deals directly with the AIPS++ master repository by specifying absolute pathnames.

• Checkins may be disabled by creating a file $MSTRETCD/ai_disable. If this file contains any text it will be printed as an informative message.

• Checkin of new files in a particular directory can be restricted by creating a .ai_control file in the master directory. Only account names listed within that file will be permitted to check new files into that directory.

• ai uses av (p) to verify the filename when a file is created and creates an addendum to the av filename cache for each new file checked in.

• ai maintains RCS revision numbers and symbolic names. It sets the release number on the RCS trunk to coincide with the major AIPS++ version number. Further, whenever a new revision of a file is checked in ai assigns it a symbolic name which matches the AIPS++ version number of the master at the time of the checkin. Assignment of these symbolic names allows the version of a file current for any particular AIPS++ version to be recovered easily.

• Files to be checked in must have read permission for user and group. ai automatically adds this.

Diagnostics

Status return values
0: success
1: initialization error
2: checkin failure
3: checked in ok to master, but slave not updated
4: code not updated
5: directory creation failed

Examples

The command

   ai -au Foo.cc

would check in Foo.cc from the current directory into the corresponding AIPS++ master repository, updating the slave and plain-text copies in the process. The copy of Foo.cc in the current directory would be deleted. The command

   ai -u *.c

would check in all .c files in the current directory and leave read-only copies behind.

Bugs

• If the network fails part-way through a checkin, or if the checkout is aborted before completion, an RCS semaphore file with a name of the form ,*, may be left behind in the master RCS repository. The presence of this empty file will cause subsequent checkins or checkouts to report an ``in use'' error. If the not deleted manually by using the ae (p) command, or ai -ae, the semaphore file will eventually be cleaned out by exhale (p) which deletes all such files which are more than one day old.

• Since ai operates over the internet the file transfers are subject to network corruption. On a several occasions, usually when the network response was unusually poor, truncation of the last few characters of a file has been observed. A utility, xrcs (p), is available to verify the internal consistency of RCS version files.

• ai invokes RCS commands directly on the master RCS repository, which may be NFS mounted from a machine on the other side of a slow internet link. A checkin involves reading the RCS version file from the master, inserting the new revision, then writing it back. These file transactions are handled more efficiently by rai (p).

• ai requires that the host operating system support setuid shell scripts. Some operating systems, most notably Linux and Digital UNIX, do not support setuid shell scripts for security reasons.

See also

The manual page for ci(1), the RCS checkin command.
The unix manual page for chmod(1).
AIPS++ variable names (§1.2).
AIPS++ code management configuration (§1.1.4).
ae (p), AIPS++ RCS semaphore file deletion utility.
ao (p), AIPS++ code checkout utility.
am (p), AIPS++ utility to change descriptive text.
amv (p), AIPS++ code rename utility.
asme (p), execute a command with the effective uid set to the real uid.
au (p), AIPS++ code update utility.
av (p), AIPS++ filename validation utility.
ax (p), AIPS++ code deletion utility.
mktree (p), create AIPS++ directory hierarchy.
rai (p), invoke ai remotely via ssh(1).
xrcs (p), verify the internal consistency of RCS version files.

Author

Original: 1992/04/28 by Mark Calabretta, ATNF.