Developer Setup Guide

Table of Contents

• Clone the Repo
• Compiling Cesium Native
  • Compile from command line
  • Compile from Visual Studio Code
  • Compile with any Visual Studio version using CMake generated projects
• Generate Documentation
• Regenerate glTF and 3D Tiles classes
• Regenerate Dependency Graphs

This guide contains the basic setup information for developers looking to work with Cesium Native. To follow this guide, you will need the following prerequisites:

• Visual Studio 2019 (or newer), GCC v11.x+, or Clang 12+
  • Other compilers are likely to work but are not regularly tested.
• CMake 3.15+
• For best JPEG-decoding performance, you must have nasm installed so that CMake can find it. Everything will work fine without it, just slower.

Clone the Repo

Check out the repo with:

git clone git@github.com:CesiumGS/cesium-native.git --recurse-submodules

If you forget the --recurse-submodules, nothing will work because the git submodules will be missing. You should be able to fix it with:

git submodule update --init --recursive

Compiling Cesium Native

Compile from command line

## Windows compilation using Visual Studio
cmake -B build -S . -G "Visual Studio 17 2022" -A x64
cmake --build build --config Debug
cmake --build build --config Release
 
## Linux compilation
cmake -B build -S .
cmake --build build

Compile from Visual Studio Code

1) Install the CMake Tools extension. It should prompt you to generate project files from CMake. 2) On Windows, choose Visual Studio 2017 Release - amd64 as the kit to build. Or choose an appropriate kit for your platform. 3) Then press Ctrl-Shift-P and execute the CMake: Build task or press F7.

Compile with any Visual Studio version using CMake generated projects

1) Open the CMake UI (cmake-gui) 2) Under "Where is the source code", point to your repo 3) Specify your output folder in "Where to build the binaries" 4) Click "Configure". 5) Under "Specify the generator for this project", choose the VS version on your system 6) Click Finish, wait for the process to finish 7) Click Generate

Look for cesium-native.sln in your output folder.

Unit tests can also be run from this solution, under the cesium-native-tests project.

Generate Documentation

• Install Doxygen.
• Run: npm install
• Run: cmake --build build --target cesium-native-docs
• Open build/doc/html/index.html

Regenerate glTF and 3D Tiles classes

Much of the code in CesiumGltf, Cesium3DTiles, CesiumGltfReader, CesiumGltfWriter, Cesium3DTilesReader, Cesium3DTilesWriter, and CesiumQuantizedMeshTerrain is generated from the standards' JSON Schema specifications. To regenerate the code:

• Make sure you have a relatively recent version of Node.js installed.
• Install dependencies by running:

npm install
cd tools/generate-classes
npm install
cd ../..

• From the repo root directory, run these commands
  • npm run generate-gltf
  • npm run generate-3d-tiles
  • npm run generate-quantized-mesh-terrain
• On Windows, the line endings of the generated files will be different than those checked into the repo. Just git add them and git will fix the line endings (no need to commit).

Regenerate Dependency Graphs

The dependency graphs used in the Cesium Native documentation are generated using a script that parses CMake's GraphViz output and generates a set of Mermaid diagrams. To regenerate the graphs:

• Make sure you have a relatively recent version of Node.js installed.
• Install dependencies by running:

  cd tools/dep-graph-gen
  npm install

• From the tools/dep-graph-gen directory, run npm run generate-dep-graph to regenerate the graphs.