Skip to content

Latest commit

 

History

History
408 lines (287 loc) · 15.2 KB

building.md

File metadata and controls

408 lines (287 loc) · 15.2 KB
Raw

Building Realm JS

Pre-Requisites

The following dependencies are required. All except Xcode can be installed by following the setup instructions for MacOS section.

Moreover, in order to avoid introducing false positives in our analytics dataset, it is highly recommended to disable analytics by adding the following to your shell configuration:

export REALM_DISABLE_ANALYTICS=1

Setup instructions for MacOS

All platforms

# Install brew
bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

# Install nvm
brew install nvm

# Install the latest LTS version of Node.js and set it as the default
nvm install --lts

# Install the project's JavaScript dependencies
npm install

iOS

# Install cocoapods and cmake
brew install cocoapods cmake

Android

First, install OpenJDK:

brew install --cask temurin

# Check this returns: openjdk version "18.0.1" 2022-04-19
# If not, check if you have a JAVA_HOME environment variable set pointing elsewhere.
java -version

Next you need to define some environment variables. The best way to do this is in your shell’s configuration file, e.g. ~/.zshrc, then open a new terminal window or source ~/.zshrc to reload the config. Add the following:

# Location of your Android SDK
export ANDROID_SDK_ROOT=$HOME/Library/Android/sdk

# Location of your Android NDK
export ANDROID_NDK_HOME=$ANDROID_SDK_ROOT/ndk/21.0.6113669
export ANDROID_NDK=$ANDROID_NDK_HOME

# Other required locations
export ANDROID_SDK_HOME=$HOME/.android
export ANDROID_EMULATOR_HOME=$HOME/.android
export ANDROID_AVD_HOME=$HOME/.android/avd

# Add the Android SDK tools to your PATH
export PATH=$PATH:$ANDROID_SDK_ROOT/tools/bin
export PATH=$PATH:$ANDROID_SDK_ROOT/platform-tools
export PATH=$PATH:$ANDROID_SDK_ROOT/cmdline-tools/latest/bin

Then you can install the SDK, NDK and CMake by running: (you can alternatively do this via Tools > SDK Manager in Android Studio)

sdkmanager --install "platforms;android-31"
sdkmanager --install "ndk;21.0.6113669"
sdkmanager --install "cmake;3.18.1"

Optional extras

ccache

To improve compilation speed. you can use ccache:

# Install ccache
brew install ccache

# check path of ccache
which ccache

# Export the ccache variants of compilation tools
export PATH=<ccache location>/libexec:$PATH

Cloning the repository

To clone the RealmJS repository and install git submodules:

git clone https://github.com/realm/realm-js.git
cd realm-js
git submodule update --init --recursive

In order to improve the accuracy of git blame locally by ignoring commits in which the code was reformatted by an automated tool, run: git config blame.ignoreRevsFile .gitignore-revs from inside the repository.

Cloning the repository on Windows

On Windows the RealmJS repo should be cloned with symlinks enabled:

# run in elevated command prompt
git clone -c core.symlinks=true https://github.com/realm/realm-js

or manually create the symlinks using directory junctions if you already have the repo cloned:

# run in elevated command prompt
cd realm-js\react-native\android\src\main\jni
# remove src and vendor files
del src
del vendor
mklink /j "src" "../../../../../src/"
mklink /j "vendor" "../../../../../vendor"
cd realm-js\tests\ReactTestApp\android\app\src\main
# remove assets file
del assets
mklink /j assets "../../../../../data"

Note: If you have cloned the repo previously make sure you remove your node_modules directory since it may contain stale dependencies which may cause the build to fail.

Visual Studio Code setup

Visual Studio Code is the recommended editor for the best experience working with the Realm JS codebase.

TypeScript

You should check that VS Code is using the workspace version of TypeScript rather than the VS Code version. This should be automatically configured but does not always seem to take effect. You can do this by:

  1. Open the realm-js root directory in VS Code and open any TypeScript file
  2. Press Shift+Cmd+P to open the command palette
  3. Start typing select typescript version to select the TypeScript: Select TypeScript Version command
  4. Ensure Use Workspace Version is selected.

C++

If you are using Visual Studio Code as your editor, you can get greatly improved C++ Intellisense by installing the clangd extension, which should be recommended by VS Code when you open the repository. This should prompt you to disable the built in C++ extensions Intellisense, but if not you should do this in Settings, searching for cpp intellisense.

This extension picks up the build/compile_commands.json file generated by CMake (symlinked in the root directory), enabling full Intellisense.

Other editors should also be able to be configured to use the compile_commands.json file.

Building Realm JS

Building for iOS

  • Run ./scripts/build-ios.sh from the realm-js root directory

Building for Android

  • Run node scripts/build-android.js from the realm-js root directory
    • The compiled version of the Android module is output to <project-root>/android

Building for Node.js

You can build for Node.js by running the command:

npm run build

If you want to build for Apple Silicon on an Intel based Mac, you can use the following command instead:

 npm run build-m1

Additional steps for Windows

On Windows you will need to setup the environment for node-gyp:

  • Option 1: Install windows-build-tools Node.js package

    # run in elevated command prompt (as Administrator)
npm install -g --production windows-build-tools

  • Option 2: Manually install and configure as described in the node-gyp manual.

    Note you may need to configure the build tools path using npm

    npm config set msbuild_path "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Current\Bin\MSBuild.exe"

You also need to install openssl libraries with vcpkg:

