Configuring repo_build#

This page outlines available configuration values which can be used with repo_build in the repo.toml file.

[repo_build]#

Top-level config values.

repo_build.verbose#

By default, projects are not verbose when they compile. This setting changes them to be verbose by default.

Either way, the command line can be used to override the setting; the command line always has precedence.

Default value:

verbose = false

repo_build.build_configs#

All build configs supported

Default value:

build_configs = ["debug", "release"]

repo_build.default_build_config#

The build config to use when no arguments are passed.

When not empty, this overrides repo.default_build config.

This allows you to specify an array of configurations for the default build config.

Default value:

default_build_config = []

repo_build.disable_ci_config_check#

This can be set to true to allow the default build configuration to be used on CI.

This is not allowed by default because the default build configuration changed in 0.34.0.

Default value:

disable_ci_config_check = false

Platform Filters#

repo_build config supports additional platform filters: platform_target:windows-x86_64 in configs, to make custom settings for target platform, in addition to repo_man’s platform:... filters (see repo_man repo_tools.toml file). An example might be:

foo.x = 2
foo."platform_target:linux-x86_64".x = 3 # Set x to 3 on linux.

[repo_build.clean]#

Section related to -c/–clean, -x/–rebuild CLI flags.

repo_build.clean.enabled#

Some repos are designed in a manner that does not allow them to be cleaned (older Omniverse repos).

Therefore this step can be disabled and handled as a separate concern.

Default value:

enabled = true

repo_build.clean.folders#

List of folders to remove when running in “partial clean mode” (-f flag)

Default value:

folders = ["${root}/_build", "${root}/_compiler", "${root}/_builtpackages"]

[repo_build.fetch]#

Section for “dependency fetch step” setup configuration.

repo_build.fetch.packman_host_files_to_pull#

List of packman dependency files to pull (in order), with host-platform passed in as a key.

Default value:

packman_host_files_to_pull = [
    "${root}/deps/host-deps.packman.xml",
]

repo_build.fetch.packman_target_files_to_pull#

List of packman dependency files to pull (in order), with target-platform passed in as a key.

Default value:

packman_target_files_to_pull = [
    "${root}/deps/target-deps.packman.xml",
    "${root}/deps/assets.packman.xml",
]

repo_build.fetch.packman_extra_tokens#

Extra key-value-pair tokens to pass in when resolving packages in packman.

Default value:

packman_extra_tokens = {}

repo_build.fetch.packman_exclude_tags#

A list of strings to packman pull as ‘exclude_tags’. Tags can be added to packman dependencies via a tags keyword

and a space separated list of values. exclude_tags provide a mechanism to filter out dependencies for certain operations.

For example, with a dependency tagged as “non-redist”

<dependency name="python" linkPath="../_build/target-deps/python" tags="non-redist foo bar">

and packman_exclude_tags = ["non-redist"], we can prevent pulling this dependency during a packaging process.

Default value:

packman_exclude_tags = []

repo_build.fetch.enable_exclude_configs_tags#

Pass excluded configs (say “release” in case of “debug” build) to packman pull as ‘exclude_tags’.

This extends the packman_exclude_tags setting with the additional config tags.

Default value:

enable_exclude_configs_tags = true

repo_build.fetch.generated_packman_file#

Generate a Packman project file that will contain all dependencies that were pulled, to package and use downstream.

Example: "${root}/_build/$platform/$config/dev/all-deps.packman.xml"

Default value:

generated_packman_file = ""

repo_build.fetch.before_pull_commands#

Multiple commands (processes) can be executed in order before pulling.

Example:

before_pull_commands = [
    ["${root}/repo${shell_ext}", "-c", "${config}"]
]

Default value:

before_pull_commands = []

repo_build.fetch.after_pull_commands#

Multiple commands (processes) can be executed in order after pulling.

after_pull_commands = [
    ["${root}/repo${shell_ext}", "-c", "${config}"]
]

Default value:

after_pull_commands = []

[repo_build.fetch.pip]#

Subsection for Python dependency fetch via pip

repo_build.fetch.pip.files_to_pull#

List of pip files to pip install from (in order)

Default value:

files_to_pull = [
    "${root}/deps/pip.toml"
]

repo_build.fetch.pip.licensing_enabled#

Enable gathering of pip package licenses.

This flag is separate from repo_build.licensing.enabled to retain existing behavior, being able to turn licensing off for components separately.

Default value:

licensing_enabled = true

