Package a Build

../../_images/dev_guide_package_banner.png

At the conclusion of your development and testing phases, packaging your project is often necessary in preparation for publishing. While some extensions may not require this step, it becomes essential for applications and more complex extensions involving advanced features. The packaging process organizes and structures your project assets for delivery and deployment. The specifics of the packaging step depend on your desired method of distribution.

Introduction

Important Notes:

  • Packaging is OS dependent. Linux is required for Linux packages and Windows is required for Windows packages

  • Packaging requires a build of the desired Project. See Build a Project for additional details

  • Instructions provided here assume use of Repo tooling

Packages are a collection of all the files that compose your Project. Although it is possible to manually assemble your package by creating an archive with the necessary files and folders, Omniverse conveniently offers a more efficient alternative via the Repo Package tool. This tool verifies that you have all the essential config files and that your build folder is accurately configured.

Packaging Extensions

It’s important to note that sometimes, specifically with simpler extensions, you may only need to manually copy the files into the destination directory for distribution. Generally, the repo package method is best used for projects that contain a premake5.lua file and result in a _build folder.

Packaging Applications

Lock Extension Versions

Before packaging, it is advised to lock your Extension versions. While iterative development typically benefits from using the latest versions without specifying one, it’s good practice to lock Extension versions for distributed Applications. This ensures that end users install and experience the fully tested and developed version.

The following steps apply if you’re working on a Kit project that includes the Repo tool, like the kit-app-template, for example.

To lock Extension versions:

  1. Build the Project

  2. Open the repo.toml file (most likely in the root directory of the project) and insert a reference to the application .kit file in the [repo_precache_exts] section:

[repo_precache_exts]
# Apps to run and precache
apps = [
"${root}/source/apps/my_company.my_app.kit",
]

  1. Run the command repo precache_exts -u.

  2. Open the .kit file. There should be a section labeled BEGIN GENERATED PART. This is where Extension versions have been locked.

Warmup Script

When an end user installs an Application we can provide a warmup procedure that caches shaders and a does a few other things to improve the Application startup performance. This is an optional step and is most relevant to packages published via an Omniverse Launcher.

Open .\kit-app-template\premake5.lua.

Note this section:

-- App warmup script for the Launcher
create_app_warmup_script("omni.usd_explorer", {
    args = "--exec \"open_stage.py ${SCRIPT_DIR}exts/omni.usd_explorer.setup/data/BuiltInMaterials.usda\" --/app/warmupMode=1 --no-window --/app/extensions/excluded/0='omni.kit.splash' --/app/extensions/excluded/1='omni.kit.splash.carousel' --/app/extensions/excluded/2='omni.kit.window.splash' --/app/settings/persistent=0 --/app/settings/loadUserConfig=0 --/structuredLog/enable=0 --/app/hangDetector/enabled=0 --/crashreporter/skipOldDumpUpload=1 --/app/content/emptyStageOnStart=1 --/app/window/showStartup=false --/rtx/materialDb/syncLoads=1 --/omni.kit.plugin/syncUsdLoads=1 --/rtx/hydra/materialSyncLoads=1 --/app/asyncRendering=0 --/app/file/ignoreUnsavedOnExit=1 --/renderer/multiGpu/enabled=0 --/app/quitAfter=10"
})
By including this section for the app, an additional [app name].warmup.bat\.sh is added in the build. Go ahead and change omni.usd_explorer to my_company.usd_explorer (there’s two places):

-- App warmup script for the Launcher
create_app_warmup_script("my_company.usd_explorer", {
    args = "--exec \"open_stage.py ${SCRIPT_DIR}exts/my_company.usd_explorer.setup/data/BuiltInMaterials.usda\" --/app/warmupMode=1 --no-window --/app/extensions/excluded/0='omni.kit.splash' --/app/extensions/excluded/1='omni.kit.splash.carousel' --/app/extensions/excluded/2='omni.kit.window.splash' --/app/settings/persistent=0 --/app/settings/loadUserConfig=0 --/structuredLog/enable=0 --/app/hangDetector/enabled=0 --/crashreporter/skipOldDumpUpload=1 --/app/content/emptyStageOnStart=1 --/app/window/showStartup=false --/rtx/materialDb/syncLoads=1 --/omni.kit.plugin/syncUsdLoads=1 --/rtx/hydra/materialSyncLoads=1 --/app/asyncRendering=0 --/app/file/ignoreUnsavedOnExit=1 --/renderer/multiGpu/enabled=0 --/app/quitAfter=10"
})

Run a build.

A my_company.usd_explorer.warmup.bat.sh file was created in the build directory.

To prepare for a Launcher package, open .kit-app-templatesourcelauncherlauncher.toml.

Note the per platform post-install = “” entries. Edit these settings to provide the warmup script (the default has them commented out):

[defaults.windows-x86_64.install]
...
post-install = "${productRoot}/my_company.usd_explorer.warmup.bat"
...

[defaults.linux-x86_64.install]
...
post-install = "${productRoot}/my_company.usd_explorer.warmup.sh"
...

Create the Package

There are primarily two types of packages: ‘Fat’ and ‘Thin’.

  • ‘Fat’ Package

    Includes all the necessary components to run the app, encompassing both the Kit Kernel and all Extensions. This is the package type you should opt for if you don’t want end users to download anything during installation. It is particularly useful in environments without access to public repositories, such as air-gapped organizations.

  • ‘Thin’ Package

    Contains the bare essentials needed for an installation, necessitating the download of the Kit Kernel and Extensions during app installation. Thin packages optimize the use of local storage by only downloading components that other thin packaged apps haven’t already downloaded. However, this package type isn’t suitable for air-gapped environments.

Both ‘fat’ and ‘thin’ packages come as zip-archives and can be directly shared with end users.

A variant is the ‘Launcher’ Package. This type includes either a ‘fat’ or ‘thin’ application package along with additional resources, enabling the application to be listed in the Omniverse Launcher.

Both fat and thin packages can be renamed - nothing inside the package depends on the package name.

Fat Package

  1. Build the Project

  2. Execute repo package.

  3. Package is created in the .\_build\package directory.

Thin Package

  1. Build the Project

  2. Execute repo package --thin.

  3. Package is created in the .\_build\package directory.

Connectors

Note

There is no set method for packaging connectors. Please reference the Connect Sample and associated documentation for best practices