iOS cross-compilation: Linux toolchain requirements

The current build scripts recognize iOS cross-compilation through OSXCROSS_IOS. This enables a configuration branch; it neither installs a toolchain nor proves a working Linux build. If you need a template without maintaining your own toolchain, use the macOS build guide.

Toolchain requirements

Work in Source, alongside SConstruct. In addition to Python 3.9+ and SCons 4.4+, you need compatible Apple SDK, C/C++ and Swift tools:

Setting	Current build expectation
`OSXCROSS_IOS`	An environment variable: presence is sufficient, even with an empty value. Do not set it for a normal native macOS build.
`APPLE_TOOLCHAIN_PATH`	A directory with `usr/bin` containing the required compiler, archive and link tools. Without an explicit path the helper tries `xcode-select`.
`APPLE_SDK_PATH`	The matching SDK directory, not an archive. Without an explicit path the helper calls `xcrun`.
`apple_target_triple`	A tool-name prefix, including a trailing hyphen if present in the names. This is neither the Swift target nor a `clang -target` flag.
`SWIFT_COMPILER`	An explicit path to a Linux-executable `swiftc` capable of compiling the Apple target with the required SDK. The cross branch does not select Swift automatically.

The script looks for ${apple_target_triple}clang, clang++, ar, ranlib and libtool under APPLE_TOOLCHAIN_PATH/usr/bin. Having only clang is insufficient. The iOS SCsub always includes Swift sources, the shared SwiftUI controller and Swift→Objective-C header generation. Swift runs with -swift-version 6 and C++ interop; its device target is arm64-apple-ios15.0, while simulator targets are arm64-apple-ios15.0-simulator or x86_64-apple-ios15.0-simulator.

The old “extract an SDK and build cctools” recipe does not supply this entire chain. Do not download an arbitrary SDK or assume a macOS swiftc binary executes on Linux. Use SDKs and tools under their suppliers' terms; this guide makes no claim about redistribution rights.

Invocation parameters

After preparing and checking your toolchain, pass the paths explicitly. This is a command outline, not an installer: replace every /absolute/... path and the prefix with actual values. If tools are named simply clang, ar, etc., pass an empty apple_target_triple.

Shell
export OSXCROSS_IOS=1
scons platform=ios target=template_release arch=arm64 simulator=no APPLE_TOOLCHAIN_PATH="/absolute/toolchain" APPLE_SDK_PATH="/absolute/iPhoneOS.sdk" SWIFT_COMPILER="/absolute/swiftc" apple_target_triple="your-tool-prefix-" -j4

First obtain a bin/libreckfell…a library without packaging. For debug, change the target to template_debug. For a simulator, change simulator=yes, use an iPhoneSimulator SDK and change the architecture if needed; changing only arch is insufficient. The configurator rejects x86_64 without the simulator option. The current build disables Metal and Vulkan for the simulator.

Verification boundaries

Failure	Cause or next step
Missing `xcode-select`/`xcrun`	Explicit toolchain/SDK paths were not supplied. These helpers expect macOS.
`Swift compiler path is not set`	Missing `SWIFT_COMPILER`. `OSXCROSS_IOS` alone is insufficient.
Swift cannot execute or find an Apple module	Check the executable host format, supported target, SDK and Swift dependencies. `clang --version` does not establish these.
A `.a` exists but packaging fails	`generate_bundle=yes` is separate; the packager uses `lipo`, the Xcode template and framework dependencies. An archiver alone does not supply them.
Libraries exist but the game does not run	Continue in the Xcode/export toolchain and separately check slices, signing, device launch and rendering.

C# is disabled by default; adding module_mono_enabled=yes does not replace managed/AOT publication. This page reviews source configuration logic but provides no verified end-to-end Linux→iOS recipe: no compiler, Swift, packaging, export or device launch was run. Do not treat OSXCROSS_IOS as a promise of a supported ready-made build environment.