vesta(1)

Name

vesta - Evaluate a Vesta system model

Synopsis

vesta [ options ... ] [ modelfile ]

Contents

Description

vesta is the Vesta evaluator. It evaluates the model in modelfile. If no modelfile is specified, a default filename is taken from the Vesta configuration file. If modelfile names a directory, the evaluator appends the default filename. The .ves extension can be omitted in modelfile.

See the vesta-intro man page's Terminology section for definitions of terms, and its Name Interpretation section for an explanation of how model names given on the command line are looked up.

Options

All options marked with *toggleable* have both a positive and a negative form. The negative form is the positive form with "no-" prepended to it. A few examples: -k/-no-k, -CLEAN/-no-CLEAN

Shipping Options

The following options can be used to ship derived files to a regular file system. By default, no derived files are shipped.

-shipto pathname
Ship the evaluation result to the directory specified by pathname, appending a log of the items shipped to the file pathname/.log. The -shipto flag must be specified if any of the -shipfrom, -s, -clean, and/or -CLEAN flags are present.

The specified pathname may be a file (rather than a directory) if the -shipfrom flag is given and specifies exactly one value of type text. In this case the specified value is shipped to the given file, and the .log file is not written.

-shipfrom pathname
Specify the component in the evaluation result to be shipped. By default, the complete evaluation result is shipped to the directory specified by the -shipto switch.

-s *toggleable*
Ship the evaluation result by symbolic links. By default, the evaluation result is shipped by copying. Note: these symbolic links point to derived files that are not protected from deletion by VestaWeed. Use this form of shipping with caution.

-clean *toggleable*
Remove the old contents of the "shipto" directory (including subdirectories and the .log file) before shipping into it. If the directory is nonempty, it must contain a .log file; this feature is meant to protect against inadvertently cleaning out the wrong directory in the event of a typo. If this flag is not given, the shipped value is merged with the existing contents of the "shipto" directory.

-CLEAN *toggleable*
Same as -clean, except that the directory is always cleaned, regardless of whether a .log file exists in it.

-hushship *toggleable*
Only prints that the evaulator has started and finished shipping instead of printing that it's shipping each file.

Evaluation Options

-result *toggleable*
Print out the result of the evaluation.

-maxthreads n
Set the maximum number of threads that can be run in parallel by all invocations of the _par_map primitive to n. Roughly speaking, this is the number of tool invocations (e.g., compilations) that can be run in parallel. The default is set in the Vesta configuration file; see below.

-k *toggleable*
When specified, keep evaluating even when the tool fails in a primitive run_tool call. Any other kind of run-time error (such as selecting a non-existent field of a binding) is considered fatal, and terminates the evaluation.

-parse *toggleable*
Parse the model only; do not evaluate the model. Yes, the negative version does both parse and execute in spite of being -no-parse.

-version *toggleable*
Print the evaluator's version number.

Debugging Options

The following options cause the evaluator to print various sorts of debugging information.

-stack *toggleable*
Print the function call stack when a runtime error occurs. This is useful for debugging Vesta evaluation errors.

-trace *toggleable*
Turn on trace mode. At the end of the evaluation, print the function call graph for the current evaluation to the standard output. This is useful for debugging the caching behavior of Vesta builds.

-fsdeps *toggleable*
Print file system dependencies to the standard error output. Whenever an external tool touches a file in the file system, the name of that file is printed. This is useful for debugging the case when an external tool fails because the environment in which it was run does not contain enough files.

-evalcalls *toggleable*
Print to the standard error output all requests made by the repository in response to file system references by an external tool. The output generated by this switch is a superset of that generated by the -fsdeps switch.

-ps *toggleable*
Print the current evaluator process status right before it exits.

Caching Options

The following options control caching behavior.

-cache level
Specify the caching level. There are four different caching levels: none means not to use the Vesta cache; runtool means to cache runtool calls only; model means to cache runtool and model calls only; all means to cache all cacheable function calls. When the caching level is model or all, precise fine grained dependency analysis is enabled. The default caching level is all.

-noaddentry *toggleable*
Prevent any new cache entry from being added to the cache. This option is useful when one wants to reproduce repeatedly the same behavior of an evaluation in the presence of a Vesta cache. Note that this option is different from "-cache none" because the evaluator can get hits on existing cache entries when this option is used. This has two negative versions: -no-noaddentry and -addentry.

-cstats *toggleable*
Print cache statistics after the evaluation.

