vtypes(5)

Name

vtypes - a guide to Vesta-2 types used in the standard models

Contents

Introduction

This man page documents the Vesta-2 types used in the standard environment and bridge models included with the Vesta-2 system. 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).

Index

Here are the types documented in this man page:

B
Bridge, BridgeExpert, BridgeGenerics, BridgeOptions, BridgeOvs, BridgeSwitches BuiltLibs
C
CompileOvs
D
DerivedFiles
E
Env, EnvOvs
L
LeafLibDesc, LibDesc, LibFunc, LibFuncs, LibPkgResult, LibPkgResults
N
NamedCompileOvs, NamedFile, NamedFiles, NamedLibDesc, NamedLibDescs, NamedLibOvs, NamedLibPkgResults, NamedPkgOvs, NamedPkgs
P
PkgFunc, PkgModel, PkgResult, PrebuiltLibDesc
Q
QNamedLibPkgResults, QNamedPkgOvs, QNamedPkgs,
T
ToolSwitches
U
UmbrellaLibDesc

Files and Packages

type NamedFile = binding(:text);
type NamedFiles = binding(:text);
A value of type "NamesFiles" is a binding containing pairs of the form "[ name = <File> ]", where "<File>" denotes to the contents of a file in the file system. A value of type "NamedFile" is always a singleton binding.

type DerivedFiles = binding(
  objects: NamedFiles, // derived object files (required)
  others: NamedFiles   // other derived files (optional)
);
A value of type "DerivedFiles" contains derived object files (to be linked against) and other derived files to be installed in the working directory at link time. For example, the Modula-3 compiler produces "link info" (.ix, .mx) files in addition to object files. Only the object files must be named on the link line, but the link info files must be in the current directory for the link to succeed.

type PkgModel = function();
The type "PkgModel" corresponds to the top-level "build.ves" model of a package. It is a function of no arguments (not counting the implicit argument ".").

type NamedPkgs = binding(:PkgModel);
The type "NamedPkgs" is a binding mapping package names to their corresponding top-level models (of type "PkgModel"). These are unqualified package names, as opposed to the qualified package names of the "QNamedPkgs" type below.

type QNamedPkgs = binding(:NamedPkgs);
The Vesta repository uses a 2-level name space for package names. The base package name is qualified by the name of the repository directory in which it appears. Examples of qualified package names are "vesta/basics" and "common/std_env". A value of type "QNamedPkgs" corresponds to a set of qualified named package models.

Package Results

type PkgFunc = function(env: binding);
A "PkgFunc" is a closure for building part of a package. Examples are closures for building the lib, progs, and tests of a package.

type PkgResult = binding;
A general package's "build.ves" model evaluates to a value of type "PkgResult". Most of the names in a PkgResult are mapped to functions of type "PkgFunc", but there is no requirement that all names in a PkgResult are mapped to such values.

type LibPkgResult = /* PkgResult */ binding(
  lib: LibFunc // a specialization of PkgFunc; defined below
  // other fields may be defined as well, such as "progs" and "tests"
);
A library package's "build.ves" model evaluates to a value of type "LibPkgResult". The "lib" field is a value of type "LibFunc", which is a function for building a named leaf or umbrella library description.

type UmbrellaPkgResult = /* LibPkgResult */ binding(
  children: QNamedPkgs
);
The model of a library package that builds an umbrella library evaluates to a value of type "UmbrellaPkgResult"; the "children" field evaluates to a value of type "QNamedPkgs", which are the packages that build the umbrella's child libraries.

type LibPkgResults = list(LibPkgResult);
Collections of libraries are represented by values of type "LibPkgResults". For example, the "libs" field of an "UmbrellaLibDesc" is of this type.

type NamedLibPkgResults = binding(:LibPkgResult);
type QNamedLibPkgResults = binding(:NamedLibPkgResults);
Collections of named library packages are represented by values of type "QNamedLibPkgResults". For example, the "libs" field of a "Bridge" is of this type. Like the "QNamedPkgs" type described above, a "QNamedLibPkgResults" is a two-level tree whose domain parallels the names of packages in the Vesta repository.

Library Descriptions

type LibDesc = binding(lib_type_: text);
Libraries are described by a binding structure of type "LibDesc" that contains at least the text field "lib_type_", which is one of the three values "leaf", "umbrella", or "prebuilt". The first corresponds to a leaf library, the second to a library composed of other libraries, and the third to a library that is treated as a source file. Depending on the type of the library, the binding contains other fields describing how it is built. See the types "LeafLibDesc", "UmbrellaLibDesc", and "PrebuiltLibDesc". The field name "lib_type_" ends with an underscore because it is meant to be neither read nor written by clients.

