Connect SDK Dev Tools

Premake Lua Modules

Most NVIDIA developed Connectors should be built using premake via repo_build. In the dev/tools/premake sub directory we provide a connect-sdk-public.lua file, which can be sourced from an Connector’s premake5.lua to bootstrap much of the build process. This module serves to compliment the repo_build lua module.

It will always be necessary for Connectors to further modify the build Workspace and Projects with client application specific headers, libraries, and compiler flags, but using the connect-sdk-public.lua will provide a solid foundation to start from.

For example, compiling your own cross platform Shared Library that uses Client Library, OpenUSD, the omni_connect_core library from Connect SDK, along with the native API from your client application, can be as simple as adding the following to your premake5.lua:

Note

A real use case in a client Connector will likely be considerably more complex. You will need to be familiar with the compile, link, and runtime requirements of the client application and ensure that the settings in connect-sdk-public.lua are either aligned with your needs, or overridden in your own premake5.lua.

repo_build = require("omni/repo/build")
repo_build.root = os.getcwd()

connect_build = require(path.replaceextension(os.matchfiles("_build/target-deps/omni_connect_sdk/*/dev/tools/premake/connect-sdk-public.lua")[1], ""))

workspace "foo_bar_workspace"
  connect_build.setup_workspace()

project "foo_bar_library"
  connect_build.use_connect_core()
  connect_build.shared_library{
      library_name = "omni_foo_bar",
      headers = { "path/to/headers/*.h" },
      sources = { "path/to/source/**.cpp" },
  }
  externalincludedirs { "path/to/foo_bar/include" }
  syslibdirs { "path/to/foo_bar/lib" }
  links { "foo_bar" }

project "foo_bar_test_executable"
    dependson { "foo_bar_library" }
    connect_build.use_cxxopts()
    connect_build.use_doctest()
    connect_build.use_omni_client()
    connect_build.use_usd()
    connect_build.use_connect_core()
    connect_build.executable{
        name = "test_omni_foo_bar",
        sources = { "path/to/tests/**.cpp" },
    }

Calling connect_build.use_connect_core() in your premake5.lua has 2 side effects:

It adds the necessary includes, libdirs, links, and defines required to compile against omni_connect_core and all it’s upstream dependencies (e.g. Carbonite, Client Library, and a subset of OpenUSD).
It installs the strictly required runtime components of omni_connect_core & Carbonite (i.e. the shared libraries, a small subset of carb plugins, and toml configs).

Tip

These files are installed based on a global premake variable target_build_dir. If you want to redirect your installation to a non-standard location, simply override this variable after the require line. Check connect-sdk-public.lua for more global build variables.

The partial installation may be unexpected, but Connect SDK requires the Carbonite plugins & configs to conform to a strict file layout, and this approach makes it simpler for client Connectors to remain in-sync with strict Connect SDK expectations, while remaining flexible to install other dependencies (eg OpenUSD shared libraries) in any location that the client application may require.

Repo Tools for Connectors

In addition to the standard repo_tools suite, we provide a few custom repo_tools to assist common Connector build issues.

Using any of these tools requires importing dev/tools/repoman/connect-defaults.toml from the omni_connect_sdk package. To enable these tools with a default configuration, add the following to your repo.toml:

[repo]
import_optional_configs = [
    "_build/target-deps/omni_connect_sdk/debug/dev/tools/repoman/connect-defaults.toml",
    "_build/target-deps/omni_connect_sdk/release/dev/tools/repoman/connect-defaults.toml"
]

repo_install_sdk

The first step to building a Connector using Connect SDK is to install the SDK itself. Assembling the minimal runtime requirements of the Connect SDK can be arduous. The install_sdk tool can be used to download precompiled binary artifacts for any flavor of Connect SDK, including all runtime dependencies, and assemble them into a single file tree on your local disk.

Important

Be sure to configure the –usd, –python, –nucleus, and –version arguments appropriately to download your preferred flavor of Connect SDK. See repo install_sdk -h for available options.

This tool can be invoked from a clone of the Connect Samples, or if you have source access to the Connect SDK, it can be invoked directly from a Connect SDK source archive (or git clone) as well.

To configure this tool from your own repo_tools enabled project, add the following to your repo.toml along with any tool configuration overrides from the default values:

[repo_install_sdk]
enabled = true

If you would like to run this process automatically during a build, add it to the post build commands:

[repo_build.post_build]
commands = [
    ["$root/repo${shell_ext}", "install_sdk", "-c", "$config"],
]

staging_dir

Sets the staging root folder for package links.

Required compile, link, and runtime dependencies will be downloaded & linked this folder.

Default value:

staging_dir = "$root/_install"

install_dir

Sets the install root folder.

Required runtime files will be assembled into this folder.

Default value:

install_dir = "$root/_install/$platform/$config"

usd

Sets the usd flavor.

Default value:

usd = ""

python

Sets the python version.

Use “0” to indicate that python should be disabled.

Default value:

python = ""

nucleus

Sets the nucleus enabled state.

Any value other than “off” indicates that the build is “with nucleus”.

Default value:

