Setting Up MeshLib for C++ Development

This guide explains how to set up MeshLib for C++ development on Windows, Linux, and macOS, and also shows how to build WebAssembly modules using MeshLib with Emscripten. It covers all the prerequisites and setup steps for each platform, making it easy to get started. When you are done, confirm the result with Verify your setup — two of its three checks need no graphical session and report failure through their exit status. If a step fails, see Troubleshooting at the end of this page.

Prerequisites

Compiler and language standard

MeshLib uses C++20 standard and is tested to be compiled with:

GCC 11 or newer
Clang 14 or newer
MSVC 2019 or newer

CMake

Integrating MeshLib with CMake needs CMake 3.18 or newer. See the CMake Setup Guide for the full CMakeLists.txt.

Windows

Note: MeshLib for Windows is distributed for x64 and Arm64: set the platform of your project to x64 or ARM64. A 32-bit (Win32) build is not supported and fails while compiling MRMesh/MRId.h with C2535: member function already defined or declared and C2995: function template has already been defined (on 32-bit MSVC size_t and unsigned int are the same type, so two MR::Id constructors collapse into one). Visual Studio 2019 still defaults new C++ console projects to Win32. On Windows on Arm, take the -arm64 archive; it is built with Visual Studio 2026 and ships no MRCuda, there being no CUDA toolkit for that platform.

There are two options: Download and Install release build or compile from sources:

Installing the release build

Every release publishes one Windows distributive per Visual Studio toolset and target architecture, plus one for Debug builds that keep MSVC's iterator debugging on. Take the row matching the toolset your own project is built with, or an older one: MSVC keeps its v140 to v145 build tools (Visual Studio 2015 to 2026) binary-compatible, so the VS19 archive links into a Visual Studio 2022 or 2026 project as well — the link itself must be done by the newer toolset. The opposite direction does not work: older build tools accept a newer DLL only when its exports are extern "C", and MeshLib exports C++. Matching your own toolset stays the tested configuration, though: MeshLib compiles with /std:c++latest (source/common.props), and MSVC's standard library excludes /std:c++latest features from that binary-compatibility promise.

Built with	Archive	Debug _ITERATOR_DEBUG_LEVEL
2019	MeshLibDistVS19_<version>.zip	0
2022	MeshLibDistVS22_<version>.zip	0
2026	MeshLibDistVS26_<version>.zip	0
2026, Windows on Arm	MeshLibDistVS26_<version>-arm64.zip	0
2019 (toolset v142), Debug configuration only	MeshLibDist_<version>-IteratorDebug.zip	2

The release description links the per-Visual-Studio archives; IteratorDebug appears in the asset list only. Take it if your project builds Debug with MSVC's default _ITERATOR_DEBUG_LEVEL=2: it ships install/app/Debug without install/app/Release, so it covers no Release build — but being a v142 build it serves a newer Visual Studio too, under the rule above. Whichever archive you pick, step 2 must define _ITERATOR_DEBUG_LEVEL to the value in the table — 0 for the per-Visual-Studio archives, 2 for IteratorDebug. Archives predating install/include/MRMesh/config_dist.h need MR_ITERATOR_DEBUG_LEVEL set to the same value as well; newer ones declare it themselves in that header, which leaves IteratorDebug needing no define at all.

Debug symbols ship separately: every archive above has a companion -PDB archive (MeshLibDistVS26_<version>-PDB.zip, MeshLibDistVS26_<version>-PDB-arm64.zip, MeshLibDist_<version>-IteratorDebug-PDB.zip, ...) holding only the .pdb files. Extract it over the same directory to put them back under install/lib, where the debugger looks for them. They are needed for symbolized call stacks only: without them the archive still compiles, links and runs, and is a few hundred megabytes smaller.

