Package App

Important

In order to comply with the NVIDIA Omniverse License Agreement please distribute only “thin” or “launcher thin” packages outside of your organization. Details on these packages below.

Production Build

Set Application Version

The Application version can be set in .\tools\VERSION.md. This version will be used in for example the Application title bar but also in places such as the Omniverse Launcher’s description.toml file were a launcher package created as detailed below.

Cleaning up

Packages are created from the contents of the _build directory. The kit-app-template repo comes with some Application and Extension examples, and we have created a couple of new ones along the way. This is a tutorial so it’s okay if we have some extra files; however, for production development the project should only contain elements that are intended to be released. The following instructions are intended to help with creating a clean build - but not critical for the tutorial.

1. Assuming we want to package just the my_company.usd_explorer app, make sure the .\premake5.lua only has the define_app("my_company.usd_explorer") entry in the -- Apps section.

2. Make sure these dependencies are not part of the Application kit file:

   • omni.kit.window.extensions

   • omni.kit.debug.vscode

3. For any Extension that should NOT be included - such as omni.hello.world - the Extension specific premake5.lua file can be either deleted or fully commented out:

-- Use folder name to build Extension name and tag.
-- local ext = get_current_extension_info()

-- project_ext (ext)

-- Link only those files and folders into the Extension target directory
-- repo_build.prebuild_link { "docs", ext.target_dir.."/docs" }
-- repo_build.prebuild_link { "data", ext.target_dir.."/data" }
-- repo_build.prebuild_link { "omni", ext.target_dir.."/omni" }

4. Delete the _build directory - either manually or by running build -c.

5. Run build.

Note that the build directory only has .bat \ .sh files for the Application we’re wanting to package - with the addition of a few created by default.

Locking Extension Versions

The build command is used throughout this tutorial. Before creating a package for distribution of the app, it is recommended to lock the Extension versions. There’s no harm in doing this with iterative builds during development as well - but more important prior to releasing an app.

Manually setting an explicit version of all Extensions could be time-consuming. By configuring the repo tool we can run a process that automatically locks the versions:

1. Open the .\repo.toml file.

2. Edit the kit file(s) that should have locked Extension versions in the [repo_precache_exts] section. For the my_company.usd_explorer app, change the apps setting to the below:

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

3. Add Extension versions by running the command repo precache_exts -u.

4. Note the section labeled BEGIN GENERATED PART in my_company.usd_explorer.kit - this is where Extension versions are locked down.

We now have a clean version locked build ready to be packaged.

Note

Reference: Building an App

Warmup Script

When an end user installs an Application we can provide a warmup procedure that caches shaders and 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.

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

2. 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"
})

3. 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"
})

4. Run a build.

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

6. To prepare for a Launcher package, open .kit-app-template\source\launcher\launcher.toml.

7. 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"
...

Fat Package

A “fat” package includes everything to run the app: Kit Kernel and all Extensions. This package type should be used when the goal is to not require an end user to have to download anything at time of installation. This type of package is suitable for environments that do not have access to public repositories - such as air gapped organizations.

1. Create a production build.

2. Run repo package command (command cheat-sheet).

3. Package is created in .\_build\packages.

The package can be renamed - nothing inside the package depends on the package name- and be published.

Thin Package

A “thin” package contains the bare minimum required for an installation to be possible - but requires the ability to download Kit Kernel and Extensions when the app is installed.

Installed thin packaged apps make use of shared storage of Kit Kernel and Extensions. This approach optimizes the use of local storage - only downloading components that have not already been downloaded by other thin packaged apps. This package type is not suitable for air gapped environments.

1. Create a production build.

2. Runrepo package --thin command (command cheat-sheet).

3. Package is created in .\_build\packages.

Note that compared to the “fat package”, this thin package does not contain a kit or extscache directory. This makes the package a lot smaller - but also means that user will need to download those “on demand” during installation if they are not already installed from some prior installation. The package can be renamed - nothing inside the package depends on the package name- and be published.

Launcher Package

Omniverse Launcher is an Application for distributing solutions to Omniverse users. This project has tools to create an Application package that can be installed via the IT Managed Launcher. The package can be “fat” or “thin” as mentioned above - but will also contain additional metadata so that end users can see it within the Launcher.

