NetBuild Data Model

This file describes the data model used by NetBuild's library metadata and constraint expressions. The data model is still evolving, especially the description of architectures other than ia32. However, we are trying to define it in such a way that it will not need to change much, so as to not invalidate many libraries.

name	description	implementation status
app.*	describes the user's application/code set by: client tested by: library constraint expressions, install scripts	NOT IMPLEMENTED
client.*	describes the client. set by: client tested by: library constraint expressions, install scripts	NOT IMPLEMENTED
client.version	[string] version number of client. set by: client. tested by: library constraint exprs, install scripts.	nbshim: not implemented libs: not used
library.*	[string] describes the library or package. set when library is built (by nc or other procedure) tested by: client, install scripts
library.comment	[string] Any comment about this specific package, or a specific implementation of the library. More specific than, and secondary to, library.description.	libs: supplied by pkg2nb
library.compile.*	Description of the platform/environment used to compile the library, which need not be the same as the platform on which the library is expected to be used. Contrast with library.target.*.
library.compile.cpu.*	CPU used to compile library
library.compile.cpu.arch	[string] architecture of CPU used to compile library (note 2) supplied by: library metadata used by: clients, checkin tools	required by checkin tools, used by nbshim, supplied by all libs
library.compile.os.*	OS used to compile library
library.compile.os.name	[string] name of OS on which library was built supplied by: library metadata used by: clients, check-in tools	required by checkin tools, used by nbshim, supplied by all libs
library.compile.os.release	[string] release of OS used to compile library (note 3) supplied by: library metadata used by: clients Note: should be library.compile.os.version for consistency with other *.os attributes
library.compileargN	[string] argument number N to be added by nb to compile any program that uses this library (for things like include files). If %s appears in the argument it will be replaced by the directory where the library is installed. (note 1)	nbshim: implemented libs: supplied by pkg2nb if the pkg has include files
library.constraint	[string] constraint expression to be evaluated by client (note 4) supplied by: library metadata used by: clients	supplied by several libs, implemented by nbshim
library.data_model_version	[string] version of data model This document describes version "1.0" supplied by: library metadata	required by checkin tools, not currently examined by nbshim
library.description	[string] Description of this package. May be shared across multiple implementations of a package. Contrast with library.comment.	libs: supplied by pkg2nb
library.exported_libnames	[string]list of exported library names, separated by spaces Used when a single package exports multiple libraries. (note 6) supplied by: library metadata intended use: clients	not yet implemented
library.linkargN	[string] linker argument number N to be added by nb to link in library. If %s appears in the argument it will be replaced by the directory where the library is installed. (note 1)	nbshim: implemented: libs: used by several libs
library.name	[string] name of the package. In most cases this will be the same as the name of the library.	not implemented yet.
library.precedence	[string] precedence expression supplied by: library metadata used by: clients	implemented by nbshim, used by several libs
library.tag	[string] Identifier for this specific library/package. This is used for collections maintenance. For instance, a filename for the library may be derived from the tag, a library may be deleted using the tag, and uploading a new library with the same tag as an existing library may cause the existing library to be replaced. supplied by: library metadata used by: install scripts ?
library.target.*	intended target platform characteristics for library
library.target.cpu.*	CPU characteristics of intended target platform
library.target.cpu.arch	[string] architecture name of intended target platform supplied by: library metadata used by: clients
library.target.os.*	OS of intended target platform. Note that unlike library.compile.os.version, there is no library.target.os.version attribute currently defined. This is because we can readily determine the version of the compile platform, but we cannot reliably determine whether a particular library will run on a version of a target platform. If it is known that a particular library is sensitive to the version of the target platform, this can be included in library.constraint
library.target.os.name	[string] OS name of intended target platform referenced by: library metadata, nb/netfind.c
library.target.os.version	[string] OS version of intended target platform referenced by: library metadata, nb/netfind.c
link.*	describes the platform on which the app is being linked. set by: client tested by: library constraint expressions, install scripts	NOT IMPLEMENTED
link.uname.*	results of uname() call on link platform	NOT IMPLEMENTED
link.uname.machine	[string] uname.machine from link platform	NOT IMPLEMENTED
link.uname.nodename	[string] uname.nodename from link platform	NOT IMPLEMENTED
link.uname.release	[string] uname.release from link platform (note 3)	NOT IMPLEMENTED
link.uname.sysname	[string] uname.sysname from link platform	NOT IMPLEMENTED
link.uname.version	[string] uname.version from link platform	NOT IMPLEMENTED
target.*	describes the platform being compiled for. set by: client tested by: library constraint expressions, install scripts
target.cpu.*	characteristics of the target cpu
target.cpu.arch	[string] Target platform CPU architecture. (note 2)
target.cpu.ia32.*	characteristics of IA32 family cpus
target.cpu.ia32.3dnow	[integer] nonzero iff 3DNow! is supported by target platform
target.cpu.ia32.3dnowext	[integer] nonzero iff extended 3DNow! is supported by target platform
target.cpu.ia32.family	[integer] IA32 family (from the CPUID instruction)
target.cpu.ia32.l1.*	IA32 L1 cache attributes
target.cpu.ia32.l2.*	IA32 L2 cache attributes
target.cpu.ia32.l3.*	IA32 L3 cache attributes
target.cpu.ia32.l*.dcache	IA32 L* data cache attributes
target.cpu.ia32.l*.icache	IA32 L* instruction cache attributes
target.cpu.ia32.l*.*cache.linesize	[integer] line size of that particular cache (note 5)
target.cpu.ia32.l*.*cache.size	[integer] size (bytes) of that cache (note 5)
target.cpu.ia32.l*.*cache.way	[integer] associativity of that cache (note 5)
target.cpu.ia32.mmx	[integer] 1 iff MMX is supported on target platform
target.cpu.ia32.model	[integer] IA32 model from CPUID instruction
target.cpu.ia32.l*.nocache	[integer] 1 iff that cache does not exist (note 5)
target.cpu.ia32.product	[string] IA32 CPUID product string (if it exists)
target.cpu.ia32.sse	[integer] 1 iff SSE is supported on target platform (both CPU and OS support are required for this to be set)
target.cpu.ia32.sse2	[integer] 1 iff SSE2 is supported on target platform (both CPU and OS support are required for this to be set)
target.cpu.ia32.vendor	[string] IA32 vendor string from CPUID instruction e.g. "GenuineIntel" or "AuthenticAMD"
target.cpu.powerpc.*	characteristics of POWER* CPUs (not strictly limited to PowerPCs)
target.cpu.powerpc.model	[string] CPU model. Valid types include: ppc601, ppc602, ppc603, ppc603e, ppc603ev, ppc604, ppc604e, ppc620, ppc750, ppc7400, and ppc7450. Numerous other models (not starting with "ppc") are used by IBM on AIX systems. For the ppc* model names we try to keep the names consistent between the various operating systems for ease of building libraries. For other POWER CPUs the consistency doesn't matter as much, because we'll probably only see these on AIX.	On MacOS X this is currently obtained from NXGetLocalArchInfo(), on AIX it is obtained from _system_configuration.implementation. Untested on AIX.
target.cpu.powerpc.altivec	[integer] 1 if CPU and OS support AltiVec, else 0	Implemented by trying AltiVec instructions and testing for machine exceptions. Incompletely tested on MacOS X, untested on AIX.
target.ncpu	[integer] Number of PEs on the target platform. NOTE: libraries shouldn't expect to be able to use all PEs at once unless the user has specifically requested this, since the user might have intended to allocate some CPUs for other tasks.	On AIX, uses _system_configuration.ncpus, on MacOS X, uses sysctlbyname("hw.ncpu",...)
target.os.*	Characteristics of the target OS
target.os.name	Name of the target OS.
target.os.version	Version # of the target OS.
target.sysctl.*	Selected sysctl() parameters	NOT IMPLEMENTED

