vlibraries - a guide to the organization of libraries in Vesta-2
This man page describes the organization of libraries in the standard Vesta-2 building environment. In particular, it documents the common/std_env/18 and common/cxx/14 packages (presumably, later versions of these packages will conform to this man page as well).
The standard environment defines a collection of hierarchically arranged libraries. The leaves of this hierarchy are called, appropriately, leaf libraries. The non-leaves are called umbrella libraries.
Each package exports a single library, although it is quite possible for a package to export an umbrella library one of whose children is defined in the same package (see the "vesta/basics" package, for example). As a result, there is not a one-to-one correspondence between library packages and libraries. This point is important for understanding the distinction between how library packages are named and how the libraries themselves are named.
In order to make it easy for the client of a library to arrange for it to be built suitably, the system model for a library doesn't actually build the library. Rather, it invokes a bridge function ("leaf or umbrella) that simply records the parts that make up the library. (The parts of a leaf library are header files and source code files; the parts of an umbrella library are the other libraries of which it is composed.) The results of these libraries are called library descriptions, and they correspond to the Vesta-2 type LibDesc and its three subtypes: LeafLibDesc, UmbrellaLibDesc, and PrebuiltLibDesc.
When the client actually uses a particular set of libraries to build a program, the necessary pieces are built. (Of course, in many cases, the Vesta caching machinery makes the build fast.)
Because the construction of libraries is delayed as long as possible, the client can influence the building process. For example, the client can:
- control which libraries are included in an umbrella,
- override the specific versions of libraries used at all levels of the hierarchy, and
- set the compilation switches used when the library is built (e.g., to enable debugging).
For more information about how to build a library with overrides, see the voverrides(5) man page.
As previously described, libraries are arranged in a hierarchy. The leaves of the hierarchy are called leaf libraries, and the internal nodes of the hierarchy are called umbrella libraries.
To override the way a library or some part of a library is built, you must provide a name for the library. There are two styles used for naming libraries: flat and hierarchical. If flat naming is being used, then all library names are assumed to be unique; the hierarchy of umbrellas isn't used to name libraries.
The standard construction environment provides support for both flat and hierarchical library naming. Which naming scheme is used for a particular bridge depends on the value of the "flat_lib_names" bridge option. If that value is true, flat naming is used; if it is false, hierarchical naming is used.
Hierarchical naming is desirable if the number of leaf libraries is so large that there is likely to be a naming conflict, i.e., that two or more leaf libraries will have the same name. That is certainly allowed, but if the library name space were flat, it would be impossible to name a particular leaf library uniquely for overriding purposes. Hence, you can build your program using hierarchical naming, in which cases the overrides specifications are themselves hierarchical. Here are the details.
If flat library naming is used, libraries in a library override are named by a single text corresponding to the the name provided to the "leaf" or "umbrella" call that creates the library. This is the simplest way to name a library, but it requires that all libraries have distinct names. In particular, it does not allow two different leaf libraries in different umbrella libraries to have the same name.
If hierarchical naming is used, library overrides are bindings, and the libraries named by such a binding correspond to paths in that binding. The internal nodes of the override binding are the names of umbrella libraries. For example, if the leaf library "libBasics.a" is part of the umbrella library "libBasicsUmb", which in turn was part of the umbrella library "libVestaUmb", the overrides "ovs" for the leaf would be specified by a binding of the form:
[ libVestaUmb = [ libBasicsUmb = [ libBasics.a = ovs ] ] ];Using hierarchical names, it is possible for a single library override to effect multiple umbrella and leaf libraries. See the type "NamedLibOvs" for more details about the form taken by library overrides.
This page was generated automatically by mtex software.Allan Heydon
Last modified on Fri Nov 9 12:14:21 EST 2001 by ken@xorian.net modified on Thu May 29 14:22:22 PDT 1997 by heydon