Download and Extract the Built Version
- Visit the MeshLib GitHub Releases.
- Download the archive for your Visual Studio toolset from the table above.
- Extract it to a directory, e.g., C:\meshlib-built\.
  Directory Structure After Extraction
  install/
  
  ├── include/ # Header files
  
  ├── lib/ # Static and shared libraries
  
  ├── app/ # Executables
  
  example_plugin/ # example solution for creating MeshLib/MeshInspector plugins
Configure and integrate with Visual Studio
- Debug only:
  - Debug Configuration: C/C++ → Preprocessor → Preprocessor Definitions:
    Add: _ITERATOR_DEBUG_LEVEL=0;MR_ITERATOR_DEBUG_LEVEL=0 — for the per-Visual-Studio archives (MeshLibDistVS19, MeshLibDistVS22, MeshLibDistVS26, MeshLibDistVS26-arm64).
    For the MeshLibDist-IteratorDebug archive add _ITERATOR_DEBUG_LEVEL=2;MR_ITERATOR_DEBUG_LEVEL=2 instead. Both defines must carry the same value: MeshLib stops compilation with #error _ITERATOR_DEBUG_LEVEL is inconsistent with MeshLib when they disagree.
    Check whether your archive contains install/include/MRMesh/config_dist.h. If it does, that header already declares MR_ITERATOR_DEBUG_LEVEL for you, so only _ITERATOR_DEBUG_LEVEL is yours to set — and IteratorDebug then needs no define at all, MSVC's Debug default already being 2. Setting MR_ITERATOR_DEBUG_LEVEL anyway is harmless as long as it matches the archive; a value that contradicts it is rejected at compile time.
- For all configurations:
  - Solution Platform:
    Set: x64
  - General Properties -> C++ Language Standard:
    Set: /std:c++20 or later
  - C/C++ → General → Additional Include Directories:
    Add: C:\meshlib-built\install\include
  - C/C++ → All Options → Additional Options:
    Add: /bigobj /utf-8
  - Linker → Input → Additional Dependencies:
    Add: C:\meshlib-built\install\lib\$(Configuration)\*.lib
- Copy DLLs:
  Copy all .dll files from: C:\meshlib-built\install\app\$(Configuration) to your project’s output directory: $(TargetDir)
  xcopy C:\meshlib-built\install\app\$(Configuration)\*.dll $(TargetDir)
Verify the installation
Run the checks in Verify your setup: C:\meshlib-built\install\app\Release\meshconv.exe --help needs no display and its exit status is the signal, while C:\meshlib-built\install\app\Release\MeshViewer.exe is the interactive check.

Compile Locally

Prerequisites

Git
- Install Git to manage repositories and submodules, which is also required to install vcpkg.
Visual Studio 2019, 2022 or 2026
- Download and install either Visual Studio 2019, 2022 or 2026. During installation, make sure to:
  - Select the "Desktop development with C++" workload.
  - Include support for the C++ programming language.
  - Ensure the English language pack is installed (required for vcpkg).
CUDA Toolkit
- Recommended CUDA versions (the ones the build selects for your Visual Studio toolset, see source/platform.props):
  - For Visual Studio 2019: Install CUDA v11.4
  - For Visual Studio 2022: Install CUDA v12.0
  - For Visual Studio 2026: Install CUDA v13.2
    - If your GPU or driver predates CUDA 13, install CUDA v12.0 instead and build the solution with -p:MRCudaPlatformToolset=v143: CUDA 12.0 supports a wider range of GPUs but not the Visual Studio 2026 host compiler, so it needs the 2022 one. This is the combination MeshLib's own Windows binaries and Python wheels are built with.
