How to Use MeshLib with CMake

Quick Integration Guide

MeshLib provides native CMake integration support for Linux and macOS; for Windows see the Windows Integration Guide below. Example CMake configuration files are available to demonstrate how to link against the pre-built libraries. You can find these examples in the examples directory.

MeshLib requires CMake 3.18 or newer. If configuration or the build fails, see Troubleshooting in the C++ Setup Guide.

Find MeshLib CMake Configuration Files

For a start, find the MeshLib package:

find_package(MeshLib CONFIG REQUIRED)

The Ubuntu .deb and the macOS .pkg install the package where CMake searches by default. For the portable Linux vcpkg build, pass the directory it was unpacked to:

cmake -S . -B build -DCMAKE_FIND_ROOT_PATH=path_to_install

MeshLib_DIR alone is not sufficient, since the bundled third-party libraries are looked up in the same directory.

Include the MeshLib Headers

Add both include directories from the installed MeshLib package to your project. In your CMake configuration (CMakeLists.txt):

include_directories(${MESHLIB_INCLUDE_DIR} ${MESHLIB_THIRDPARTY_INCLUDE_DIR})
# or
target_include_directories(your_project_name PUBLIC ${MESHLIB_INCLUDE_DIR} ${MESHLIB_THIRDPARTY_INCLUDE_DIR})

MESHLIB_THIRDPARTY_INCLUDE_DIR is required, not optional: MeshLib's public headers include third-party headers directly — MRMesh/MRMeshFwd.h, pulled in by essentially every MeshLib header, includes <parallel_hashmap/phmap_fwd_decl.h>. Without it even a hello-world fails to compile.

Link the MeshLib Libraries

Specify which MeshLib libraries to link with your project:

target_link_libraries(your_project_name PUBLIC MeshLib::MRMesh)
# if you want to use viewer libraries
target_link_libraries(your_project_name PUBLIC MeshLib::MRMesh MeshLib::MRViewer)

Or if you use the C API, instead link MeshLib::MeshLibC2:

target_link_libraries(your_project_name PUBLIC MeshLib::MeshLibC2)

The package defines the following targets, each guarded by the variable in parentheses. A distribution sets it to ON for every module it ships, and only those targets exist.

MeshLib::MRMesh: core data structures and algorithms, needed by every C++ project.
MeshLib::MRIOExtras (MESHLIB_BUILD_EXTRA_IO_FORMATS): additional file formats such as 3MF, CTM, E57, glTF, LAS, and STEP.
MeshLib::MRSymbolMesh (MESHLIB_BUILD_SYMBOLMESH): text converted to meshes.
MeshLib::MRVoxels (MESHLIB_BUILD_VOXELS): voxel volumes and the algorithms built on them: offsets, fusion, marching cubes.
MeshLib::MRCuda (MESHLIB_BUILD_MRCUDA): CUDA implementations of several algorithms; unavailable for macOS and Emscripten.
MeshLib::MRViewer and MeshLib::MRCommonPlugins (MESHLIB_BUILD_MRVIEWER): the viewer framework and its standard plugins.
MeshLib::MeshLibC2 (MESHLIB_BUILD_GENERATED_C_BINDINGS): the C API.

A Complete Minimal Example

Putting the steps above together, this is a complete CMakeLists.txt that compiles, links and runs a program including <MRMesh/MRMesh.h>. The Linking Additional Third-Party Libraries section below is not needed for it:

cmake_minimum_required(VERSION 3.18)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
project(hello CXX)
 
find_package(MeshLib CONFIG REQUIRED)
 
add_executable(hello main.cpp)
target_include_directories(hello PUBLIC ${MESHLIB_INCLUDE_DIR} ${MESHLIB_THIRDPARTY_INCLUDE_DIR})
target_link_libraries(hello PUBLIC MeshLib::MRMesh)

For the main.cpp this expects, see Verify your setup in the C++ Setup Guide: a self-contained program that builds a mesh, checks it, saves it and returns non-zero on failure.

A C project is the same shape, linking MeshLib::MeshLibC2 instead. Note that it needs only MESHLIB_INCLUDE_DIR as the MRC* headers include no third-party header.

cmake_minimum_required(VERSION 3.18)
set(CMAKE_C_STANDARD 11)
set(CMAKE_C_STANDARD_REQUIRED ON)
project(hello C)
 
find_package(MeshLib CONFIG REQUIRED)
 
