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.