Developing and Building Apps

Overview

While most base applications developed for desktop purposes can be deployed on Omniverse Cloud PaaS, there are a couple of additional steps to turn them into Omniverse Cloud PaaS consumable applications and this document focuses on these steps. For general application development, build, and packaging, please refer to the Omniverse Developer Guide.

Note

The information contained below is based on building an application using Kit 105.1.2.

To turn your custom application into an Omniverse Cloud PaaS ready one, follow these steps:

Create an Omniverse Cloud PaaS specific version of your application:
1. Create a OVC Kit application file (e.g., my_custom_app.my_usd_explorer.ovc.kit).
2. Import your base application (e.g., my_custom_app.my_usd_explorer.kit) into the Omniverse Cloud PaaS specific one as a dependency.
3. Add additional required extensions and settings for Omniverse Cloud PaaS consumption.
Rebuild your application for Linux and pre-caching its extensions.
Create a fat package of your application.

Developing an Omniverse Cloud PaaS version of your Application

To build a version of your application ready for Omniverse Cloud PaaS consumption along with your standard application kit file, an Omniverse Cloud PaaS specific kit file is required to ensure proper functioning and fine-tuned settings for browser streaming experience. You can name this with an .ovc.kit suffix added to your application name, for clarity and better project organization.

For example, if your application is named my_custom_app.my_usd_explorer, you will use my_custom_app.my_usd_explorer.kit for your main kit file and my_custom_app.my_usd_explorer.ovc.kit for Omniverse Cloud PaaS.

In this guide, we will use the content in this git repository as our foundation.

Creating the .kit File

In this example, we will start using omni.usd_explorer.kit as our base. Copy this file and name it as your custom app:

cp omni.usd_explorer.kit my_custom_app.my_usd_explorer.kit

Your my_custom_app.my_usd_explorer.kit file may be placed into the folder <ROOT>/source/apps/.

You can use your own custom *.kit file if you would prefer not to use the example USD Explorer Kit file. Below, we will use USD Explorer as an example workflow.

Creating the .ovc.kit File

The *.ovc.kit file requires specific extensions to be included to be prepared for OVC. Below is a reference taken from the omni.usd_explorer.ovc.kit file from the kit-app-template repository, annotated for clarity:

[dependencies]
# Items listed in this section are dependencies that this OV application requires.
# This is the main USD Explorer kit file. All of the settings and dependencies in there are also dependencies
# for this cloud based version of the application.
"omni.usd_explorer" = {}

# This extension controls what occurs when a scene is loaded on a streaming instances of USD Explorer
"omni.cloud.open_stage" = {}
"omni.kit.livestream.webrtc" = {}

[settings.app]
livestream.enabled = true

# Allows the client application to determine streaming resolution.
livestream.allowResize = true

livestream.webrtcEtli = true

# Only log errors or critical level issues.
livestream.logLevel = "error"

# Scale the application window to match the size & aspect ratio of the monitor.
window.scaleToMonitor = true

# Informs certain extensions that they are running on a cloud deployment of the application.
ovc_deployment = true

[settings.exts]
# Do not allow connections to new servers when running on OVC.
# Only 1 Nucleus server should be connected to an instance, which is setup during OVC Onboarding.
"omni.kit.window.filepicker".show_add_new_connection = false

Below are simplified steps for customizing the *.ovc.kit file:

Download the omni.usd_explorer.ovc.kit file into your project.
Rename the file based on your application name (e.g., my_custom_app.my_usd_explorer.ovc.kit).
Review the values and modify any application specific settings as needed. (Additional information below.)

The *.ovc.kit file version should import your base application and add a set of required extensions and settings specific for Omniverse Cloud PaaS usage. Starting with the sample omni.usd_explorer.ovc.kit, modify lines 13 and 52 that reference the omni.usd_explorer application so they now match your base application my_custom_app.my_usd_explorer.

[dependencies]
# Items listed in this section are dependencies that this OV application requires.
# This is the main My App Kit file. All settings and dependencies in this file are also dependencies
# for this cloud based version of the application.
"my_custom_app.my_usd_explorer" = {}

(…)

[settings.app.extensions]
generateVersionLockExclude = ["my_custom_app.my_usd_explorer"]

Creating a Kit Application Build Target

To go along with your .kit and .ovc.kit files, you need to create a corresponding build target. If you are using the standard repo-tools and project structure, this involves the following steps:

Open ./premake5.lua there (present in the root folder of the Kit App Template repository)
Find the section -- Apps:
Verify there is an entry for your main app define_app("my_custom_app.my_usd_explorer")
Add an entry for the .ovc.kit app: define_app("my_custom_app.my_usd_explorer.ovc").
Since we only want to build our custom application, all other applications should be removed.

Below is the default contents of ./premake5.lua content in kit-app-template repo:

-- Apps: for each app generate batch files and a project based on kit files (e.g., my_name.my_app.kit)
define_app("omni.usd_explorer")
define_app("my_name.my_app")

Here is what it should look like to include your new OVC application version:

-- Apps: for each app generate batch files and a project based on kit files (e.g., my_name.my_app.kit)
define_app("my_custom_app.my_usd_explorer")
define_app("my_custom_app.my_usd_explorer.ovc")

