Platform-Specific Notes

NFIQ 2 supports multiple platforms with varying levels of complexity. This page details platform-specific considerations and workarounds.

Windows

Build Requirements

Visual Studio 2015 or later (2019/2022 recommended)
CMake 3.3+
vcpkg for dependency management

Using vcpkg

Windows builds require vcpkg to manage libbiomeval dependencies.

Install vcpkg

git clone https://github.com/microsoft/vcpkg.git C:\vcpkg
cd C:\vcpkg
.\bootstrap-vcpkg.bat

Install NFIQ 2 dependencies

.\vcpkg install berkeleydb:x64-windows-static hwloc:x64-windows-static ^
  libjpeg-turbo:x64-windows-static openjpeg:x64-windows-static ^
  libpng:x64-windows-static openssl:x64-windows-static ^
  sqlite3:x64-windows-static tiff:x64-windows-static ^
  zlib:x64-windows-static zstd:x64-windows-static

For 32-bit builds, use x86-windows-static instead.

Configure CMake with vcpkg toolchain

cmake .. ^
  -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake ^
  -DVCPKG_TARGET_TRIPLET=x64-windows-static ^
  -DCMAKE_CONFIGURATION_TYPES=Release ^
  -A x64

Build

cmake --build . --config Release

Architecture Selection

Use the -A flag to specify the target architecture:

cmake .. -A x64 -DVCPKG_TARGET_TRIPLET=x64-windows-static

Static vs. Dynamic Linking

For standalone executables without external DLL dependencies, use static triplets:

# Static linking (recommended for distribution)
-DVCPKG_TARGET_TRIPLET=x64-windows-static

# Dynamic linking (for development)
-DVCPKG_TARGET_TRIPLET=x64-windows

Common Issues

vcpkg not found

Ensure the CMAKE_TOOLCHAIN_FILE path points to your vcpkg installation:

-DCMAKE_TOOLCHAIN_FILE=C:\path\to\vcpkg\scripts\buildsystems\vcpkg.cmake

Missing DLLs at runtime

Use static triplets (x64-windows-static) to avoid DLL dependencies, or copy required DLLs from vcpkg’s installed directory.

Linker errors with mixed architectures

Ensure VCPKG_TARGET_TRIPLET matches the CMake architecture:

-A x64 → x64-windows-static
-A Win32 → x86-windows-static

macOS

Build Requirements

Xcode 10+ (Xcode 15+ recommended)
Command Line Tools: xcode-select --install
MacPorts or Homebrew for dependencies

Using MacPorts (Recommended)

Install MacPorts

Download and install from macports.org

Install dependencies

sudo port install berkeley-db cmake hwloc jpeg openjpeg libpng \
  openssl sqlite3 tiff xz zlib zstd

Build NFIQ 2

cmake ..
cmake --build .

Universal Binary (Intel + Apple Silicon)

To create a universal binary that runs natively on both Intel and Apple Silicon Macs:

Install universal dependencies

Use the +universal variant for all dependencies:

sudo port install berkeley-db +universal cmake hwloc +universal \
  jpeg +universal openjpeg +universal libpng +universal \
  openssl +universal sqlite3 +universal tiff +universal \
  xz +universal zlib +universal zstd +universal

Configure for both architectures

cmake .. -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64"

Build

cmake --build .

Verify universal binary

lipo -archs NFIQ2/NFIQ2Algorithm/nfiq2
# Output: x86_64 arm64

All dependencies must be built universally. If any dependency is single-architecture, the build will fail with linker errors.

Architecture-Specific Builds

cmake .. -DCMAKE_OSX_ARCHITECTURES=x86_64

Known Limitations

Xcode 10+ does not support 32-bit applications. To build NFIQ 2 for 32-bit macOS, you must use Xcode 9.4.x or earlier.

Common Issues

OpenSSL not found

Specify the OpenSSL root directory:

cmake .. -DOPENSSL_ROOT_DIR=/opt/local

Dynamic library dependencies in release builds

For distribution, force static dependencies:

cmake .. -DMACOS_FORCE_STATIC=ON

Code signing errors

If distributing signed packages:

cmake .. -DMACOS_CODESIGN=ON \
  -DMACOS_APPLICATION_SIGNING_IDENTITY="Developer ID Application: Your Name" \
  -DMACOS_INSTALLER_SIGNING_IDENTITY="Developer ID Installer: Your Name"

Linux

Supported Distributions

NFIQ 2 has been tested on:

Ubuntu 18.04, 20.04, 22.04, 24.04
Debian 10, 11, 12
RHEL / CentOS / Rocky Linux 7, 8, 9
Fedora 36+

Build Requirements

Ubuntu/Debian
RHEL/CentOS/Fedora

sudo apt-get update
sudo apt-get install build-essential cmake libdb++-dev \
  libhwloc-dev libjbig-dev libjpeg-dev libopenjp2-7-dev \
  liblzma-dev libpng-dev libsqlite3-dev libssl-dev \
  libtiff-dev libzstd-dev zlib1g-dev

sudo yum install cmake gcc-c++ hwloc-devel jbigkit-devel \
  libdb-cxx-devel libjpeg-turbo-devel libpng-devel \
  libsqlite3x-devel libtiff-devel libzstd-devel \
  openssl-devel openjpeg2-devel xz-devel zlib-devel

