Platform-Specific Notes

Platform-specific build instructions, requirements, and known limitations

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.

1. Install vcpkg

   git clone https://github.com/microsoft/vcpkg.git C:\vcpkg
   cd C:\vcpkg
   .\bootstrap-vcpkg.bat
   
2. 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.

3. 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
   
4. Build

   cmake --build . --config Release
   

Architecture Selection

Use the -A flag to specify the target architecture:

64-bit (x64)

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)

1. Install MacPorts

   Download and install from macports.org

2. Install dependencies

   sudo port install berkeley-db cmake hwloc jpeg openjpeg libpng \
     openssl sqlite3 tiff xz zlib zstd
   
3. 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:

1. 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
   
2. Configure for both architectures

   cmake .. -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64"
   
3. Build

   cmake --build .
   
4. 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

Intel (x86_64) only

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

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

RHEL/CentOS/Fedora

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)

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

Red Hat (.rpm)

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:

32-bit

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

1. Set NDK environment variable

   export ANDROID_NDK=/path/to/android-ndk
   
2. 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
   
3. Build

   cmake --build .
   

Supported ABIs

ARM 64-bit (recommended)

-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

1. Download iOS CMake toolchain

   The repository includes cmake/ios.toolchain.cmake

2. Configure for iOS device

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

   cmake --build .
   

Platform Options

iOS Device (arm64)

-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