- Other CUDA versions work as well: if the recommended one is not installed, the build automatically falls back to the toolkit pointed to by the CUDA_PATH environment variable, which the NVIDIA installer keeps at the latest installed version.
- In the CUDA installer, keep the Visual Studio Integration component enabled: the Visual Studio build needs it.
vcpkg
- To install vcpkg, follow these steps:
  1. Open a command prompt (CMD) or PowerShell window.
  2. Navigate to a directory where you want to install vcpkg (please avoid using directories with special characters like ! in full path):
    cd C:\path\to\your\desired\directory
  3. Clone the vcpkg repository:
    git clone https://github.com/microsoft/vcpkg.git
  4. Navigate to the vcpkg directory:
    cd vcpkg
    
    git checkout 2026.07.29
  5. Run the bootstrap script to build the vcpkg executable:
    bootstrap-vcpkg.bat
  6. Integrate vcpkg with Visual Studio (requires Administrator access):
    vcpkg integrate install

Learn more about vcpkg

Installing the local build

Note: The following steps will require approximately 40 GB of disk space.

Clone the MeshLib Repository:
git clone https://github.com/MeshInspector/MeshLib.git
Clone submodules:
Run scripts/clone_submodules_windows.ps1 to clone submodules. It has the same effect as git submodules update --recursive --init, except that it skips submodules that are not needed on Windows.
(Optional) Speed Up with AWS CLI
- Optionally, install AWS CLI v2 to speed up the process before using the MeshLib Installation Script. Restart your terminal after installation.
- It also changes how the dependencies arrive: with the CLI on PATH the script restores prebuilt packages from our public S3 cache (s3://vcpkg-export/<vcpkg-tag>/<triplet>/, no credentials needed) instead of compiling them locally. That cache is keyed on the triplet name, not on your compiler, and the x64-windows-meshlib folder is written by Visual Studio 2026 builds only.
- So with the AWS CLI installed, the VCPKG_DEFAULT_TRIPLET of step 4 is what selects the toolset your dependencies were built with, not just their port overlays: on Visual Studio 2019 or 2022 it is mandatory, or you link v145 binaries into a v142/v143 project and the link fails. Without the CLI the cache is off and every package is compiled with your own toolset.
Install MeshLib Third-Party Dependencies
- Execute the following commands to run the MeshLib third-party installation script:
  cd vcpkg
  
  ..\MeshLib\thirdparty\install.bat
- This script automates the installation of necessary Third-Party Dependencies.
- If you build with Visual Studio 2019, set VCPKG_DEFAULT_TRIPLET=x64-windows-vs2019-meshlib in the environment before running the script, so the v142 triplet and its port overlays are used.
- If you build with Visual Studio 2022, set VCPKG_DEFAULT_TRIPLET=x64-windows-vs2022-meshlib the same way to get the v143 triplet.
- If you build with Visual Studio 2026, leave VCPKG_DEFAULT_TRIPLET unset: install.bat defaults to x64-windows-meshlib, the triplet MeshLib CI uses for msvc-2026. It pins no VCPKG_PLATFORM_TOOLSET, so vcpkg uses the newest toolset installed — there is no x64-windows-vs2026-meshlib.
Build and Run Visual Studio Solution
- Open MeshLib/source/MeshLib.sln in Visual Studio.
- On Visual Studio 2019 or 2022, make sure Visual Studio itself sees the VCPKG_DEFAULT_TRIPLET of step 4: source/common.props takes VcpkgTriplet from that variable and reads <vcpkg>\installed\$(VcpkgTriplet), so the solution then looks exactly where vcpkg installed. Set it for the user rather than for one shell — setx VCPKG_DEFAULT_TRIPLET x64-windows-vs2022-meshlib — and start Visual Studio afterwards (or launch it from a terminal where the variable is set); an IDE that inherited nothing falls back to the x64-windows-meshlib default.
- Building from the command line, pass the triplet instead of relying on the environment, the way MeshLib CI does: msbuild -m source\MeshLib.sln -p:Configuration=Release -p:VcpkgTriplet=x64-windows-vs2022-meshlib. As a global property it wins over both common.props lines.
- Either way you can override the triplet with a CustomMRProps.props in any directory above source\ — but its mere presence disables the common.props block defining _ITERATOR_DEBUG_LEVEL / MR_ITERATOR_DEBUG_LEVEL, so such a file has to define them itself.
- Build the solution and run the application.
Build and Run CMake Project
- Make sure you have the "C++ CMake tools for Windows" component installed.
- Open MeshLib/CMakeLists.txt in Visual Studio (File - Open - CMake).
- Build the project and run the application.
Verify the build
- Run the checks in Verify your setup: install\app\Release\meshconv.exe --help (headless, exit status is the signal) and install\app\Release\MeshViewer.exe (interactive).

Linux

Installing the release build

Download the Package for Your Distribution and CPU
Open the MeshLib GitHub Releases page: the release description links a .deb for every supported Ubuntu release and architecture. Take the one matching lsb_release -rs and uname -m.
On any other distribution use the portable Linux vcpkg build instead. It bundles its own dependencies and is not installed system-wide: unpack it and use the resulting directory as the MeshLib installation prefix, then skip to step 4.
mkdir path_to_install && tar -xf <downloaded>.tar.xz -C path_to_install
Install the Package
apt pulls in the remaining system dependencies itself. The leading ./ is required: without it apt looks for a repository package by that name.
apt refuses a package built for another CPU, but nothing tells the Ubuntu releases apart: the builds all declare the same dependencies and the preinst carries no release check, so installing the Ubuntu 22 build on Ubuntu 24 succeeds silently. Check the release in the file name first.
sudo apt install ./<downloaded>.deb
Verify the installation
Run the checks in Verify your setup. The meshconv one needs no graphical session and reports failure through its exit status:
meshconv --help # headless, non-zero exit if the installation is incomplete

MeshViewer # interactive, requires a graphical session
Integrate Using CMake

Compile Locally

Prerequisites

Git
- Install Git to manage repositories and submodules.
CMake
- Ensure CMake is installed for managing the build process.
CUDA Toolkit
- Install CUDA v12.6 from the official website. Follow the Linux installation instructions provided on the CUDA page.
  Note
  You might need to execute export PATH=$(echo $PATH | tr ':' '\n' | grep -v '/mnt' | tr '\n' ':' | sed 's/:$//') if you are on WSL to prevent interfearing with host machine CUDA Toolkit (this command will filter host machine paths from PATH enviroment)

Installing the local build

Clone the MeshLib Repository:
git clone https://github.com/MeshInspector/MeshLib.git

cd MeshLib
Clone submodules:
Run scripts/clone_submodules_linux.sh to clone submodules. It has the same effect as git submodules update --recursive --init, except that it skips submodules that are not needed on Linux.
Install/Build Dependencies and Compile:
./scripts/build_thirdparty.sh # Do not select emscripten in the corresponding question

./scripts/build_source.sh # Do not select emscripten in the corresponding question

You may also run the scripts in the non-interactive mode (see Building WebAssembly with MeshLib Using Emscripten for more info):
MR_EMSCRIPTEN=OFF ./scripts/build_thirdparty.sh

MR_EMSCRIPTEN=OFF ./scripts/build_source.sh

Note
Dependencies are installed automatically on Ubuntu only. Elsewhere build_thirdparty.sh prints "Unsupported system. Installing dependencies is your responsibility.", so install the equivalents of requirements/ubuntu.txt yourself first.
Create and Install Package:
This step will create distribution package and install it to the system
./scripts/distribution.sh

sudo apt install ./distr/meshlib-dev.deb

Note
distribution.sh builds a .deb, so this step is Ubuntu/Debian-only. On other distributions skip it and use the locally built binaries directly, as in the next step.
Verify the build
Run the checks in Verify your setup. The headless one, whose exit status is the signal:
- if you installed the package in the previous step:
  meshconv --help
- or the locally built binary:
  ./build/Release/bin/meshconv --help
  
  MeshViewer (./build/Release/bin/MeshViewer) is the interactive check and requires a graphical session.
Integrate Using CMake
Examples of integration with CMake can be found in the examples directory on GitHub.

macOS

Installing the release build

Download the Installer
Open the MeshLib GitHub Releases page: the release description links one .pkg installer for macOS Arm (Apple silicon) and one for macOS x64 (Intel). Take the one matching uname -m (arm64 or x86_64).
Install
- Double-click the downloaded .pkg and follow the installer. The release asset is the installer itself, so there is nothing to unpack first.
- The framework is installed into /Library/Frameworks/MeshLib.framework, or into ~/Library/Frameworks/MeshLib.framework if you choose to install for the current user only.
- Install Dependencies via Homebrew
  The .pkg does not pull in the Homebrew formulae MeshLib links against, so install them yourself. Skip this step if your project enables only the C language. This needs Homebrew — if you do not have it, install it first as described under Prerequisites. Open Terminal and run the following command:
  xargs brew install < /Library/Frameworks/MeshLib.framework/Versions/Current/requirements/macos.txt
- If you installed for the current user only, prefix the path with ~: ~/Library/Frameworks/MeshLib.framework/Versions/Current/requirements/macos.txt.
Verify the installation
Run the checks in Verify your setup. meshconv is not on PATH; it lives in the framework and needs no graphical session:
/Library/Frameworks/MeshLib.framework/Versions/Current/bin/meshconv --help
Integrate Using CMake
Examples of integration with CMake can be found in the examples directory on GitHub.

Compile Locally

Prerequisites

Install Homebrew
- Run the following command in your terminal to install Homebrew:
  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
- Install Homebrew
Update Homebrew
- Make sure Homebrew is up to date:
  brew update
Install Git Using Homebrew
- Once Homebrew is installed and added to your PATH, you can proceed to install Git:
  brew install git
- Learn more about Git

Installing the local build

Clone the MeshLib Repository:
git clone https://github.com/MeshInspector/MeshLib.git

cd MeshLib
Clone submodules:
Run scripts/clone_submodules_macos.sh to clone submodules. It has the same effect as git submodules update --recursive --init, except that it skips submodules that are not needed on MacOS.
Install/Build Dependencies and Compile:
./scripts/build_thirdparty.sh

./scripts/build_source.sh
Verify the build
Run the checks in Verify your setup — ./build/Release/bin/meshconv --help needs no graphical session and its exit status is the signal.
Run example We suggest starting with the mesh loading and saving example, which demonstrates how to work with mesh files programmatically.
Integrate Using CMake

Building WebAssembly with MeshLib Using Emscripten

This guide will help you build WebAssembly (WASM) using MeshLib and Emscripten. Please follow the instructions step by step.

Note: Only web and worker environments (i.e. web browsers) are officially supported.

Install Emscripten

Emscripten is required to compile C++ code into WebAssembly. You can install Emscripten by following the steps below. For more details, refer to the Emscripten official page.

Clone the Emscripten SDK Repository
Run the following command on all platforms:
git clone https://github.com/emscripten-core/emsdk.git
Navigate to the Emscripten SDK Directory
cd emsdk
Update the SDK (Optional)
This step ensures you have the latest updates:
git pull origin
Install a Specific Version of Emscripten
./emsdk install 4.0.19
Activate the Installed Version
./emsdk activate 4.0.19
Set Up Environment Variables
- macOS and Linux:
  source ./emsdk_env.sh

Note: For Windows Users:
Make sure you are using Git Bash, WSL, or another Unix-like environment if you want to follow the exact same steps as on Linux/macOS.

Installing the release build

Download the Built Version
Open the MeshLib GitHub Releases page and download the Emscripten archive whose threading mode and pointer width match the build that will consume MeshLib: the release description links a multi-thread, a single-thread and a multi-thread Wasm64 variant.
These are the same three modes that Compile locally selects with MR_EMSCRIPTEN / MR_EMSCRIPTEN_SINGLETHREAD / MR_EMSCRIPTEN_WASM64. The archive has to match your own build: an Emscripten target links only against libraries built with the same -pthread and MEMORY64 settings.
Extract the Package
Extract the package using an archiving tool or with the unzip command:
unzip -d path_to_install <downloaded>.zip
Integrate Using CMake
Specify the path to the extracted files with the CMAKE_FIND_ROOT_PATH option:
emcmake cmake -S . -B build -DCMAKE_FIND_ROOT_PATH=path_to_install

Examples of integration with CMake can be found in the examples directory on GitHub.

Compile locally

Navigate to the MeshLib directory:
cd ~/MeshLib
Run the script to build Third-Party Dependencies. When prompted, select Emscripten as the build target:
- y - Emscripten, multi-threaded
- s - Emscripten, single-threaded
- l - Emscripten, multi-threaded 64-bit (wasm64)
- any other key, or no keypress within 5 seconds - native, non-Emscripten build
  ./scripts/build_thirdparty.sh
Build the MeshLib source code. Make sure to select the same Emscripten option you used in the build_thirdparty.sh script:
./scripts/build_source.sh

Note: Non-interactive builds. You may pre-set the environment variables to skip the prompt:
export MR_EMSCRIPTEN=ON # same as 'y': multi-threaded

#export MR_EMSCRIPTEN_SINGLETHREAD=1 # ...plus this for 's': single-threaded

#export MR_EMSCRIPTEN_WASM64=1 # ...plus this for 'l': multi-threaded 64-bit

./scripts/build_thirdparty.sh

./scripts/build_source.sh; For Windows Users:
You may encounter compatibility issues if building directly on Windows. Consider using WSL (Windows Subsystem for Linux) to follow Linux-like instructions.

Running the WebAssembly Build

After building MeshLib for WebAssembly, follow these steps to run it:

Setting Up a Local HTTP Server
Navigate to the build directory:
cd ~/MeshLib/build
Start a local server:
- Windows
  python -m http.server
- macOS/Linux:
  python3 -m http.server
Configuring COEP and COOP for Multithreading
If using multithreading, set these headers:
- Cross-Origin Embedder Policy (COEP): require-corp
- Cross-Origin Opener Policy (COOP): same-origin
For Python servers, you can use this custom script (server.py):
#!/usr/bin/env python

from http import server

class MyHTTPRequestHandler(server.SimpleHTTPRequestHandler):

def end_headers(self):

self.send_my_headers()

server.SimpleHTTPRequestHandler.end_headers(self)

def send_my_headers(self):

self.send_header("Cross-Origin-Embedder-Policy", "require-corp")

self.send_header("Cross-Origin-Opener-Policy", "same-origin")

if __name__ == '__main__':

server.test(HandlerClass=MyHTTPRequestHandler)
Access and Test
- Open your browser and go to: http://127.0.0.1:8000
- Ensure headers are set correctly for multithreading. Check the browser console for errors if needed.

Verify your setup

Two of the three checks below need no graphical session and report failure through their exit status — use those on a server, in a container, in CI or from a coding agent.

1. Run meshconv. It ships in every package and needs no display. It exits 0 only if the binary and all of its shared libraries load, so a non-zero status means the installation is incomplete:

meshconv --help # Linux: on PATH from /usr/local/bin

/Library/Frameworks/MeshLib.framework/Versions/Current/bin/meshconv --help # macOS: not on PATH

install\app\Release\meshconv.exe --help

A broken installation fails loudly here, e.g. error while loading shared libraries: libMRIOExtras.so with exit 127.

2. Build and run a program against MeshLib. The strongest check: it verifies the headers, the libraries and linking, which running a prebuilt binary does not. Take the complete CMakeLists.txt from the CMake Setup Guide and use this as main.cpp:

#include <MRMesh/MRCube.h>
#include <MRMesh/MRMesh.h>
#include <MRMesh/MRMeshSave.h>
 
#include <iostream>
 
int main()
{
    // create a mesh in memory: verifies that headers and libraries match
    const MR::Mesh mesh = MR::makeCube();
 
    const int verts = mesh.topology.numValidVerts();
    const int faces = mesh.topology.numValidFaces();
    std::cout << "verts=" << verts << " faces=" << faces << std::endl;
    if ( verts != 8 || faces != 12 )
    {
        std::cerr << "unexpected cube topology" << std::endl;
        return 1;
    }
 
    // write it out: verifies that the library can reach the filesystem
    const auto saveRes = MR::MeshSave::toBinaryStl( mesh, "cube.stl" );
    if ( !saveRes.has_value() )
    {
        std::cerr << saveRes.error() << std::endl;
        return 1;
    }
 
    std::cout << "MeshLib setup OK" << std::endl;
    return 0;
}

It prints verts=8 faces=12, writes a 684-byte cube.stl next to the executable, and returns non-zero on any mismatch or save error. MeshLib CI compiles it on every supported platform as examples/cpp-examples/VerifySetup.dox.cpp.

3. Open MeshViewer — the interactive check, and the only one that requires a graphical session. Without one it logs X11: The DISPLAY environment variable is missing and glfwInit failed. Its exit status is not a dependable success signal (1 on the Ubuntu package, reported as 0 on other builds), so never gate an automated check on it — use check 1 or 2 for that.

Troubleshooting

Failures most often hit while following the steps above, with the message each one actually produces.

Path	Symptom	Cause	Fix
Windows, prebuilt	Compilation of any file including MeshLib stops with #error _ITERATOR_DEBUG_LEVEL is inconsistent with MeshLib. This is a compile error raised by MeshLib itself, not a linker error.	The archive was built for a different iterator-debug setting than your project uses. MR_ITERATOR_DEBUG_LEVEL is the level MeshLib's own binaries were built with — taken from install/include/MRMesh/config_dist.h when the archive ships one, otherwise defaulting to 0 — and MeshLib refuses to compile when your _ITERATOR_DEBUG_LEVEL differs from it. A Debug configuration implies _ITERATOR_DEBUG_LEVEL=2, which is why an unconfigured Debug build hits this against the per-Visual-Studio archives.	Take the archive matching your toolset and iterator-debug setting from the table in Windows, then define _ITERATOR_DEBUG_LEVEL to that row's value, plus MR_ITERATOR_DEBUG_LEVEL to the same value if the archive has no config_dist.h.
Windows, from source	thirdparty\install.bat finishes, but the Visual Studio solution stops with fatal error C1083: Cannot open include file on a third-party header. Hits Visual Studio 2019 and 2022 builds, i.e. the ones step 4 of Installing the local build has set VCPKG_DEFAULT_TRIPLET for.	The solution and vcpkg disagree on the triplet. source/common.props takes VcpkgTriplet from VCPKG_DEFAULT_TRIPLET and reads <vcpkg>\installed\$(VcpkgTriplet), so this needs the variable to have reached install.bat but not the build: set with set in the one terminal that ran the script, or set after Visual Studio was started, so the build fell back to the x64-windows-meshlib default while the packages are in installed\x64-windows-vs2019-meshlib. A stale CustomMRProps.props above source\ naming a third triplet does the same. Rerunning the script cannot help.	Name the triplet vcpkg actually installed — check which folder exists under <vcpkg>\installed\ — and do not edit common.props. For the IDE, setx VCPKG_DEFAULT_TRIPLET x64-windows-vs2022-meshlib and restart Visual Studio; from the command line, msbuild -m source\MeshLib.sln -p:Configuration=Release -p:VcpkgTriplet=x64-windows-vs2022-meshlib, which overrides the environment. Both are step 5 of the same list.
Linux, macOS, WASM (consuming an installed MeshLib)	MRMeshFwd.h:70:10: fatal error: parallel_hashmap/phmap_fwd_decl.h: No such file or directory	MeshLib's public headers include third-party headers, and ${MESHLIB_THIRDPARTY_INCLUDE_DIR} is missing from your target's include directories.	Add it next to ${MESHLIB_INCLUDE_DIR}: target_include_directories(${TARGET} PUBLIC ${MESHLIB_INCLUDE_DIR} ${MESHLIB_THIRDPARTY_INCLUDE_DIR}). See MeshLib CMake Setup Guide and examples/cpp-examples/CMakeLists.txt.
Linux, macOS (consuming an installed MeshLib)	CMake configuration stops with Target "..." links to: MeshLib::MeshLibC2 but the target was not found, suggesting a typo.	meshlib-config.cmake defines the C API target only when the project has the C language enabled.	Add C to the languages of your project() call.
macOS	CMake configuration fails inside MRMeshConfig.cmake with find_dependency: Could NOT find Boost (missing: Boost_INCLUDE_DIR) (Boost is just the first of several such dependencies).	The Homebrew requirements were never installed — the .pkg installer does not pull them in.	xargs brew install < /Library/Frameworks/MeshLib.framework/Versions/Current/requirements/macos.txt (for a current-user-only install, prefix the path with ~).
WASM	build_thirdparty.sh or build_source.sh silently produces a native build although Emscripten was selected.	The prompt is a read -t 5: with no keypress within five seconds it falls back to OFF. Each script asks separately, so the two can disagree.	Skip the prompt entirely — export MR_EMSCRIPTEN=ON once, before running both scripts. Each script prints its resolved mode (Emscripten ON …); check that line before waiting on a long build.
WASM, runtime	SharedArrayBuffer is not defined in the browser console.	The page is served without the cross-origin isolation headers that the multithreaded build needs for shared memory.	Serve with Cross-Origin-Embedder-Policy: require-corp and Cross-Origin-Opener-Policy: same-origin — see Running the WebAssembly Build.
Any, runtime	glfw_error_callback: X11: The DISPLAY environment variable is missing, then glfwInit failed.	MeshViewer was started without a graphical session. Expected over plain SSH or on a headless server — not a broken installation. Its exit status is not a dependable success signal (1 on the Ubuntu package, reported as 0 on other builds), so do not gate an automated check on it.	Open a desktop session, or run under a virtual display the way MeshLib CI does: xvfb-run -a MeshViewer -hidden -noEventLoop -unloadPluginsAtEnd. To check an installation without a display, use Verify your setup instead.
Windows, runtime	MeshViewer.exe logs icons path …\app\Release\resource\logos\X1 is not directory (and X3).	Benign: those logo directories are not part of the release archive. The viewer still starts, creates its window and renders.	Nothing to fix — this is not an installation problem.

Where the logs are

Runtime. MeshViewer writes a log per run to <system temp>/MeshLib/Logs/MRLog_<YYYY-MM-DD_HH-MM-SS>_<pid>.txt — /tmp/MeshLib/Logs/ on Linux, TEMP%\MeshLib\Logs\ on Windows, $TMPDIR/MeshLib/Logs/ on macOS. The exact path is printed on startup as a Log file: … line, which is the reliable way to find it. Logs older than 24 hours are deleted at startup, so collect the file before the next run.
Third-party build. scripts/build_thirdparty.sh writes install_thirdparty_<dd-mm-YYYY_HH:MM:SS>.log in the current directory and announces it on its second line of output (You could find output in …). The console shows only a fraction of the output; the failing compiler invocation is in that file.

Anything not listed here: please open an issue at MeshLib Issues, attaching the relevant log above.

Table of Contents

Setting Up MeshLib for C++ Development

Prerequisites

Compiler and language standard

CMake

Windows

Installing the release build

Compile Locally

Prerequisites

Installing the local build

Linux

Installing the release build

Compile Locally

Prerequisites

Installing the local build

macOS

Installing the release build

Compile Locally

Prerequisites

Installing the local build

Building WebAssembly with MeshLib Using Emscripten

Install Emscripten

Installing the release build

Compile locally

Running the WebAssembly Build

Verify your setup

Troubleshooting

Where the logs are