Skip to content

Commit d829f42

Browse files
ammarahm-edammarahm-ed
committed
update README.md
1 parent 2768b56 commit d829f42

1 file changed

Lines changed: 66 additions & 74 deletions

File tree

‎README.md‎

Lines changed: 66 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,15 @@
1-
# Node-API Android Runtime for NativeScript
2-
[![Build Status](https://travis-ci.org/NativeScript/android-runtime.svg?branch=master)](https://travis-ci.org/NativeScript/android-runtime)
1+
<h1 align="center">Node-API Android Runtime for NativeScript</h1>
32

4-
Contains the source code for the NativeScript's Android Runtime. [NativeScript](https://www.nativescript.org/) 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.
3+
[NativeScript](https://www.nativescript.org/) is an open-source framework for building truly native mobile applications using JavaScript. This repository contains the source code for the Node-API based Android Runtime used by NativeScript.
4+
5+
The Android Runtime is a key component of the NativeScript framework. It is responsible for executing JavaScript code on Android devices. The runtime is built on top of [Node-API](https://nodejs.org/api/n-api.html) and provides a way to interact with the Android platform APIs from JavaScript.
6+
7+
The new runtime is based on the Node-API and is designed to be more stable, faster, and easier to maintain. It also supports multiple JavaScript engines, including V8, QuickJS, Hermes, and JavaScriptCore.
58

69
<!-- TOC depthFrom:2 -->
710

811
- [Main Projects](#main-projects)
912
- [Helper Projects](#helper-projects)
10-
- [Architecture Diagram](#architecture-diagram)
1113
- [Build Prerequisites](#build-prerequisites)
1214
- [How to build](#how-to-build)
1315
- [How to run tests](#how-to-run-tests)
@@ -16,118 +18,108 @@ Contains the source code for the NativeScript's Android Runtime. [NativeScript](
1618

1719
<!-- /TOC -->
1820

19-
## Additional docs
20-
Several Wiki pages describe some internal topics about the runtime [here](https://github.com/NativeScript/android-runtime/wiki)
21+
## Project structure
2122

22-
## Main Projects
2323
The repo is structured in the following projects (ordered by dependencies):
2424

25-
* [**android-metadata-generator**](android-metadata-generator) - generates metadata necessary for the Android Runtime.
26-
* [**android-binding-generator**](test-app/runtime-binding-generator) - enables Java & Android types to be dynamically created at runtime. Needed by the `extend` routine.
27-
* [**android-runtime**](test-app/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.
28-
* [**android-runtime-testapp**](test-app/app) - this is a vanilla Android Application, which contains the tests for the runtime project.
25+
- [**android-metadata-generator**](android-metadata-generator) - generates metadata necessary for the Android Runtime.
26+
- [**android-binding-generator**](test-app/runtime-binding-generator) - enables Java & Android types to be dynamically created at runtime. Needed by the `extend` routine.
27+
- [**android-runtime**](test-app/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.
28+
- [**android-runtime-testapp**](test-app/app) - this is a vanilla Android Application, which contains the tests for the runtime project.
29+
- [**napi-implementations**](test-app/runtime/src/main//cpp/napi/) - contains the implementation of the Node-API for each supported JS engine.
2930

3031
## Helper Projects
3132

32-
* [**android-static-binding-generator**](android-static-binding-generator) - build tool that generates bindings based on the user's javascript code.
33-
* [**project-template**](build-artifacts/project-template-gradle) - this is an empty placeholder Android Application project, used by the [NativeScript CLI](https://github.com/NativeScript/nativescript-cli) when building an Android project.
33+
- [**android-static-binding-generator**](android-static-binding-generator) - build tool that generates bindings based on the user's javascript code.
34+
- [**project-template**](build-artifacts/project-template-gradle) - this is an empty placeholder Android Application project, used by the [NativeScript CLI](https://github.com/NativeScript/nativescript-cli) when building an Android project.
3435

35-
## Architecture Diagram
36-
The NativeScript Android Runtime architecture can be summarized in the following diagram.
36+
### Build Prerequisites
3737

38-
![Android Runtime diagram](https://github.com/NativeScript/docs/blob/master/docs/img/ns-runtime-android.png)
38+
Following are the minimal prerequisites to build the runtime package.
3939

40-
For more details on how it works, read the [documentation](https://v7.docs.nativescript.org/core-concepts/android-runtime/overview).
40+
- Install the latest [Android Studio](https://developer.android.com/studio/index.html).
41+
- From the SDK Manager (Android Studio -> Tools -> Android -> SDK Manager) install the following components:
4142

42-
## Build Prerequisites
43-
Following are the minimal prerequisites to build the runtime package.
43+
- Android API Level 23, 24, 25, 26, 27
44+
- Android NDK
45+
- Android Support Repository
46+
- Download Build Tools
47+
- CMake
48+
- LLDB
4449

45-
* Install the latest [Android Studio](https://developer.android.com/studio/index.html).
46-
* From the SDK Manager (Android Studio -> Tools -> Android -> SDK Manager) install the following components:
47-
* Android API Level 23, 24, 25, 26, 27
48-
* Android NDK
49-
* Android Support Repository
50-
* Download Build Tools
51-
* CMake
52-
* LLDB
53-
* Clone this repository as well as the submodules: `git clone --recurse-submodules git@github.com:NativeScript/android-runtime.git`
50+
## How to Build
5451

55-
## Working with the Runtime in Android Studio
52+
Clone the repo:
5653

57-
* 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.
54+
```Shell
55+
git clone https://github.com/NativeScript/napi-android.git
56+
```
5857

59-
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.
58+
Install the jsparser dependencies:
6059

61-
## How to Build
60+
```Shell
61+
cd test-app/build-tools/jsparser
62+
npm install
63+
```
6264

63-
* Install dependencies from NPM:
65+
Set the following environment variables:
6466

65-
```Shell
66-
cd test-app/build-tools/jsparser
67-
npm install
68-
```
67+
- `JAVA_HOME` such that `$JAVA_HOME/bin/java` points to your Java executable
68+
- `ANDROID_HOME` pointing to where you have installed the Android SDK
69+
- `ANDROID_NDK_HOME` pointing to the version of the Android NDK needed for this version of NativeScript
6970

70-
* Set environment variables:
71-
- `JAVA_HOME` such that `$JAVA_HOME/bin/java` points to your Java executable
72-
- `ANDROID_HOME` pointing to where you have installed the Android SDK
73-
- `ANDROID_NDK_HOME` pointing to the version of the Android NDK needed for this version of NativeScript
71+
Run command
7472

75-
* Run command
73+
Windows:
7674

77-
Windows:
75+
```Shell
76+
gradlew -Pengine=V8
77+
```
7878

79-
```Shell
80-
gradlew -Pengine=V8
81-
```
79+
Mac/Linux:
8280

83-
Mac/Linux:
81+
```Shell
82+
./gradlew -Pengine=V8
83+
```
8484

85-
```Shell
86-
./gradlew -Pengine=V8
87-
```
8885
You can pass in `QUICKJS`, `HERMES`, `JSC` or `V8` to compile the runtime with the respective JS engine.
8986

90-
* 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
91-
* The result of the build will be in the dist folder.
87+
- 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
88+
- The result of the build will be in the dist\_[engine] folder. For example if you are building with V8, the result will be in the dist_v8 folder.
9289

9390
`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](https://github.com/NativeScript/android-runtime/blob/v3.0.0-rc.1/build.gradle#L114) script.
9491

9592
## How to Run Tests
9693

97-
* Go to subfolder test-app after you built the runtime.
98-
* Start an emulator or connect a device.
94+
- Go to subfolder test-app after you built the runtime.
95+
- Start an emulator or connect a device.
96+
97+
- Run command
9998

100-
``Note: Keep in mind the device or emulator needs to have an sdcard mounted.``
101-
* Run command
10299
```Shell
103100
gradlew runtests
104101
```
105102

106-
## How to Connect the Inspector
103+
## Working with the Runtime in Android Studio
107104

108-
* Install dependencies: run command
109-
```Shell
110-
cd test-app
111-
npm install
112-
```
113-
* Run the test app in Android Studio, or manually in the emulator.
114-
* Run command
115-
```Shell
116-
npx ns debug android --start
117-
```
118-
(If you instead have the `nativescript` NPM module installed globally,
119-
you can omit the `npm install` and the `npx` prefix.)
120-
* This will print out a URL, such as
121-
`devtools://devtools/bundled/inspector.html?ws=localhost:40000`.
122-
Open this URL in Chrome or Chromium.
105+
- 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.
106+
107+
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.
108+
109+
You can change the JS engine used by the runtime by setting the `jsEngine` property in the [`build.gradle`](test-app/runtime/build.gradle) file in the root of the project. The possible values are `QUICKJS`, `HERMES`, `JSC` or `V8`.
123110

124111
## Contribute
125-
We love PRs! Check out the [contributing guidelines](CONTRIBUTING.md). If you want to contribute, but you are not sure where to start - look for [issues labeled `help wanted`](https://github.com/NativeScript/android-runtime/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22).
126112

113+
We love PRs! Check out the [contributing guidelines](CONTRIBUTING.md). If you want to contribute, but you are not sure where to start - look for [issues labeled `help wanted`](https://github.com/NativeScript/android-runtime/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22).
127114

128115
## Misc
129116

130-
* [Implementing additional Chrome DevTools protocol Domains](docs/extending-inspector.md)
117+
- [Implementing additional Chrome DevTools protocol Domains](docs/extending-inspector.md)
131118

132119
## Get Help
120+
133121
Please, use [github issues](https://github.com/NativeScript/android-runtime/issues) strictly for [reporting bugs](CONTRIBUTING.md#reporting-bugs) or [requesting features](CONTRIBUTING.md#requesting-new-features). For general questions and support, check out [Stack Overflow](https://stackoverflow.com/questions/tagged/nativescript) or ask our experts in [NativeScript community Slack channel](http://developer.telerik.com/wp-login.php?action=slack-invitation).
122+
123+
## License
124+
125+
This project is licensed under the Apache License Version 2.0. See the [LICENSE file](LICENSE) for more info.

0 commit comments

Comments
 (0)