type LeafLibDesc = /* LibDesc */ binding(
  lib_type_: text,              // == "leaf"
  headers: NamedFiles,
  priv_headers: NamedFiles,
  code: NamedFiles,
  ovs: EnvOvs,                  // general override for "code" files
  per_file_ovs: NamedCompileOvs // named override for "code" files
);
A "LeafLibDesc" is a logical subtype of a "LibDesc". It describes a leaf library, and is produced by the bridge's "leaf" function. The "ovs" and "per_file_ovs" fields are optional. The "ovs" field is a general override that is recursively overlaid on the environment "." before the "code" files are compiled. The "per_file_ovs" is a named override that is consulted as each of the files named in the "code" field is compiled.

type UmbrellaLibDesc = /* LibDesc */ binding(
  lib_type_: text,     // == "umbrella"
  libs: LibPkgResults, // nested libraries (umbrellas or leaves)
  flatten: bool,       // flatten archive?
  ovs: EnvOvs          // general override for building nested libs
);
An "UmbrellaLibDesc" is a logical subtype of a "LibDesc". It describes an umbrella library, that is, a library comprised (and containing) other libraries. The "libs" field contains a list of "LibPkgResult" values, one for each library in the umbrella, in the order in which the libraries should be listed on the link line.

The "flatten" field controls how the archive for the umbrella is formed. If "flatten" is true, then the umbrella's libraries are exploded into object files, and the objects are then combined into a single archive. If "flatten" is false, the libraries remain separate; the names given to the libraries will be hierarchical iff the bridge's flat_lib_names option is false.

The "ovs" field is a general override that is recursively overlaid on the environment "." before the nested libraries are compiled.

type PrebuiltLibDesc = /* LibDesc */ binding(
    lib_type_: text,          // == "prebuilt"
    headers: NamedFiles,      // exported header files
    libs: NamedFiles          // the library archives
);
A "PrebuiltLibDesc" is a logical subtype of a "LibDesc". It describes a prebuilt library, i.e., one in which the library archive is treated as source. The "headers" field contains exported header files, and the "libs" field contains the library archives themselves.

type NamedLibDesc = binding(:LibDesc);
type NamedLibDescs = binding(:LibDesc);
A value of type "NamedLibDescs" is a binding containing pairs of the form "[ name = LibDesc ]". It is a collection of named library descriptions. A value of type "NamedLibDesc" is always a singleton binding.

type LibFunc = function(env: binding): NamedLibDesc;
A value of type "LibFunc" builds a library; it evaluates to a value of type "NamedLibDesc".

type LibFuncs = list[LibFunc];
A list of "LibFunc" values obtained by selecting the "lib" fields from a value of type "LibPkgResults".

type BuiltLibs = binding[
    libs: NamedFiles,
    pub_code: binding,   // exported source code
    sources: binding,    // optional
    objects: binding     // optional
];
The result of building a value of type "LibPkgResults" is a binding that stores all libraries built so far and the public code they export (e.g., header files). The result may optionally contain fields named "sources" and "objects", depending on whether the bridge's options are set to return the sources contributing to a build and their corresponding intermediate object files.

Overrides

type NamedPkgOvs = binding(:PkgModel);
A value of type "NamedPkgOvs" is a binding mapping package names to their corresponding package models (which are typically imported via an "include" clause in a top-level model).

type QNamedPkgOvs = binding(:NamedPkgOvs);
Package overrides are specified using qualified package names, similar to the "QNamedPkgs" type described above. A value of this type is used to specify how various packages are overridden when the standard environment is constructed.

type BridgeOvs = binding;
A value of type "BridgeOvs" is a binding that is recursively overlaid on some bridge of the current environment. It is generally of type "Bridge", except that it is not required to have all the fields of that type.

type CompileOvs = binding(
  lang: text,     // optional bridge name
  ovs: BridgeOvs  // bridge-specific overrides
);
The type "CompileOvs" specifies compiler overrides for a specific bridge. It is associated with named files (see "NamedCompileOvs" below). If the "lang" field is present, it specifies which bridge the file should be compiled with; it defaults to the bridge associated with the file's extension. The "ovs" field is a binding that is recursively overlayed on the selected bridge of the current environment before the compiler is invoked.

type NamedCompileOvs = binding(:CompileOvs);
A value of type "NamedCompileOvs" is a binding containing pairs of the form "[ filename = compile_ovs ]", where the "compile_ovs" value is of type CompileOvs and specifies overrides to be used when compiling the file named "filename" as described above.

