Initial commit of working Android app embedded with v8, with prebuilt library included

Author: cmdr2

.gitignore

@@ -0,0 +1 @@
+.DS_Store

README.md

@@ -1,2 +1,71 @@
 # v8-android
 Example Android Studio project that embeds v8 (plus some notes on compiling v8 for android)
+
+The intention is to embed v8 inside an Android app, and this project is an example of getting "Hello World" from Javascript to show up on the Android app (using v8).
+
+## How to use:
+1. Clone this repository, and open the `jni-test` directory as a project in your Android Studio.
+2. Run the project after connecting your phone via USB.
+
+Incase it has issues, try renaming the `app/libs/armeabi-v7a` directory to your phone's ABI format, like `app/libs/arm64-v8a` or something. Or maybe just edit the `app/CMakeLists.txt` file and remove the `${ANDROID_ABI}` parameter.
+
+This uses a prebuilt v8 library for Android, compiled from the 6.8 branch of v8 on July 22, 2018 (5b8126a8d6fa0c58c89c2d618264ee087d6795a1 (HEAD -> 6.8, tag: lkgr/6.8, tag: 6.8.275.2)). You may want to create a new binary.
+
+## Here's what was done broadly:
+1. Compile v8 for android_arm target
+2. Manually generate the ".a" static libraries from the ".o" files using the 'ar' command. The build-generated versions weren't working for some reason.
+3. Create an Android NDK project from Android Studio.
+4. Copy the `include` directory from v8, and the static libraries created previously and paste into an Android project's `app/libs/armeabi-v7a/` directory.
+5. Specify these libraries and include directory path in the Android project's `CMakesLists.txt` file.
+6. Use v8 in the native C++ file, which gets called from the Java Android Activity via JNI.
+
+## For compiling v8:
+0. Build on Ubuntu (or some Linux with ELF and glibc). I was on a Mac, so I created a Virtual Machine and used Ubuntu Server for a minimal distro. Give it atleast 40 GB of disk (can use dynamic resize).
+1. Follow https://github.com/v8/v8/wiki/Building-from-Source
+2. But before running `v8gen.py`, first run `echo "target_os = ['android']" >> /path/to/workingDir/.gclient && gclient sync`
+3. Then run `tools/dev/v8gen.py gen -m client.v8.ports -b "V8 Android Arm - builder" android_arm.release`
+4. Next, run `gn args out.gn/android_arm.release` and use these flags:
+```
+is_component_build = false
+is_debug = false
+symbol_level = 1
+target_cpu = "arm"
+target_os = "android"
+use_goma = false
+v8_android_log_stdout = true
+v8_static_library = true
+use_custom_libcxx = false
+use_custom_libcxx_for_host = false
+v8_use_external_startup_data = false
+```
+5. Next, run `ninja -C out.gn/android_arm.release`
+6. Then create the `libv8_base.a` and `libv8_snapshot.a` static libraries manually (the built ones don't seem to work for some reason):
+```
+mkdir libs
+cd libs
+ar -rcsD libv8_base.a /path/to/v8/out.gn/android_arm.release/obj/v8_base/*.o
+ar -rcsD libv8_base.a /path/to/v8/out.gn/android_arm.release/obj/v8_libbase/*.o
+ar -rcsD libv8_base.a /path/to/v8/out.gn/android_arm.release/obj/v8_libsampler/*.o
+ar -rcsD libv8_base.a /path/to/v8/out.gn/android_arm.release/obj/v8_libplatform/*.o
+ar -rcsD libv8_base.a /path/to/v8/out.gn/android_arm.release/obj/src/inspector/inspector/*.o
+ar -rcsD libv8_base.a /path/to/v8/out.gn/android_arm.release/obj/third_party/icu/icuuc/*.o
+ar -rcsD libv8_base.a /path/to/v8/out.gn/android_arm.release/obj/third_party/icu/icui18n/*.o
+ar -rcsD libv8_snapshot.a /path/to/v8/out.gn/android_arm.release/obj/v8_snapshot/*.o
+```
+6. Then copy the includes using `cp -R /path/to/v8/include .`
+7. Now you can use these in your Android NDK project
+
+## Using the compiled v8 binaries in an Android NDK project
+1. Either create a new Android NDK project in your Android Studio, or use one that's already set up with CMake
+2. Copy the `include` directory from v8, and the static libraries created previously and paste into an Android project's `app/libs/armeabi-v7a/` directory.
+3. Specify these libraries and include directory path in the Android project's `CMakesLists.txt` file.
+4. Use v8 in the native C++ file, which gets called from the Java Android Activity via JNI.
+
+Use the example project for the example `CMakeLists.txt` and C++ file.
+
+## Random note
+The key gotcha was that the `.a` files created by the build didn't seem to work for some reason, or maybe I was messing the order. So what worked was manually combining the relevant `.o` files (base, libbase, platform, sampler, inspector, icui18n, icuuc) into libv8_base.a, and the v8_snapshot `.o` files into libv8_snapshot.a.
+
+Then the order in CMakeList was important: v8_base followed by v8_snapshot.
+
+Another thing to remember: this process will probably take 30 GB of disk space, and download probably 15 GB of stuff. This could be because it downloaded stuff a few times, mostly because of my sheer incompetence at compiling v8. But size your VM disk, time and patience accordingly.

jni-test/.gitignore

@@ -0,0 +1,10 @@
+*.iml
+.gradle
+/local.properties
+/.idea/libraries
+/.idea/modules.xml
+/.idea/workspace.xml
+.DS_Store
+/build
+/captures
+.externalNativeBuild

jni-test/.idea/caches/build_file_checksums.ser

@@ -0,0 +1 @@
+/build

jni-test/.idea/codeStyles/Project.xml

@@ -0,0 +1,12 @@
+cmake_minimum_required(VERSION 3.4.1)
+
+add_library( v8_base STATIC IMPORTED )
+set_target_properties( v8_base PROPERTIES IMPORTED_LOCATION ${CMAKE_SOURCE_DIR}/libs/${ANDROID_ABI}/libv8_base.a )
+
+add_library( v8_snapshot STATIC IMPORTED )
+set_target_properties( v8_snapshot PROPERTIES IMPORTED_LOCATION ${CMAKE_SOURCE_DIR}/libs/${ANDROID_ABI}/libv8_snapshot.a )
+
+add_library( native-lib SHARED src/main/cpp/native-lib.cpp )
+target_include_directories( native-lib PRIVATE ${CMAKE_SOURCE_DIR}/libs/include )
+
+target_link_libraries( native-lib v8_base v8_snapshot log )

jni-test/.idea/compiler.xml

@@ -0,0 +1,38 @@
+apply plugin: 'com.android.application'
+
+android {
+    compileSdkVersion 26
+    defaultConfig {
+        applicationId "org.cmdr2.jnitest"
+        minSdkVersion 19
+        targetSdkVersion 26
+        versionCode 1
+        versionName "1.0"
+        testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner"
+        externalNativeBuild {
+            cmake {
+                cppFlags "-std=c++0x"
+            }
+        }
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+        }
+    }
+    externalNativeBuild {
+        cmake {
+            path "CMakeLists.txt"
+        }
+    }
+}
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation 'com.android.support:appcompat-v7:26.1.0'
+    implementation 'com.android.support.constraint:constraint-layout:1.1.2'
+    testImplementation 'junit:junit:4.12'
+    androidTestImplementation 'com.android.support.test:runner:1.0.2'
+    androidTestImplementation 'com.android.support.test.espresso:espresso-core:3.0.2'
+}

