Autolinking
Autolinking simply means executing in the RN frontend project:
npm install <library-with-native-dependencies> --save
After which native code or modules are automatically discovered, dependencies installed and compiled. For more about Autolinking, refer to:
In RNOH projects, to implement Autolinking functionality, it requires cooperation between RNOH framework, RN third-party libraries and RNOH project. The following sections describe the responsibilities and adaptation work for 3 roles. Choose the section based on your role.
You can also run AutolinkingSample to experience the entire process.
RNOH Framework (Framework Maintainers)
For this functionality, RNOH framework provides developers with a @rnoh/hvigor-plugin hvigor plugin (located in RNOH frontend project node_modules/@react-native-oh/react-native-harmony-cli/harmony directory). This plugin calls the link-harmony command in @react-native-oh/react-native-harmony-cli to complete HAR package installation, SO linking, Package registration and other manual linking operations.
link-harmony Command Parameters
The link-harmony command can be executed separately. Here are the parameters:
-
--harmony-project-path <path>: Specifies the relative path of
harmonyproject, default is./harmony; -
--node-modules-path <path>: Specifies the relative path of
node_modules, default is./node_modules; -
--cmake-autolink-path-relative-to-harmony <path>: Specifies the location where
autolinking.cmakeis generated, generated inharmonyproject, default is./entry/src/main/cpp/autolinking.cmake; -
--cpp-rnoh-packages-factory-path-relative-to-harmony <path>: Specifies the location where
RNOHPackagesFactory.his generated, generated inharmonyproject, default is./entry/src/main/cpp/RNOHPackagesFactory.h; -
--ets-rnoh-packages-factory-path-relative-to-harmony <path>: Specifies the location where
RNOHPackagesFactory.etsis generated, generated inharmonyproject, default is./entry/src/main/ets/RNOHPackagesFactory.ets; -
--oh-package-path-relative-to-harmony <path>: Specifies the location of
oh-package.json5, thelink-harmonycommand modifies this file to install third-party HAR packages, default is./oh-package.json5; -
--exclude-npm-packages [string...]: Specifies the list of third-party libraries to skip
Autolinking. By defaultlink-harmonyattempts to link all third-party libraries, but in some cases compilation errors may occur due to incorrect library configuration. Use this parameter to exclude such packages. Cannot be used with--included-npm-packages; -
--include-npm-packages [string...]: Specifies the list of third-party libraries to execute
Autolinking. By defaultlink-harmonyattempts to link all third-party libraries. Cannot be used with--excluded-npm-packages.
RN Third-party Libraries (Library Developers)
For RN third-party library developers, if you want the link-harmony command to automatically link your library, some adaptation work is needed. Here are the main changes, also refer to third-party-library-sample in AutolinkingSample.
package.json Changes
Library developers need to configure harmony.autolinking in package.json. harmony.autolinking usually requires an object with the following properties:
-
etsPackageClassName: ETS package class name. If not specified, it defaults to generating based on the
namefield inpackage.json. The rule is: [org name]+[package name]+Package, e.g.,third-party-library-sampleconverts toThirdPartyLibrarySamplePackage; -
cppPackageClassName: C++ package class name. If not specified, follows the same generation rule as
etsPackageClassName; -
cmakeLibraryTargetName: Dynamic library name. If not specified, defaults to generating based on
namefield. The rule is: rnoh__+[org name]+[package name], e.g.,third-party-library-sampleconverts tornoh__third_party_library_sample; -
ohPackageName: OHOS module name. Recommended to use the
namefield from HAR package'soh-package.json5. In some scenarios DevEco strictly validates this name. If not specified, defaults to generating based onnamefield. The rule is: @rnoh/+[org name]+--+[package name], e.g.,third-party-library-sampleconverts to@rnoh/third-party-library-sample;{ "harmony": { "autolinking": { "ohPackageName": "@rnoh/third-party-library-sample" } } }Multi-HAR package configuration (array format): When a library contains multiple HAR files, use array format to specify different ohPackage names for each HAR:
{ "harmony": { "autolinking": { "ohPackageName": [ { "harName": "main.har", "packageName": "@scope/my-library" }, { "harName": "sdk.har", "packageName": "@scope/my-library-sdk" } ] } } }harName: HAR file name (only filename, no path)packageName: Corresponding ohPackage name- Configuration order: The first HAR in the array is considered the main HAR, used for generating CMake
add_subdirectoryand import statements - Unmatched HARs use default naming:
@rnoh/{npm-pkg-name}--{har-name}
Remote dependency support: Array format supports configuring remote dependencies via
versionfield, fetching HAR packages from OHPM repository:{ "harmony": { "autolinking": { "ohPackageName": [ { "harName": "local.har", "packageName": "@scope/local-lib" }, { "harName": "remote.har", "packageName": "@ohos/remote-lib", "version": "1.0.0" } ] } } }version: Optional field, specifies version number- With
version: Generates version dependency (e.g.,"@ohos/remote-lib": "1.0.0"),ohpm installdownloads from remote repository - Without
version: Generatesfile:path dependency (e.g.,"@scope/local-lib": "file:../node_modules/..."), fetches from local node_modules
- With
-
mainHarPath: Custom HAR scanning path, default is
harmony. If HAR files are not in the defaultharmonydirectory, specify via this field:{ "harmony": { "autolinking": { "mainHarPath": "custom/path/to/hars" } } }- Supports recursive scanning of all
.harfiles in the specified directory and its subdirectories
- Supports recursive scanning of all
If all names in your code follow the default rules and you have only a single HAR file, you can set harmony.autolinking to true.
HAR Package Requirements
-
OHOS module needs a default export
Like
third-party-library-sample/harmony/libraryin AutolinkingSample, you need a default export inindex.etsfile:export { ThirdPartyLibrarySamplePackage as default } from './src/main/ets/ThirdPartyLibrarySamplePackage'; -
HAR package location requirements
- By default, HAR packages should be placed in
[third-party-library]/harmonydirectory - If
mainHarPathis configured, place them in the specified directory - Autolinking recursively scans all
.harfiles in the directory and its subdirectories
- By default, HAR packages should be placed in
Registering Custom TurboModule and ArkTS Components
In previous versions, custom ArkTS components required developers to pass them through wrappedCustomRNComponentBuilder parameter when creating RNInstance, which doesn't align with Autolinking design. Therefore, RNOH framework added the RNOHPackage class. Library developers can design their own ETS Package class by inheriting from RNOHPackage:
-
Override
getUITurboModuleFactoryByNameMapmethod to register custom TurboModules in the module; -
Override
getAnyThreadTurboModuleFactoryByNameMapmethod to register custom Worker TurboModules in the module; -
Override
createWrappedCustomRNComponentBuilderByComponentNameMapmethod to register custom ArkTS components in the module.
RNOH Project (Developers Using RNOH Framework and RN Third-party Libraries)
Besides adapting RN third-party libraries, RNOH projects also need changes. Developers can refer to AutolinkingSample/NativeProject to read the following guidance.
- Install
@rnoh/hvigor-pluginplugin (plugin location see above):