To start diving into the v8 iOS runtime make sure you have XCode and Homebrew installed, and then run the following
# Install CMake
brew install cmake
# Clone repo
git clone https://github.com/NativeScript/ns-v8ios-runtime.git
# Initialize and clone the submodules
cd ns-v8ios-runtime
git submodule update --init
# Open the runtime in XCode
open v8ios.xcodeproj
Select the TestRunner
target and an emulator and hit Run (the play button).
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:
Runtime initialization took 55ms
2020-09-09 18:30:37.797265+0200 TestRunner[14285:1238340] CONSOLE LOG: Application Start!
2020-09-09 18:30:38.288740+0200 TestRunner[14285:1238340] No implementation found for exposed method "nonExistingSelector"
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.
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.
In the existing app, we need to prepare the XCode project using ns prepare ios
. This should create a folder named platforms/ios
and in there a <appname>.xcworkspace
(if there is no .xcworkspace
use the .xcodeproj
instead). Open it in XCode and then drag the v8ios.xcodeproj
from the ns-v8ios-runtime
folder under the <appname>
in the XCode sidebar.
Remove the NativeScript.xcframework
from the General tab, as we will no longer be using the framework from node_modules and instead will use the source directly:
Add the Nativescript.framework
from the v8ios workspace (only required when running on a physical device):
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.
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):
/path/to/ns-v8ios-runtime/NativeScript/inspector/src/base/atomicops.h:311:11: No matching function for call to 'Relaxed_Load'
This is most likely related to Build Active Architecture Only
setting in Xcode for various targets (your app and the included v8ios runtime). You should check to make sure your app Build Settings
and the v8ios targets NativeScript
and TKLiveSync
Build Settings are set to YES for both Debug and Release. See this reference:
QuickBlox/quickblox-ios-sdk#993 (comment)
POC showing the {N} iOS runtime running with the V8 engine.
Supported architectures:
- x86_64
- arm64
iOS deployment target:
- 9.0
The --jitless
mode in which V8 is running is explained in the following document
In order to build the V8 engine for iOS and produce the static libraries used in the NativeScript iOS runtime follow these steps:
Prerequisites:
git clone https://github.com/NativeScript/ns-v8ios-runtime.git
cd ns-v8ios-runtime
You will need Google depot_tools
- If you have not cloned the repo yet, clone the following and export a path setting so they can be referenced properly:
git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git
// copy/paste this command in current terminal window:
export PATH=`pwd`/depot_tools:"$PATH"
- Fetch the latest v8 source (or specific version):
If you have an existing v8 source fetched, delete the folder, and fetch it fresh each time updates are needed.
// IMPORTANT: Make sure you are inside the clone of this repo...
cd ns-v8ios-runtime
// Fetch v8 source:
fetch v8
This will create a v8
repo folder automatically checking out the master
branch.
Always check https://omahaproxy.appspot.com/ for the specific version you intend to build.
- Ensure you checkout the version you intend to build:
cd v8
// for example:
git checkout 9.2.230.18
gclient sync
This will checkout a specific tag and fetch additional dependencies for building the intended version.
- Apply patches from v8 updates to the iOS runtime:
npm run apply-patches
NOTE: Oftentimes the patches may not apply immediately and can run into issues like this:
error: patch failed: BUILD.gn:538
error: BUILD.gn: patch does not apply
error: patch failed: src/inspector/inspector_protocol_config.json:21
error: src/inspector/inspector_protocol_config.json: patch does not apply
~/Documents/ns-v8ios-runtime/v8/build ~/Documents/ns-v8ios-runtime/v8 ~/Documents/ns-v8ios-runtime
error: patch failed: config/ios/ios_sdk.gni:32
error: config/ios/ios_sdk.gni: patch does not apply
You can look at each patch failure, for example BUILD.gn: patch does not apply
, you can apply the patch manually instead. This can be done by opening the ./v8.patch
file and applying each patch manually to the corresponding file.
- Build v8 source:
npm run build-v8-source
Troubleshooting build errors
- Example failure 1:
@Mac ns-v8ios-runtime % npm run build-v8-source
> @nativescript/[email protected] build-v8-source
> ./build_v8_source.sh
~/Documents/ns-v8ios-runtime/v8 ~/Documents/ns-v8ios-runtime
Building for out.gn/x64-release (simulator)
Done. Made 212 targets from 92 files in 4004ms
ninja: Entering directory `out.gn/x64-release'
ninja: error: unknown target 'v8_libsampler'
In this case, the v8_libsampler module no longer needs to be built specifically as a target, therefore the MODULES inside the build_v8_source.sh
can be modified to remove the target of v8_libsampler
and the build can be invoked again.
- Example failure 2:
ERROR at //build/config/ios/ios_sdk.gni:181:33: Script returned non-zero exit code.
ios_code_signing_identity = exec_script("find_signing_identity.py",
Automatic code signing identity selection was enabled but could not
find exactly one codesigning identity matching "Apple Development".
Check that the keychain is accessible and that there is exactly one
valid codesigning identity matching the pattern. Here is the parsed
output of `xcrun security find-identity -v -p codesigning`:
1) 1ABE0***********************************: "Apple Development: Your Name (U4********)"
2) CB529***********************************: "Apple Distribution: Your Org (29********)"
3) BACD5***********************************: "Apple Development: Your Name (VV********)"
4) 0D42D***********************************: "Apple Development: Your Team (D3********)"
5) 055BA***********************************: "Apple Development: Your Name (GF********)"
6) A5306***********************************: "Apple Development: Your Name (9V***********)"
6 valid identities found
If this occurs you can manually modify v8/build/config/ios/ios_sdk.gni
. A property named ios_code_signing_identity
. You can set that explicitly to one of your code signing identities. You can use the command it suggests to list out your identities in full: xcrun security find-identity -v -p codesigning
- Copy the id and paste it as the value of ios_code_signing_identity
.
You will want to make ios_code_signing_identity_description
an empty string so the final change should look something like this:
# Explicitly select the identity to use for codesigning. If defined, must
# be set to a non-empty string that will be passed to codesigning. Can be
# left unspecified if ios_code_signing_identity_description is used instead.
ios_code_signing_identity = "...your-id..."
# Pattern used to select the identity to use for codesigning. If defined,
# must be a substring of the description of exactly one of the identities by
# `security find-identity -v -p codesigning`.
ios_code_signing_identity_description = ""
- If building of the v8 source succeeds, Verify the build output.
The compiled fat static libraries will be placed inside the v8/dist
folder.
-
Bump the version in package.json
-
Run:
npm run update-version
(This will update the runtime headers with version info) -
Build & pack:
npm run build
This will create: dist/npm/nativescript-ios-{version}.tgz
NPM package ready for publishing.