Quick Start — Build Environment and Dependencies

This page is your complete guide to setting up the Himalaya renderer build environment from scratch. It covers every external tool, SDK, and library the project depends on, explains how they are wired together through CMake and vcpkg, and walks you through the configuration process end-to-end. By the end, you will understand what each dependency provides, where it lives in the build graph, and how to reproduce a working build on a fresh machine.

Sources: CMakeLists.txt, vcpkg.json, CLAUDE.md

Development Environment Summary

Himalaya is developed on Windows 11 using MSVC (Visual Studio 2022 toolchain) with the ISPC SIMD compiler for texture compression. The build system is CMake 4.1 with Ninja generators, and all third-party C/C++ libraries are managed through vcpkg manifest mode, which guarantees reproducible dependency versions across machines.

Sources: cmake-build-debug/CMakeCache.txt, cmake-build-debug/CMakeCache.txt, cmake-build-debug/CMakeCache.txt, CLAUDE.md

Build Graph and Layered Architecture

The project compiles as four CMake static libraries plus one executable, arranged in a strict unidirectional dependency chain. No reverse or lateral dependencies are permitted between the core layers — this is enforced structurally by only linking to layers below.

The dependency direction flows strictly downward: app → passes → framework → rhi. Each layer only #includes headers from layers below it, and CMake target_link_libraries propagates transitive dependencies upward through PUBLIC linkage. The bc7enc target is special — it contains ISPC source files and is compiled with multi-SIMD-width targets (SSE2 through AVX-512), with the ISPC runtime selecting the optimal path at call time.

Sources: CMakeLists.txt, rhi/CMakeLists.txt, framework/CMakeLists.txt, passes/CMakeLists.txt, app/CMakeLists.txt

Dependency Catalog

Every dependency in Himalaya serves a specific, non-overlapping role. The table below is your quick reference for understanding what each library does and which build target consumes it.

vcpkg-Managed Dependencies

These are declared in vcpkg.json and installed automatically during CMake configuration.

Sources: vcpkg.json, CLAUDE.md

Prebuilt / Manual Dependencies

These libraries are not managed by vcpkg. They ship as prebuilt binaries inside the repository or require a system-level SDK install.

The OIDN integration is notable: it is linked as an IMPORTED SHARED library pointing to a local .lib import library and .dll at runtime. The build system copies all OIDN DLLs (including device backends for CPU, CUDA, HIP, and SYCL) to the output directory as a post-build step.

Sources: framework/CMakeLists.txt, app/CMakeLists.txt, third_party/bc7enc/CMakeLists.txt, cmake-build-debug/CMakeCache.txt

CMake Configuration Walkthrough

The following flowchart shows the complete configuration process from opening the project in CLion to having a ready-to-build configuration:

Key Configuration Variables

These are the critical CMake cache variables that control the build. They are typically set through CLion's CMake settings dialog or passed on the command line.

Sources: cmake-build-debug/CMakeCache.txt, cmake-build-debug/CMakeCache.txt

Post-Build Steps

Two post-build commands run automatically after every successful build of himalaya_app:

1. Shader sync: Deletes the shaders/ directory in the build output, then copies the entire source shaders/ tree into the build directory. This ensures the runtime always has the latest GLSL sources for hot-reload compilation.
2. OIDN DLL copy: Globs all .dll files from third_party/oidn/bin/ and copies them to the executable directory. This includes the core denoiser, all device backends (CPU, CUDA, HIP, SYCL), and their TBB/SYCL runtime dependencies.

Sources: app/CMakeLists.txt

Shader Development Workflow

Himalaya uses runtime GLSL-to-SPIR-V compilation via shaderc rather than offline SPIR-V baking. All shaders are written in GLSL 460 and target Vulkan 1.4. The workflow is designed for fast iteration:

If you only modify shaders without touching C++ code, CLion will not trigger a CMake build, so the shader copy step won't execute. In that case, run scripts/sync-shaders.sh to manually push source shaders into the build directory.

Sources: CLAUDE.md, scripts/sync-shaders.sh

ISPC and Texture Compression

The bc7enc library in third_party/ is the sole reason Himalaya requires the ISPC compiler. It provides high-performance BC7, BC4, and BC5 texture compression using ISPC's SIMD auto-vectorization. The CMake configuration instructs ISPC to generate code for four SIMD widths simultaneously:

At runtime, the ISPC dispatch layer automatically selects the best available target for the current CPU. The ISPC compiler must be installed separately — it is not provided by vcpkg or the Vulkan SDK.

Sources: third_party/bc7enc/CMakeLists.txt

Setting Up a Fresh Environment

To build Himalaya on a new Windows machine, install the following tools in order:

1. Visual Studio 2022 (Community or higher) with the C++ desktop workload — provides MSVC and OpenMP support
2. CLion (or any CMake-aware IDE) — the primary development environment
3. CMake 4.1+ — typically bundled with CLion, verify the version
4. Vulkan SDK 1.4.x — install from LunarG, ensure VULKAN_SDK environment variable is set
5. ISPC v1.30.0 — download from ispc.github.io, extract to a known path and set CMAKE_ISPC_COMPILER in CLion's CMake settings
6. vcpkg — CLion can manage this automatically via its built-in vcpkg integration; the CMAKE_TOOLCHAIN_FILE should point to vcpkg.cmake

Once the toolchain is installed, open the project in CLion. The vcpkg manifest in vcpkg.json will automatically download and compile all listed dependencies on the first configuration. Subsequent builds only rebuild changed targets.

Sources: CLAUDE.md, cmake-build-debug/CMakeCache.txt

Build Targets Reference

The following table summarizes every CMake target in the project and its relationship to the source tree:

Sources: CMakeLists.txt, rhi/CMakeLists.txt, framework/CMakeLists.txt, passes/CMakeLists.txt, app/CMakeLists.txt

Next Steps

Now that your build environment is configured, you are ready to explore the codebase. The recommended reading progression follows the architectural layers from foundation to application:

1. Coding Conventions and Naming Standards — understand the naming rules and namespace conventions before reading any code
2. Project Structure and Layered Architecture — see how the four layers map to directories and enforce dependency boundaries
3. GPU Context Lifecycle — Instance, Device, Queues, and Memory — the deepest layer, where Vulkan initialization begins