A.3.1 Library Catalogs

Library catalogs consist of files named .idlwave_catalog stored in directories containing .pro routine files. They are discovered on the IDL search path and loaded automatically when routine information is read. Each catalog file documents the routines found in that directory—one catalog per directory. Every catalog has a library name associated with it (e.g., AstroLib). This name will be shown briefly when the catalog is found, and in the routine info of routines it documents.

Many popular libraries of routines are shipped with IDLWAVE catalog files by default, and so will be automatically discovered. Library catalogs are scanned externally to Emacs using a tool provided with IDLWAVE. Each catalog can be re-scanned independently of any other. Catalogs can easily be made available system-wide with a common source repository, providing uniform routine information, and lifting the burden of scanning from the user (who may not even know they’re using a scanned catalog). Since all catalogs are independent, they can be re-scanned automatically to gather updates, e.g., in a cron job. Scanning is much faster than with the built-in user catalog method. One minor disadvantage: the entire IDL search path is scanned for catalog files every time IDLWAVE starts up, which might be slow if accessing IDL routines over a slow network.

A Perl tool to create library catalogs is distributed with IDLWAVE: idlwave_catalog. It can be called quite simply:

idlwave_catalog MyLib

This will scan all directories recursively beneath the current and populate them with .idlwave_catalog files, tagging the routines found there with the name library “MyLib”. The full usage information:

Usage: idlwave_catalog  [-l] [-v] [-d] [-s] [-f] [-h] libname
       libname - Unique name of the catalog (4 or more alphanumeric
                 characters).
            -l - Scan local directory only, otherwise recursively
                 catalog all directories at or beneath this one.
            -v - Print verbose information.
            -d - Instead of scanning, delete all .idlwave_catalog files
                 here or below.
            -s - Be silent.
            -f - Force overwriting any catalogs found with a different
                 library name.
            -h - Print this usage.

To re-load the library catalogs on the IDL path, force a system routine info update using a single prefix to idlwave-update-routine-info: C-u C-c C-i.

User Option: idlwave-use-library-catalogs (t) ¶

Whether to search for and load library catalogs. Disable if load performance is a problem and/or the catalogs are not needed.