Skip to content

Latest commit

 

History

History

cmake-rn

README.md

cmake-rn

A wrapper around Cmake making it easier to produce prebuilt binaries targeting iOS and Android matching the prebuilt binary specification.

Serves the same purpose as cmake-js does for the Node.js community and could potentially be upstreamed into cmake-js eventually.

Commands

cmake-rn (or cmake-rn build) configures and builds the CMake project in the current directory for the requested triplets. Run cmake-rn build --help for its options.

cmake-rn init [path]

Scaffold a package building a CMake Node-API module, or bring an existing package up to what cmake-rn build expects of it:

npx cmake-rn init packages/my-addon

The command creates whatever is missing — package.json, CMakeLists.txt, src/addon.c, the my-addon.js entrypoint loading the addon, its my-addon.d.ts declarations and .gitignore — and adds the package to the pnpm-workspace.yaml or "workspaces" of the mono-repo it is initialized into.

Running it against a package which already exists updates rather than overwrites:

  • package.json gains the scripts, dependencies and prebuilt artifacts it lacks, and outdated dependencies are bumped.
  • An existing CMakeLists.txt is left alone. The command points out when it doesn't get Node-API the way --weak-node-api asks for, or doesn't build the library the entrypoint loads.
  • A main, types, entrypoint or src/addon.c that differs is skipped, printing a diff to merge by hand. Pass --force to overwrite them, along with an existing CMakeLists.txt.

A new CMakeLists.txt gets Node-API in the way --weak-node-api <mode> asks for:

  • link (the default): links the weak-node-api target, defined by include(${WEAK_NODE_API_CONFIG}).
  • cmake-js: uses the CMAKE_JS_* variables instead, so the project builds with both cmake-js (for Node.js) and cmake-rn --cmake-js, which the build script passes.
  • omit: leaves Node-API out of the project for you to provide, which it won't build without.

The mode also decides what is pointed out about an existing CMakeLists.txt.

The name of the CMake target and the library it builds defaults to the package name without its npm scope (@my-org/my-addon becomes my-addon) and can be set with --name. The entrypoint loads the library from build/Release, where cmake-rn build emits a Release build by default.

Every file it updates is printed as a diff, and --dry-run prints the whole plan without writing anything:

npx cmake-rn init packages/my-addon --dry-run

The cmake-rn-example package is generated by this command: run pnpm run init-cmake-rn-example from the root of the repository after changing the templates, which CI asserts leaves no diff.

Linking against Node-API

Android's dynamic linker imposes restrictions on the access to global symbols (such as the Node-API free functions): A dynamic library must explicitly declare any dependency bringing symbols it needs as DT_NEEDED.

The implementation of Node-API is split between Hermes and our host package and to avoid addons having to explicitly link against either, we've introduced a weak-node-api library (published in react-native-node-api package). This library exposes only Node-API and will have its implementation injected by the host.

To link against weak-node-api just use find_package to import the weak-node-api target and add it to the target_link_libraries of the addon's library target.

cmake_minimum_required(VERSION 3.15...3.31)
project(tests-buffers)

# Defines the "weak-node-api" target
find_package(weak-node-api REQUIRED CONFIG)

add_library(addon SHARED addon.c)
target_link_libraries(addon PRIVATE weak-node-api)
target_compile_features(addon PRIVATE cxx_std_20)

if(APPLE)
  # Build frameworks when building for Apple (optional)
  set_target_properties(addon PROPERTIES
    FRAMEWORK TRUE
    MACOSX_FRAMEWORK_IDENTIFIER async_test.addon
    MACOSX_FRAMEWORK_SHORT_VERSION_STRING 1.0
    MACOSX_FRAMEWORK_BUNDLE_VERSION 1.0
    XCODE_ATTRIBUTE_SKIP_INSTALL NO
   )
else()
  set_target_properties(addon PROPERTIES
    PREFIX ""
    SUFFIX .node
   )
endif()

This is different from how cmake-js "injects" the Node-API for linking (via ${CMAKE_JS_INC}, ${CMAKE_JS_SRC} and ${CMAKE_JS_LIB}). To allow for interoperability between these tools, we inject these when you pass --cmake-js to cmake-rn.