git clone https://github.com/Microsoft/vcpkg
cd vcpkg
bootstrap-vcpkg.bat
vcpkg install openssl:x64-windows-static
mkdir C:\src\vcpkg\installed\x64-windows-static\lib
copy .\packages\openssl-windows_x64-windows-static\lib\libeay32.lib C:\src\vcpkg\installed\x64-windows-static\lib\
copy .\packages\openssl-windows_x64-windows-static\lib\ssleay32.lib C:\src\vcpkg\installed\x64-windows-static\lib

Building for ARM/Linux

You can build Realm JS for ARM/Linux from source and include it in your own project.

The following instructions assume you are using Debian GNU/Linux or a derived distribution.

First you need to have your build environment set up:

apt install build-essential cmake git libssl-dev curl
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
source $HOME/.bashrc
nvm install 16 # you can use any supported node version

You can now build Realm JS from source:

export REALM_USE_SYSTEM_OPENSSL=1
git clone https://github.com/realm/realm-js
cd realm-js
git submodule update —-init —-recursive
npm install --ignore-scripts
npx cmake-js build

Finally, you can use Realm JS in your project MyProject:

cd MyProject
npm init -y  # skip this if you've already initialised your project
npm install path/to/realm-js

Building the documentation

API documentation is written using JSDoc. To generate the documentation, run:

npm run jsdoc

The generated docs can be found in docs/output/realm/<version>/index.html.

Installing the project's sub-packages

We've decided to slowly migrate this repository to a mono-repository containing multiple packages (stored in the ./packages directory). To install and link these, run (from the realm-js repo root directory):

npx lerna bootstrap

Note: you must successfuly build Realm JS for iOS and Android before running lerna, or the command may fail.

Please familiarise yourself with Lerna to learn how to add dependencies to these packages.

Running the tests

There are two sets of tests for Realm JS, one legacy and one modern. The intention is to move all tests over to the modern set, but for now you will need to execute both sets of tests.

Modern tests

See the instructions in the integration-tests directory.

Legacy tests

To run the the tests, run the scripts/test.sh script, passing an argument for which tests you would like to execute. The following options are available:

  • react-tests - runs all React Native tests on iOS Simulator
  • react-tests-android - runs all React Native Android tests on Android emulator
  • node - runs all tests for Node.js
  • test-runners - checks supported tests runners are working correctly

For example:

scripts/test.sh node

Linting the source code

JS

Run npm run lint to lint the JS source code using eslint.

C++

Run npm run lint:cpp to lint the C++ source code using clang-format. We use a .clang-format based on the one from realm-core, but should feel free to modify if required.

Testing on Windows

On Windows some of these targets are available as npm commands.

npm run eslint
npm run node-tests
npm run test-runners

Node version setup

The tests will spawn a new shell when running, so you need to make sure that new shell instances use the correct version of npm. If you have Homebrew correctly installed, this should work – if it is not working, you can add the following to your preferred shell configuration:

export NVM_DIR="$HOME/.nvm"
. "$(brew --prefix nvm)/nvm.sh"

Testing against real apps

There are a couple of suggested workflows for testing your changes to Realm JS against real apps:

Debugging

See Debugging C++ and Debugging React Native.

Debugging failing Github Actions CI tests

To debug failing Github Actions CI tests, it can be helpful to ssh into the runner and test out the CI commands manually. This Github Action can be used to add a step into the workflow which pauses it and outputs details to ssh into it: https://github.com/marketplace/actions/debugging-with-tmate

The relevant snippet is:

- name: Setup tmate session
  uses: mxschmitt/action-tmate@v3
  with:
      limit-access-to-actor: true
  timeout-minutes: 30

Updating the Android JNI headers

If you add a new JNI method to RealmReactModule.java, you will need to regenerate the auto-generated header file.

  1. First you need to find some classpaths required to generate the header. In a terminal, cd ~/.gradle/caches and then run:

    1. find "$(pwd -P)" -name "jetified-react-native-0.69.1-debug" -exec find {} -name "classes.jar" \;
    2. find "$(pwd -P)" -name "jetified-soloader-0.10.3" -exec find {} -name "classes.jar" \;
    3. find "$(pwd -P)" -name "nanohttpd-2.2.0.jar"

  2. Build up a classpath string (e.g. in the terminal or in a text editor):

    1. Start with ~/Library/Android/sdk/platforms/android-31/android.jar
    2. Add the first result for each of the above find commands to this string, separated by a :.

    You should end up with something like: ~/Library/Android/sdk/platforms/android-31/android.jar:~/.gradle/caches/transforms-3/7d342974325594036ab59618107595df/transformed/jetified-react-native-0.69.1-debug/jars/classes.jar:~/.gradle/caches/transforms-3/6c67d7687cdaa9b6d194c80ea9a580e2/transformed/jetified-soloader-0.10.3/jars/classes.jar:~/.gradle/caches/modules-2/files-2.1/org.nanohttpd/nanohttpd/2.2.0/73a02117620b6cc7683a1ed6ae24c2f36e2a715/nanohttpd-2.2.0.jar

  3. Change to the react-native/android/src/main/java directory in your Realm JS checkout

  4. Run javac -h ../../../../../src/android/ -classpath <CLASSPATH_STRING> io/realm/react/RealmReactModule.java, replacing <CLASSPATH_STRING> with the string you built up in step 2

  5. Delete the .class files that the javac command created