Configuration

Kit comes with a very rich and flexible configuration system based on Carbonite settings. Settings is a runtime representation of typical configuration formats (like json, toml, xml), and is basically a nested dictionary of values.

Quick Start

When you run a Kit app it a loads default configuration file: kit-default.json, to support backward compatible behavior. The easiest way to start simple is to pass the --empty flag.

> kit.exe --empty

That will start kit and exit, without enabling any extensions or applying any configuration, except for built-in config: kit-core.json.

Note

To see all flags call > kit.exe -h

To see default kit settings pass --/app/printConfig=true:

> kit.exe --empty --/app/printConfig=true

That will print all settings. This syntax --/ is used to apply settings from the command line. Any setting can be modified in this way. You may notice that the config it printed includes app/printConfig. You can try adding your own settings to the command line and observing them in the printed config to prove yourself that it works as expected.

Another useful flag to learn early is -v to enable info logging or -vv to enable verbose logging. There are setting to control logging more precisely, but is easy way to get more logging in console and debug startup routine.

> kit.exe --empty -v

To make kit do something let’s enable some extensions:

> kit.exe --empty --enable omni.kit.console

That enables a simple console extension. You may also notice that it enabled a few extension this console depends on. You can stack multiple --enable keywords to enable more extensions.

You can also add more folders to search for extensions in with --ext-folder:

> kit.exe --empty --enable omni.kit.console --ext-folder ./exts --enable foo.bar

That enables you to create e.g exts/foo.bar/extension.toml and start hacking your own extension right away.

Those flags, like --enable, --ext-folder and many others are just shorthand for commonly-used settings. For example they just respectively append to /app/exts/enabled and ``/app/exts/folders``arrays respectively.

The Next step is to control settings by applying configuration files. You can apply multiple configuration file using -m=[path_to_file] flags. Those files can be json or toml files.

> kit.exe --empty --enable omni.kit.console -m=my.toml

Application Config

Settings can also be applied by passing a configuration file as a positional argument to Kit:

> kit.exe my.toml

This kind of config file becomes the “Application config”. It receives special treatment from Kit:

  1. Config name becomes application name.

  2. Separate data, documents and cache folders are created for applications.

  3. The Folder where this config is located becomes the application path.

This allows you to build separate applications with their own data.

Kit File

A Kit file is the recommended way to configure applications.

> kit.exe my.kit

Kit files are single file extensions (basically renamed extension.toml files). Only the [settings] part of them is applied to settings (as with any extension). Here is an example:

[package]
title = "Console"
version = "0.1.0"
keywords = ["app"]

[dependencies]
"omni.kit.console" = {}

[settings]
foo.bar = "123"

exts."omni.kit.console".autoRunREPL = true

As with any extension, it can be named, versioned and even published to the registry. It defines dependencies in the same format to pull in additional extensions.

Notice that the setting autoRunREPL of the console extension is being overriden. Any extension can define it’s own settings and a guideline is to put them in the extension.toml file of the extension. If you look at the one for omni.kit.console you will sett it. Another guideline is to use root exts folder and the name of the extension.

The goal of the .kit file is to bridge the gap between settings and extensions and have one file that user can click and run Kit-based application (associate .kit file with kit.exe in OS).

User Settings

You can create system wide configuration files to override any setting. There are 2 places to put them:

  1. To override settings of any kit application in the shared documents folder, typically in (on Windows): C:\Users\[username]\Documents\Kit\shared\user.toml

  2. To override settings of particular application in the application documents folder, typically in: C:\Users\[username]\Documents\Kit\experiences\[experience_name]\user.toml

To find those folders you can run Kit with info logging enabled and look for [omni.kit.app.plugin] Tokens: message at the beginning. Look for documents and shared_documents tokens. For more info: Tokens.

Special Keys

Appending Arrays

When configs are merged one value can override another. Sometimes we want instead to append values for array. You can use the special ++ key for that. For example to add additional extension folder to /app/folders settings you can do:

[app.exts]
folders."++" = ["c:/temp"]

You can put that for instance in user.toml described above to add more extension folder search paths.

Importing Other Configs

You can use the @import@ key to import other config files in that location:

[foo]
"@import@": ["./some.toml"],

That will import config some.toml under the key foo. The ./ syntax implies that the config file is in the same folder.