Note

The reason you should define two applications is because a dedicated *.ovc app version is required, and this version contains the additional Omniverse Cloud PaaS required extensions and settings that augment the base application previously defined. By defining the *.ovc app here, we will ensure additional extensions are properly pre-cached and dedicated *.ovc batch launch files are automatically generated.

For distributed applications, we lock extension versions and pre-cache them. This step is important to ensure the necessary extension versions are packaged up in the container later. To do so, add my_custom_app.my_usd_explorer.ovc.kit to ./repo.toml:

Open ./repo.toml.
Find the section [repo_precache_exts].
Find the apps list.
Ensure the base application ${root}/source/apps/my_custom_app.my_usd_explorer.kit is included.
Add an entry for the .ovc.kit app: ${root}/source/apps/my_custom_app.my_usd_explorer.ovc.kit
Comment out any other applications.

An example of the file default content in kit-app-template repo contains:

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

Here is what it should look like to include your my_custom_app.my_usd_explorer.ovc.kit dependencies:

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

Performing the Initial Build of the custom Omniverse application

In order to perform a build of your kit application to run on an Omniverse Cloud PaaS Instance, you must perform the build on Linux. To learn more about the Kit application build process, follow the comprehensive docs found here.

Note

If you are a Windows-only developer you might develop and test your application locally. To test locally, this requires an extra build step by your devOps or IT team in a Linux environment, once you pass them your application code. Building and containerizing the application in Windows is NOT supported.

Build your application and verify that it runs correctly:

./repo.sh build

Once the application is built, ensure the application operates as intended, based on your original design. This is performed by using the validation steps listed below. After verification, perform a final clean release build that only includes the applications you want to publish and precache the extensions. The instructions to execute a clean release build are included here:

# cd into the directory where your source code is located
cd ~/kit-app-template-github

# clean the build directory
./repo.sh build -c

# build a release version of usd-viewer
./repo.sh build -r

# precache extensions
./repo.sh precache_exts -u

If the build completed successfully, you will see the following confirmation message:

BUILD (RELEASE) SUCCEEDED (Took XX.YY seconds)
# confirm that you see the above message when the build ends

The build process for my_custom_app.my_usd_explorer uses nearly 20GB when using the omni.usd_explorer.kit and omni.usd_explorer.kit.ovc files as the base.

Note that after you run the pre-caching of the extensions, your *.kit files will also have a new section labeled BEGIN GENERATED PART. This is where extension versions have been locked.

Validating Build of Custom Omniverse Application

After the build completes, you will see a new folder in your root directory called ./_build where the application resides:

~/kit-app-template-github/_build$ ls -al
total 36
drwxrwxr-x  9 horde horde 4096 Jun 27 21:17 .
drwxrwxr-x 12 horde horde 4096 Jun 27 21:17 ..
-rw-r--r--  1 horde root    0 Jun 27 21:13 .lastpippull
drwxr-xr-x  2 horde root  4096 Jun 27 21:17 PACKAGE-LICENSES
drwxr-xr-x  2 horde root  4096 Jun 27 21:17 deps
drwxrwxr-x  4 horde horde 4096 Jun 27 21:17 generated
drwxrwxr-x  2 horde horde 4096 Jun 27 21:17 host-deps
drwxr-xr-x  4 horde root  4096 Jun 27 21:17 linux-aarch64
drwxrwxr-x  4 horde horde 4096 Jun 27 21:17 linux-x86_64
drwxrwxr-x  2 horde horde 4096 Jun 27 21:12 target-deps

To locally test the built application, ensure you have an active desktop session to the system on which you have the build, which requires a desktop environment. Then execute the launch file located in ~/kit-app-template-github/_build/linux-x86_64/release/ using the following commands:

cd _build/linux-x86_64/release/

./my_custom_app.my_usd_explorer.ovc.sh

The launched application on a desktop will appear like the following:

../_images/ovc_app_validation_sample.png

Packaging your Application for Omniverse Cloud PaaS Deployment

Packaging for Omniverse Cloud PaaS requires the following steps:

Start from a clean release Linux build of your application with pre-cached extensions (Reference the Performing the Initial Build of the custom Omniverse application section.)
Create a Fat application package (Additional information is provided below.)

For further information on how to package your application, refer to the packaging guide.

Create a Fat Application Package

To create a container image of a kit application, ensure you have all required dependencies. Creating a fat application package leverages the NVIDIA provided repo tool to accomplish this. By doing so, it identifies all dependencies required by the kit application and packages them in a structured way, into a completely contained .zip file.

./repo.sh package

If the package was built successfully, you will see a similar confirmation message:

Packaging app (fat package)...
...
Package Created:
/home/horde/kit-app-template-github/_build/packages/kit-app-template-fat@2023.2.1+usd-viewer.0.92902f4b.local.linux-x86_64.release.zip
(Took 226.32 seconds)

This creates a large .zip file of your application in the _build/packages directory. For reference, the omni.usd_explorer.kit file will create a zip file of size 2.4GB.

du -h /home/horde/kit-app-template-github/_build/packages/

# 2.4G    /home/horde/kit-app-template-github/_build/packages/