About Wrappers

September 20, 2023 ยท View on GitHub

Wrappers contains all our native code and its interfaces to C#.

It has a reference to the Realm Core repository as a git submodule.

Wrappers also contains a small amount of C++ code which provides the mapping from C# to the Core logic.

Downloading Realm Core

Cloning

If you cloned your realm-dotnet repository, you can use a git command to get the submodule:

  1. Open a terminal window in the realm-dotnet source directory
  2. Enter the command git submodule update --init --recursive

Direct Download

If you downloaded a zip of the source, you need to go back to github to identify which version of Core is required. There is no git information in the zip file which specifies this.

  1. Look in the github repo wrappers and you will see the link to the submodule, eg: realm-core @ 802aa43.
  2. Click the link to take you to the tree in Core
  3. Download a zip using the GitHub download button in that tree, eg realm-core-fb2ed6aa0073be4cb0cd059cae407744ee883b77.zip
  4. Unpack its contents into wrappers/src/realm-core

Building iOS, tvOS, and macCatalyst wrappers on macOS

Building for iOS required cmake and zlib installed. In case you do not have them installed, you can do it with brew install cmake zlib.

You can use build-apple-platform.ps1 to build for iOS, tvOS, and macCatalyst, specifying one or more of the available platforms, Device, Simulator or Catalayst, and either Debug or Release configuration.

Building Android wrappers

Building for Android uses CMake with a toolchain file. You can either configure CMake with an Android toolchain file manually, or build with build-android.sh. By default it will build for armeabi-v7a, arm64-v8a, x86, and x86_64. You can specify a single ABI to build by passing --arch=$ABI. You can also choose a build configuration by passing --configuration=$CONFIG. The script also accepts CMake arguments like -GNinja.

You need to have the Android NDK installed, version r10e, and set an environment variable called ANDROID_NDK_HOME pointing to its location.

Building in Docker

If you don't have NDK setup or don't want to set up paths, you can build the wrappers in docker. You can use the CircleCI android docker image and build in it:

docker pull cimg/android:2023.05.1-ndk
docker run --rm -it -v ${pwd}:/source cimg/android:2023.05.1-ndk /bin/bash
/source/build-android.sh -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake

Building Windows wrappers

You need Visual Studio 2017 (or later) with the C++ Universal Windows Platform tools and Visual C++ tools for CMake components as well as a version of the Windows SDK installed.

Valid Windows platforms (architectures) are Win32, x64, ARM and ARM64. You can specify all or a subset to save time when building.

  • To build for regular Windows run .\build.ps1 Windows -Configuration Debug/Release -Platforms Win32, x64

  • To build for Windows Universal run .\build.ps1 WindowsStore -Configuration Debug/Release -Platforms Win32, x64, ARM

You can find the CMake-generated Visual Studio project files in cmake\$Target\$Configuration-$Platform and use them for debugging.

Building macOS wrappers

You need Xcode 13 (or later) installed.

  • To build a universal (x64 and Arm64) binary, run ./build-macos.sh -c=Debug/Release.

Building Linux wrappers

build-linux.sh automates configuring and building wrappers with CMake. It accepts CMake arguments like -GNinja.

  1. For Linux x64 builds you can just build and run centos.Dockerfile if you don't have access to a Linux environment:
    • docker build . -f centos.Dockerfile -t realm-dotnet/wrappers
    • docker run --rm -v $(pwd):/source realm-dotnet/wrappers
  2. For Linux Arm/Arm64 builds you can build and run debian-multiarch-arm.Dockerfile:
    • docker build . -f debian-multiarch-arm.Dockerfile -t realm-dotnet/wrappers-arm
    • docker run --rm -v $(pwd):/source realm-dotnet/wrappers-arm -a=arm64/arm

General Notes

All builds steps download the required realm components (core and sync) automatically.

Note if you have changed the wrappers source and added, deleted or renamed files, you need to update src/CMakeLists.txt for builds to work.