Skip to main content

macOS Simulator

Build a macOS version of your SPECS NDK native library with the macOS Simulator toolchain, to run it in Lens Studio on an Apple silicon Mac.

macOS Simulator support is in beta. The simulator implements some SPECS modules, and the rest are still stubs; see which SPECS modules the macOS Simulator implements.

The SPECS NDK's macOS Simulator toolchain builds a macOS version of your native library instead of an aarch64 SPECS binary. It compiles your code with Xcode's Clang and links it against the SPECS Simulator's macOS implementations of the SPECS module APIs, so the library can run in Lens Studio's preview on a Mac. Use it to iterate on native code without deploying to a SPECS device.

Before you start with the macOS Simulator

  • A Mac with Apple silicon. The simulator libraries are arm64 only. On an Intel Mac the library still builds, but it runs only in Lens Studio on Apple silicon.
  • Xcode Command Line Tools, which provide Xcode's Clang and the macOS SDK. Install them with xcode-select --install.
  • CMake 3.24 or later, as for device builds (see Host Setup on macOS).
  • The macOS tarball of the SPECS NDK. The Simulator toolchain file and the simulator libraries ship only in the macOS tarball.

Build a native library for the macOS Simulator

Point CMake at SpecsNDK-Toolchain-Simulator-macOS.cmake instead of the device toolchain, and keep the project itself unchanged. Link SPECS modules by name, as for a device build:

cmake_minimum_required(VERSION 3.15)
project(MyLensModule CXX)

add_library(lensmodule SHARED binding.cpp)
target_compile_features(lensmodule PRIVATE cxx_std_20)
target_link_libraries(lensmodule PRIVATE specs_camera specs_log)

SpecsFs is the one exception. On the device it is header-only, so there is no specs_fs library to link, and linking it fails with unable to find library -lspecs_fs. In a simulator build it is a library, and leaving it out fails with undefined symbols. The Simulator toolchain sets the CMake variable SPECSNDK_SIMULATOR, so link it only there:

if(SPECSNDK_SIMULATOR)
target_link_libraries(lensmodule PRIVATE specs_fs)
endif()

Configure and build into a separate build folder, so device and simulator builds don't share a CMake cache:

NDK=/path/to/specsndk-armv8-1.3.0

cmake -B build-simulator \
-DCMAKE_TOOLCHAIN_FILE="${NDK}/SpecsNDK-Toolchain-Simulator-macOS.cmake" \
-DCMAKE_BUILD_TYPE=Release
cmake --build build-simulator

The result is a macOS library:

file build-simulator/liblensmodule.dylib
# build-simulator/liblensmodule.dylib: Mach-O 64-bit dynamically linked shared library arm64

It requires macOS 11.0 or later, and refers to the SPECS libraries through @rpath (for example @rpath/libspecs_camera.2.dylib). Lens Studio provides those libraries when it loads your library, so the .dylib doesn't run on its own outside Lens Studio.

Add the simulator library to your Lens project

Give the simulator library the same name as the device library, so liblensmodule.dylib pairs with liblensmodule.so. Place the .dylib next to the .so in your Lens project's Assets/NativeModules/:

Assets/NativeModules/
├── liblensmodule.so # device build
└── liblensmodule.dylib # macOS Simulator build

For loading the library from a script, see Deployment Steps.

What the macOS Simulator toolchain sets

The macOS Simulator toolchain is standalone. It doesn't include SpecsNDK-Toolchain-common.cmake, and it never uses the device sysroot (sysroots/armv8a-snap-linux/).

SettingValue
CompilerXcode's Clang, found with xcrun --find clang and xcrun --find clang++
SDKThe macOS SDK, from xcrun --sdk macosx --show-sdk-path
ArchitectureCMAKE_OSX_ARCHITECTURES = arm64 unless you set it
Minimum macOSCMAKE_OSX_DEPLOYMENT_TARGET = 11.0
Preprocessor-DSPECSNDK -DSPECSNDK_SIMULATOR on every C and C++ compile
CMake variablesSPECSNDK and SPECSNDK_SIMULATOR, both ON
SPECS headersThe same Specs*.h headers as device builds
SPECS librariessysroots/x86_64-specsndk-darwin21/usr/lib/specs-simulator/
Install name@rpath

The toolchain doesn't set CMAKE_SYSTEM_NAME, because a simulator build is a native macOS build, not a cross-compile, so try_run() checks and native code paths work as usual. find_library() and find_package() search only the macOS SDK, so the NDK's own host-tool libraries are never picked up. To use your own dependencies, add their install prefixes to CMAKE_FIND_ROOT_PATH.

To keep code that only makes sense on the device out of a simulator build, test SPECSNDK_SIMULATOR:

#ifdef SPECSNDK_SIMULATOR
// macOS Simulator build
#else
// SPECS device build
#endif

SPECSNDK is defined in both builds; see Detecting the SPECS Target in Code.

Which SPECS modules the macOS Simulator implements

ModuleLibraryIn the macOS Simulator
SpecsCameraspecs_cameraImplemented
SpecsLogspecs_logImplemented: messages print as [I] <tag>: <message>
SpecsFsspecs_fs (simulator builds only)Implemented: returns the SPECS_SIM_DATA_DIR and SPECS_SIM_LIB_DIR environment variables, or NULL when they're unset or empty
SpecsAudio (playback and record)specs_audio_playback, specs_audio_recordStub
SpecsForegroundAudioSessionspecs_foreground_audioStub
SpecsLocationspecs_locationStub
SpecsMedia, SpecsRecorder, SpecsCapturespecs_mediaStub
SpecsPlayerspecs_playerStub

A stub module links and loads, so the same code builds for the device and the simulator. Its functions do nothing and return success. Each call logs a warning such as:

[W] SpecsSimulator: SpecsPlayer_create is not implemented in the simulator yet

A stub call that returns success therefore hasn't created a player, opened a stream or recorded anything. Test behaviour that depends on a stub module on a SPECS device.