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/).
| Setting | Value |
|---|---|
| Compiler | Xcode's Clang, found with xcrun --find clang and xcrun --find clang++ |
| SDK | The macOS SDK, from xcrun --sdk macosx --show-sdk-path |
| Architecture | CMAKE_OSX_ARCHITECTURES = arm64 unless you set it |
| Minimum macOS | CMAKE_OSX_DEPLOYMENT_TARGET = 11.0 |
| Preprocessor | -DSPECSNDK -DSPECSNDK_SIMULATOR on every C and C++ compile |
| CMake variables | SPECSNDK and SPECSNDK_SIMULATOR, both ON |
| SPECS headers | The same Specs*.h headers as device builds |
| SPECS libraries | sysroots/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
| Module | Library | In the macOS Simulator |
|---|---|---|
| SpecsCamera | specs_camera | Implemented |
| SpecsLog | specs_log | Implemented: messages print as [I] <tag>: <message> |
| SpecsFs | specs_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_record | Stub |
| SpecsForegroundAudioSession | specs_foreground_audio | Stub |
| SpecsLocation | specs_location | Stub |
| SpecsMedia, SpecsRecorder, SpecsCapture | specs_media | Stub |
| SpecsPlayer | specs_player | Stub |
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.
Related
- Build your first Native Lens: the same project built for the SPECS device.
- CMake toolchain: the device toolchain and its variables.
- Detecting the SPECS Target in Code:
SPECSNDKand the version macros.