Skip to main content

Prerequisites and NDK Layout

Host requirements, tarball choice, and directory layout of the SPECS NDK, before you cross-compile your first native library.

The Get Started pages walk you from first receiving the SPECS NDK to successfully cross-compiling a working native library. This page lists what your build host needs and how the extracted NDK is laid out.

Prerequisites

RequirementDetails
Host OSmacOS (darwin21 or later) or Windows 10+ x86_64
DeviceSPECS OS 3.0.0 or later on the device
CMake≥ 3.15 (≥ 3.24 strongly recommended: automatic .snap.permissions embedding relies on CMAKE_PROJECT_TOP_LEVEL_INCLUDES, which CMake silently ignores below 3.24; see Permission Annotations and Manifest Embedding). macOS hosts must supply their own (for example brew install cmake). Windows hosts can use the bundled cmake.exe (3.28.3) under sysroots/x86_64-w64-mingw32/usr/bin/, or supply their own.
pkg-configOnly if your CMake project uses pkg_check_modules (see Linking and pkg-config). Supply your own on each host (macOS: brew install pkg-config; Windows: MSYS2/Chocolatey choco install pkgconfiglite).
CompilerNot required: Clang is bundled in the NDK. Clang is 18.1.8 on macOS (Yocto nativesdk-clang) and 22 on Windows (upstream llvm-mingw; see Host Setup on Windows).
LinkerNot required: LLD is bundled as part of the Clang toolchain on both hosts
Disk~3 GB free for the extracted SDK

No separate Xcode command line tools or Homebrew cross-compilers are needed. Everything is self-contained.

The host portion of the toolchain is platform-specific:

  • macOS host → specsndk-armv8-<VERSION>-darwin21-x86_64.tar
  • Windows host → specsndk-armv8-<VERSION>-mingw32-x86_64.tar

Both tarballs are XZ-compressed despite the .tar extension. Use tar -xJf to extract (Windows 10+ has tar.exe built in). Both produce identical aarch64 target binaries; only the host tools differ.

NDK layout

The macOS tarball extracts to this layout, where <version> is the NDK release (for example, 1.3.0):

specsndk-armv8-<version>/
├── SpecsNDK-Toolchain-Clang.cmake # ← use this in new projects
├── SpecsNDK-Toolchain-common.cmake # shared settings (included by above)
├── SpecsNDK-Toolchain-Simulator-macOS.cmake # macOS Simulator toolchain
├── source.properties # package metadata (NDK revision, minimum SPECS OS, modules)
├── version-armv8a-snap-linux # version metadata file
├── relocate_sdk.py, post-relocate-setup.sh # not needed on macOS or Windows
├── licenses/
│ ├── THIRD_PARTY_NOTICES.txt # license texts for all bundled third-party packages
│ └── specsndk-armv8-<version>-darwin21-x86_64.spdx.json # SPDX SBOM for this tarball
└── sysroots/
├── armv8a-snap-linux/ # TARGET sysroot
│ └── usr/
│ ├── include/ # SPECS headers + stdlib headers
│ │ ├── SpecsPlayer.h
│ │ ├── SpecsAudioPlayback.h
│ │ ├── SpecsAudioRecord.h
│ │ ├── SpecsMedia.h
│ │ ├── SpecsMediaCodec.h
│ │ ├── SpecsMediaExtractor.h
│ │ ├── SpecsMediaFormat.h
│ │ ├── SpecsMediaPresenter.h
│ │ ├── SpecsMediaBuffer.h
│ │ ├── SpecsMediaGLTexture.h
│ │ ├── SpecsRecorder.h
│ │ ├── SpecsCapture.h # one-shot MP4 capture
│ │ ├── SpecsForegroundAudioSession.h
│ │ ├── SpecsForegroundAudioSessionCoordinator.h
│ │ ├── SpecsCameraManager.h
│ │ ├── SpecsCameraStructures.h
│ │ ├── SpecsCameraDefinitions.h
│ │ ├── SpecsLocationProvider.h
│ │ ├── SpecsLocationDefinitions.h
│ │ ├── SpecsLog.h
│ │ ├── SpecsFs.h # app directories (header-only on the device)
│ │ ├── SpecsPermissions.h # permission annotation macro
│ │ ├── SpecsNDKVersion.h # NDK version macros
│ │ └── ... # standard C/C++ and other headers
│ ├── lib/
│ │ ├── libspecs_player.so
│ │ ├── libspecs_media.so
│ │ ├── libspecs_audio_playback.so
│ │ ├── libspecs_audio_record.so
│ │ ├── libspecs_foreground_audio.so
│ │ ├── libspecs_camera.so
│ │ ├── libspecs_location.so
│ │ ├── libspecs_log.so
│ │ └── ... # standard and platform shared libraries
│ └── share/specsndk/
│ └── specs-permissions.json # symbol → permission map used by specs-perm-embed
└── x86_64-specsndk-darwin21/ # HOST tools (macOS)
└── usr/
├── bin/
│ ├── clang, clang++ # Clang 18.1.8
│ ├── ld.lld # LLVM linker
│ ├── ninja # Ninja 1.11.1
│ └── specs-perm-embed # embeds .snap.permissions
└── share/specsndk/
├── SpecsPostLink.cmake # auto perm-embed hook (loaded by the toolchain)
└── specs-perm-read.py # reference reader for .snap.permissions

