From a4f29846abbdf065093d73ca0deee6824d003edd Mon Sep 17 00:00:00 2001 From: Jaime Bernardo Date: Tue, 20 Feb 2018 10:28:25 +0000 Subject: [PATCH] docs: Add native modules instructions --- README.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index dc37555..a3821af 100644 --- a/README.md +++ b/README.md @@ -236,8 +236,24 @@ $ npm install module-name Rebuild your Cordova project so that the newly added Node modules are added to the Cordova application. -Currently, only pure JavaScript modules are supported. Native modules, that require to be cross-compiled for the target platform, are not supported yet. - On Android, the project files and the Node modules need to be extracted from the APK assets in order to make them available to the Node.js for Mobile Apps engine. They are extracted from the APK and copied to a working folder (`context.getFilesDir().getAbsolutePath() + "/www/nodejs-project/"`) when the application is launched for the first time or a new version of the application has been installed. Given the project folder will be overwritten after each application update, it should not be used for persistent data storage. To expedite the process of extracting the assets files, instead of parsing the assets hierarchy, a list of files `file.list` and a list of folders `dir.list` are created when the application is compiled and then added to the application assets. On Android 6.x and older versions, this allows to work around a serious perfomance bug in the Android assets manager. + +### Native Modules + +On Linux and macOS, there is experimental support for building modules that contain native code. + +The plugin automatically detects native modules in `./www/nodejs-project/` by searching for `.gyp` files. It's recommended to have the build prerequisites mentioned in `nodejs-mobile` for [Android](https://github.com/janeasystems/nodejs-mobile#prerequisites-to-build-the-android-library-on-linux-ubuntudebian) and [iOS](https://github.com/janeasystems/nodejs-mobile#prerequisites-to-build-the-ios-framework-library-on-macos). For Android it's also recommended that you set the `ANDROID_NDK_HOME` environment variable in your system. + +Building native modules can take a long time for Android, since it depends on building a standalone NDK toolchain for each required architecture. The resulting `.node` binaries are then included in the final application in a separate asset path for each architecture and the correct one will be chosen at runtime. + +While the plugin tries to detect automatically the presence of native modules, there's a way to override this detection and turn the native modules build process on or off, by setting the environment variable `NODEJS_MOBILE_BUILD_NATIVE_MODULES` to `1` or `0`, respectively. This can also be done by starting the application like this: +```sh +NODEJS_MOBILE_BUILD_NATIVE_MODULES=1 cordova run android +``` +```sh +NODEJS_MOBILE_BUILD_NATIVE_MODULES=1 cordova run ios +``` + +If you're using Xcode for building the application for iOS, you can add a `User-Defined Setting` to your project's `Build Settings`, with the key `NODEJS_MOBILE_BUILD_NATIVE_MODULES` and the value of `1` or `0`, for turning the native modules building on or off, respectively. Xcode will use it as an environment variable for the build process.