Building Carbonite

Carbonite’s build system in completely self-contained. Any third party dependencies, such as Python, are dynamically downloaded by the build system at build time. In general, simply typing build should just work. No legwork tracking down tools and libraries is needed.

Building Source

To build on Windows:

# build both release and debug
build

# debug build
build -d

# release build
build -r

# clean build output
build -c

The commands above also work on Linux, though build should be replaced with ./build.sh.

./build.sh

Output from the build can be found in a platform/flavor subfolder of _build/. For example:

_build/windows-x86_64/release/

Improving Build Times

The build process is divided into a “generation” step and a “build” step. The generation step only needs to be run once (or anytime you change premake5.lua). You can skip the generation step and only proceed with the build step as follows:

build -b

You can also build individual targets. For example:

# build carb.dll
build -t carb

# build carb.tokens.plugin.dll
build -t plugins\carb.tokens.plugins

On Mac OS and Linux, ccache can substantially reduce build times when doing rebuilds. To use ccache, first install ccache (on Ubuntu: apt-get install ccache; on Mac OS, you can use homebrew: brew install ccache or macports: port install ccache), then add export CARB_CCACHE=ccache to your shell startup file (On Linux, the default shell is typically bash, so this will be $HOME/.bashrc. Mac OS uses zsh by default, so you need to use $HOME/.zshrc; if you switch to the version of bash Mac provides, it uses $HOME/.profile). This unfortunately will remove the colored highlighting from Clang/GCC’s diagnostics most of the time.

Tips

On Linux, the parallel build may make it difficult to read build warnings and serializing the build with -j1 is slow. You can avoid this slowdown by passing the -k parameter to make; this is done with the -e parameter of build.sh. This will rebuild everything possible, so you can run a serial build without having to wait as long.

# build everything possible
./build.sh -e-k

# serial build, so the error message is easier to read
./build.sh -j1

Carbonite supports a number of debugging features, such as Clang’s address sanitizer on Linux. Use ./build.sh --help to view the list of extra flags.

Building Documentation

Documentation is built as follows:

./repo docs

Output from the build can be found in:

_build/docs/carbonite/lastet

Curious readers can refer to How the Omniverse Documentation System Works for a deep-dive into how the documentation system works.

Tip

See Documentation Build Stages to decrease your build iteration time by understanding how the documentation build process works.