tns-android

Android Runtime for NativeScript

Contains the source code for the NativeScript's Android Runtime. NativeScript is a framework which enables developers to write truly native mobile applications for Android and iOS using JavaScript and CSS. Each mobile platform has its own ecosystem and offers completely different development tools and language(s) - Java for Android and Objective C (Swift) for iOS. In order to translate JavaScript code to the corresponding native APIs some kind of proxy mechanism is needed. This is exactly what the "Runtime" parts of NativeScript are responsible for. The Android Runtime may be thought of as "The Bridge" between the JavaScript and Android worlds. A NativeScript application for Android is a standard native package (apk) which besides the JavaScript files embed the runtime as well.

• Main Projects
• Helper Projects
• Architecture Diagram
• Build Prerequisites
• How to build
• How to run tests
• Misc
• Get Help

Additional docs

Several Wiki pages describe some internal topics about the runtime here

Main Projects

The repo is structured in the following projects (ordered by dependencies):

• android-metadata-generator - generates metadata necessary for the Android Runtime.
• android-binding-generator - enables Java & Android types to be dynamically created at runtime. Needed by the extend routine.
• android-runtime - contains the core logic behind the NativeScript's Android Runtime. This project contains native C++ code and needs the Android NDK to build properly.
• android-runtime-testapp - this is a vanilla Android Application, which contains the tests for the runtime project.

Helper Projects

• android-static-binding-generator - build tool that generates bindings based on the user's javascript code.
• project-template - this is an empty placeholder Android Application project, used by the NativeScript CLI when building an Android project.

Architecture Diagram

The NativeScript Android Runtime architecture can be summarized in the following diagram.

For more details on how it works, read the documentation.

Build Prerequisites

Following are the minimal prerequisites to build the runtime package.

• Install the latest Android Studio.
• From the SDK Manager (Android Studio -> Tools -> Android -> SDK Manager) install the following components:
  • Android API Level 23, 24, 25, 26, 27
  • Android NDK
  • Android Support Repository
  • Download Build Tools
  • CMake
  • LLDB
• Clone this repository as well as the submodules: git clone --recurse-submodules [e-mail]:NativeScript/android-runtime.git

Working with the Runtime in Android Studio

• Open the test-app folder in Android Studio. It represents a valid Android project and you are able to build and run a test application working with the Runtime from the source.

Note: You might need to run the Android Studio from the command line in order to preserve the environment variables. This is in case you get errors like "missing npm" if starting the studio the usual way.

How to Build

• Run command

  Windows:

  gradlew
  

  Mac/Linux:

  ./gradlew
  

• The build process includes building of the runtime package (both optimized and with unstripped v8 symbol table), as well as all supplementary tools used for the android builds: metadata-generator, binding-generator, metadata-generator, static-binding-generator

• The result of the build will be in the dist folder.

  Note: To cut the build time in half and package only the optimized (stripped) version of the runtime package comment out 'tasks.generateRuntimeAar.execute()' in the build.gradle script.

How to Run Tests

• Go to subfolder test-app after you built the runtime.

• Start an emulator or connect a device.

  Note: Keep in mind the device or emulator needs to have an sdcard mounted.

• Run command

gradlew runtest

Contribute

We love PRs! Check out the contributing guidelines. If you want to contribute, but you are not sure where to start - look for issues labeled help wanted.

Misc

• Implementing additional Chrome DevTools protocol Domains

Get Help

Please, use github issues strictly for reporting bugs or requesting features. For general questions and support, check out Stack Overflow or ask our experts in NativeScript community Slack channel.

Changelog

8.2.0 (2022-03-08)

Bug Fixes

