Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions .github/workflows/react-native-linux.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
name: React Native Linux example
on:
pull_request:
paths:
- 'Examples/ReactNativeLinux/**'
- '.github/workflows/react-native-linux.yml'
push:
branches:
- main
paths:
- 'Examples/ReactNativeLinux/**'
- '.github/workflows/react-native-linux.yml'
jobs:
adapter-tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Check adapter without Apple SDK or signing credentials
working-directory: Examples/ReactNativeLinux
run: |
python3 -m unittest discover -s tests -v
bash -n scripts/*.sh tools/bin/*
ruby -c ios/Podfile
8 changes: 8 additions & 0 deletions Examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,11 @@ Each demo is designed to make some assertions shortly after launching, and then

- Omit `--build`/`--run` to build _and_ run
- Omit the demo name to loop through all demos

## Experimental React Native build on Linux

[ReactNativeLinux](ReactNativeLinux/README.md) is a separate experiment for
[issue #364](https://github.com/xtool-org/xtool/issues/364): a CocoaPods source
graph compiled with Linux Clang/LLD, then signed and installed with xtool.
It uses React Native 0.77.3, JavaScriptCore, and the legacy renderer. It is
not a SwiftPM fixture and is not included in `test.sh`.
9 changes: 9 additions & 0 deletions Examples/ReactNativeLinux/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
node_modules/
build/
ios/Pods/
ios/build/
native-build-manifest.json
.cache/
evidence/
__pycache__/
.bundle/
4 changes: 4 additions & 0 deletions Examples/ReactNativeLinux/Gemfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
source 'https://rubygems.org'
gem 'cocoapods', '1.17.0'
# Some Linux Ruby distributions package erb separately.
gem 'erb', '6.0.7'
134 changes: 134 additions & 0 deletions Examples/ReactNativeLinux/Gemfile.lock
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
GEM
remote: https://rubygems.org/
specs:
CFPropertyList (3.0.8)
activesupport (7.2.4)
base64
benchmark (>= 0.3)
bigdecimal
concurrent-ruby (~> 1.0, >= 1.3.1)
connection_pool (>= 2.2.5, < 3)
drb
i18n (>= 1.6, < 2)
logger (>= 1.4.2)
minitest (>= 5.1, < 6)
securerandom (>= 0.3)
tzinfo (~> 2.0, >= 2.0.5)
addressable (2.9.0)
public_suffix (>= 2.0.2, < 8.0)
algoliasearch (1.27.5)
httpclient (~> 2.8, >= 2.8.3)
json (>= 1.5.1)
atomos (0.1.3)
base64 (0.3.0)
benchmark (0.5.0)
bigdecimal (4.1.3)
claide (1.1.0)
cocoapods (1.17.0)
addressable (~> 2.8)
claide (>= 1.0.2, < 2.0)
cocoapods-core (= 1.17.0)
cocoapods-deintegrate (>= 1.0.3, < 2.0)
cocoapods-downloader (>= 2.1, < 3.0)
cocoapods-plugins (>= 1.0.0, < 2.0)
cocoapods-search (>= 1.0.0, < 2.0)
cocoapods-trunk (>= 1.6.0, < 2.0)
cocoapods-try (>= 1.1.0, < 2.0)
colored2 (~> 3.1)
fourflusher (>= 2.3.0, < 3.0)
gh_inspector (~> 1.0)
molinillo (~> 0.8.0)
nap (~> 1.0)
ruby-macho (~> 4.1.0)
xcodeproj (>= 1.28.1, < 2.0)
cocoapods-core (1.17.0)
activesupport (>= 5.0, < 8)
addressable (~> 2.8)
algoliasearch (~> 1.0)
concurrent-ruby (~> 1.1)
fuzzy_match (~> 2.0.4)
nap (~> 1.0)
netrc (~> 0.11)
public_suffix (~> 4.0)
typhoeus (~> 1.0)
cocoapods-deintegrate (1.0.5)
cocoapods-downloader (2.1)
cocoapods-plugins (1.0.0)
nap
cocoapods-search (1.0.1)
cocoapods-trunk (1.6.0)
nap (>= 0.8, < 2.0)
netrc (~> 0.11)
cocoapods-try (1.2.0)
colored2 (3.1.2)
concurrent-ruby (1.3.8)
connection_pool (2.5.5)
drb (2.2.3)
erb (6.0.7)
ethon (0.19.1)
ffi (>= 1.15.0)
logger
ffi (1.17.4)
ffi (1.17.4-aarch64-linux-gnu)
ffi (1.17.4-aarch64-linux-musl)
ffi (1.17.4-arm-linux-gnu)
ffi (1.17.4-arm-linux-musl)
ffi (1.17.4-arm64-darwin)
ffi (1.17.4-x86-linux-gnu)
ffi (1.17.4-x86-linux-musl)
ffi (1.17.4-x86_64-darwin)
ffi (1.17.4-x86_64-linux-gnu)
ffi (1.17.4-x86_64-linux-musl)
fourflusher (2.3.1)
fuzzy_match (2.0.4)
gh_inspector (1.1.3)
httpclient (2.9.0)
mutex_m
i18n (1.15.2)
concurrent-ruby (~> 1.0)
json (3.1.0)
logger (1.7.0)
minitest (5.27.0)
molinillo (0.8.0)
mutex_m (0.3.0)
nanaimo (0.4.0)
nap (1.1.0)
netrc (0.11.0)
nkf (0.3.0)
public_suffix (4.0.7)
rexml (3.4.4)
ruby-macho (4.1.0)
securerandom (0.4.1)
typhoeus (1.7.1)
ethon (>= 0.19.1, < 0.20.0)
tzinfo (2.0.6)
concurrent-ruby (~> 1.0)
xcodeproj (1.28.1)
CFPropertyList (>= 2.3.3, < 4.0)
atomos (~> 0.1.3)
base64
claide (>= 1.0.2, < 2.0)
colored2 (~> 3.1)
nanaimo (~> 0.4.0)
nkf
rexml (>= 3.3.6, < 4.0)

PLATFORMS
aarch64-linux-gnu
aarch64-linux-musl
arm-linux-gnu
arm-linux-musl
arm64-darwin
ruby
x86-linux-gnu
x86-linux-musl
x86_64-darwin
x86_64-linux-gnu
x86_64-linux-musl

DEPENDENCIES
cocoapods (= 1.17.0)
erb (= 6.0.7)

BUNDLED WITH
2.6.9
151 changes: 151 additions & 0 deletions Examples/ReactNativeLinux/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,151 @@
# Experimental React Native iOS build on Linux

This experiment for [#364](https://github.com/xtool-org/xtool/issues/364)
compiles a small React Native app on Linux and uses **xtool to sign and install
it on an iPhone**. Native compilation uses a separate CocoaPods-to-Clang adapter
in this directory; `xtool dev build` does not build this project.

The app renders a real React Native JavaScript screen with a `Pressable` and a
React `useState` counter. It uses React Native **0.77.3**, React **18.3.1**, the
**legacy bridge/Paper renderer**, and the iOS system **JavaScriptCore** engine.
A release JavaScript bundle is embedded in the application. No web view, Expo Go,
remote Mac, or precompiled React Native library is involved.

This is a feasibility example, not general React Native project support. It does
not implement Expo modules, Hermes, the New Architecture, Swift pods, arbitrary
CocoaPods build phases/resources, simulator builds, or Fast Refresh. Updating
React Native requires reviewing the adapter and its two dependency patches.

## Prerequisites

- Linux with Python 3.10+, Bash, Node.js/npm, Ruby 3.2+, Ruby development headers,
`make`, a host C compiler, Git, curl, and standard archive utilities. Native Ruby
gems may need your distribution's development packages. The tested host was
Omarchy x86_64 with Node 26.12.1, Ruby 3.4.10 and Python 3.14.
- Linux Clang/Clang++, `llvm-ar`, and **`ld64.lld`** (the Mach-O LLD driver).
Tested with LLVM **23.1.3**. This example does not install system packages.
- A genuine **iPhoneOS device SDK**, obtained from your own Apple Xcode download,
and the corresponding Xcode toolchain's **`libclang_rt.ios.a`**. Tested with
Xcode/iPhoneOS **27.1** and its Clang 21 availability archive. No Apple files
are distributed here. The minimum app deployment target is **iOS 15.1**.
- [xtool](../../Documentation/xtool.docc/Installation-Linux.md), tested with
**1.24.0**, and a signing identity configured using its interactive login.
Pair/trust the USB-connected iPhone and enable Developer Mode as required by
xtool. Signing credentials stay in xtool's storage, outside this example.

Download Xcode from [Apple Developer Downloads](https://developer.apple.com/download/all/?q=Xcode).
Supply SDK/toolchain paths from an extraction that **preserves Xcode archive
hardlinks**. A naive selective CPIO extraction can leave `NULLcanary` placeholder
headers when the shared file's first entry belongs to another platform. The
preflight checks one representative header; it cannot certify the whole SDK.
SDK acquisition/extraction is an external prerequisite of this example.

## Setup and build

From this directory, set the two Apple input paths (substitute your own location):

```bash
export XCODE_ROOT=/path/to/extracted/Xcode.app
export IOS_SDK="$XCODE_ROOT/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk"
# Use the version directory present in your matching Xcode toolchain:
export IOS_AVAILABILITY_LIBRARY="$XCODE_ROOT/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/lib/clang/21/lib/darwin/libclang_rt.ios.a"

bash scripts/setup.sh
bash scripts/build.sh
```

The native Linux tools default to those on `PATH`. Override any with an executable
path using `CLANG`, `CLANGXX`, `LD64_LLD`, or `LLVM_AR`. If your tools are extracted
outside the system installation, configure their shared-library search path
(e.g. `LD_LIBRARY_PATH`) as required by your distribution. Keep the same exported
configuration when rebuilding.

`setup.sh` runs `npm ci --ignore-scripts` from the npm lockfile and installs
Bundler 2.6.9 and the locked Ruby gems into the ignored `.cache/` directory.
CocoaPods is pinned to **1.17.0**, with erb **6.0.7** for distributions that package
it separately. `build.sh` uses `pod install --deployment` with the checked-in
Podfile lock. Re-running setup intentionally restores npm dependency sources;
`build.sh` applies the patches again after dependency resolution.

The unsigned output is `build/OmarchyReactNative.app`. Inspect generated
`build/compile_commands.json`, `build/link-command.json`, and `build/link.map`
for the actual native build commands. Logs go to the ignored `evidence/`
directory. Objects are cached using command/compiler identity and dependency
modification times; remove `build/` for a clean native build after replacing a
compiler or SDK in place.

## Install and exercise

With the phone connected, unlocked and trusted, and xtool authentication set up:

```bash
xtool install --usb build/OmarchyReactNative.app
```

For an AppImage installation, use the equivalent invocation for your environment
(e.g. `APPIMAGE_EXTRACT_AND_RUN=1 /path/to/xtool.AppImage install --usb ...`). xtool
provisions/signs a staged copy of the app and installs it. This may register the
sample bundle identifier in your selected development team. The local input app
remains unsigned.

Open **React Native Linux** from the iPhone Home Screen. Confirm that **Hello from
Omarchy.** appears and tapping **Add one** changes the counter from 0 to 1 to 2.
The sample emits `[OmarchyRN]` native and JavaScript logs, including each counter
value. See [VALIDATION.md](VALIDATION.md) for recorded results and limitations.

## Adapter design and compatibility patches

`ios/Podfile` uses React Native's standard CocoaPods dependency definitions with
Hermes and the New Architecture disabled. It skips the host Xcode/Rosetta probes,
then exports resolved source paths, per-file compiler flags, Release settings,
frameworks, weak frameworks, and libraries into `native-build-manifest.json`.
It does not run an Xcode build. CocoaPods still resolves some Fabric-related
source targets; this does not make the app a New Architecture app.

`scripts/build-native.py` compiles that fixed source graph with Linux Clang for
arm64 iOS, creates Darwin archives with `llvm-ar`, and links using `ld64.lld`.
The linker SDK version comes from `SDKSettings.plist`. The adapter represents
Xcode header maps with CocoaPods header directories, explicitly includes the
existing `RCTTurboModule.h` definition for textual compilation of
`RCTCxxBridge.mm`, and links CoreText plus Apple's availability helpers.
Unresolved native symbols are errors; no dummy implementations are supplied.

The project-scoped `tools/bin/xcrun` supports only glog's compiler and SDK lookup
queries. Its `ios-clang` wrapper invokes the configured real Clang and LLD. Other
queries fail explicitly; these wrappers are not installed system-wide.

Two version-checked, idempotent source adjustments are applied to downloaded
sources only, with replacement files to preserve CocoaPods cache hardlinks:

- [React Native WebSocket signature](patches/react-native-0.77.3-websocket-signature.patch):
match the implementation's socket identifier type to its existing `NSNumber *`
public declaration/dictionary keys.
- [fmt 11.0.2 format checker](patches/fmt-11.0.2-constexpr-identity.patch):
make the constexpr parser and checker share the stored string view, avoiding
repeated wrapper conversions producing distinct string-literal pointers under
newer Clang. This follows the diagnosis in
[fmt #4177](https://github.com/fmtlib/fmt/issues/4177); compile-time checking stays
enabled. This is a local compatibility patch, not a claim of upstream acceptance.

The example's original source uses the repository's MIT license. Downloaded React
Native, fmt, CocoaPods and their dependencies retain their respective licenses;
installation leaves their license files in their dependency directories. The
patch files are small diffs against React Native (Meta, MIT) and fmt (Victor
Zverovich and contributors, MIT). Apple SDK/toolchain files remain external and
subject to Apple's terms.

## Regression checks

These checks require neither an Apple SDK nor signing credentials:

```bash
python3 -m unittest discover -s tests -v
bash -n scripts/*.sh tools/bin/*
ruby -c ios/Podfile
```

They cover SDK validation, paths with spaces, inherited/per-file build flags,
header-driven cache invalidation, failed-compilation cancellation, safe/idempotent
patching, and explicit rejection of unsupported xcrun queries. A separate CI job
runs them without Apple downloads. This example is intentionally excluded from
`Examples/test.sh`, whose fixtures are SwiftPM simulator apps.
Loading