The Windows tarball has the same target sysroot and the same SpecsNDK-Toolchain-Clang.cmake and SpecsNDK-Toolchain-common.cmake. It differs at the root and in the host tree:

specsndk-armv8-<version>/ # Windows tarball
├── SpecsNDK-Toolchain-Clang.cmake
├── SpecsNDK-Toolchain-common.cmake
├── source.properties
├── version-armv8a-snap-linux
├── relocate_sdk.py, post-relocate-setup.sh # not needed on macOS or Windows
├── licenses/
│ ├── THIRD_PARTY_NOTICES.txt
│ └── specsndk-armv8-<version>-mingw32-x86_64.spdx.json # SPDX SBOM for this tarball
└── sysroots/
├── armv8a-snap-linux/ # TARGET sysroot (same as macOS)
└── x86_64-w64-mingw32/ # HOST tools (Windows)
└── usr/
├── bin/
│ ├── cmake.exe, cpack.exe, ctest.exe # CMake 3.28.3
│ ├── ninja.exe # Ninja 1.11.1
│ └── specs-perm-embed.exe # embeds .snap.permissions
├── lib/llvm-mingw/bin/
│ ├── clang.exe, clang++.exe # Clang 22 (llvm-mingw; selected by the toolchain file)
│ └── ld.lld.exe # LLVM linker
└── share/specsndk/
├── SpecsPostLink.cmake
└── specs-perm-read.py

The Windows tarball has no SpecsNDK-Toolchain-Simulator-macOS.cmake. Both tarballs also contain Yocto environment and site-config scripts (environment-setup-*, site-config-*); SPECS NDK v1.3.0 builds use the CMake toolchain files instead, so you don't need them.

Host-tools directory by host

The following table lists the supported tools only (see Host-only tools).

HostDirectory under sysroots/Supported tools
macOS (darwin21+)x86_64-specsndk-darwin21/usr/bin/Clang/LLVM 18.1.8 (clang, clang++, ld.lld), Ninja 1.11.1, specs-perm-embed. CMake is not bundled on macOS (supply your own, ≥ 3.24 recommended)
Windows 10+ x86_64x86_64-w64-mingw32/usr/bin/ (CMake/Ninja/SPECS tools) plus x86_64-w64-mingw32/usr/lib/llvm-mingw/bin/ (host Clang/LLD)Clang/LLVM 22 via llvm-mingw (clang.exe, clang++.exe, ld.lld.exe), CMake 3.28.3 (cmake.exe, cpack.exe, ctest.exe), Ninja 1.11.1 (ninja.exe), specs-perm-embed.exe

The host trees contain additional binaries beyond these; they are internal toolchain support and not part of the supported NDK surface (see the note under Host-only tools).

Which files reach the device

Key rule: Only files under sysroots/armv8a-snap-linux/ end up in your target binary. The host-tools tree (x86_64-specsndk-darwin21/ on macOS, x86_64-w64-mingw32/ on Windows) is purely for the build host and is never shipped to the device.

On both hosts the toolchain works in place after extraction: Mach-O on macOS and PE/COFF on Windows both resolve library paths relative to the executable, so no path patching is needed. See Host Setup on macOS and Host Setup on Windows.