jni-test/.idea/gradle.xml

@@ -0,0 +1,69 @@
+# The V8 public C++ API
+
+# Overview
+
+The V8 public C++ API aims to support four use cases:
+
+1. Enable applications that embed V8 (called the embedder) to configure and run
+   one or more instances of V8.
+2. Expose ECMAScript-like capabilities to the embedder.
+3. Enable the embedder to interact with ECMAScript by exposing API objects.
+4. Provide access to the V8 debugger (inspector).
+
+# Configuring and running an instance of V8
+
+V8 requires access to certain OS-level primitives such as the ability to
+schedule work on threads, or allocate memory.
+
+The embedder can define how to access those primitives via the v8::Platform
+interface. While V8 bundles a basic implementation, embedders are highly
+encouraged to implement v8::Platform themselves.
+
+Currently, the v8::ArrayBuffer::Allocator is passed to the v8::Isolate factory
+method, however, conceptually it should also be part of the v8::Platform since
+all instances of V8 should share one allocator.
+
+Once the v8::Platform is configured, an v8::Isolate can be created. All
+further interactions with V8 should explicitly reference the v8::Isolate they
+refer to. All API methods should eventually take an v8::Isolate parameter.
+
+When a given instance of V8 is no longer needed, it can be destroyed by
+disposing the respective v8::Isolate. If the embedder wishes to free all memory
+associated with the v8::Isolate, it has to first clear all global handles
+associated with that v8::Isolate.
+
+# ECMAScript-like capabilities
+
+In general, the C++ API shouldn't enable capabilities that aren't available to
+scripts running in V8. Experience has shown that it's not possible to maintain
+such API methods in the long term. However, capabilities also available to
+scripts, i.e., ones that are defined in the ECMAScript standard are there to
+stay, and we can safely expose them to embedders.
+
+The C++ API should also be pleasant to use, and not require learning new
+paradigms. Similarly to how the API exposed to scripts aims to provide good
+ergonomics, we should aim to provide a reasonable developer experience for this
+API surface.
+
+ECMAScript makes heavy use of exceptions, however, V8's C++ code doesn't use
+C++ exceptions. Therefore, all API methods that can throw exceptions should
+indicate so by returning a v8::Maybe<> or v8::MaybeLocal<> result,
+and by taking a v8::Local<v8::Context> parameter that indicates in which
+context a possible exception should be thrown.
+
+# API objects
+
+V8 allows embedders to define special objects that expose additional
+capabilities and APIs to scripts. The most prominent example is exposing the
+HTML DOM in Blink. Other examples are e.g. node.js. It is less clear what kind
+of capabilities we want to expose via this API surface. As a rule of thumb, we
+want to expose operations as defined in the WebIDL and HTML spec: we
+assume that those requirements are somewhat stable, and that they are a
+superset of the requirements of other embedders including node.js.
+
+Ideally, the API surfaces defined in those specs hook into the ECMAScript spec
+which in turn guarantees long-term stability of the API.
+
+# The V8 inspector
+
+All debugging capabilities of V8 should be exposed via the inspector protocol.

