A configuration file and zero or more fragments are merged to form a new configuration file in the following way.

First, a copy of the selected configuration file is created, and then the currently in-use Vrui root section (e.g., /Vrui/Desktop or /Vrui/<hostname>) is renamed to /Vrui/* and all other sections are eliminated.

Note: The special section named * is used by the VruiConfig system to denote the section to be used; it's name is replaced with the hostname (by VruiConfigDriver) just prior to actual use so that Vrui will be sure to use that section.

Then, the chosen configuration fragments are merged into the configuration file to produce the resultant configuration. The original configuration file (as well as the fragments) may additionally define a top-level VruiCommandOptions tag; see below for details.

Configuration fragments are Vrui configuration files that define some small aspect of an overall configuration. They must confine their definitions to the special /Vrui/* section of the file except for the following two optional top-level (i.e., not within any section) tags:

• VruiCommandOptions (under development) The value will be merged with the other VruiCommandOptions values from other configuration files and fragments, and then will be passed on the command line to programs using the resulting configuration file. Example:

  VruiCommandOptions -vislet VncVislet hostname localhost \;

• VruiConfigurationFragmentType The value specifies the type of fragment. This tag name must be followed by an empty string (indicating that the file is not a fragment but a full configuration file), or it must be followed by one of:
  • Vislet
  • Tool
  • Device

Fragments are merged into a resultant configuration file according the following rules:

• Empty or No VruiConfigurationFragmentType - This is actually a full configuration file, not just a fragment. Within each section (including the outermost, unnamed section), tags from from the fragment overwrite same-named tags in the result, and tags from the fragment that do not exist in the result are added. Sections are merged by name recursively.

• VruiConfigurationFragmentType Vislet - This fragment is merged the same as a full configuration file (above), except that the following String Lists are merged using the Indirected Merging Rules:
  • /Vrui/*/(vislets)/visletSearchPaths

• VruiConfigurationFragmentType Tool - This fragment is merged the same as a full configuration file (above), except that the following String Lists are merged using the Indirected Merging Rules:
  • /Vrui/*/(tools)/toolSearchPaths
  • /Vrui/*/(tools)/toolClassNames
  • /Vrui/*/(tools)/toolNames

• VruiConfigurationFragmentType Device - This fragment is merged the same as a full configuration file (above), except that the String Lists named by the following tags are merged (eliminating duplicate entries) and stored in the result:
  • /Vrui/*/inputDeviceAdapterNames
  • /Vrui/*/DeviceDaemonAdapter/inputDeviceNames

In the following, a parenthesized name such as /Vrui/Desktop/(vislets) refers to an indirected name in the sense that the parenthesized name is replaced by the value of the tag with that name at that level. Therefore, if /Vrui/Desktop/vislets is the string DesktopVislets, then /Vrui/Desktop/(vislets) refers to the name /Vrui/Desktop/DesktopVislets.

Furthermore, when an indirected name is merged from a fragment to a resultant configuration file, then the entity that is referenced by the parenthesized name is made consistent with the fragment. For example, if the fragment's /Vrui/Desktop/vislets value is DesktopVislets but the result's /Vrui/Desktop/vislets value is CAVEVislets, and if /Vrui/Desktop/(vislets)/name is merged, then the value of the result's /Vrui/Desktop/vislets tag is changed to DesktopVislets, and also the result's /Vrui/Desktop/(vislets) entity (tag or section) is renamed to the fragment's /Vrui/Desktop/(vislets). I.e., in this example, the result's /Vrui/Desktop/CAVEVislets is renamed to /Vrui/Desktop/DesktopVislets to match the fragment.

Finally, when a tag values that are String Lists (i.e., parenthesized, comma-separated lists of strings) are merged, the resulting String List contains the union of the two String Lists but without duplicates.