• chrome-devtools: Elements tab (e935a61), closes #1641 #1640
• ensure buildMetadata is done before R8 (01ad92e)
• js -> buffer handling (b49801c)
• load before-plugins.gradle in build.gradle to allow to override androidBuildToolsVersion and other vars (d926dd4)
• loop (95ba9f5)
• material lib as debugImplementation (c6946fe)
• pending intent api31 flags (d8781fd)
• update to jsparser (ea1517c)
• workers: invalidate cached isolates on dispose (#1704) (67e9daf)

Features

• commonGradleProperties (77585ad)
• expose PerformMicrotaskCheckpoint (4b58570)
• log used androidX lib versions (#1651) (528c46f)
• make console.time use 3 decimals (7d9f90b)
• support passing typedArrays as nio buffers (38230e5)
• working gradle7 (501f884)

7.0.1

• Gradle not respecting kotlinVersion (#1642)
• --debug-brk crashing android runtime (#1641)

7.0.0

Bug Fixes

• appPath & appResourcePath now passed in (#1635)
• Kotlin extension overwriting metadata & metadata duplication (#1633)
• Update gradle & kotlin dependancies (#1629)

6.5.3

• Java 8 compatibility when build with Java 9 (#1625)
• metadata crash on startup with Local Notification plugin (#1621)

6.5.1

Bug Fixes

• Cleanup of warnings / possible not checked nullpointers (#1610)

• [metadata] not rebuilding on json api usage change (#1589)

6.5.0

No changes

6.4.1

What's New

• [FR] Customize metadata generation to avoid adding unnecessary unused JS wrappers (#1485)
• Provide verbose metadata filtering output (#1583)
• Upgrade v8 to 8.0.426.16 (#1579)
• Upgrade android gradle plugin to the latest 3.5.3 version (#1564)

Bug Fixes

• Using Android KTX is causing NativeScript app to crash (#1571)
• SBG generating conflicting class definitions (#1569)
• WebAssembly won't initialize without the debugger (#1558)
• Clean up allocations from finalized object links (#1566)
• Fix Kotlin Object issue (#1562)

6.3.1

Bug Fixes

• Kotlin enum values not visible at runtime (#1560)
• Code cache breaks HMR (#1554)
• Worker memory leak in android (#1550)

6.3.0

What's New

• Upgrade v8 to 7.8.279.19 (#1526)
• Restrict Kotlin internal modifier from metadata (#1551)
• Restrict Kotlin properties with non-public type (#1552)

Bug Fixes

• Android 9: signal 11 (SIGSEGV), code 1 (SEGV_MAPERR) in libNativeScript.so (#1413)

6.2.0

What's New

• Add Kotlin extension functions support (#1515)
• update dts generator to the latest version (#1506)
• Unify exceptions information in try/catch and __onUncaughtError (#1445)
• Interop between JS Objects and JSONObjects (#1500)
• Collect build analytics (#1501)
• expose the NDK revision used to build the V8 and the Runtime (#1498)
• Upgrade android gradle plugin to the latest 3.5.1 version (#1502)
• support snapshot libs out of the box (#1496)
• Upgrade v8 to 7.7.299.11 (#1478)

Bug Fixes

• Console.log in worker makes chrome debugging crash (#1511)
• fix searching for merge assets folder on windows (#1503)
• Background job with WorkManager (#1488)
• Deprecated API used in the ErrorActivity is crashing the app (when latest support library is used) (#1494)

6.1.2

Bug Fixes

• UI freezes with tns-android 6.1.0 (Android only) (#1479)

6.1.1

Bug Fixes

• When using kotlin sometimes the metadata is not existing in the result apk (#1476)

6.1.0

What's New

• Runtime Binding Generator depends on deprecated APIs #1441)
• The runtime depends on accessing a hidden value field (#1458)
• Upgrade v8 to 7.6.303.28 (#1439)
• Unify JS stack trace when exception is thrown #1443
• Update androidSdk, targetSdk and build tools to 29 (#1452)
• Upgrade android gradle plugin to the latest 3.5.0 version (#1456)
• Add initial Kotlin support (#1459)
• Add support for user defined gradle.properties (#1463)

Bug Fixes

• SIGSEGV in libNativeScript.so on callback from java with console.log when displaying an object. #1366

6.0.2

What's New

• Include x86_64 architecture

6.0.1

Bug Fixes

• Arabic and Kurdish characters show as gibberish in console.log() (#1302)
• IntentService extending fails at runtime when service is started (#1426)
• SBG may fail when parsing big JS files (#1430)
• Upgrade android gradle plugin to the latest 3.4.2 version (#1425)

6.0.0

Breaking Changes

• Exception information in onDiscarderError and onUnhandledError is changed so that message contains the exception message and stackTrace contains only the stackTrace. In the previous implementation stackTrace contained some additional details (including the exception message) and the message was something like:

  The application crashed because of an uncaught exception. You can look at "stackTrace" or "nativeException" for more detailed information about the exception.
  

• The built-in JSON.stringify method is used for cross workers communication. Circular object references are no longer supported and attempting to send such object will throw an exception.

What's New

• Use the built-in JSON.stringify for cross workers communication (#1411)
• Enable AndroidX and Jetifier(#1370)
• Upgrade v8 to 7.5.288.22(#1387)
• Upgrade android gradle plugin to the latest 3.4.1 version(#1390)
• Remove printStackTrace method calls from the source code(#1359)

Bug Fixes

• Improve package.json parsing in SBG (#1407)
• Improve error message in SBG class parsing (#1401)
• java.lang.NullPointerException in Metadata generator(#13795)
• Buffer() is deprecated(#1392)
• Warnings when building android(#1396)
• No JS stack on discardedError and unhandledError(#1354)

5.4.0

What's New

• Upgrade v8 to 7.4.288.25(#1356)
• Upgrade the android gradle plugin to the latest 3.4.0 version(#1360)
• Enable V8 symbols using from application's package.json file(#1368)

Bug Fixes

• HashMaps improvements - fix for "Attempt to use cleared object reference"(#1345)
• Unable to start Service when the application process is killed by the OS(#1347)
• gradlew not compatible with sh(#1349)
• Memory leak in global.postMessage(#1358)
• memory leak java <-> javascript when java returns [] array(#1363)
• Bug when reifying some generic classes in the SBG(#1372)
• Extending an Android service fails if onCreate hasn't been overridden()

5.3.1

Bug Fixes

• 5.3 build failing (Android) (#1329)
• fix(build): Correct dependencies of cleanupAllJars gradle task (#1338)

5.3.0

What's New

• Upgrade v8 to 7.3.492.25(#1301)
• Upgrade the android gradle plugin to the latest 3.3.2 version(#1304)
• Fail SBG when there's no sbg-bindings.txt file generated(#1286)
• Enable arm64-v8 in app.gradle(#1284)
• Support external buildscript configurations(#1279)
• Refactor SBG to support generics and proper handling of overridable methods(#1322)

Bug Fixes

• The minSdk version should not be declared in the android manifest file(#1316)
• "Unable to resolve dependency" error when runtime is not build (#1309)
• App crashes after tns debug android --debug-brk and trying to debug with "Step into/over"(#892)
• Unable to call plugin's native code if application has been build before adding the plugin(#1293)
• Android build fails when tns-core-modules is updated(#1257)
• Generate better code(#689)

5.2.1

Bug Fixes

• Breakpoint stop to hit when you have two open tabs and close one(#1247)

5.2.0

What's New

• Upgrade v8 to 7.1.302.32(#1237)
• Add OnDiscardedError handler(#1245)
• Upgrade the android gradle plugin to the latest 3.3.1 version(#1251)
• Add android X support(#1226)
• Provide a JS helper function on the global object to release the native object wrapped by a JS instance(#1254)

Bug Fixes

• ClassNotFound exception when calling nested static class with correct argument(#1195)
• If you refresh or close the chrome dev tools window an error will be log in the console (#1202)
• Debug on Android fails when stopped on breakpoint and change in .xml/.css/.html is applied(#1243)
• Upgrade V8 to v7 to fix unstable sort() method(#1176)
• CodeCache option is broken since Android Runtime 4.1.0(#1235)
• Snapshots with ABI splits do not work since Android Runtime 4.1.0(#1234)

5.1.0

What's New

• Add a setting to wrap calls to CallJSMethod in try catch(#1223)
• Support for abstract interface with static methods(#1157)
• Use gradle plugin 3.2.1 instead of 3.2.0(#1209)
• Add a concrete exception when the runtime cannot be found(#1201)

Bug Fixes

• __extends not working as expected for non native inheritance(#1181)

5.0.0

What's New

• Upgrade v8 to 6.9.427.23(#1168)
• Added support for before-plugins.gradle file applied before plugin(#1183)
• Make JSParser in SBG fail the build when failing(#1152)
• Generate interface names list in SBG in parallel(#1132)
• Upgrade android gradle plugin to 3.2.0(#1147)

Bug Fixes

• Static Binding Generator fails if class has static properties that are used within the class(#1160)
• Fixing NoClassDefFoundError when using older API(#1164)

4.2.0

What's New

• Upgrade v8 to 6.7.288.46(#1130)
• Static binding generator now uses bundled npm packages(#1096)
• Add gradle dependencies versions in package.json(#1102)
• Introduce a setting for auto catching exceptions when calling JS method native(#1119)
• Make livesync work entirely through named sockets(#932)

Bug Fixes

• Unable to increase minSdk version by modifying AndroidManifest.xml(#1104)
• UTF8 symbols in inspector protocol are not properly encoded(#1116)
• ChromeDevTools: If you close the socket the app will crash on the device/emulator(#1122)
• App tries to write in /data/local/tmp(#828)
• Rewrite livesync implementation(#929)

4.1.3

Bug Fixes

• Use google repository as primary gradle repository

4.1.2

Bug Fixes

• Webview Crash With Android 8.1.0 / Chromium 67.0.3396.68 (#1075)

4.1.1

What's New

• Add support for java.nio.HeapByteBuffer to ArrayBuffer conversion(#1060)
• Upgrade Gradle version (wrapper and plugin) to latest(#1054)
• Accessing Native Packages starting with 'in'(#1046)
• tns-android 4.0.1: undefined objects are dumped with console.log making the log unreadable(#1026)
• Support new gradle dependency configuration(#993)
• new Date() does not work as expected after time zone change(#961)
• Update V8 to latest stable version(#808)
• Checking if java class implements java interface(#739)
• How to disable console.logs in release builds(#1024)

Bug Fixes

• Calling java method with incorrect params crashes with a JNI exception (#844)
• Chrome DevTools: App crashes after adding new view element(#1051)
• Extraneous classes generated by SBG are not cleaned on rebuild(#904)
• Source files have different roots, while using debug command(896)

4.0.1

Bug Fixes

• App crash on startup on Android 4.4

4.0.0

Breaking Changes

• Rewrite the build script routine to no longer use flavors as the primary mechanism to apply nativescript plugin Android configurations (#890) - If you see the All flavors must now belong to a named flavor dimension. build error, ensure that you are using the latest CLI. Plugins will be built implicitly by the CLI, version 4.0.0-rc or newer.
• Application package outputs are now located at platforms/android/app/build/outputs/<build-type>/<flavor - if any>/app-<build-type>.apk (#938)

What's New

• Respect .jar and .aar libraries from App_Resources/Android/libs (#899)
• Add user-defined Android project files - .java, resources, assets in App_Resources/Android (#700) - Enabled after updating the App_Resources/Android subdirectory structure. Use tns resources update android with CLI 4.0.0-rc or newer.
• Console API improvements - file name, line, column support in Chrome DevTools; Objects are expanded to JSON representations (#894) (#884) - Replaces the console API in the tns-core-modules.
• Update Gradle to 4.1 and Android plugin for Gradle to 3.0.1 (#938)

Bug Fixes

• fix: static binding generator creating wrong files, when two extended classes have the same name (#692)

3.4.2

Bug Fixes

• fix include gradle flavor generation for plugins with incomplete include.gradle scripts (#937)

3.4.1

Bug Fixes

• Want help to access webview document height and cookies (#5243)
• Question about plugin using native lib NS 3.4 (#5254)

3.4.0

What's New

• Android Studio Integration (#876)

Bug Fixes

• Faulty Java class name when extending a class inside a file containing dots (#761)

3.3.1

Bug Fixes

• app.gradle applies before other plugin gradle scripts (#878)

3.3.0

Bug Fixes

• Provide better error message while parsing js files (#833)
• Improve JavaScript Metadata generation (#832)
• Improve Error handling incorrectly implementing Java interface (#836)

3.2.0

Bug Fixes

• Static binding generator fails when using Webpack + Workers (#778)

3.1.1

Bug Fixes

• APKS with ABI split crash on start up (#785)

3.1.0

What's New

• Chrome DevTools Elements Tab Support (#746)

3.0.1

Bug Fixes

• --debug-brk flag not working (#2741)
• Clean app between different versions of application package. Ensure Android 6's AutoBackup feature doesn't restore files for NS apps

3.0.0

What's New

• Chrome DevTools Network Domain (#715)
• Chrome DevTools Scope Tab (#713)
• Enabling java source code or direct dex generation #663)
• Improve Gradle incremental build (#562)

Bug Fixes

• Javascript array not marshalling to Java long[] properly (#696)

2.5.0-RC

What's New

• Error when running on real android device (#628)
• Updating v8 to 5.4/5.5 #631)

Bug Fixes

• Can't use npm packages ending with ".js" (#666)
• Static binding generator crash build-time: clazz is null causes app to crash (#665)
• Decorators aren't respected when extending classes with TypeScript 2.1.4+ (#651)
• Samples SDK app crashes (#632)
• Missing stack trace on worker errors (#629)
• Classes using fields from compileSdk > Platform Sdk on device cause crash when extended in TS (#626)
• A failure building in debug and release in series (#649)

2.4.0

What's New

• Update the V8 JavaScript Engine to 5.2.361 (97% ES6 support)
• [Experimental] Generate typings for android.jar and android support libs (--androidTypings) (#605)
• [Experimental] Multithreading support enabled with Web Workers API (#532)
• Enable enableProguardInReleaseBuilds in build.gradle (#567)
• Optimized default apk size (#529)
• Improved debug Error Activity (#293)

Bug Fixes

• Build for armv7 and x86 only by default (#614)
• Make javascript parsing during build incremental (#572)
• App won't launch on Android 22 device (#592)
• Metadata isn't created for generated dex files (#552)
• App doesn't load with the new custom Application\Activity support (#546)

Performance

• Enable enableProguardInReleaseBuilds in build.gradle (#567)
• Optimize default apk size (#529)

2.3.0

What's New

• Extend is not working as previous versions in all cases. (#514)
• JS: Binding: Run-time error occured in file: undefined at line: undefined and column: undefined (#443)

Bug Fixes

• Crash when invoking a second (different) signature of an overloaded method (meta generator cache?) (#555)
• App crashes when set undefined to reference type field (#306)

2.2.0

What's New

• Classes can implement multiple interfaces (#501)

Performance

• Update gradle wrapper version to 2.10, and gradle plugin to 2.1.2 (#516)

2.1

What's New

• Implement custom gradle clean (#459)

Bug Fixes

• App crash (#476)
• The static binding generator should clean redundant files (#467)
• Android builds fail on nativescript 2.0 (#460)
• Need to add a Gradle Android.defaultConfig (#454)

Performance

• Initial builds of ng2 apps are slow (#436)

2.0.0

What's New

• Android N early developer preview (#378)
• [Proposal] Static binding generator specification. (#363)
• Android Runtime Support for older Android versions (#357)
• Data Marshalling: Support for typed arrays (#65)
• Support Android Widgets
• Add support for caching already compiled JS code
• Additional Intents Crashes app
• Enable Multidex support

Bug Fixes

• Wrong object lifecycle management (#382)
• CLI can easily fail and blow project up on windows when you have multiple plugins. (#369)
• Provide method implementations for partially implemented interfaces. (#259)
• Generate metadata for protected interfaces (#236)
• Cannot resolve method/constructor signatures when null is passed (#90)
• App seems to load up with a white screen on run, but works in debug mode #397

Performance

• Wrong object lifecycle management (#382)

1.7.1

Bug Fixes

• Fix application initialization
• Fix error activity

1.7.0

What's New

• Extendind Application and Activity classes
• Gradle script improvements

Bug Fixes

• App crashes with "NativeScriptApplication already initialized"
• Upgrade to Gradle 1.5.0

1.6.0

What's New

• Build common test infrastructure for Android and iOS
• New syntax for Java arrays
• Improved debugger
• Log in the debugger console
• Update documentation
• Provide support for ARMv8a
• Imroved exception handling
• Gradle script improvements

Bug Fixes

• Fix app crash during debugging (#270)
• Fix app hang during array marshalling
• Fix incorrect module resolution
• Fix app crash during debugging (#338)

1.5.1

What's New

• Enable requiring of JSON files (like in Node) (#217)
• Revisit the "assert" routine in the JNI part (#221)
• Android CallStack (#228)
• error handling introducing c++ exceptions (#277)
• Simplify require errors (#287)
• Experimental: Support native modules (#291)
• Gradle script improvements

Bug Fixes

• Print meaningful error when metadata generator fails to reflect a class (#245)

1.5.0

What's New

• Improved LiveSync
• Improved error handling
• Use Gradle Wrapper
• Use V8 code cache (experimental)

Bug Fixes

• Proper handling of HTTP 401 status code
• Generate metadata for protected interfaces
• Fix loading module with NULL char in it

1.4.0

Bug Fixes

• Generated metadata is not updated after initial build until after 'gradle clean' is called (#227)
• Incorrect behavior when getting or setting java fields from javascript (#219)
• Better handling of package.json main configuration (#190)
• Calling non existen ctor crashesh the runtime (#180)
• ClassCastException when tries to convert numeric return value of overridden methods (#139)

1.3.0

What's New

• Expose public API for NativeScript Companion App for deleting old *.dex files (#187)
• Add support for AppBuilder LiveSync (#186)
• Create a new template project for Gradle build (#182)
• Support ~ path syntax in require (#177)
• Enable using the Google Design library (and alike) with "library add" command (#140)
• Implement support for CLI live sync feature (#137)
• Ahead-of-time generation of binding proxies (#103)
• Use pool of arrays for marshalling (#33)

Bug Fixes

• Run after LiveSync starts the last synced app on the device/emulator (#214)
• Cannot load module with relative path on Android 6 (#206)
• App crashes when call overloaded method of a base class (#203)
• Fix file is external to application error on Android M (#185)
• App crash during GC (#184)
• JNI reference leaks when passing JavaScript arrays (#167)
• ArrayBuffer broken (#164)
• ClassCastException when tries to convert numeric return value of overridden methods (#139)
• Allow debugger reconnects (#136)
• __onUncaughtError is not called. (#108)

Performance

• Cache parsed method signature (#181)
• Use pool of arrays for marshalling (#33)

Android Runtime Changelog

1.2.1

What's New

• Updated android widgets library
• Allow verbose logging system property to enable debug messages early in engine bootstrap

Bug Fixes

• Additional null checks in V8 to handle certain possible garbage collection issues
• Fix sync support in runtime for specific (Samsung) Android devices where run-as is not working
• Fix JNI memory leak
• Fix copy of correct android.jar referenced in project properties

1.2.0

What's New

• Support http cookies in build-in http client (#159)
• Implement support for CLI live sync feature (#137)
• Rethink 0 day support for new android versions (#86)

Bug Fixes

• Fix ErrorActivity not displayed on uncaught exceptions (#158)
• Fix JNI memory leak when resolving classes in metadata reader (#157)
• Application crash with JNI ERROR (app bug): local reference table overflow (max=512) (#149)
• Cannot set float field (#148)
• IndexedPropertySetter not called (#127)
• Fix GetDbgPort intent (#117)
• Recreating an Activity with fragments on same process crashes the runtime (#96)
• Grunt tasks fail on Windows (#61)

Performance

• Optimize Strings marshaling between Java and V8 (#160)
• Improve required module loading (#156)
• Improve JNI String marshalling (#126)
• Cache folder-as-module resolved path (#121)