Source and common options

Get the SDK source and its dependencies, then choose a platform build. Run subsequent build commands from the SDK directory entered below unless a block explicitly changes directory.

Get the source

Choose one of the following sources.

Release version (recommended)

For regular integration, start with the Release version in InsightFace. Enter cpp-package/inspireface before downloading the dependencies:

git clone https://github.com/deepinsight/insightface.git
cd insightface/cpp-package/inspireface
git clone --recurse-submodules https://github.com/tunmx/inspireface-3rdparty.git 3rdparty

Develop version

Use the Develop repository for the latest features, more frequent updates and faster bug-fix follow-up:

git clone https://github.com/HyperInspire/InspireFace.git
cd InspireFace
git clone --recurse-submodules https://github.com/tunmx/inspireface-3rdparty.git 3rdparty

Continue with the build guide for your target platform.

Prepare the build tools

Tool	Requirement
Git	Fetch the SDK and recursive third-party dependencies.
CMake	3.20 or newer.
C++ compiler	C++14 support; use the target platform’s compiler or cross toolchain.
Build tool	Make or Ninja for direct CMake builds; most `command/` scripts call Make.
Platform SDK	Android NDK, Xcode, OpenHarmony Native SDK or board toolchain as applicable.

Some bundled dependencies use older CMake policy settings. The direct CMake commands here pass -DCMAKE_POLICY_VERSION_MINIMUM=3.5 for CMake 4 compatibility. The unified Apple builder also passes this setting. The HarmonyOS HAR script does not, so use CMake 3.20–3.x for that script.

Build a CPU SDK

On Linux or macOS, this builds a shared SDK for the active compiler’s target and retains intermediate files for incremental builds:

cmake -S . -B build/local-cpu \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_POLICY_VERSION_MINIMUM=3.5 \
  -DISF_BUILD_SHARED_LIBS=ON \
  -DISF_INSTALL_CPP_HEADER=ON \
  -DISF_BUILD_WITH_SAMPLE=OFF \
  -DISF_BUILD_WITH_TEST=OFF
cmake --build build/local-cpu --parallel 4
cmake --install build/local-cpu

This direct build produces the native C/C++ library. For Objective-C and Swift frameworks, use the unified Apple builder in the iOS or macOS chapter.

Use a separate build directory for each architecture and backend. The Linux and macOS chapters add platform-specific settings and binary inspection commands.

Understand the output layout

Direct CMake builds install into the build directory’s install subdirectory. The CPU command above produces:

build/local-cpu/install/
  InspireFace/
    include/
      inspireface.h
      intypedef.h
      herror.h
      inspireface/
      inspirecv/
    lib/
      libInspireFace.so       # Linux; libInspireFace.dylib on macOS
  version.txt

Set INSPIREFACE_ROOT to build/local-cpu/install/InspireFace when using the C or C++ application examples. Python needs the full shared-library file path instead; see Python packaging.

Release scripts reorganize their output

Many scripts under command/ move installed files to the top of their own build directory and delete intermediate compilation files. Their final paths therefore differ from a direct CMake build. Keep application files outside those directories, and use each platform page’s stated output path.

The Apple builder keeps reusable dependency caches under build/apple-cache and stages SDK outputs separately; see the macOS and iOS guides.

Common CMake options

Option	Default	Effect
`ISF_BUILD_SHARED_LIBS`	`ON`	Build a shared library; static applications must link its dependencies too.
`ISF_INSTALL_CPP_HEADER`	`ON`	Install C++ and image-processing headers alongside the C API.
`ISF_BUILD_WITH_SAMPLE`	`ON`	Build the source sample programs.
`ISF_BUILD_WITH_TEST`	`ON`	Build the test target; model files and fixtures are needed when running it.
`ISF_NEVER_USE_OPENCV`	`ON`	Use the default image path without an OpenCV dependency.
`ISF_ENABLE_TENSORRT`	`OFF`	Enable the NVIDIA TensorRT backend.
`ISF_ENABLE_RKNN`	`OFF`	Enable the Rockchip NPU backend.
`ISF_ENABLE_RGA`	`OFF`	Enable Rockchip preprocessing with a supported RKNPU2 configuration.
`ISF_ENABLE_APPLE_EXTENSION`	`OFF`	Enable Apple extensions, including CoreML support.
`ISF_BUILD_APPLE_FRAMEWORK`	`OFF`	Build the Objective-C framework and Swift overlay on Apple platforms.
`ISF_BUILD_APPLE_TESTS`	`OFF`	Build Apple API contract tests.
`ISF_ENABLE_INSPIRECV_TASK_PREPROCESS`	`OFF`	Use the Task preprocessing path.

These are the top-level defaults. Platform scripts override them, particularly shared/static linkage, samples, tests and hardware backends. ISF_INSPIRECV_SOURCE_DIR can select another image-processing source checkout; rebuild the native SDK and keep its installed headers together after changing it.

Check the build in an application

Check the binary architecture and dynamic dependencies using your platform chapter. Then load a matching resource pack, run a still-image example and query the SDK version. Verify this small path before adding camera input, Python packaging or hardware-specific tuning. The API diagnostics examples provide version and build information queries.