Note

The instructions below detail how to get started developing NativeScript's V8-based iOS runtime, @nativescript/ios.

If you are interested in building the standalone Node-API libraries, instructions for those can be found as follows:

• @nativescript/ios-node-api: packages/ios/README.md
• @nativescript/macos-node-api: packages/macos/README.md

Getting Started

Prerequisites:

• Download v8 static libraries from here:
  • Create a Frameworks folder at the root. Unzip and move the v8_ios folder inside so they are at Frameworks/v8_ios.

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

# Install jq (for scripting json replacements)
brew install jq

# (Optional) Install clang-format to format the code
brew install clang-format

# To avoid errors, you might need to link cmake to: /usr/local/bin/cmake
# xcode doesn't read your profile during the build step, which causes it to ignore the PATH
sudo ln -s /usr/local/bin/cmake $(which cmake)

# Clone repo
git clone https://github.com/NativeScript/ios.git

# Initialize and clone the submodules
cd ios
git submodule update --init

# Ensure that you have the required llvm binaries for building the metadata generator
./download_llvm.sh

sudo gem install xcodeproj
sudo gem install cocoapods

# Open the runtime in Xcode
open NativeScriptRuntime.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.

Attaching the runtime to a NativeScript app

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...).

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:

Add a new file App_Resources/iOS/Podfile with the following contents:

pod 'IQKeyboardManager'

Now ns clean and prepare again with ns prepare ios. 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.

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.

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:

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.

Only required when running on a physical device

Add the Nativescript.framework and TKLiveSync.framework from the NativeScriptRuntime workspace:

Troubleshooting

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/ios/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 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: QuickBlox/quickblox-ios-sdk#993 (comment)

Overview

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

V8 Artifacts

Local V8 source build and patch scripts have been removed from this repo.

To provision V8 artifacts, use:

./download_v8.sh

This downloads and extracts prebuilt V8 binaries into Frameworks/.

Building a Distribution Package

1. Bump the version in package.json

2. Run: npm run update-version (This will update the runtime headers with version info)

3. Build & pack: npm run build

This will create: dist/npm/nativescript-ios-{version}.tgz NPM package ready for publishing.