Skip to content

building_and_distribution.md

Latest commit

 

History

History
255 lines (194 loc) · 9.79 KB

building_and_distribution.md

File metadata and controls

255 lines (194 loc) · 9.79 KB
Raw

Building and Distribution

Requirements

  • CUDA Toolkit 12.8+
  • cuDNN 9 for CUDA 12 (CI installs cuDNN 9.5.0 only when the runner image does not already provide it)
  • CMake 3.30+
  • vcpkg (VCPKG_ROOT environment variable set)
  • GCC 14+ (Linux) or Visual Studio 2022 v17.10+ (Windows)

Windows builds require the C++ Clang Compiler for Windows Visual Studio Installer individual component in addition to the regular C++ desktop workload. It provides clang-cl, which is used only to build libplacebo (an unconditional dependency of the standard build) with a Microsoft-compatible ABI. The port locates clang-cl.exe on PATH or under VSINSTALLDIR/VCINSTALLDIR (for example from the x64 Native Tools Command Prompt). MSBuild support for LLVM (clang-cl) toolset is optional and only needed if you want the LLVM toolset selectable in Visual Studio IDE projects; the vcpkg port itself does not use MSBuild. The rest of LichtFeld Studio continues to use the configured Visual Studio/MSVC toolchain.

On Windows, set CUDNN_ROOT_DIR to the cuDNN version root so the build can copy the CUDA-versioned cuDNN runtime DLLs next to the executable and into portable installs:

set CUDNN_ROOT_DIR=C:\Program Files\NVIDIA\CUDNN\v9.24

For unusual layouts, pass -DLFS_CUDNN_BIN_DIR=... directly to the cuDNN DLL directory, for example ...\bin\<cuda-version>\x64.

Contributor Setup

Install the repository's pre-commit hook after cloning:

cp tools/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

The hook applies clang-format to staged C, C++, and CUDA source files outside external/ before each commit.

Linux Prerequisites

On Linux, LichtFeld Studio requires SDL3 to be built with at least one windowing backend (x11 or wayland). SDL3's vcpkg port can otherwise build "successfully" and produce a binary that fails at startup with No available video device.

Debian/Ubuntu packages used by CI:

sudo apt install \
  git curl unzip cmake gcc-14 g++-14 ccache ninja-build zip tar pkg-config python3 python3-dev \
  libxinerama-dev libxcursor-dev xorg-dev libglu1-mesa-dev \
  libwayland-dev libxkbcommon-dev libegl-dev libdecor-0-dev libibus-1.0-dev libdbus-1-dev \
  libsystemd-dev libgtk-3-dev nasm autoconf autoconf-archive automake libtool

libgtk-3-dev is required because nativefiledialog-extended is built from source on Linux against its GTK backend rather than taken from vcpkg; see cmake/SetupNativeFileDialog.cmake. Without it configure fails with pkg-config could not locate gtk+-3.0``.

The configure step now fails early if neither a usable X11 stack nor a usable Wayland stack is present. If you intentionally want a headless or experimental build, pass -DLFS_ENFORCE_LINUX_GUI_BACKENDS=OFF.

Build Options

1. Native Build (Development)

Builds for your GPU only. Fastest compile time.

cmake -B build
cmake --build build -j 16
./build/LichtFeld-Studio --help

# Example training run
./build/LichtFeld-Studio -d /path/to/data -o /path/to/output

2. Portable Build (Distribution)

Creates a self-contained package that works on any machine with an NVIDIA driver.

cmake -B build -DBUILD_PORTABLE=ON
cmake --build build -j 16
cmake --install build --prefix ./dist

./dist/bin/run_lichtfeld.sh --help

# Example training run
./dist/bin/run_lichtfeld.sh -d /path/to/data -o /path/to/output

Tests

The tensor comparison tests validate the built-in tensor library against LibTorch as an oracle, so a LibTorch SDK is required to configure the test build. It is not needed for the application itself, which is LibTorch-free.

Download the LibTorch C++ SDK matching your CUDA version from pytorch.org (select LibTorch as the package and C++/Java as the language) and unpack it so TorchConfig.cmake resolves:

Platform Expected location
Linux external/libtorch/
Windows (Release) external/release/libtorch/
Windows (Debug) external/debug/libtorch/ 
# Linux, from the repository root
curl -L -o libtorch.zip "<libtorch-download-url>"
unzip -q libtorch.zip -d external/

Configuring without it fails at find_package(Torch REQUIRED). Some LibTorch builds link CUDA libraries they do not ship; if the test binaries then fail to start with a missing shared library, install the named library or use a build that bundles its CUDA dependencies.

Tests are a separate opt-in build:

cmake -S . -B build/tests -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_TESTS=ON
cmake --build build/tests \
  --target lichtfeld_tests tensor_hardening_tests \
  -j6

Run the CTest label that matches the subsystem and cost of the change:

