|
1 | | -> [!NOTE] |
2 | | -> The instructions below detail how to get started developing NativeScript's V8-based iOS runtime, `@nativescript/ios`. |
3 | | -> |
4 | | -> Package docs: |
5 | | -> |
6 | | -> - `@nativescript/ios`: [packages/ios/README.md](packages/ios/README.md) |
7 | | -> - `@nativescript/macos`: [packages/macos/README.md](packages/macos/README.md) |
8 | | -> - `@nativescript/visionos`: [packages/visionos/README.md](packages/visionos/README.md) |
9 | | -> - `@nativescript/ios-node-api`: [packages/ios-node-api/README.md](packages/ios-node-api/README.md) |
10 | | -> - `@nativescript/macos-node-api`: [packages/macos-node-api/README.md](packages/macos-node-api/README.md) |
| 1 | +# NativeScript Runtime |
11 | 2 |
|
12 | | -# Getting Started |
| 3 | +The core backbone that powers [NativeScript](https://nativescript.org/) apps and provides powerful, zero-boilerplate interop with native APIs directly from JavaScript. |
13 | 4 |
|
14 | | -**Prerequisites**: |
15 | | -- Download v8 static libraries from here: |
16 | | - - Create a `Frameworks` folder at the root. Unzip and move the `v8_ios` folder inside so they are at `Frameworks/v8_ios`. |
| 5 | +## Key Features |
17 | 6 |
|
18 | | -To start diving into the v8 iOS runtime make sure you have Xcode and [Homebrew](https://brew.sh/) installed, and then run the following |
19 | | -```bash |
20 | | -# Install CMake |
21 | | -brew install cmake |
| 7 | +- **Direct Native Interop**: Access 100% of the underlying platform APIs (Objective-C/C/C++) directly from JS/TS without writing native plugin wrappers |
| 8 | +- **Multiple JS Engines**: Engine-agnostic architecture natively supporting **V8, Hermes, QuickJS, and JavaScriptCore** |
| 9 | +- **Node-API Support**: Runs on Node.js & Deno as well |
| 10 | +- **React Native Ecosystem**: Includes JSI-based TurboModule support and seamless React Native compatibility layers |
22 | 11 |
|
23 | | -# Install jq (for scripting json replacements) |
24 | | -brew install jq |
| 12 | +## Repository Structure |
25 | 13 |
|
26 | | -# (Optional) Install clang-format to format the code |
27 | | -brew install clang-format |
| 14 | +- `NativeScript/`: The core C++ runtime source code handling FFI (Foreign Function Interface) operations and JS engine bindings. |
| 15 | +- `metadata-generator/`: Clang-based utility that parses C/Obj-C to generate the metadata consumed by the FFI |
| 16 | +- `packages/`: The NPM packages published from this repo (e.g., `@nativescript/ios`, `@nativescript/macos`, `@nativescript/visionos`, and specific engine combinations). |
| 17 | +- `examples/`: Sample JS/TS test beds demonstrating platform APIs (AppKit, Metal, SpriteKit, etc.) driven purely over the runtime FFI. |
| 18 | +- `scripts/`: Shell and Node utilities for building frameworks, packaging runtimes, and driving CI/CD. |
| 19 | +- `TKLiveSync/`: Provides fast LiveSync capability and Hot Module Replacement (HMR) implementation. |
28 | 20 |
|
29 | | -# To avoid errors, you might need to link cmake to: /usr/local/bin/cmake |
30 | | -# xcode doesn't read your profile during the build step, which causes it to ignore the PATH |
31 | | -sudo ln -s /usr/local/bin/cmake $(which cmake) |
| 21 | +## Development & Building |
32 | 22 |
|
33 | | -# Clone repo |
34 | | -git clone https://github.com/NativeScript/ios.git |
| 23 | +1. **Prerequisites**: Ensure you have modern versions of **Xcode**, **CMake**, and **Node.js** installed. |
| 24 | +2. **Install Dependencies**: |
| 25 | + ```bash |
| 26 | + npm install |
| 27 | + ``` |
| 28 | +3. **Main Build Commands**: |
| 29 | + - `npm run build-ios`: Builds the iOS runtime frameworks. |
| 30 | + - `npm run build-macos`: Builds the macOS runtime platforms. |
| 31 | + - `npm run build-vision`: Builds the visionOS runtime platforms. |
| 32 | + - `npm run build-node-api`: Compiles the Node-API (N-API) addon. |
| 33 | + - `npm run build-rn-turbomodule`: Compiles the React Native TurboModules compatibility layer. |
| 34 | +4. **Core Dependencies**: |
| 35 | + - `npm run build-metagen`: Builds the Clang metadata generator binary. |
| 36 | + - `npm run metagen`: Runs the metadata generator against Xcode SDKs to produce type information. |
| 37 | + - `npm run build-libffi`: Compiles the multi-architecture LibFFI statically linked into the runtime. |
35 | 38 |
|
36 | | -# Initialize and clone the submodules |
37 | | -cd ios |
38 | | -git submodule update --init |
| 39 | +## Testing |
39 | 40 |
|
40 | | -# Ensure that you have the required llvm binaries for building the metadata generator |
41 | | -./scripts/download_llvm.sh |
| 41 | +Execute engine-specific and FFI boundary tests via the included test runners: |
| 42 | +- `node scripts/run-tests-ios.js` — iOS tests across supported runtimes |
| 43 | +- `node scripts/run-tests-macos.js` — macOS test runner |
| 44 | +- `npm run test-rn-turbomodule` — React Native TurboModules unit tests |
| 45 | +- `npm run check:ffi-boundaries` — Validates C/Objective-C boundaries via FFI |
42 | 46 |
|
43 | | -sudo gem install xcodeproj |
44 | | -sudo gem install cocoapods |
| 47 | +## Contribute |
45 | 48 |
|
46 | | -# Open the runtime in Xcode |
47 | | -open NativeScriptRuntime.xcodeproj |
48 | | -``` |
| 49 | +We welcome community contributions! For major architecture changes or engine integrations, please open an issue first to discuss what you'd like to alter. |
49 | 50 |
|
50 | | -Select the `TestRunner` target and an emulator and hit Run (the play button). |
| 51 | +## License |
51 | 52 |
|
52 | | -<img width="453" alt="Screenshot 2020-09-09 at 18 25 43" src="https://user-images.githubusercontent.com/879060/92626234-ee627680-f2c9-11ea-941b-6b43600f54e4.png"> |
53 | | - |
54 | | -This should take a while, but once built the emulator should start and show a black screen (this is normal). In this phase the app will run all the built-in tests, and report the results to the console: |
55 | | -``` |
56 | | -Runtime initialization took 55ms |
57 | | -2020-09-09 18:30:37.797265+0200 TestRunner[14285:1238340] CONSOLE LOG: Application Start! |
58 | | -2020-09-09 18:30:38.288740+0200 TestRunner[14285:1238340] No implementation found for exposed method "nonExistingSelector" |
59 | | -2020-09-09 18:30:49.720055+0200 TestRunner[14285:1238340] CONSOLE LOG: SUCCESS: 684 specs, 0 failures, 0 skipped, 0 disabled in 11.81s. |
60 | | -``` |
61 | | - |
62 | | -If all tests pass, everything is good! At this point you can make changes to the runtime, add breakpoints and step through with the debugger. In the next section we'll see how to attach the runtime to an existing NativeScript application allowing us to debug runtime issues in actual apps. |
63 | | - |
64 | | -# Attaching the runtime to a NativeScript app |
65 | | - |
66 | | -In the existing app, we need to prepare the Xcode project using `ns prepare ios`. This will create a folder named `platforms/ios` and in there a `<appname>.xcworkspace` (or .xcodeproject but note the following...). |
67 | | - |
68 | | -**IMPORTANT**: You can only attach the runtime to a `.xcworkspace` project (not a `.xcodeproj` project). If your app's platforms/ios folder does not contain a .xcworkspace file yet, you can do the following: |
69 | | - |
70 | | -Add a new file `App_Resources/iOS/Podfile` with the following contents: |
71 | | - |
72 | | -``` |
73 | | -pod 'IQKeyboardManager' |
74 | | -``` |
75 | | - |
76 | | -Now `ns clean` and prepare again with `ns prepare ios`. |
77 | | -This will make sure when the iOS project is generated that you end up with a .xcworkspace file so attaching the v8 runtime source works properly. |
78 | | - |
79 | | -You can now open the `platforms/ios/{project-name}.xcworkspace` file in Xcode and then drag the `NativeScriptRuntime.xcodeproj` from the root of this repo under the `<appname>` in the Xcode sidebar. |
80 | | - |
81 | | -<img width="941" alt="Screenshot 2020-09-09 at 18 46 18" src="https://user-images.githubusercontent.com/879060/92628228-c294c000-f2cc-11ea-8822-58df689d3cd3.png"> |
82 | | - |
83 | | -Remove the `NativeScript.xcframework` and `TKLiveSync.xcframework` from the General tab, as we will no longer be using the framework from node_modules and instead will use the source directly: |
84 | | - |
85 | | -<img width="693" alt="Screenshot 2020-09-09 at 18 47 23" src="https://user-images.githubusercontent.com/879060/92628311-e6f09c80-f2cc-11ea-8977-201517badc3b.png"> |
86 | | - |
87 | | -Hitting Run in Xcode should start the app in the simulator, and we can now add breakpoints to the runtime and step through it with the debugger. To apply changes to the javascript, make sure you run `ns prepare ios` to re-bundle it into the `platforms/ios` folder. |
88 | | - |
89 | | -## Only required when running on a physical device |
90 | | - |
91 | | -Add the `Nativescript.framework` and `TKLiveSync.framework` from the NativeScriptRuntime workspace: |
92 | | - |
93 | | -<img width="402" alt="Screen Shot 2021-04-12 at 11 49 10 AM" src="https://user-images.githubusercontent.com/2379994/114423589-51c8c580-9b85-11eb-9d30-eb1cbf73454a.png"> |
94 | | - |
95 | | -## Troubleshooting |
96 | | - |
97 | | -If you encounter vague errors like this when building your app with the runtime included (This has been observed sometimes while Profiling apps in Xcode): |
98 | | - |
99 | | -``` |
100 | | -/path/to/ios/NativeScript/inspector/src/base/atomicops.h:311:11: No matching function for call to 'Relaxed_Load' |
101 | | -``` |
102 | | - |
103 | | -This is most likely related to `Build Active Architecture Only` setting in Xcode for various targets (your app and the included NativeScript runtime). You should check to make sure your app `Build Settings` and the NativeScript runtime targets `NativeScript` and `TKLiveSync` Build Settings are set to YES for both Debug and Release. See this reference: |
104 | | -https://github.com/QuickBlox/quickblox-ios-sdk/issues/993#issuecomment-379656716 |
105 | | - |
106 | | - |
107 | | -# Overview |
108 | | - |
109 | | -POC showing the [{N} iOS runtime](https://github.com/NativeScript/ios-runtime) running with the V8 engine. |
110 | | - |
111 | | -Supported architectures: |
112 | | - |
113 | | - - x86_64 |
114 | | - - arm64 |
115 | | - |
116 | | -iOS deployment target: |
117 | | - - 9.0 |
118 | | - |
119 | | -The `--jitless` mode in which V8 is running is explained in the following [document](https://docs.google.com/document/d/1YYU17VqFMBeSJ8whCqXknOGXtXDVDLulchsTkmi0YdI/edit#heading=h.mz26kq2dsu6k) |
120 | | - |
121 | | -# V8 Artifacts |
122 | | - |
123 | | -Local V8 source build and patch scripts have been removed from this repo. |
124 | | - |
125 | | -To provision V8 artifacts, use: |
126 | | - |
127 | | -```bash |
128 | | -./scripts/download_v8.sh |
129 | | -``` |
130 | | - |
131 | | -This downloads and extracts prebuilt V8 binaries into `Frameworks/`. |
132 | | - |
133 | | -# Hermes Artifacts |
134 | | - |
135 | | -To provision Hermes artifacts, use: |
136 | | - |
137 | | -```bash |
138 | | -./scripts/download_hermes.sh |
139 | | -``` |
140 | | - |
141 | | -This downloads and extracts a prebuilt Hermes XCFramework into `Frameworks/`. |
142 | | - |
143 | | -# Building a Distribution Package |
144 | | - |
145 | | -1. Bump the version in `packages/ios/package.json` |
146 | | - |
147 | | -2. Run: `npm run update-version:ios` (*This will update the runtime headers with version info*) |
148 | | - |
149 | | -3. Build & pack: `npm run build-ios` |
150 | | - |
151 | | -This will create: `packages/ios/dist/nativescript-ios-{version}.tgz` NPM package ready for publishing. |
| 53 | +This project is licensed under the [MIT License](https://opensource.org/licenses/MIT). |
0 commit comments