There are source files within this project that are used for this kind of a package - you’ll find them in .\source\launcher.

Launcher Data

File: .\source\launcher\launcher.toml.

This file provides settings for the Launcher used at installation. Be sure to set the entrypoint and command fields for Windows and/or for Linux to the .bat and .sh files launching your Application.

Example for my_company.usd_explorer app:

## install and launch instructions by environment
[defaults.windows-x86_64]
...
entrypoint = "${productRoot}/my_company.usd_explorer.bat"
...
[defaults.windows-x86_64.open]
command = "${productRoot}/my_company.usd_explorer.bat"
...
[defaults.windows-x86_64.install]
...
[defaults.linux-x86_64]
url = ""
entrypoint = "${productRoot}/my_company.usd_explorer.sh"
...

Images

The following images inside .\source\launcher should be updated according to the intended branding:

• background.png

• card.png

• icon.png

• icon_ovc.png

• image.png

Do NOT change the resolution of these images.

Metadata

File: .\source\launcher\description.toml.

Version

If you leave version = "${version}" then the version label will be injected automatically using version mentioned in .\tools\VERSION.md. It could also be written “manually” here if that is desirable.

Slug

A critical entry in this file is the slug. The slug is an identifier that is not used by the UI. Keep this the same for all versions of the app so that users can see updates and versions in a single place:

#unique identifier for component, all lower case, persists between versions
slug = "my_company.usd_explorer"

URL

Another critical entry is the [url]: only define the platform(s) supported by the package you are creating. For example, remove the windows-x86_64 entry if only Linux is supported by the given package.

[url]
windows-x86_64 = 'windows-x86_64/package.zip'
linux-x86_64 = 'linux-x86_64/package.zip'

Launcher UI Data

Here are other metadata fields to use in description.toml which are used in the Launcher UI:

• The Publisher and Developer metadata are sections in the toml file; for example:

  [developer]
  #name of developer
  name = 'My Company'
  # hyperlink on developer name (can be left as empty string)
  url = 'https://www.my-company.com/'
  
  [publisher]
  #name of publisher
  name = 'My Company'
  # hyperlink on publisher name (can be left as empty string)
  url = 'https://www.my-company.com/'
  

• You can add as many [[links]] as you’d like.

  [[links]]
  title = "My Page"
  url = "https://www.my-page.com/"
  

File: .\source\launcher\requirements.toml.

This defines the system requirements for your Application to be used. This metadata is shown in the EXCHANGE section underneath the metadata provided by description.toml; for example:

Command to Package

1. Create a production build.

2. Run repo package --launcher or repo package --launcher --thin command (command cheat-sheet).

3. Package is created in .\_build\packages.

The top level package structure is the same whether the --thin argument was used or not:

linux-x86_64
    package.zip
windows-x86_64
    package.zip
background.png
description.toml
icon.png
icon_ovc.png
image.png
requirements.toml

What varies is what is inside the package.zip. This is where the “thin” or “fat” packaged Application ends up. The Linux and/or Windows version can be included in the same package. A workstation build can of course only generate one or the other so if both are to be delivered together you’ll have to manually construct one archive from two packages.

The package can be renamed - nothing inside the package depends on the package name- and be published.

Preview in Launcher

Omniverse Launcher (both the Workstation and IT Managed Launcher) supports installing Applications via commands. Here’s how to install the package to preview and make sure it is displayed correctly:

1. Make sure an Omniverse launcher is installed.

2. Open up a shell and execute the following (with the appropriate absolute filepath for the zip file):

   • Windows: start omniverse-launcher://install?path="C:\my_company.usd_explorer.zip" command cheat-sheet

   • Linux: xdg-open omniverse-launcher://install?path="/home/my_username/my_company.usd_explorer.zip" command cheat-sheet

3. The Launcher shows an installation progress bar.

4. Once installation is complete, the Application is listed in the Library tab’s Apps section.

Note

Reference: Workstation Launcher

Reference: IT Managed Launcher

Omniverse Cloud

If you are not familiar with Omniverse Cloud (OVC) then you can read more here.

To package an Application for OVC, use the repo package --launcher command mentioned above. This will create the necessary “fat launcher” package.