Notes:

1.	For library.compileargN and library.linkargN to work, N must start at 0 and use consecutive integers following 0.
2.	Currently-defined CPU architecture names include ia32, alpha, powerpc, and sparc. For ease in maintenance of libraries, an attempt will be made to keep CPU names consistent between different operating systems. An effort is also made to use the same name for all processors with a (more-or-less) common instruction set, especially if it is generally expected that executables can be written for a common subset of those instructions and run on any processor within the family. Tentatively we are lumping all POWER* processors in the powerpc category even though this is not consistent with the way IBM names processors in this series, and the instruction sets of all POWER* aren't quite compatible. Similarly, we are lumping all sun4* as sparc, even though there are sun4s that aren't SPARCs.
3.	An attempt is made to describe IA32 cache sizes in a uniform fashion, even though Intel and AMD report these differently. There is currently no support for querying the cache sizes of other IA32 vendors' CPUs.
4.	NetBuild constraint expressions use a subset of the C exprssion syntax. The following operators are supported: unary minus, logical negation (!), ones complement (~), binary multiply, divide, modulus, addition, subtraction, left and right shifts, bitwise AND (&), bitwise OR (|), bitwise XOR (^), logical AND (&&), logical OR (||), relational ops (<, >, <=, >=, ==, !=), and the conditional expression operator ? :. Precedence for these operations is as in C. Identifiers are of the form [A-Za-z][A-Za-z0-9._$]*. Data types currently supported are integer, string, and error. Most operations result in error if any of their operands are of type error. This way, an error evaluating any part of an expression generally results in the entire expression having a type of error. There is no assurance of short circuit evaluation for &&, ||, or ? =, but expressions (including function calls) do not have side-effects. Syntactically, function calls may have a variable number of arguments, but any function can check its argument list and return an error if the number or types of arguments are inappropriate. Functions return a single result. Currently supported functions include Function Description error(e) Return 1 if the expression e results in an error; otherwise return 0. have_file(s1[,s2]) Return 1 if the file named s1 satisfies each of the criteria specified in s2, else return 0. If s2 is missing, check only for the existence of the file. Otherwise check each of the criteria specified by the inclusion of letters s2: r checks whether the file is readable by the netbuild user; w checks whether the file is writable; x checks whether the file is executable have_library(s1) return 1 if the library named s1 is "natively installed" on the link target. version_compare(s1,s2) Compare s1 and s2 treating them as version numbers. Return > 0 if s1 > s2; < 0 if s1 < s2; 0 if s1 and s2 are equal. A typical constraint expression might be: cpu.ncpu>1&&cpu.ia32.vendor=="GenuineIntel"&&cpu.ia32.family==6&&cpu.ia32.sse==1&&cpu.ia32.l2.dcache.size>=256*1024
5.	Occasionally NetBuild needs to compare version numbers - of operating systems, compilers, whatever. NetBuild expects version numbers to be of the form ([0-9]+".")*[0-9]+ that is, sequences of 1 or more digits separated by "."s. There is an implicit "." at the end. The portion to the left of the leftmost "." is called the major version; the remainder is the minor version. The version_compare operation works as follows: If the major version numbers are unequal, the version with the higher numbered major version is greater, Else, if only one of the versions has a minor version, the one with the minor version is greater, Else, the version_compare operation is invoked recursively on the two minor versions. When necessary, NetBuild tools coerce version numbers so that this comparison function does the right thing. So NetBuild's idea of an operating system's version number might be slightly different than the one supplied by the operating system.
6.	This is confusing because the top-level name library. can contain more than one library file, which might or might not all be linked into a program. At the time this version of the data model was designed it was not realized that a single package might need to export multiple libraries. library.* should probably be renamed to package.* in the next revision of this data model.