nucleus = ""

use_existing_build

Enable this to use an existing build of Connect SDK rather than download a package.

The Connect SDK distro must already exist in the install_dir or the process will fail.

Default value:

use_existing_build = false

repo_connect_client_config

Client Connectors are required to install an omni.connect.client.toml file alongside the toml config files from Connect SDK, in order to configure application specific settings. For more details, see Core and Client Settings.

Often the app & connector versions can be determined automatically during a build. Rather than hardcode those values in a source toml file, we provide a tool to automatically substitute them into a target toml file. This tool identifies special tokens %APP_VERSION% and %CLIENT_VERSION% and %PYTHON_VERSION% and substitutes them based on the tool configuration.

To use this tool add the following to your repo.toml along with any tool configuration overrides from the default values:

[repo_connect_client_config]
enabled = true

If you would like to run this process automatically during a build, add it to the post build commands:

[repo_build.post_build]
commands = [
    ["$root/repo${shell_ext}", "connect_client_config", "-c", "$config"],
]

source_file

Path to the source config file

Default value:

source_file = "source/config/omni.connect.client.toml"

target_file

Path to generate the target config file

Default value:

target_file = "$root/_build/$platform/$config/config/omni.connect.client.toml"

app_version

Either an explicit version string or a path to a file containing the app version

Default value:

app_version = ""

client_version

Either an explicit version string or a path to a file containing the client connector version

Default value:

client_version = "VERSION.md"

python_version

Either an explicit version string or a path to a file containing the python version

Default value:

python_version = "3.10"

repo_stubgun

Client Connectors can use repo_stubgen to generate Python Stubs for IntelliSense in IDEs. This tool is specifically adapted to work with pybind11 compiled bindings modules, as well as some OpenUSD module specifics.

Connect SDK ships stubs for its own modules, but OpenUSD does not currently ship stubs. You can use this tool to generate OpenUSD stubs or to generate stubs for your own compiled python modules.

Important

This tool requires repo_test to also be enabled in your repo. It uses repo_test underlying functionality to configure a runtime environment for your Connector. If that is not possible for your Connector, this tool will not work.

If you would like to generate stubs for your own python modules, add the following to your repo.toml along with any tool configuration overrides from the default values:

[repo_stubgen]
enabled = true

If you would like to run this process automatically during a build, add it to the post build commands:

[repo_build.post_build]
commands = [
    ["${root}/repo${shell_ext}", "stubgen", "-c", "${config}"],
]

pybind11_stubgen

Location of the pybind11_stubgen.py script

Default value:

pybind11_stubgen = "${root}/tools/repoman"

stubgen_include

Only generate stubs for python libraries within the subtree of these paths

Default value:

stubgen_include = ["${root}/_build/$platform/$config/python", "${root}/_build/$platform/$config/bindings-python"]

stubgen_exclude

Explicitly exclude stubs for python libraries on these paths, even if they would be included via the stubgen_include list

Default value:

stubgen_exclude = []

repo_version_header

Client Connectors can use repo_version_header to generate an include file (e.g. Version.h) for common precomplier macros based on repo_build_number.

For Windows builds, the tool can optionally generate a version.rc resource file, to embed the versioned assembly information into the final DLLs.

If you would like to generate these files, add the following to your repo.toml along with any tool configuration overrides from the default values:

[repo_version_header]
enabled = true
target_file = "include/foo/Version.h"
target_resource_file = "source/foo/version.rc"
company = "Foo Bar Inc."
product = "Omniverse"
component = "Foo Bar Connector"
macro_namespace = "OMNIFOO"

If you would like to run this process automatically during a build, add it to the fetch.after_pull_commands.

Important

This is different to other tools, where we usually suggest using post_build.commands. These files need to be in place before project generation occurs, and after fetch dependencies is the only hook available currently.

fetch.after_pull_commands = [
    ["${root}/repo${shell_ext}", "version_header"],
]

target_version_header_file

Path to generate the target Version.h file

Default value:

target_version_header_file = "include/omni/foo/Version.h"

target_resource_file

Path to generate the target version.rc resource file.

See https://learn.microsoft.com/en-us/windows/win32/menurc/versioninfo-resource for details.

If empty, no version.rc will be generated.

Default value:

target_resource_file = "source/foo/version.rc"

company

The company name

Default value:

company = "NVIDIA"

product

The overall product name

Default value:

product = "Omniverse"

component

The individual component of the product in human readable form

Default value:

component = "Foo Bar Connector"

macro_namespace

The namespace macro for the library

Default value:

macro_namespace = "OMNIFOO"

company_legal

The company name to use in legal blubs.

If empty, will fallback to company setting

Default value:

company_legal = "NVIDIA CORPORATION"

start_year_legal

Sets the start year for legal blurbs.

If empty, will fallback to the current year.

Default value:

start_year_legal = ""

generate_version_stub_file

Generates a sidecar $root/VERSION file.

This is a workaround for repo_docs not respecting repo.folders.version_file. Only set this flag if you use a non-standard version_file and you use repo_docs.

Default value:

generate_version_stub_file = false