KP Template File Format

Introduction

KP template files are used to allow Knowbot Program definitions to be built without including information on a specific instantiation of the KP; specific instantiations can be created by "launching" a template file. These files can currently be launched only by the rs utility.

File Format

A template file is stored as a simple text file consisting of header lines, comments, and blank lines, freely interspersed. Header lines have the form key:value; they follow some of the rules of RFC 822. Headers are categorized into two groups: template headers and KP metadata headers. Tools which use KP template files are free to use information in both header groups, but should only include headers from the metadata group as metadata submitted as part of the KP. Entries from the template group should only be used by tools which handle template files, but the use may include generating KP metadata.

Headers from the template group are distinguished by starting with the string "kp-template--"; headers from the metadata group cannot begin with this string.

The metadata group should be used to generate metadata for the KP as needed, preferably without changing the settings. Some entries of particular interest to tools may be the knowbot-class and main-module headers; the rs tool provides graphical controls which affects the values of these fields. Metadata entries which are not explicitly edited by tools should be passed along unmodified. This may take the form of metadata entries in a KP or headers in the metadata group in a KP template file, or any other appropriate treatment.

Comment lines begin with the hash character ("#", also known as the pound symbol). The comment begins with the hash character and extends to the end of the line. Text in the comment should be ignored and has no semantic meaning for tools which process KP template files. Tools are not required to retain comments, though it is advisable to do so when possible.

Blank lines in KP template files are ignored.

Template Group Headers

Headers with names beginning with the leading string "kp-template--" belong to the template group, and should only be used by tools which use or manipulate KP template files. There are a number of header names which are standardized here, but others may be defined as needed.

Standard Headers

Standard template group headers are defined for a few specific bits of interesting information. These headers begin with the required starting string and have names which do not include the string "--" (two consecutive hyphens). The further use of two consecutive hyphens within the template group is reserved for tool-specific headers.

The specific headers defined in this document are listed below.

kp-template--kernel:

The name of the KOS kernel recommended for the KP being defined. If this is omitted or left blank, the default kernel for submission should be used.

kp-template--modules-base:

Name of the directory from which module file names should be resolved if they cannot be located relative to the location of the template file.

kp-template--modules:

Space-separated list of module names. The ordering of the names is not significant.

kp-template--module-name:

Name of the file which stores the code of the module name, where name is one of the names in the value of the kp-template--modules: header. This allows filenames to be different from module names. The file name given here should be relative to the directory named by kp-template--modules-base: when the template file is saved. The name should be resolved relative to the location of the template file if the file exists, otherwise the name should be attempted relative to the directory named by kp-template--modules-base:.

kp-template--stream-stdin:

kp-template--stream-stderr:

kp-template--stream-stdout:

These three headers correspond to the three traditional I/O streams available to system processes. Each specifies the type of handler which should be set up for the corresponding stream. Each should take a single name as a value. Since different file-like I/O services may be available, the set of names which occur as values may be extended. The following standard names are suggested:

• kos-console -- I/O for the stream should occur on the console of the KOS running the KP at any given time.

• launcher -- I/O for the stream should occur using the default mechanism used by the tool which launched the KP.

• null -- I/O for the stream should be handled by the "null" device (/dev/null under UNIX or NUL under Windows NT).

Tool-Specific Headers

Headers which are specific to a particular tool or set of tools should have the same basic format as the standard headers but with an extension of the required starting string. Each tool or tool set should have a "tool ID" which can be used to form the extension; the tool ID should be one or more hyphen-separated words. The distinguishing starting string for tool-specific headers should be the required starting string followed by the tool ID and two hyphens. For example, if the tool ID is "foo-bar" the tool-specific starting string would be "kp-template--foo-bar--".

Metadata Group Headers

There are no restrictions on the header names used for metadata other than on the use of the string "kp-template--" as the leading portion of the name. The metadata headers may include those with special meaning for the KOE, such as "main-module", with the caveat that tools may explicitly set some or all such special headers directly when appropriate.