README.md

cordova-plugin-hello-c

A simple example of a Cordova plugin that uses pure C code.

It illustrates how to use platform-specific (either Android or iOS) C code and how to share C code cross-platform (between Android and iOS).

For Android it utilizes the Android NDK to compile architecture-specific libraries and a JNI wrapper to expose the C functions to the Java plugin API.

For iOS it uses the pure C source code in place alongside the Objective-C plugin wrapper, as well as an example cross-platform library compiled as a static library for iOS.

usage example

• Clone the test project
• Add Android and iOS platforms: cordova platform add android && cordova platform add ios
• Run: cordova run android / cordova run ios

Plugin structure

• plugin.xml - Specifies the plugin's source files and libraries to copy to the platforms of the Cordova project into which the plugin is installed
• compile-android and compile-android.cmd - Script to recompile C source code as a shared library for use with Android platform
• compile-ios - Script to recompile cross-platform C library as static library for use with iOS platform
• src/ - C source code and build scripts
  • common/ - cross-platform C source code to run on both Android and iOS
    • mylib/ - example cross-platform C library
  • android/ - source code and build scripts for Android platform
    • build-extras.gradle - Gradle build script to link up the NDK make file for debugging C code in Android Studio
    • HelloCPlugin.java - Provides the native Java implementation for Android of the Cordova plugin
    • HelloCJni.java - Provides the Java interface to the underlying JNI C implementation
      • jni/ - JNI C implementation and build script
        • HelloJni.c - C implementation of the JNI interface defined by HelloCJni.java, including
          • Android-specific implementation to get current CPU architecture
          • interfaces to cross-platform C functionality
        • Android.mk - NDK Make script to build the C source code into architecture-specific shared libraries
      • libs/ - contains folders for the various architecture-specific shared libraries built by the NDK Make script
  • ios/ - source code and build scripts for iOS platform
    • c_getArch.c & c_getArch.h - iOS-specific implementation to get current CPU architecture
    • HelloCPlugin.c & HelloCPlugin.h - Provides the native Objective-C implementation for iOS of the Cordova plugin
    • ios_compile.sh - Script to compile the cross-platform example library in src/common/mylib/ as a static library
    • Makefile - Make script invoked by the above script to perform the C compilation.
    • libs/ - the compiled cross-platform library
      • libmylib.a - the compiled cross-platform library as a multi-architecture static library
      • headers/ - the header files of the cross-platform library (static libraries require the headers externally)

Recompiling libraries

If you modify the C source files, be sure to re-build the compiled libraries.

Android

You can re-build the libhelloc.so binaries using the ndk-build script.

To do so:

• Install Android NDK as instructed here
• Add the NDK install path to your path environment variable
  • By default it's installed under $ANDROID_SDK_HOME/ndk-bundle
  • e.g. export PATH=$PATH;$ANDROID_SDK_HOME/ndk-bundle
• Set the ANDROID_NDK_HOME environment variable to your NDK install path
  • e.g. export ANDROID_NDK_HOME=$ANDROID_SDK_HOME/ndk-bundle
• Open terminal in plugin root folder
• Run ./compile-android (compile-android.cmd on Windows)

If you are editing the C source code of the plugin in place in the example project:

• Modify the C source in plugins/cordova-plugin-hello-c/src/android/jni or plugins/cordova-plugin-hello-c/src/common
• Open terminal in plugins/cordova-plugin-hello-c
• Delete src/android/libs and src/android/obj
• Run compile-android (compile-android.cmd on Windows)
• From the project root, remove and re-add the android platform to apply the plugin changes to the project cordova platform rm android && cordova platform add android

iOS

If you modify the C source code in common/mylib/ you'll need to rebuild the static library and headers in src/ios/libs.

• Open terminal in plugin root folder
• Run ./compile-ios

If you are editing the C source code of the plugin in place in the example project:

• Modify the C source in plugins/cordova-plugin-hello-c/src/ios/ or plugins/cordova-plugin-hello-c/src/common
• Open terminal in plugins/cordova-plugin-hello-c
• Run ./compile-ios
• From the project root, remove and re-add the platform to apply the plugin changes to the project cordova platform rm ios && cordova platform add ios

Debugging C source code

Android

• The Android NDK enables C/C++ source code to be debugged in Android Studio alongside Java.
• To do so, the source code must be included but not the compiled libraries.
• To debug this plugin in Android Studio do the following:
  • Edit plugin.xml and in the <platform name="android"> block, comment out the source-file lines in the PRODUCTION block which include the compiled libraries
  • Remove/re-add the plugin or Android platform in your project to update the plugin files in the platform project
  • Open the Android platform project (platforms/android) in Android Studio
  • Connect an Android device for debugging
  • Use the Project Explorer to find and open one of the .c source files
  • Place a breakpoint, for example on a return statement
  • Select "Run" > "Debug ..." from the menu

iOS

• Since iOS is a C-based platform, C debugging is inherently supported in the Xcode IDE
• However, to debug the C code in the static library src/ios/libs/libmylib.a, you'll need to comment out the library files and comment in the source code for it:
• Edit plugin.xml and in the <platform name="ios"> block
  • comment out the lines in the PRODUCTION block which include the compiled library and headers.
  • comment in the the commented-out lines in the DEBUG block which will include the uncompiled C source code for the library
• Remove/re-add the plugin or iOS platform in your project to update the plugin files in the platform project
• Use the OSX Finder to browse to platforms/ios/ in your Cordova project and double-click the .xcodeproj file to open it in Xcode.