Standard Build

cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .

Creating Distribution Packages

Debian (.deb)
Red Hat (.rpm)

cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .
cpack -G DEB

Output:

nfiq2_{version}-1_{arch}.deb (CLI)
nfiq2-dev_{version}-1_{arch}.deb (development files)

Install:

sudo dpkg -i nfiq2_*.deb

cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .
cpack -G RPM

Output:

nfiq2-{version}-1.el{ver}.{arch}.rpm (CLI)
nfiq2-devel-{version}-1.el{ver}.{arch}.rpm (development files)

Install:

sudo rpm -i nfiq2-*.rpm

Architecture

Architecture is typically auto-detected. For explicit control:

cmake .. -DCMAKE_C_FLAGS="-m32" -DCMAKE_CXX_FLAGS="-m32"

Android

NFIQ 2 supports Android NDK builds for ARM and x86 architectures.

Build Requirements

Android NDK (r21e or later recommended)
CMake 3.10+

Using Android Toolchain

Set NDK environment variable

export ANDROID_NDK=/path/to/android-ndk

Configure for Android

cmake .. \
  -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK/build/cmake/android.toolchain.cmake \
  -DANDROID_ABI=arm64-v8a \
  -DANDROID_PLATFORM=android-21 \
  -DBUILD_NFIQ2_CLI=OFF

Build

cmake --build .

Supported ABIs

-DANDROID_ABI=arm64-v8a

Minimum API Level

NFIQ 2 supports Android API level 21 (Android 5.0 Lollipop) and later:

-DANDROID_PLATFORM=android-21

The CLI is typically not built for Android. Use -DBUILD_NFIQ2_CLI=OFF for library-only builds.

iOS

NFIQ 2 supports iOS builds for both physical devices and simulators.

Build Requirements

Xcode 10+
CMake 3.14+
iOS Deployment Target: iOS 12.0+

Using iOS Toolchain

Download iOS CMake toolchain

The repository includes cmake/ios.toolchain.cmake

Configure for iOS device

cmake .. \
  -DCMAKE_TOOLCHAIN_FILE=../cmake/ios.toolchain.cmake \
  -DPLATFORM=OS64 \
  -DBUILD_NFIQ2_CLI=OFF

Build

cmake --build .

Platform Options

-DPLATFORM=OS64

Bitcode

To enable bitcode for App Store submission:

cmake .. \
  -DCMAKE_TOOLCHAIN_FILE=../cmake/ios.toolchain.cmake \
  -DPLATFORM=OS64 \
  -DENABLE_BITCODE=ON

The CLI is not supported on iOS. Always use -DBUILD_NFIQ2_CLI=OFF for iOS builds.

Cross-Compilation

For cross-compiling to other platforms, specify a CMake toolchain file:

cmake .. -DCMAKE_TOOLCHAIN_FILE=/path/to/toolchain.cmake

Refer to the CMake documentation for creating custom toolchain files.

Next Steps

Library Build

Build the NFIQ 2 library only

CLI Build

Build with command-line interface

Get Started

Core Concepts

Guides

CLI Tool

Building from Source

Platform-Specific Notes

Windows

Build Requirements

Using vcpkg

Architecture Selection

Static vs. Dynamic Linking

Common Issues

macOS

Build Requirements

Using MacPorts (Recommended)

Universal Binary (Intel + Apple Silicon)

Architecture-Specific Builds

Known Limitations

Common Issues

Linux

Supported Distributions

Build Requirements

Standard Build

Creating Distribution Packages

Architecture

Android

Build Requirements

Using Android Toolchain

Supported ABIs

Minimum API Level

iOS

Build Requirements

Using iOS Toolchain

Platform Options

Bitcode

Cross-Compilation

Next Steps

Library Build

CLI Build

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

CLI Tool

Building from Source

Documentation Index

​Windows

​Build Requirements

​Using vcpkg

​Architecture Selection

​Static vs. Dynamic Linking

​Common Issues

​macOS

​Build Requirements

​Using MacPorts (Recommended)

​Universal Binary (Intel + Apple Silicon)

​Architecture-Specific Builds

​Known Limitations

​Common Issues

​Linux

​Supported Distributions

​Build Requirements

​Standard Build

​Creating Distribution Packages

​Architecture

​Android

​Build Requirements

​Using Android Toolchain

​Supported ABIs

​Minimum API Level

​iOS

​Build Requirements

​Using iOS Toolchain

​Platform Options

​Bitcode

​Cross-Compilation

​Next Steps

Library Build

CLI Build

Build docs developers (and LLMs) love

Windows

Build Requirements

Using vcpkg

Architecture Selection

Static vs. Dynamic Linking

Common Issues

macOS

Build Requirements

Using MacPorts (Recommended)

Universal Binary (Intel + Apple Silicon)

Architecture-Specific Builds

Known Limitations

Common Issues

Linux

Supported Distributions

Build Requirements

Standard Build

Creating Distribution Packages

Architecture

Android

Build Requirements

Using Android Toolchain

Supported ABIs

Minimum API Level

iOS

Build Requirements

Using iOS Toolchain

Platform Options

Bitcode

Cross-Compilation

Next Steps