Repo Build Walkthrough#

A repo_build project needs a few components:

repo.toml#

This is the configuration file for every project. It must be present in the repo root. There are a few settings that should be enabled on any Omniverse project.

[repo_build]

# This defaults to "vs2017", but we standardize on "vs2019" now.
msbuild.vs_version = "vs2019"

# This affects the prebuild copy/link step from prebuild.toml and repo_build.prebuild_*() inside
# premake5.lua.
# This will cause the step to fail if you try to copy a nonexistent file. This is false by
# default but should be set to true wherever possible.
stage_files.error_if_missing = true

deps/repo-deps.packman.xml#

This specifies the repo tools that you want to use. You need repo_man and repo_build for any project. Internal to NVIDIA, you will need a version of repo_licensing if you’re redistributing dependencies.

<dependency name="repo_man" linkPath="../_repo/deps/repo_man" tags="non-redist">
  <package name="repo_man" version="1.68.1" />
</dependency>
<dependency name="repo_format" linkPath="../_repo/deps/repo_format" tags="non-redist">
  <package name="repo_format" version="2.13.0" />
</dependency>

deps/host-deps.packman.xml#

This specifies build tools you want to download for your project. Platform-specific packages, such as premake, will use the platform of the host system in this case. It is typically necessary to list the platforms on host dependencies in the xml because Mac OS packages are typically compiled as a universal binary. If you want to add additional host dependency files to the build, you can override repo_build.fetch.packman_host_files_to_pull and add additional deps files to the list.

<project toolsVersion="5.0">
  <dependency name="premake" linkPath="../_build/host-deps/premake" tags="non-redist">
    <package name="premake" version="5.0.0-beta2+nv1-${platform}" platforms="linux-x86_64 linux-aarch64 windows-x86_64"/>
    <package name="premake" version="5.0.0-beta2+nv1-macos-universal" platforms="macos-x86_64 macos-aarch64"/>
  </dependency>
  <dependency name="compiler" linkPath="../_build/host-deps/compiler" tags="non-redist">
    <package name="compiler" version="2022-1.2.3" platforms="windows-x86_64" />
  </dependency>
</project>

deps/target-deps.packman.xml#

This specifies packages you want to use for your project. This is intended to be used for build-time and runtime dependencies. Platform-specific packages will use the platform target that you are building for, which may differ from the host platform when cross-compiling. Mac OS projects, for example, typically build for macos-universal despite building on macos-x86_64 or macos-aarch64. It is typically not necessary to specify platforms in the xml for each package unless a package is not available for all target platforms. If you want to add additional host dependency files to the build, you can override repo_build.fetch.packman_host_files_to_pull and add additional deps files to the list.

<project toolsVersion="5.0">
  <dependency name="opus" linkPath="../_build/target-deps/opus-${config}" >
    <package name="opus" version="1.3.1-1-${platform}-static-${config}" />
  </dependency>
  <dependency name="devsdk" linkPath="../_build/host-deps/devsdk" tags="non-redist">
    <package name="devsdk" version="16.0.0" platforms="windows-x86_64"/>
  </dependency>
</project>

Note

If building for Linux and using the --abi argument or setting the abi token in repo.tokens, the packman dependency fetching stage of repo_build will change your target platform from linux-${arch} to manylinux_${underscore_abi}_${arch}. For example repo.sh build --abi=2.35 on linux-x86_64 would yield a packman platform of manylinux_2_35_x86_64. Additionally ${platform_target_abi} is a special token that by default is set to ${os}-${arch} but when --abi is set on Linux will be set to manylinux_${underscore_abi}_${arch}. In both cases the new ${platform_target} token will yield linux-x86_64. The below is a sample target-deps.packman.xml that targets a newer manylinux zlib package for manylinux platforms, but targets the same python interpreter package for all builds.

<project toolsVersion="6.11" chroniclePath="../_build/chronicles">
  <dependency name="zlib" linkPath="../_build/target-deps/abi_zlib">
    <package name="zlib" version="2.0.0-0-${platform_target_abi}-static-release" platforms="manylinux_2_35_x86_64" />
    <package name="zlib" version="1.3.1-0-${platform}-static-release" platforms="linux-x86_64" />
  </dependency>
  <dependency name="python">
    <package name="python" version="3.10.11+nv1-${platform_target}" />
  </dependency>
