Deploying a Carbonite Application

Applications developed with the Carbonite SDK will need to redistribute some of its components to function correctly.

The Carbonite package for applications is carb_sdk+plugins.${platform} and is distributed via Packman. You can use the Packman search tool to find package versions.

Generally speaking, there is little harm in redistributing too many files. If in doubt, redistribute it.

Redistributable

The package contains a _build/{platform}/{config} directory where binary artifacts that must be redistributed are placed. Not all of these files will need to be redistributed. The following sections describe the requirements in more details.

Debug vs Release

The package contains both debug and release builds of binaries. If debugging Carbonite itself is not desired, your application can use the release binaries, even if the application itself is built as debug. This also tends to be faster at runtime as the debug binaries are non-optimized and therefore less performant.

On Windows, the debug binaries may require debug runtime libraries. Carbonite is not licensed to distribute the Microsoft debug runtime files, so these files must be sourced elsewhere. A possible means of acquiring the debug Microsoft libraries is to install a version of Microsoft Visual Studio.

Core Library

If you are using the Carbonite Framework with plugins, or Omniverse Native Interfaces, or the Carbonite memory management functions (i.e. carb::allocate()) you will need to package the core library along with your application. This is carb.dll (Windows), libcarb.so (Linux) or libcarb.dylib (Mac).

Plugins

Only the plugins that your application uses (and their recursive dependencies) must be redistributed. For instance, few applications use carb.simplegui.plugin though it is among the largest Carbonite plugins. It need not be redistributed with your application if it is not being used.

However, keep in mind that there may be dependencies between plugins. For instance, carb.settings.plugin requires carb.dictionary.plugin. The provided plugin.inspector tool application can be used to examine these dependencies.

Python

Carbonite provides a means of embedding Python through carb.scripting-python.plugin. Python 3.7 and 3.10 are both offered. These are meant to be singular: that is, only one version of Python may be loaded into an application. The contents of the scripting-python-${version} directory must be redistributed along with your application if you use embedded Python.

Python Bindings

If you are using the Carbonite plugins through embedded Python, or are running as a Python application (i.e. started from Python), then you likely also want to include the relevant portions of the bindings-python directory.

Python uses dot-notation with the import directive to load python code from directories and packages. .py files may exist loose in a directory to comprise a package, or compiled into a library file (a .pyd file on Windows or .so file on Linux/Mac). Carbonite Python Bindings are generally compiled into a library file.

In some cases, Carbonite Python Bindings are prefixed with an underscore (i.e. _carb) and a wrapper __init__.py file is used to import and augment the library package contents. In these cases, both the library with the underscore prefix and the __init__.py file must be redistributed in the same directory structure layout.

Since Python interprets directories as package names, the directory structure is important. Therefore, it is important that the directory structure under bindings-python is replicated in your application distribution, and the root of the bindings is added to the PYTHONPATH environment variable.

Bindings are available for the following versions of Python, identified by the cpXXX number in their filename: 3.7 (cp37), 3.8 (cp38), 3.9 (cp39), 3.10 (cp310). Only the version that is in use must be redistributed.

Core library bindings

The Core library bindings are prefixed with _carb and located in the bindings-python/carb directory. The __init__.py is also required to be redistributed along with the Core library bindings. The Core library bindings are required if you are redistributing any of the other bindings (or have your own bindings for additional plugins).

Plugin bindings

Plugins that do not have an associated __init__.py file are located in either the carb or omni subdirectories of bindings-python and do not have an underscore prefix.

Plugins that have an associated __init__.py are located in an additional subdirectory. The subdirectory name must be redistributed along with the binding library for the desired version of Python as well as the __init__.py file.

Platform Specific

Windows

Some plugins may require the Visual Studio 2019 Runtime Redistributable. The files therein are not distributed as part of the carb_sdk+plugins package and must be sourced separately. Typically the files required would be located in the /X64/Microsoft.VC142.CRT directory: vcruntime140*.dll and msvcp140*.dll.

In some cases the Windows SDK runtime is required as well: x64/ucrtbase.dll.

If carb.profiler-nvtx.plugin is redistributed, the nvToolsExt64_1.dll file must also be present in the same directory.

Linux

If carb.profiler-nvtx.plugin is redistributed, the libnvToolsExt.so file must also be present in the same directory.

Telemetry Transmitter

If an application makes use of omni.structuredlog.plugin to gather telemetry data, the omni.telemetry.transmitter application can be used to send the gathered information to a server that collects this data. The omni.telemetry.transmitter application changes less frequently and is distributed via Packman in a separate package: telemetry_transmitter.${platform}. The entire contents of _build/${platform}/release from within that package should be redistributed along with your application in a separate directory.

Warning

The telemetry_transmitter package contains copies of various plugins required by the transmitter. It is generally assumed that these are older versions than the plugins from the carb_sdk+plugins package, and should be located in a separate directory and loaded only by the transmitter.

Symbols

Symbols are not distributed along with any of the Carbonite packages. Instead they are stored at build time using the repo_symbolstore utility.