-cdebug level
Print cache debugging information. The relevant options (in increasing order of verbosity) are: None (the default), AddEntryOp, OtherOps, and All. See VCache(1) for more details.

Recognized Pragmas

The evaluator recognizes two stylized comments, or pragmas, which can be used to control how it caches calls of user-defined functions. The two pragmas are /**nocache**/ and /**pk**/. We expect that these pragmas will be required only in bridge models, not typical client models.

When a user-defined function is called, the evaluator first looks to see if that function has already been evaluated with sufficiently similar arguments. If so, it gets a hit in the cache and uses the function result returned by the cache. Otherwise, it evaluates the called function and adds an entry to the cache for the result.

To do a cache lookup, the evaluator provides a cache key. The cache key is actually composed of two parts: the run-time values on which the function result is thought to depend, which together comprise the primary key, and the run-time values on which the function result may depend, which together comprise the secondary key.

By default, calls of all user-defined functions are cached. If the /**nocache**/ pragma appears immediately before a function definition, calls of that function are not cached. The /**nocache**/ pragma can be used if the work performed by the function is trivial and if the number of calls made by the function is known or expected to be small (preferably 0 or 1).

By default, the primary key is a combination of the closure value (i.e., the function) being called and the values of all actual arguments that are not composite values (i.e., not of type list, binding, or closure). If the /**pk**/ pragma appears immediately before the name of a function's formal parameter, the value of the corresponding actual parameter is also folded into the function's primary key, regardless of whether it is a composite value or not. The /**pk**/ pragma can be used to include a composite value into the function's primary key when the function's result is known to depend on the entire composite value.

Configuration Variables

The evaluator reads site-specific configuration information from a Vesta configuration file named vesta.cfg.

The following values are obtained from the [Evaluator] section of the Vesta configuration file:

DefaultMain
Gives one or more default model names to evaluate if none is explicitly specified. Multiple names are given separated by whitesapce, and are tried in order. (For example, if set to "linux_alpha.main.ves linux_ia32.main.ves .main.ves", if a model named "linux_alpha.main.ves" exists it will be evaluated, or if not and a model named "linux_ia32.main.ves" exists it will be evaluated, otherwise if a model named ".main.ves" exists it will be evaluated.) If not set, ".main.ves" is used.

Switches
Specifies evaluator command line switches that will be used on every run. These switches are overridden by any explicit switches used on the evaluator command line.

MaxThreads
Gives the default value for the -maxthreads option; see above.

FpContent
Newly created derived files that are strictly less than FpContent bytes long are fingerprinted deterministically according to their contents. Longer files are fingerprinted with arbitrary unique identifiers. The cost of fingerprinting a file's contents is non-trivial, but doing so allows for cache hits in cases where two evaluations depend on files that have identical contents but were created in separate evaluations. The special value -1 causes all files to be fingerprinted by contents, while 0 causes all files to be fingerprinted by unique identifier. (See the documentation for the _run_tool primitive function for more information.)

server_max_threads
A tuning parameter which controls the number of file access callbacks from the repository simultaneously served during a tool invocation. A reasonable value is 4. There's normally no need to change it. (Note that there is no built-in default value.)

server_max_pending
A tuning parameter which controls the number of file access callbacks from the repository held pending while serving other requests. This can be set to a fixed integer, but if the evaluator submits more tool invocations than server_max_threads+server_max_pending, an evaluation failure is likely. If set to "auto", the value used is based on the maximum number of expected requests: either [Repository]threads or the number of evaluator threads (from MaxThreads or the -maxthreads switch if used), whichever is higher, minus server_max_threads. Defaults to "auto".