add_executable(hello main.c)
target_include_directories(hello PUBLIC ${MESHLIB_INCLUDE_DIR})
target_link_libraries(hello PUBLIC MeshLib::MeshLibC2)

For the main.c, take one of the C code samples; Load and Save Meshes is the shortest.

Linking Additional Third-Party Libraries

Only if your own code links a third-party library bundled with MeshLib (rather than just using MeshLib's API), add the directory those libraries live in:

target_link_directories(your_project_name PUBLIC ${MESHLIB_THIRDPARTY_LIB_DIR})

The MeshLib::* imported targets already carry the paths of the third-party libraries they need, so this line is not required by the example above. See the CMakeLists.txt in the examples directory for a working configuration.

Windows Integration Guide

MeshLib supports Windows via CMake, including integration with Visual Studio: ensure the CMake component is installed in your Visual Studio setup.

Prebuilt archive from GitHub Releases

The MeshLibDistVS*.zip archives contain no CMake config files, so find_package(MeshLib CONFIG REQUIRED) fails at configure time. Point CMake at the extracted tree instead — assuming the archive was extracted to C:/meshlib-built as described in the C++ Setup Guide:

cmake -S . -B build -A x64 ^
  -D MESHLIB_INCLUDE_DIRS=C:/meshlib-built/install/include ^
  -D MESHLIB_LIB_DIRS=C:/meshlib-built/install/lib/Release

target_include_directories(your_project_name PUBLIC ${MESHLIB_INCLUDE_DIRS})
target_link_directories(your_project_name PUBLIC ${MESHLIB_LIB_DIRS})
target_link_libraries(your_project_name PRIVATE MRMesh)
# if you want to use viewer libraries
target_link_libraries(your_project_name PRIVATE MRViewer)
# or, if you use the C API
target_link_libraries(your_project_name PRIVATE MeshLibC2)

Finally, copy the runtime libraries next to your executable, as described in the C++ Setup Guide.

Iterator debug level

Building with a non-zero iterator debug level needs a different archive (MeshLibDist_*-IteratorDebug.zip), and the level your project compiles with has to agree with the one the archive was built with, or the build stops with fatal error C1189: _ITERATOR_DEBUG_LEVEL is inconsistent with MeshLib. An archive shipping install/include/MRMesh/config_dist.h declares its own level, so a Debug build against IteratorDebug needs no flags at all; the form below also covers older archives, where MR_ITERATOR_DEBUG_LEVEL has to be named explicitly:

cmake -S . -B build -A x64 ^
  -D MESHLIB_INCLUDE_DIRS=C:/meshlib-built/install/include ^
  -D MESHLIB_LIB_DIRS=C:/meshlib-built/install/lib/Debug ^
  -D CMAKE_CXX_FLAGS="/D_ITERATOR_DEBUG_LEVEL=2 /DMR_ITERATOR_DEBUG_LEVEL=2"

Building MeshLib from source with vcpkg

To build MeshLib itself from source, install its dependencies with vcpkg as described in Installing the local build in the C++ Setup Guide, then configure from the repository root:

cmake -S . -B build ^
  -DCMAKE_TOOLCHAIN_FILE=C:\path\to\vcpkg\scripts\buildsystems\vcpkg.cmake ^
  -DVCPKG_TARGET_TRIPLET=x64-windows-meshlib

The triplet must be the one the dependencies were actually installed with. x64-windows-meshlib is install.bat's default, so it is the right value for Visual Studio 2026; on Visual Studio 2019 or 2022, step 4 of Installing the local build has you set VCPKG_DEFAULT_TRIPLET to x64-windows-vs2019-meshlib or x64-windows-vs2022-meshlib, so pass that same value here.

Warning: Do not fall back to x64-windows-meshlib on an older toolset because it pins no VCPKG_PLATFORM_TOOLSET — that only governs what vcpkg builds itself. With the AWS CLI installed (step 3 of the same list), install.bat instead restores prebuilt packages from our public S3 cache at s3://vcpkg-export/<vcpkg-tag>/<triplet>/, keyed on the triplet name, not on your compiler. CI fills the x64-windows-meshlib folder from msvc-2026 builds only, and the triplets set VCPKG_DISABLE_COMPILER_TRACKING, so vcpkg accepts those Visual Studio 2026 binaries on v142/v143 instead of rebuilding, and the link fails.

Note: This builds MeshLib from source (~40 GB) and does install the CMake config files, so the Quick Integration Guide above applies to the result. To consume a pre-built MeshLib in your own project instead, use Prebuilt archive from GitHub Releases above.

Table of Contents