jni-test/.idea/misc.xml

@@ -0,0 +1,4 @@
+include_rules = [
+  # v8-inspector-protocol.h depends on generated files under include/inspector.
+  "+inspector",
+]

jni-test/.idea/runConfigurations.xml

@@ -0,0 +1,13 @@
+set noparent
+
+[email protected]
+[email protected]
+[email protected]
+[email protected]
+
+per-file [email protected]
+per-file [email protected]
+per-file [email protected]
+per-file [email protected]
+
+# COMPONENT: Blink>JavaScript>API

jni-test/app/.gitignore

@@ -0,0 +1,29 @@
+# Copyright 2017 the V8 project authors. All rights reserved.')
+# Use of this source code is governed by a BSD-style license that can be
+# found in the LICENSE file.
+
+"""Presubmit script for //v8/include
+
+See http://dev.chromium.org/developers/how-tos/depottools/presubmit-scripts
+for more details about the presubmit API built into depot_tools.
+"""
+
+import os
+
+
+def PostUploadHook(cl, change, output_api):
+  """git cl upload will call this hook after the issue is created/modified.
+
+  This hook adds extra try bots to the CL description in order to run layout
+  tests in addition to CQ try bots.
+  """
+  def header_filter(f):
+    return '.h' in os.path.split(f.LocalPath())[1]
+  if not change.AffectedFiles(file_filter=header_filter):
+    return []
+  return output_api.EnsureCQIncludeTrybotsAreAdded(
+    cl,
+    [
+      'luci.chromium.try:linux_chromium_rel_ng'
+    ],
+    'Automatically added layout test trybots to run tests on CQ.')

jni-test/app/CMakeLists.txt

@@ -0,0 +1,9 @@
+include_rules = [
+  "+libplatform/libplatform-export.h",
+]
+
+specific_include_rules = {
+  "libplatform\.h": [
+    "+libplatform/v8-tracing.h",
+  ],
+}

jni-test/app/build.gradle

@@ -0,0 +1,29 @@
+// Copyright 2016 the V8 project authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef V8_LIBPLATFORM_LIBPLATFORM_EXPORT_H_
+#define V8_LIBPLATFORM_LIBPLATFORM_EXPORT_H_
+
+#if defined(_WIN32)
+
+#ifdef BUILDING_V8_PLATFORM_SHARED
+#define V8_PLATFORM_EXPORT __declspec(dllexport)
+#elif USING_V8_PLATFORM_SHARED
+#define V8_PLATFORM_EXPORT __declspec(dllimport)
+#else
+#define V8_PLATFORM_EXPORT
+#endif  // BUILDING_V8_PLATFORM_SHARED
+
+#else  // defined(_WIN32)
+
+// Setup for Linux shared library export.
+#ifdef BUILDING_V8_PLATFORM_SHARED
+#define V8_PLATFORM_EXPORT __attribute__((visibility("default")))
+#else
+#define V8_PLATFORM_EXPORT
+#endif
+
+#endif  // defined(_WIN32)
+
+#endif  // V8_LIBPLATFORM_LIBPLATFORM_EXPORT_H_