repo_build.fetch.pip.gather_licenses_path#

The filepath to gather pip package licenses to.

Default value:

gather_licenses_path = "${root}/_build/PACKAGE-LICENSES/PIP-packages-LICENSES.txt"

repo_build.fetch.pip.packman_remote#

Packman remote to push a cache of the pip.toml installed packages to.

Credentials to push to that remote must be set independently, e.g. as part of CI.

Default value:

packman_remote = "cloudfront"

repo_build.fetch.pip.kit_extension_configs_search_wildcards#

Wildcard-enabled (** or * can be used) path, used to search for kit extension configs, in order to look for pip packages in their omni.kit.pip_archive key, to have licenses gathered.

Default value:

kit_extension_configs_search_wildcards = [
    "${root}/source/extensions/**/extension.toml"
]

repo_build.fetch.pip.ignore_pip_cache_failure#

By default repo_build will try to cache pip.toml Python dependencies as a repo_pip_cache package that will be pushed to the configred S3 remote via Packman. Usage of this can speed up rebuilds where the pip.toml hasn’t changed. However, this will cause failures if your CI build stage does not have permission to publish to the S3 remote. Set this to True to ignore those failures.

Default value:

ignore_pip_cache_failure = false

repo_build.fetch.pip.publish_pip_cache#

If you want to skip packaging and publishing the repo_build pip package cache to S3 via Packman, or if you know your project will never have the necessary credentials to do such a thing, you can outright skip this stage by setting this to false. This will cause repo_build to skip trying to retrieve your dependencies from the cache as well.

Default value:

publish_pip_cache = true

[repo_build.premake]#

Section for premake setup configuration.

repo_build.premake.enabled#

Calls premake to generate makefile/sln project files. Disable this, and disable repo_build.build, to turn repo_build into just a dependency fetching tool that can optionally calls arbitrary pre/post-fetch commands via repo_build.fetch.before_pull_commands and repo_build.fetch.after_pull_commands.

Default value:

enabled = true

repo_build.premake.extra_args#

Additional arguments to pass to premake.

Default value:

extra_args = []

repo_build.premake.pass_platform_target#

Enable passing a –platform-target argument to premake (needs to be defined in your root premake5.lua)

Default value:

pass_platform_target = false

repo_build.premake.linux_x86_64_cxx_abi#

Enables use of the C++11 ABI on linux-x86_64.

The same effect occurs by setting a premake argument which passes –linux-x86_64-cxx11-abi=true.

Default value:

linux_x86_64_cxx_abi = false

[repo_build.pre_build]#

Section for custom “pre build” step configuration.

repo_build.pre_build.commands#

Multiple commands (processes) can be executed in order during the generation step.

These commands will not run if you build from Visual Studio!

If you use the ${config} token in the command, it will be run once per config. Otherwise it will only be run once.

These each execute a program with a set of arguments; they are not shell commands, so commands that run successfully on your shell may not work here. You can test your command using subprocess.Popen([...]) in python.

Cygwin’s git actually enforces the executable bit on .bat files on Windows, so this could break the build for Cygwin users. If you are using this, please document your project to specify that Cygwin is not supported or add the executable bit to these files in git.

Example:

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

Default value:

commands = []

[repo_build.build]#

Section for “build” step configuration.

repo_build.build.enabled#

The build step can be disabled and ignored. Typically used with python-only projects with no toolchain.

Default value:

enabled = true

repo_build.build.error_processing#

Enable post-processing of the log emitted from the build to scan for targeted error patterns, and dump them with context at the end of the build.

Useful for drawing attention to compiler errors on CI without manually searching, or needing to know what to grep for.

Default value:

error_processing = true

repo_build.build.error_patterns#

Regex patterns to match log text against as errors. This sample works for GCC and MSBuild compilation errors.

These defaults are also set in omni.repo.build.settings.py.

You can just set error_processing = true and rely on these hard-coded defaults.

Default value:

enabled = true

repo_build.build.error_context#

Optionally configure error_context, which indicates the number of lines to select before and after a error_pattern match. This is a one size fits most approach for now. By default 2 lines before and 2 lines after are hard-coded in omni.repo.build.settings.py

Example:

error_context = [2,2]

Default value:

error_context = []

repo_build.build.job_count#

You have several options for limiting the number of parallel build processes repo_build kicks off. The first is via this config file/your repo.toml/your global or project local toml files (reference the repo_man global config). Setting repo_build.build.job_count will set a static limit. The next check is the OMNI_REPO_BUILD_JOBS environment variable, this will override the static config file value. Lastly the --jobs CLI argument will override everything.

