The VFL runtime is invoked using the vv command. This command accepts options which effect its execution. They can be provided on the command line using either short form or long form arguments, or in some cases through a rulebook options configuration file.
The short form is a single dash followed by a single letter followed by a space and the commandline argument. The long form is two dashes followed by a keyword followed by an equals sign and the commandline argument. For example, to evaluate the two V language files apache.v and dns.v, the administrator could enter either of these equivalent commands:
$ vv -f apache.v,dns.v
$ vv --files=apache.v,dns.v
Short form and long form options can be intermixed on the same command line.
It is often more convenient to specify commandline options in a rulebook options file and to provide the location of the rulebook on the command line. This is done by specifying the fully qualified filename of the rulebook options file using the "-r" or "--rulebook" option. By convention a file with the name rulebook-options
is normally used. When this convention is followed, the filename itself can be omitted and the "-d" or "--directory" option can be used instead.
Command line options instruct the VFL runtime as to where to find source code files, and whether or not to send output to the syslog or to the console. The effect of these options is described in the following table. The first two of these options can be provided either on the command line or in a rulebook-options file. The others can only be provided on the command line.
C/R = options that can be specified on the command line or in a rulebook.
C = options that can only be specified on the command line.
| short form | long form | C / R | effect |
|---|---|---|---|
| d | directory | C / R | The path to the rulebook options file and the namespace object files. |
| f | files | C / R | A comma separated list {namespace_file1,namespace_file2,...} of filenames within the "--directory" to execute. If not specified, this defaults to all files in the directory, (but filenames starting with # are always ignored.) |
| r | rulebook | C | The name of the rulebook options file, defaults to "rulebook-options"; may be relative to the "--directory" argument or may be a fully qualified filename. |
| h | help | C | Show a brief list of command line options. |
| q | quiet | C | Use quiet mode, and send errors to /log/vermont.log only, not to stdout, (mutually exclusive with "--suppress_log"). |
| t | tabs | C | Create tab separated output format, suitable for grep or awk. |
| v | version | C | Display the current version of the software. |
| x | noexec | C | Parse the source code files, but do not execute them. |
| z | suppress_log | C | Suppress error logging to /log/vermont.log, (mutually exclusive with "--quiet"). |
Rulebook options instruct the VFL runtime in how to evaluate and validate the source code files, and how to report validation status back to the user. The effect of these options is described in the following tables. The first two of these options can be provided either on the command line or in a rulebook-options file. The others can only be provided in a rulebook.
C/R = options that can be specified on the command line or in a rulebook-options file.
R = options that can only be specified in a rulebook-options file.
R/S = options that can be specified in a rulebook-options file or in a source code file on an object-by-object basis.
| option | C/R/S | effect |
|---|---|---|
| directory | C / R | The path to the rulebook options file and the namespace object files. |
| files | C / R | A comma separated list {namespace_file1,namespace_file2,...} of filenames within the "--directory" to execute. If not specified, this defaults to all files in the directory, (but filenames starting with # are always ignored.) |
| module_dir | R | Path to plugin modules, normally /var/vermont/modules. |
| log_file | R | stderr output file, normally /var/vermont/log. |
These options can be used to help with verifying the installation configuration.
| option | C/R/S | effect |
|---|---|---|
| verbose_headers | R | Add a visual line, separating headers between verbose sections; true or false. |
| verbose_configuration | R | List the contents of the rulebook options file with command-line argument overrides; true or false. |
| verbose_modules | R | List all installed modules, as they are discovered during initialization; true or false. |
| verbose_plugins | R | List plugins as they are first autoloaded at runtime; true or false. |
These options can be helpful when debugging object specifications.
| option | C/R/S | effect |
|---|---|---|
| verbose_base_objects | R | Show all objects, as they are initially parsed from files; true or false. |
| verbose_composite_objects | R | Show all composite objects, where object and namespace attributes have been merged; true or false. |
| verbose_substitution_objects | R | Show all objects, where static substitution variables have been replaced with values; true or false. |
| verbose_resource_objects | R | Show all resource objects, where dynamic substitution variables have been replaced with values; true or false. |
| verbose_object_line_numbers | R | Show filenames and line numbers for each parsed attribute of every object; true or false. |
| verbose_dependency_tree | R | Show the object dependency tree; true or false. |
Note that the rulebook-options file uses the same syntax as the V language source code files. In order to distinguish between the two, and in order to prevent the VFL runtime from trying to evaluate and validate the rulebook-options file, the keyword-value "type=null" should be added to the file.
Source code files define objects using keyword-value pairs. Each type of object understands different keyword-value pairs, but all objects understand a basic set of keywords that act as options to influence the runtime's behavior. These options can be specified either in the rulebook-options file or in source code files. When specified in the rulebook-options file, these options become the default setting for all objects. When specified in a source code file, these options are applied on an object-by-object basis, overriding the defaults.
Some of these options are helpful with monitoring the progress of the runtime execution.
| option | C/R/S | effect |
|---|---|---|
| runtime_trace | R/S | true or false. When true, each object's start and stop times are logged to the console. |
| comment | R/S | A text string that, if specified, is displayed as part of all error messages. |
| pass | R/S | A text string, containing replacement variables, that is sent to output for any objects that passes all module tests. The replacement variables may be any module keyword preceded by a dollar sign, or may be the special variables or . |
| fail | R/S | A text string, containing replacement variables, that is sent to output for any object that fails to pass all module tests. |
Briefly describe replacement variables. Show a source code example, show a listing of an object that passed and failed.
These options set whether or not any prerequisites apply.
| option | C/R/S | effect |
|---|---|---|
| dependency | R/S | One or more [namespace:object] specifications, concatenated with '|', that specify objects that must be validated before this object is validated. |
| vocabulary_check | R/S | Should objects be checked against a 'strict' set of allowable keywords, or should 'lax' rules be applied, where only required keyword are checked. |
Show examples of dependency checking for [A] and [N:B] and for multiple dependencies.
Show vocabulary strict failure output
These options control which meta-data is displayed for any objects that are tripped.
| option | C/R/S | effect |
|---|---|---|
| output_line_number | R/S | Show the filename and line number, in <filename+linenum> format, of the trip-point object. |
| output_object_name | R/S | Show the namespace and object name, in [namespace:object] format, of the trip-point object. |
| output_comment | R/S | Show the value of the object's comment keyword, in (comment) format, of the trip-point object. |
| output_method | R/S | Show the module's method and argument, in ->method(argument) format, of the trip-point object. |
| output_limit | R/S | Show no more than this many errors per object. The default value is 10, use 'false' for no limit. |
The VFL runtime will often need superuser access in order carry out many of its operations. For example, traversal of a directory tree and validation of the directory's ownership, permissions, and security contexts will often require the software to be run as root or run using the "sudo" command.