</project>

tools/packman/**#

This is the tool used to pull down the repo_* packages.

The only file you need to look at is tools/packman/config.packman.xml

<config remotes="cloudfront">
    <!-- repo_* are hosted here. You will need this endpoint for these tools to work at all. -->
    <remote2 name="cloudfront">
        <transport actions="download" protocol="https" packageLocation="d4i3qtqj3r0z5.cloudfront.net/${name}@${version}" />
        <transport actions="upload" protocol="s3" packageLocation="packages-for-cloudfront" />
    </remote2>
</config>

tools/repoman/*#

This directory contains bootstrap scripts for these tools. You can copy this from the repo_man repo here: https://gitlab-master.nvidia.com/omniverse/repo/repo_man

tools/repo.sh and tools/repo.bat#

These are platform-specific launcher scripts for repo_man. These bootstrap and launch into repo_man to build your project.

premake5.lua#

This file specifies how your project is built. This is a sample demonstrating a minimal C++ project. See build.lua for documentation of the repo_build lua API used here.

-- This is the build module from repo_build. This does most of the work to set up your project.
local repo_build = require("omni/repo/build")

-- Inform repo_build about where the root of your project is (`os.getcwd()` evaluates to the
-- current lua file being executed, not the shell's working directory).
-- By default, repo_build uses `%{root}` since it doesn't know where the root of your project is.
-- `%{root}` usually evaluates to the current lua file being executed (it evalutes to unexpected
-- values in some cases), so you need to set this value if your project uses multiple lua files.
repo_build.root = os.getcwd()

-- This adds a bunch of command line options to premake.
-- This is required to add the --platform-host option that premake adds.
-- You can look through build.lua for details.
repo_build.setup_options()

workspace "project"
    -- Set up the project workspace.
    -- This will add support for all standard Omniverse platforms (e.g. windows-x86_64,
    -- linux-x86_64, linux-aarch64, macos-universal).
    -- You can disable specific platforms with the arguments to this function.
    repo_build.setup_workspace {
        -- These parameters are necessary if you're targeting windows-x86_64.
        -- Replace them with the actual versions in-use.
        msvc_version = "14.29.12345",
        winsdk_version = "10.0.0.0",

        -- Disable the macos-universal platform target. Other platforms can be disabled similarly.
        macos_universal_enabled = false,

        -- This option defaults to true. This will copy vcruntime140d.dll and ucrtbased.dll into
        -- the target directory on Windows. If this is not set to false, you need to ensure your
        -- project does not redistribute these binaries.
        copy_windows_debug_libs = false,

        -- This will set the warning level on the compiler to extra. This is disabled by default.
        -- This setting is recommended when possible.
        extra_warnings = true,

        -- Add some extra security settings like -fstack-protector-strong. This is off by default.
        -- This setting usually has a negligible performance impact but it is recommended if
        -- you're handing unsanitized user data.
        security_hardening = true,

        -- Use the gold linker instead of ld to speed up linking.
        -- Note that you may need to add linkoptions{"-Wl,--disable-new-dtags"} if you get library
        -- loading failures at runtime.
        linux_linker = "gold",
    }

    includedirs { "include" }


project "example"
    kind "ConsoleApp"
    files { "source/*.cpp", "source/*.h" }

conanfile.txt or conanfile.py#

There is rudimentary support for retrieving project dependencies via Conan by defining a Conan-2.0 valid Conanfile. If you want to use Conan to pull your dependencies at a minimum you must enable repo_build.conan.enabled and it will default to searching for a top-level conanfile.py or conanfile.txt. Reference the repo_build.conan configuration options, there are several knobs for manipulating where Conan-specific directories and files are located in your repository. Currently on Linux repo build will pull clang 16.0.6-0-${platform}-release via Packman at build time in order to build Conan dependencies from source that are missing a binary distribution.

On this page