Default value:

job_count = -1

repo_build.build.core_percentage#

To further complicate things you can also set the following flag to instruct repo_build to use a percentage of the host’s CPU cores. This matches up with the --core-percentage argparse flag, and supercedes any job_count/--jobs value. This will also inspect cgroups for accurate core counts in container systems if applicable.

Example:

core_percentage = 50

Default value:

# (Unset)

repo_build.build.mem_per_core#

If you are concerned about potentially thrashing the memory of your build machine, you can set a limit on how much memory you want available for each core when determining how many cores to allocate by setting repo_build.build.mem_per_core - This option accepts an int and is processed in gigabytes per core.

Default value:

mem_per_core = 4
# This default on Windows seems to limit the job count to a value that doesn't
# completely hitch/hang a host without wrecking compilation performance.
"platform:windows-x86_64".mem_per_core = 3

repo_build.build.max_cores#

In the circumstance where cgroups v2 returns a cpu.max of “max” we need some numerical value to set as an absolute cap on the number of cores to utilize.

Default value:

max_cores = 32

repo_build.build.msbuild_renice#

This setting will kick off a msbuild compiler watchdog that repeatedly sets all instances of cl.exe to Idle priority and tries to isolate cores 0 and 1 from cl.exe.

This will slow compilation times slightly at the benefit of not turning your Windows experience into a slideshow of functionality.

