Skip to content

Latest commit

 

History

History
250 lines (195 loc) · 8.91 KB

BUILDING.md

File metadata and controls

250 lines (195 loc) · 8.91 KB
Raw

Getting started / building from source

  1. clone the source code from the forked J2V8 GitHub repository
  2. run j2v8-cli.cmd (on Win32) or source j2v8-cli.sh on MacOS / Linux
  3. TYR git clone https://github.com/jvuesource/node.git --config core.autocrlf=false --depth 1 --branch v7.4.0
    OR
    nodejs git clone to clone the Node.js/V8 source code
  4. !!! THIS STEP IS NO NEED FOR jvuesource NODE VERSION !!!
    do nothing
    OR
    nodejs diff apply to apply the required modifications to the Node.js source code
  5. start the desired J2V8 build either via build -i
    OR
    build ...args (see below for details)

Build-System CLI

Interactive

build --i, --interactive
# or
python build.py --i, --interactive

entering interactive mode...

[0] android-x86 @ Docker
[1] android-arm @ Docker
[2] alpine-linux-x64 @ Docker
[3] linux-x64
[4] linux-x64 @ Docker
[5] linux-x86 @ Docker
[6] macosx-x64
[7] macosx-x64 @ Vagrant
[8] macosx-x86 @ Vagrant
[9] windows-x64
[10] windows-x64 @ Docker
[11] windows-x64 @ Vagrant

Select a predefined build-configuration to run: 3
Building: linux-x64

Override build-steps ? (leave empty to run pre-configured steps): nodejs j2v8 test

Non-interactive

build -h, --help
# or
python build.py -h, --help

usage: build [-h] --target {android,linux,macos,win32} --arch {x86,x64,arm}
             [--vendor VENDOR] [--keep-native-libs] [--node-enabled]
             [--docker] [--vagrant] [--sys-image SYS_IMAGE] [--no-shutdown]
             [--redirect-stdout] [--interactive]
             [build-steps [build-steps ...]]

Basic Examples

Build for Debian/Ubuntu Linux x64 on the host-system:
build -t linux -a x64

Build for Debian/Ubuntu Linux x64 using Docker:
build -t linux -a x64 -dkr

Build for Alpine-Linux x64 using Docker and Node.js features included:
build -v alpine -t linux -a x64 -dkr -ne

Build for MacOSX x64 using Vagrant excluding Node.js features:
build -t macos -a x64 -vgr

Build for Windows x64 directly on the host-system, Node.js features included:
build -t win32 -a x64 -ne

Build-Step syntax

If no build-steps are specified, then the CLI will run all available build-steps by default. To see a list of available build-steps run build --help or see the Build-Steps section below.

For ease of use, there are also some advanced build-step aliases that when specified will run a collection of some of the base-steps:

  • all ... is the default, and will run all known build-steps
  • native ... will run only the build-steps that are relevant for building native artifacts
    • node_js, j2v8_cmake, j2v8_jni, j2v8_cpp, j2v8_optimize
  • j2v8 ... runs all build-steps, except for nodejs and j2v8test
  • java ... alias for the single j2v8java step
  • test ... alias for the single j2v8test step

Anti-Steps

Anti-steps provide a way to exclude a particular step, or a step-alias from the set of build-steps that should be run. To use such an anti-step, just prefix any of the available build-steps with the "~" symbol.

Build everything but do not optimize and do not run J2V8 unit tests:
build <...other-args> all ~j2v8optimize ~test

Build only the Java parts and also run tests:
build <...other-args> all ~native

Step-Arguments

For some of the build-steps, you can pass additional command-line parameters that will be added as arguments when the CLI build-tool of this particular build-step is run.

Run the j2v8test step with additional args that will be passed to maven:
(e.g. run only the LibraryLoaderTest)
build -t linux -a x64 --j2v8test="-Dtest=LibraryLoaderTest"

Build-Steps

The J2V8 build-system performs several build steps in a fixed order to produce the final J2V8 packages for usage on the designated target platforms. What follows is a short summary for what each of the executed build-steps does and what output artifacts are produced by each step.

Node.js --> CMake --> JNI --> C++ --> Optimize --> Java/Android Build --> Java/Android Test

Node.js

CLI name: nodejs

Builds the Node.js & V8 dependency artifacts that are later linked into the J2V8 native bridge code. (only works if the Node.js source was checked out into the J2V8 ./node directory)