NegligibleExternalLoadPerCPU
A tuning parameter which controls how hosts are selected for _run_tool() jobs. It is a scaling factor that is multiplied by the number of CPUs in the candidate Run Tool Host. If the load average is below the result of this multiplication and the RunToolServer is running no other jobs, the host is immediately chosen to run the tool invocation. (If not, it may still be chosen later if it's the least loaded candidate host.) If not set, it defaults to 0.75.

The following values are obtained from the [CacheServer] section of the Vesta configuration file:

MetaDataRoot
See VCache(1).

Host
See ChkptCache(1).

The following values are obtained from the [Repository] section of the Vesta configuration file:

metadata_root
umask
See repository(8).

The following values are obtained from the [Run_Tool] section of the Vesta configuration file:

SRPC_port
The default port at which to contact the RunToolServer. (See the next section.)

get_info_read_timeout
Maximum number of seconds that the evaluator will wait for a response from a RunToolServer when getting information about its configuration (OS, architecture, etc.) and number of allowed and currently running tools. This allows the evaluator to give up and move on to another candidate host if one is very slow in responding. Defaults to 120 seconds (2 minutes). (Note that this timeout only applies after a connection is established, and is only provided to guard against misbehaving or overloaded peers.)

See also the next section.

Runtool Host Selection

When the _run_tool primitive is invoked to run an external tool, the evaluator must choose a specific host machine to run the tool on. To do so, it first looks up the platform argument in a correspondingly named section of the Vesta configuration file, [platform]. This section describes the platform type by giving a list of characteristics that a host machine of this type must have, and it includes a list of candidate hosts to try. The evaluator searches the list for a host that matches the description and is not too heavily loaded. The following names must be defined in a platform section:

sysname
Specifies the name of the operating system, as returned by the uname(2) system call in the sysname field. The given value can be a glob(3) pattern (a pattern using *, ?, and [] characters as in shell filename matching). Typical values are "OSF1" for Tru64 Unix, or "Linux" for Linux.

release
The release of the operating system, as returned by the uname(2) system call in the release field. This value can be a glob(3) pattern. Typical values are "V[45].0" to match either Tru64 Unix 4.0 or 5.0, or "2.2.*" to match any 2.2-series Linux kernel.

version
The minor version number of the operating system, as returned by the uname(2) system call in the version field. This value can be a glob(3) pattern. Typically "*" is used in this field, as the OS minor version number is not usually significant in choosing a machine to run tools on.

machine
The type of processor, as returned by the uname(2) system call in the version field. This value can be a glob(3) pattern. Typical values are "alpha" to select an Alpha processor, or "i?86" to select an Intel x86 processor.

cpus
The minimum number of CPUs present. Use 1 if a uniprocessor is acceptable.

cpuMHz
The minimum CPU clock speed, in megahertz. Typically set to 0, but you can specify a larger number if only machines of at least a certain speed are acceptable.

memKB
The minimum number of kilobytes of physical memory. Typically set to 0, but you can specify a larger number if only machines with at least a certain amount of memory are acceptable.

hosts
A list of candidate hosts to try, separated by spaces. Hosts are specified as either hostname, or hostname:port. If the port is not specified, it defaults to the standard RunToolServer port, given in section [Run_Tool], value SRPC_port. There must be a RunToolServer(1) at the given port on each host; if not, the evaluator prints a warning and drops the host from the list. The evaluator also prints a warning if a host on the list does not match the platform description.

If the first hostname is the string "localhost", the local host will always be considered first. If the string "localhost" appears elsewhere in the list, the local host will be considered but not given any special preference. If the string "localhost" does not appear, the local host will be used only if its name appears explicitly. If the same host appears twice (in particular, if it appears both as "localhost" and under its own name), the duplicates are eliminated.

By convention, the following target platform names are normally used:

DU4.0
An Alpha machine running version 4.0x of the Digital Unix (aka Compaq/HP Tru64 Unix) operating system

Linux2.4-alpha
An Alpha machine running version 2.4.x of the Linux kernel

Linux2.4-i386
An Intel 386 or higher running version 2.4.x of the Linux kernel

Linux2.4-i686
An Intel 686 or higher running version 2.4.x of the Linux kernel

Linux2.4-ppc
A PowerPC running version 2.4.x of the Linux kernel

Linux2.4-sparc
A Sparc running version 2.4.x of the Linux kernel

Environment Variables

If set, the DEBUG_TOOL_DIR_SERVER environment variable can be used for debugging purposes. It causes the evalutor to display extra information that can be helpful in intercepting and understanding the traffic between the evaluator and the repository. There are two kinds of information printed when this environment variable is set:

See Also

vmake(1), repos-ui(1), VCache(1), repository(8), RunToolServer(1), vesta.cfg(5)

Author

Yuan Yu and Jim Horning 

Last modified on Tue Oct 28 14:01:48 EST 2003 by ken@xorian.net   
     modified on Thu Jan  4 15:45:29 PST 2001 by mann   
     modified on Wed Nov 15 13:16:19 PST 2000 by yuanyu 
     modified on Mon Jun  1 15:18:16 PDT 1998 by heydon
This page was generated automatically by mtex software.