This is best set in a local user.repo.toml or global `global_repo.toml.

This setting can also be toggled via the --msbuild-renice argparse flag.

Default value:

msbuild_renice = false

[repo_build.post_build]#

Section for “post build” step configuration

repo_build.post_build.commands#

Multiple commands (processes) can be executed in order after build.

These have the same behavior as repo_build.pre_build.commands, except that they run after the build.

Example:

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

Default value:

commands = []

[repo_build.msbuild]#

Section for msbuild setup configuration.

repo_build.msbuild.sln_file#

Solution file name

Default value:

sln_file = "solution.sln"

repo_build.msbuild.vs_version#

Visual Studio version

Default value:

vs_version = 'vs2019'

repo_build.msbuild.link_host_toolchain#

If set to true, repo_build will attempt to link to the host’s Visual Studio and Windows SDK installations.

Default value:

link_host_toolchain = false

repo_build.msbuild.vs_path#

Visual Studio path; This will be used if the user would like to point to a specific VS installation rather than rely on heuristic locating.

Example:

vs_path = "C:\Program Files\Microsoft Visual Studio\2022\Community\"

Default value:

# (Unset)

repo_build.msbuild.vs_edition#

Filter any Visual Studio installations specifically to “Enterprise”, “Professional”, or “Community” editions of Visual Studio.

Example:

vs_edition = "Community"

Default value:

# (Unset)

repo_build.msbuild.msvc_version#

Filter any Visual Studio installations specifically to ones that have installed this version of the MSVC compiler.

Example:

msvc_version = "143"

Default value:

# (Unset)

repo_build.msbuild.msbuild_version#

Filter any Visual Studio installations specifically to ones that ship with an MSBuild of this major version.

Example:

msbuild_version = "17"

Default value:

# (Unset)

repo_build.msbuild.winsdk_version#

Windows SDK version

Example:

winsdk_version = "10.0.17763.0"

Default value:

# (Unset)

repo_build.msbuild.winsdk_path#

Windows SDK path; This will prevent needing to dynamically locate an installation by guesswork.

Example:

winsdk_path = "C:\\Program Files (x86)\\Windows Kits\\10\\bin\\10.0.17763.0"

Default value:

# (Unset)

repo_build.msbuild.prefer_devenv#

Attempt to search for devenv.exe installations and prefer it over MSBuild on windows. It may handle incremental builds better.

Default value:

prefer_devenv = false

[repo_build.partial_clean]#

Section for “partial clean” (-f/–fast-rebuild flag) step configuration.

repo_build.partial_clean.folders#

List of folders to remove when running in “partial clean mode” (-f flag).

Default value:

folders = ["${root}/_build/$platform/$config", "${root}/_build/generated"]

[repo_build.stage_files]#

Section for “stage files” (copy and folder linking) step configuration.

repo_build.stage_files.prebuild_files#

List of prebuild files (stage files configs) to process

Default value:

prebuild_files = [ "${root}/prebuild.toml", "${root}/_build/generated/prebuild.toml"]

repo_build.stage_files.extra_mapping#

Additional tokens to be used in stage files config (like prebuild.toml)

Example:

extra_mapping = { "foo": ${root}/_build/foo }

Default value:

extra_mapping = {}

repo_build..stage_files.error_if_missing#

Produce errors if one of staging entries missing.

Default value:

error_if_missing = false

repo_build.stage_files.allowed_paths#

List of paths that must be allowed to link and copy to, otherwise an error is produced. If empty, the check is ignored.

Default value:

allowed_paths = ["${root}/_build"]

[repo_build.vscode]#

Section for vscode+python setup configuration.

repo_build.vscode.python#

# Path to python to set into host-deps. By default use PM_python_DIR env var.

Default value:

python = "${env:PM_PYTHON_DIR}"

repo_build.vscode.#

Generate python_${config}.env files

Default value:

generate_python_env_file = true

repo_build.vscode.python_env#

# Dict with env vars to write into python env files.

Default value:

python_env.PYTHONPATH = [
        "$${PYTHONPATH}",
        "${env:PYTHONPATH}",
        "$root/_build/pip-packages",
        "$repo_deps/repo_man",
        "$repo_deps/repo_build",
        "$repo_deps/repo_fileutils",
        "$repo_deps/repo_format",
        "$repo_deps/repo_package",
        "$root/tools/repoman",
        "$root/_build/$platform/$config/bindings-python",
]

python_env.PATH = ["$${PATH}", "$root/_build/$platform/$config"]

repo_build.vscode.python_env_extra_mapping#

Additional mappings/tokens to write into the VSCode python env dict.

Default value:

python_env_extra_mapping = {}

repo_build.vscode.generate_python_setup_shell_script#

Generate setup_python_${config}.bat/.sh

Default value:

generate_python_setup_shell_script = true

repo_build.vscode.write_python_paths_in_settings_json#

Fill up ‘python.analysis.extraPaths’ of .vscode/settings.json file

Default value:

write_python_paths_in_settings_json = false

repo_build.vscode.settings_template_file#

Settings template file to copy from

Default value:

settings_template_file = "$root/.vscode/settings.template.json"

[repo_build.docker]#

Section for docker setup configuration. Only applies to linux.

repo_build.docker.enabled#

Currently repo_build’s docker integration through linbuild is an NVIDIA-internal feature.

This will likely change in the future. It is recommended that external users disable this feature, and run their linux builds within containers chosen for their requirements.

Each kit version and product may have specific requirements that should be outlined with their projects.

Relaunch build in docker on linux. Assumes _build/host-deps/linbuild/linbuild.sh will exist.

Default value:

enabled = true

repo_build.docker.image_url#

If specified, will use the docker image located at image_url to perform the build.

Example:

image_url = "DOCKER_IMAGE_NAME:TAG"

Default value:

# (Unset)

repo_build.docker.linbuild_version#

Linbuild version to install (if not installed already / default path doesn’t exist)

Default value:

linbuild_version = "3.6.0-${platform}"  # Not a public version

repo_build.docker.linbuild_extra_args#

Extra args to pass to linbuild

Default value:

linbuild_extra_args = []

repo_build.docker.extra_volumes#

List of extra folders to pass to docker –with-volume.

Default value:

extra_volumes = []

repo_build.docker.kit_user_file_path#

Kit user file used to source link extensions

Default value:

kit_user_file_path = "${root}/deps/user.toml"

repo_build.docker.use_host_home_dir#

Use host $HOME in linbuild. Kit can access $data/$cache dirs and have shared extension download cache.

Default value:

use_host_home_dir = false

[repo_build.licensing]#

Section for licensing setup configuration.

repo_build.licensing.enabled#

Currently repo_builds licensing integration is NVIDIA-internal only. External users should disable this. The repo_licensing tool may be made public in the future to enable this feature.

Enable license gathering. If enabled, repo_build expects the repo_licensing tool to be available in sys.path. Ensure that it is included in your repos ‘repo-deps.packman.xml’.

Default value:

enabled = false

repo_build.licensing.run_by_default#

Set this to false if you want to disable the licensing step when no arguments are passed.

You will be able to re-enable licensing using the –licensing flag.

Licensing can be very slow and does not reuse progress, so this is encouraged during development.

Default value:

run_by_default = true

repo_build.licensing.directory#