type NamedLibOvs = binding;
A value of type "NamedLibOvs" represents a value used to override which libraries a program is linked against. There are two kinds of "NamedLibOvs" values, depending on whether flat or hierarchical library names are being used for this bridge (as determined by the bridge's flat_lib_names option).

If flat library names are being used, the value will be of type "NamedLibDescs", that is, it will be a binding that maps library names to "LibDesc" bindings. This "LibDesc" is overlayed (but not recursively so) over the "LibDesc" of the corresponding library in the libraries being linked against. Which fields the overriding binding contains depends on whether the library being overridden is a leaf (LeafLibDesc), umbrella (UmbrellaLibDesc), or prebuilt (PrebuiltLibDesc) library.

If hierarchical names are being used, the value will be a binding whose "leaves" are "NamedLibDescs" values and some of whose internal nodes may contain a "NamedLibDesc" value as well. A "NamedLibDesc" is recognized at an internal node by the appearence of the "lib_type_" or "ovs" field in all cases, or by the appearence of the "per_file_ovs" field in the case of a leaf library. As above, when a "NamedLibDesc" is recognized, it is overlayed (again, not recursively so) on the "LibDesc" of the corresponding library in the list of libraries being linked against.

type EnvOvs = binding;
A value of type "EnvOvs" is a binding overlayed over some top-level environment of type "Env".

Bridges

type BridgeExpert = binding(
  compile: function,         // compile a single module
  link_leaf: function,       // link a leaf library
  link_umbrella: function,   // link an umbrella library
  link_program: function     // link an executable program
);
A value of type "BridgeExpert" defines the four low-level bridge functions for compiling and linking.

type ToolSwitches = binding(:text);
A value of type "ToolSwitches" defines command-line switches for one of the low-level "BridgeExpert" functions. It maps abstract switch names (like "debug" and "optimize") to the text of an actual switch as it should appear in the tool's command-line. Only the values of a "ToolSwitches" binding are significant; the names are just used for overrides purposes.

type BridgeSwitches = binding(
  compile: ToolSwitches,  // defaults for 'compile' tool
  leaf: ToolSwitches,     // defaults for 'link_leaf' tool
  umbrella: ToolSwitches, // defaults for 'link_umbrella' tool
  program: ToolSwitches   // defaults for 'link_program' tool
);
A value of type "BridgeSwitches" defines the default command-line switches for the low-level "BridgeExpert" functions used by a particular "Bridge". It may be overridden to invoke each tool with different command-line switches.

type BridgeOptions = binding(
  flat_lib_names: bool,   // use hierachical library naming iff false
  useGClib: text          // name of gc library (or "no" for none)
);
A value of type "BridgeOptions" defines a set of general options that pertain to a particular bridge. The values of these options are used by user models and by the low-level "BridgeExpert" functions.

type Bridge = binding(
  libs: QNamedLibPkgResults, // named per-bridge library models
  program: function,         // builds an executable
  leaf: function,            // defines a leaf library
  umbrella: function,        // defines a non-leaf library
  prebuilt: function,        // defines a pre-built library
  expert: BridgeExpert,      // low-level functions; can be overridden
  switches: BridgeSwitches,  // default switches for "expert" functions
  options: BridgeOptions     // default options for "expert" functions
);
A value of type "Bridge" provides an interface to a collection of language-specific tools, called a bridge. The "libs" field contains a binding of libraries built for this bridge; the binding is typically installed by the function that constructs the standard environment.

Each bridge exports the "program", "leaf", "umbrella", and "prebuilt" functions for building programs and the three kinds of libraries. The "expert" field hides a binding of expert functions used to implement the bridge.

The "switches" field is a binding of command-line switches for the bridge's tools. The "options" field is a binding of options that control how programs are built with this bridge.

Generic Bridge Functions

type BridgeGenerics = binding(
  base_name: function,         // base name of a file name
  extension: function,         // extension of a file name
  binding_names: function,     // return list of names in a binding
  binding_values: function,    // return list of values in a binding
  reverse_list: function,      // reverse a list value
  reverse_binding: function,   // reverse a binding value
  eval_binding_vals: function, // evaluate values of a binding
  compile: function,           // compile list of sources, various langs
  bridge_map: binding          // maps file extensions -> bridge names
    // for example [ c = "C", C = "Cxx", i3 = "M3", m3 = "M3" ]
);
A value of type "BridgeGenerics" defines various generic functions for use by bridge implementations. See the "common/bridge_generic" package for details. This type should not be of interest to most general users.

Environments

type Env = binding(
  target_platform: text,   // name of target platform (a platform name)
  root: binding,           // file system for bridge tools
  envVars: binding,        // environment variables
  generic: BridgeGenerics, // generic functions
  C: Bridge,               // C bridge
  Cxx: Bridge,             // C++ bridge
  M3: Bridge,              // Modula-3 bridge
  lib_ovs: NamedLibOvs,    // library override definitions
  env_ovs: EnvOvs,         // environment override definitions
  env_for_bridges: Env,    // environment used to build bridges
  temp: binding(           // temporary files
    includes: NamedFiles,  // header files during C compilations
    libs: NamedFiles       // library archives
  )
);
A value of type "Env" corresponds to an environment, typically bound to the name "." (dot). A value of this type is usually constructed using the standard environment model, and then augmented.

See Also

vlibraries(5), vmodels(5), voverrides(5).

Author

Allan Heydon 

Last modified on Fri Nov  9 12:14:21 EST 2001 by ken@xorian.net
     modified on Mon Feb 22 16:43:04 PST 1999 by heydon
This page was generated automatically by mtex software.