Label Use it for
fast Default developer loop: core unit tests, fast Python tests, focused GPU contracts, and some real-data loader checks
slow Dataset loaders, training, interop, and other multi-second integration paths
nightly Stress, large-tensor, real-data, and optional-codec coverage
hardening Isolated tensor hardening and crash-prone oracle tests
discovery Discovery fuzzing and parameter sweeps
gpu All registered tests that require GPU execution

For example:

ctest --test-dir build/tests --output-on-failure -L fast
ctest --test-dir build/tests --output-on-failure -L slow
ctest --test-dir build/tests --output-on-failure -L nightly

Localization contracts

The localization contracts are a small, headless validation suite. They validate locale key and placeholder parity, one-key-per-line JSON formatting, literal translation-key references, RML directives, count-sensitive plural-form rules, the hardcoded-UI-text audit, and localized cached UI state. They do not build or execute the GUI, LibTorch, or CUDA test targets. The contributor guide documents the locale conventions and language-specific grammar policy.

Register the contracts in an existing build directory:

cmake -S . -B build -DBUILD_LOCALIZATION_TESTS=ON
cmake --build build --target test_localization_contracts

The custom target runs the single CTest entry named LocalizationContracts. It can also be invoked directly after configuration:

ctest --test-dir build/tests --output-on-failure -R LocalizationContracts

The repository intentionally ignores data/, but several fast, slow, nightly, and GPU tests read real files from data/bicycle or data/garden. Populate those paths with compatible real datasets before running the affected tiers. Synthetic placeholder input is not a substitute: loader, training, image-codec, and checkpoint tests assert the expected images, masks, COLMAP files, or point cloud exist on disk.

What's the Difference?

Native Build Portable Build
Output build/LichtFeld-Studio (66 MB) dist/ folder (518 MB)
Target needs CUDA Yes No
Target needs vcpkg Yes No
Self-contained No Yes
Use case Development End-user distribution

Distribution Contents

dist/
├── bin/
│   ├── LichtFeld-Studio
│   └── run_lichtfeld.sh    # Use this to launch
├── lib/                    # Bundled CUDA & runtime libs
├── share/LichtFeld-Studio/ # Shaders, icons, fonts
└── LICENSE                 # GPL-3.0

CMake Options

Option Default Description
BUILD_PORTABLE OFF Create self-contained distribution
BUILD_CUDA_PTX_ONLY OFF PTX-only build (auto-enabled by PORTABLE)
BUILD_CUDA_MIN_SM 75 Minimum GPU (75=Turing, 80=Ampere, 89=Ada)
BUILD_TESTS OFF Build test suite
BUILD_LOCALIZATION_TESTS OFF Register headless localization contract tests
LFS_ENFORCE_LINUX_GUI_BACKENDS ON Linux only. Fail configure if SDL3 would be built without both X11 and Wayland
LFS_CUDA_COMPILER_CACHE (empty) Compiler cache for CUDA only. Empty follows the auto-detected launcher; OFF disables CUDA caching; or name/path of a launcher such as ccache. Needed where nvcc cannot be wrapped by sccache

ONNX Runtime is consumed as a pinned prebuilt GPU SDK on x64 Windows and Linux instead of being built by vcpkg. The default SDK is controlled by LFS_ONNXRUNTIME_VERSION; set LFS_ONNXRUNTIME_ROOT to an unpacked ONNX Runtime SDK to use a local or custom build. Set LFS_ONNXRUNTIME_USE_PREBUILT=OFF to fall back to a package-provided onnxruntime CMake config.

Preprocess Model Downloads

The preprocess subcommand downloads the default MoGe-2 ONNX model on first use when --model is not provided. The cached model and every downloaded temporary file are SHA-256 verified on Windows and Linux before ONNX Runtime can load them. A hash mismatch deletes the untrusted temporary file, rejects the cached model, and exits with an error. Use preprocess --download-only to preload and verify the cache, or --no-download to require an already verified cache entry.

Troubleshooting

"CUDA driver version is insufficient" - Update NVIDIA driver.

"no kernel image is available" - GPU is older than BUILD_CUDA_MIN_SM. Rebuild with lower value.

Missing libraries on target - Use run_lichtfeld.sh (Linux) or ensure DLLs are with .exe (Windows).

"SDL3 was found, but the resolved SDL build does not expose an X11 or Wayland video backend" - A stale vcpkg SDL3 artifact is being reused. Remove SDL3 from the local vcpkg install/build cache, then reconfigure with binary-cache bypass enabled:

lfs="$(pwd)"
triplet="${VCPKG_TARGET_TRIPLET:-x64-linux}"
cd "$VCPKG_ROOT"
./vcpkg remove "sdl3:$triplet" --recurse \
  --x-install-root="$lfs/build/vcpkg_installed" \
  --x-packages-root="$VCPKG_ROOT/packages" \
  --x-buildtrees-root="$VCPKG_ROOT/buildtrees"

cd "$lfs"
VCPKG_BINARY_SOURCES='clear;default,write' cmake -B build -G Ninja --fresh
cmake --build build -j"$(nproc)"