Naming and Configuration

This document provides best practice guidance on the naming and configuration of applications and extensions for use with the Omniverse Kit SDK.

Naming

The discussion on naming conventions in this section focuses primarily on technical, namespaced identifiers rather than the commercial or display names of your projects. Specifically, this pertains to the naming of .kit files for applications, and the identifiers for Python modules or C++ plugins in the case of extensions.

Experienced developers know the importance of properly managing namespaces. When developing with the Kit SDK, careful use of namespaces prevents conflicts with other applications and extensions created within the platform.

The repo template tool, provided as part of the kit-app-template repository, assists in setting the following:

  • The Application and Extension Names: A validated input to ensure names adhere to a specific naming convention—dot-separated, lowercase alphanumeric characters with underscores allowed for spacing.

  • The Application and Extension Display Names: A free-form text input that will set the application or extension name presented to users.

Applications

The following represent best practice suggestions for naming applications:

  • Top Level Namespace: When creating applications, particularly those with common names (e.g., “Viewer” or “Editor”), we recommend the use of top-level namespaces that help to disambiguate your particular application. For example, my_company.my_app.

Extensions

The following represent best practice suggestions for naming extensions:

  • Common Extensions: When creating an extension to provide specific functionality across various applications, we recommend using the top-level namespace followed by a function-informed extension name. For example, my_company.extension_name.

  • Component Extensions: When creating an extension that is designed to be used as a component within a higher-level extension, we recommend using the top-level namespace, followed by the higher-level extension, ending with the component name. For example, my_company.extension_name.component_name.

  • Application-Specific Extensions: When creating an extension specifically for the purpose of supporting a single application, such as in setup extensions, we recommend using the top-level namespace, followed by the app name, ending with the extension name. For example, my_company.my_app.extension_name.

Configuration

Both applications and extensions have dedicated configuration files that define their behavior and properties. For applications, this is the .kit file, and for extensions, this is the extension.toml file. This section provides best practice recommendations for both application and extension configuration files.

Application .kit File

The .kit file is a TOML-like configuration file that defines the behavior and properties of an application. While low-level TOML styling is left to the developer, we do recommend adherence to the following general structure:

kit File Structure

  • Package Information: The top level of the file should contain the package information, including the name, version, and description of the application.

  • Dependencies: The dependencies section should list all the dependencies required by the application.

  • Settings: The settings applied to extension dependencies.

  • Test: Configuration and extension dependencies specific to testing.

  • Auto Generated Precache: This section is auto-generated during the build process and details the specific extension versions used by the application.

Additionally, it is helpful if all content within a given section is sorted alphabetically.

Note: This is only a recommendation and no such structure is enforced. However, a common structure across applications will help other developers understand the behavior of a given application from its .kit file.

Extension extension.toml File

Extensions contain many of the same components as applications; however, the information that is typically defined can vary.

  • Package Information: The top level of the file should contain the package information, including the name, version, and description of the extension, and typically include:

    • Version

    • Author(s)

    • Title

    • Description

    • Readme

    • Changelog

  • Dependencies: Similar to the .kit file, the dependencies section should list all the dependencies required by the extension.

  • Python Module or Native Plugin: The main Python module or native plugin this extension provides.

  • Test: Similar to the .kit file, this section contains configuration and extension dependencies specific to testing.

  • Documentation: This section contains the pages that will be displayed in the extension documentation.

Hands-on Exploration

In this section, we will use the repo template tool to create a new application and explore the structure of the generated files.

1. Create an Application

An example of a well-structured project and associated configuration files can be generated by accepting the defaults for the repo template tool to create an application. You can see a range of complexity across .kit files and extension.toml files, ranging from the Kit Service Template at the simpler end to the USD Explorer Template at the more complex end, with the Kit Base Editor Template falling somewhere in between.

Linux:

./repo.sh template new

Windows:

.\repo.bat template new

Follow the prompt instructions:

  • ? Select with arrow keys what you want to create: Application

  • ? Select with arrow keys your desired template: Kit Service

  • ? Enter name of application .kit file [name-spaced, lowercase, alphanumeric]: accept default

  • ? Enter application_display_name: accept default

  • ? Enter version: accept default

The application template you have selected requires a setup extension. Setup Extension -> kit_service_setup

  • ? Enter name of extension [name-spaced, lowercase, alphanumeric]: accept default

  • ? Enter extension_display_name: accept default

  • ? Enter version: accept default

-Notice-

Within the newly generated /source directory:

  • The default naming of the application and its associated setup extension (if applicable)

  • The initial structure of the .kit file.

  • The extensions directory structure

  • The structure of the extension.toml file.

2. Build the Application

To observe the additional generation of the extension precache section in the .kit file, build the application.

Linux:

./repo.sh build

Windows:

.\repo.bat build

-Notice-

Within the newly generated /source/apps directory:

  • The existence of a section beginning with # BEGIN GENERATED PART

  • Within the autogenerated section, the listing of the extension dependencies with specific version numbers.

This ensures the stability of your applications and its extension dependencies until a developer decides to update them. Any extension that is listed without a specific version number will be updated to the latest version available upon the next build.

3. Cleanup

Before continuing to the next section, it is recommended to clean up the applications, extensions, and any other repository changes that were created during this exploration.

Either revert all changes made to the repository or delete the repository and clone it again before continuing.

Typical cleanup steps include:

  • Revert changes to top level premake5.lua file

  • Revert changes to repo.toml

  • Delete the source/ directory

  • Delete the _build/ directory, or run ./repo.sh build -c or .\repo.bat build -c

Additional Resources