Linux SDK

Build a shared CPU SDK for Linux x86_64, ARMv7 or ARM64, then link it from a native application or package it with Python. NVIDIA and Rockchip builds have separate TensorRT and RKNPU instructions.

Complete source preparation first. Run the commands below from the InspireFace repository root. For an existing binary package, use the SDK downloads.

For ARM CPU image processing, feature comparison and camera-loop tuning, see ARM deployment.

Choose the build environment

Choose the C library and compiler runtime for the target device as well as its CPU architecture. These generic ARM scripts use GNU/Linux toolchains; use the Rockchip chapter for the RV1106 uClibc build.

Build on the target machine

On a Linux desktop, server or ARM development board, this builds for the active compiler's architecture. It keeps the build tree so you can change options and rebuild incrementally.

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

The default CPU build compiles MNN into the shared SDK. Its image handling does not require an OpenCV installation. Headers and the library are installed here:

build/linux-cpu/install/
  InspireFace/
    include/inspireface.h
    include/intypedef.h
    include/herror.h
    include/inspireface/
    include/inspirecv/
    lib/libInspireFace.so
  version.txt

Set INSPIREFACE_ROOT to build/linux-cpu/install/InspireFace when following the C API linking example. A model pack remains a separate file; download it using Models and builds.

Build an x86_64 release directory

The packaging scripts build with four jobs, disable tests and samples, and collect the installed files into a named directory. With VERSION=1.2.4:

On an x86_64 Linux host with Docker Compose, use the repository's Ubuntu 18.04 environment:

VERSION=1.2.4 docker compose run --build --rm build-ubuntu18

For the manylinux2014 environment, override the service command to build only the native SDK:

VERSION=1.2.4 docker compose run --build --rm \
  build-manylinux2014-x86 bash command/build_linux_manylinux2014.sh

Both commands mount the checkout at /workspace and write the result back to its build/ directory. VERSION changes the directory suffix; the SDK's actual version comes from the source. Omit it for an unversioned directory.

Ubuntu and manylinux

The build environment determines the required glibc and C++ runtime versions. Running build_linux_ubuntu18.sh directly on a newer distribution uses that newer system's compiler and libraries; the script name does not set an Ubuntu compatibility level.

Use the manylinux container when preparing the corresponding Linux Python package. The Compose service normally runs build_wheel_manylinux2014_x86.sh, which also copies the .so into the Python project and builds a wheel. The override above stops at the native SDK. Wheel contents, platform tags and replacing the .so are covered in Python packaging.

Cross-compile for ARM

Install an x86_64-hosted GNU toolchain whose target runtime matches your board. ARM_CROSS_COMPILE_TOOLCHAIN points to the toolchain root, one level above bin/. Run each build with the matching toolchain.

ARMv7 hard-float

export ARM_CROSS_COMPILE_TOOLCHAIN=/opt/arm-linux-gnueabihf-toolchain
"$ARM_CROSS_COMPILE_TOOLCHAIN/bin/arm-linux-gnueabihf-gcc" --version
VERSION=1.2.4 bash command/build_cross_armv7_armhf.sh

This sets CMAKE_SYSTEM_PROCESSOR=armv7 and ISF_BUILD_LINUX_ARM7=ON. The result is build/inspireface-linux-armv7-armhf-1.2.4/InspireFace, containing include/ and lib/libInspireFace.so.

ARM64

export ARM_CROSS_COMPILE_TOOLCHAIN=/opt/aarch64-linux-gnu-toolchain
"$ARM_CROSS_COMPILE_TOOLCHAIN/bin/aarch64-linux-gnu-gcc" --version
VERSION=1.2.4 bash command/build_cross_aarch64.sh

This sets CMAKE_SYSTEM_PROCESSOR=aarch64 and ISF_BUILD_LINUX_AARCH64=ON. The result is build/inspireface-linux-aarch64-1.2.4/InspireFace.

Both scripts pass the compiler paths to CMake and use the toolchain's default sysroot. For a board with a separate vendor sysroot, use a CMake toolchain file that defines the compiler and CMAKE_SYSROOT, then apply the corresponding ISF_BUILD_LINUX_* option. Link and run the application against the board's own runtime libraries.

The repository's ARM Dockerfiles use Linaro GCC 6.3.1 toolchains. Check cmake --version inside the image before building: the ARM64 Dockerfile installs Ubuntu 18.04's distribution CMake, so it needs upgrading to at least 3.20 for this source tree. The compiler itself is an x86_64 Linux executable; use a Linux x86_64 host or container environment for these toolchains.

Check and deploy the library

Inspect the native CPU build with:

file build/linux-cpu/install/InspireFace/lib/libInspireFace.so
readelf -h build/linux-cpu/install/InspireFace/lib/libInspireFace.so
readelf -d build/linux-cpu/install/InspireFace/lib/libInspireFace.so

For a cross build, substitute its output path and use the matching toolchain's readelf. Check Machine and Class for architecture and bitness, and NEEDED entries for runtime dependencies. The build also checks that the shared library does not request an executable stack.

Copy the SDK's include/ and lib/ directories together. Configure the application's runtime search path to find its packaged libraries, then run the complete detection program on the target with a matching CPU resource pack. An ARM library cannot be smoke-tested by loading it into an x86_64 application.

Common build issues

Build definitions: Linux packaging scripts, Docker environments and SDK installation rules.