Version 1.9 Build 1556

News	FAQ
Search	Home

Next: Code development Up: System generation Previous: mkinst

Subsections

`updatelib`

Update AIPS++ object libraries.

updatelib updates the object libraries associated with a particular AIPS++ package and language (see §1). It is normally used only by AIPS++ makefiles (p) but can be invoked in stand-alone mode. It can process dual debug and optimized libraries concurrently with another invokation, possibly on another machine.

An ``_f'' or ``_c'' appended to the package name, for example ``aips_f'', indicates that the FORTRAN or C libraries for the package are to be updated rather than the default C++ libraries. The libraries themselves have names of this form, for example $LIBOPTD/libaips_f.a.

The lib and lib/% targets of the implement and fortran makefiles deposit object modules in package/language-specific subdirectories of $ARCHTMPD referred to as $TMPPCKGD, for example $ARCHTMPD/aips_f. These have separate dbg and opt subdirectories for debug and optimized compilations. When the lib rules have finished compiling all modules they invoke updatelib to insert them into the libraries.

Once invoked, updatelib copies the library into the temporary area, inserts the object modules into it, and then ranlibs it. It does this in turn for the debug and and optimized libraries.

updatelib uses the library control variables to determine whether sharable libraries are to be built (see makedefs (p)). If so, they are constructed in a subdirectory called BLDSHR.$ID, where $ID is an identification string of the form <user>@<host>.

Only if each static and sharable library was successfully updated does it copy them back to $LIBDBGD and/or $LIBOPTD.

With reference to the library control variables, updatelib explicitly looks for and deletes static and/or shared libraries for the package/language which are not being maintained, thus ensuring that the libraries remain synchronized.

This whole process is complicated by the fact that the debug and optimized libraries for a package-language combination can be updated concurrently by multiple invokations of updatelib, possibly on different machines. Independent invokations of updatelib communicate via semaphore files with names of the form updatelib.*. These are described below.

Options

-f: Force a ranlib and rebuild of the sharable objects (if applicable) even if no new object modules are found.

Notes

When building the system the implement makefile recurses through all module subdirectories, compiling object modules and accumulating them in a temporary directory. The object library is only updated after all modules have been compiled. The alternative of updating the object library after processing each software module imposes a large overhead because of the large size of the object library, particularly the debug version. However, the large number of object modules in some AIPS++ packages may cause problems for updatelib simply by causing the argument list to exceed the maximum imposed by the unix kernel. This is particularly troublesome for systems which use do-it-yourself template instantiation (§10.8), or have a small value of ARG_MAX in limits.h (e.g. HPUX).
To circumvent this updatelib recognizes an UPDBATCH makedefs variable which causes it to process object modules in batches no bigger than the specified size.
updatelib should not be terminated with a SIGKILL (``kill -9'') since this would prevent it from cleaning up its semaphore files and possibly cause library updates to be locked out for 24 hours. updatelib exits gracefully on receiving a SIGHUP (``kill -1'') or a SIGTERM (``kill -15'').
Stand-alone invokations of updatelib obtain makedefs variable definitions via the eval_vars target.

Diagnostics

Status return values
0: success
1: initialization error
2: library update failed

If any library update fails, none of the libraries will be updated--with one exception: if a static library build succeeds and its corresponding shared library build fails then the static library will be updated.

Examples

The command

   updatelib aips

would update $LIBDBGD/libaips.a, $LIBOPTD/libaips.a, and the corresponding sharable libraries if enabled for the installation.

Files

updatelib uses the following semaphore files:

$TMPPCKGD/updatelib.process.$ID: ...This file simply declares an invokation of updatelib. updatelib determines whether it is the first invokation by testing for the existence of any file with a name of the form updatelib.process.*.
$TMPPCKGD/updatelib.proceed: ...This file is created by the first invokation of updatelib. It is used as an ``all-is-well'' semaphore and is deleted by any invokation which fails to update a library. Other invokations abort their updates if it disappears.
$TMPPCKGD/{dbg,opt}/updatelib.$ID: ...This is a lock file for the task of updating the static library, whether debug or optimized, and possibly its sharable counterpart. Files older than 24 hours are ignored when testing for the existence of one of these locks. If a valid lock does already exist then updatelib reports it before looking for further work.
$TMPPCKGD/{dbg,opt}/updatelib.done: ...When an invokation of updatelib has finished updating the library it renames updatelib.$ID to updatelib.done and then looks for further work. The invokation which has reserved the job of installing the updated libraries tests for the existence of this file as a signal that the invokation responsible for updating the library has finished.
$TMPPCKGD/updatelib.lock: ...Lock file for the invokation of updatelib which will install the updated libraries. If an invokation sees that this file already exists it waits for it to disappear before proceeding, thereby synchronizing the termination of multiple invokations and ensuring that updatelib doesn't return before the library update is complete.

The invokation of updatelib which installs the libraries also deletes all semaphore files on completion.

Author

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

Next: Code development Up: System generation Previous: mkinst Contents Index