Inputs:

  • Node.js source code
  • Node.js GIT patches with customizations for integrating Node.js into J2V8
    • ./node.patches/*.diff

Artifacts:

  • Node.js & V8 static link libraries
    • ./node/out/
    • win32 specific
      • ./node/build/
      • ./node/Debug/
      • ./node/Release/

CMake

CLI name: j2v8cmake

Uses CMake to generate the native Makefiles / IDE project files to later build the J2V8 C++ native bridge shared libraries.

Inputs:

  • Node.js / V8 static link libraries
    • ./cmake/NodeJsUtils.cmake
  • CMakeLists & CMake utilities
    • CMakeLists.txt
    • ./cmake/*.cmake

Artifacts:

  • CMake generated Makefiles / IDE Project-files
    • ./cmake.out/{platform}.{architecture}/

JNI Header Generation

CLI name: j2v8jni

Generate the JNI glue header file from the native method definitions of the Java V8 class.

Inputs:

  • Java V8.class file
    • ./target/classes/com/eclipsesource/v8/V8.class

Artifacts:

  • J2V8 C++ JNI header file
    • ./jni/com_eclipsesource_v8_V8Impl.h

C++

CLI name: j2v8cpp

Compile and link the J2V8 native shared libraries (.so/.dylib/.dll), which contain the C++ JNI bridge code to interop with the embedded Node.js / V8 parts.

Inputs:

  • CMake generated Makefiles / IDE Project-files
  • Node.js / V8 static link libraries & C++ header files
  • J2V8 C++ JNI source code
    • ./jni/com_eclipsesource_v8_V8Impl.h
    • ./jni/com_eclipsesource_v8_V8Impl.cpp

Artifacts:

  • J2V8 native shared libraries
    • ./cmake.out/{platform}.{architecture}/libj2v8-[vendor-]{platform}-{abi}.{ext}
    • e.g. ./cmake.out/linux.x64/libj2v8-alpine-linux-x86_64.so

Optimize

CLI name: j2v8optimize

The native J2V8 libraries are optimized for performance and/or filesize by using the available tools of the target-platform / compiler-toolchain.

Inputs:

  • unoptimized J2V8 native shared libraries
    • ./cmake.out/{platform}.{architecture}/libj2v8-[vendor-]{platform}-{abi}.{ext}
    • e.g. ./cmake.out/linux.x64/libj2v8-alpine-linux-x86_64.so
  • platform-specific optimization tools:
    • Android: -
    • Linux: execstack, strip
    • MacOSX: -
    • Windows: -

Artifacts:

  • optimized J2V8 native shared libraries
    • ./cmake.out/{platform}.{architecture}/libj2v8-[vendor-]{platform}-{abi}.{ext}
    • e.g. ./cmake.out/linux.x64/libj2v8-alpine-linux-x86_64.so

Java / Android

CLI name: j2v8java / java

Compiles the Java source code and packages it, including the previously built native libraries, into the final package artifacts. For the execution of this build-step Maven (Java) or Gradle (Android) are used for the respective target platforms.

Inputs:

  • J2V8 native shared libraries (will be automatically copied to the required Java / Android project directories to be included in the .jar/.aar packages)
    • ./src/main/resources/ (Java)
    • ./src/main/jniLibs/{abi}/libj2v8.so (Android)
  • J2V8 Java source code
    • ./src/main/
  • J2V8 Java test source code
    • ./src/test/
  • J2V8 build settings
    • ./build_settings.py

Artifacts:

  • Maven platform-specific packages
    • ./build.out/j2v8_{platform}_{abi}-{j2v8_version}.jar
    • e.g. ./build.out/j2v8_linux_x86_64-4.8.0-SNAPSHOT.jar
  • Gradle Android packages
    • ./build/outputs/aar/j2v8-release.aar

Java Tests

CLI name: j2v8test / test

Runs the Java (JUnit) unit tests.

Inputs:

  • J2V8 platform-specific packages
  • J2V8 Java test source code
    • ./src/test/

Artifacts:

  • Maven Surefire test reports (Desktop platforms)
    • ./target/surefire-reports/
  • Gradle Spoon test reports (Android only)
    • ./build/spoon/debug/

Cross-Compiling

For cross-compiling J2V8 uses Docker (android, linux, windows) and Vagrant (macos, windows). The full source-code (of both J2V8 and Node.js) on the build-host are just shared via mounted volumes with the Docker / Vagrant machines, so you can quickly make changes and perform builds fast.

To invoke a cross-compile build, simply invoke the build.py script as usual but add the --docker, -dkr or --vagrant, -vgr flags. This will automatically provision and run the necessary virtualization to run the requested build fully independent of your local environment.

Note: using Docker / Vagrant for cross-compilation requires many gigabytes of hard-drive space as well as downloading the required images & tools.