search

gradle / native-platform

Java bindings for various native APIs
Apache License 2.0
117 stars 38 forks source link
gradle-bt gradle-bt-core-runtime

readme

Native-platform: Java bindings for native APIs

A collection of cross-platform Java APIs for various native APIs. Currently supports OS X, Linux, Windows and FreeBSD on Intel architectures.

These APIs support Java 5 and later. Some of these APIs overlap with APIs available in later Java versions.

Available bindings

Terminal and console

These bindings work for the UNIX terminal, the Windows console and Mintty from Cygwin and MSys on Windows.

See Terminals

See Prompter

System information

See SystemInfo

Processes

See Process

File systems

See Files

See FileSystems

Windows registry

See WindowsRegistry

Supported platforms

Currently ported to OS X, Linux, FreeBSD and Windows. Support for Solaris is a work in progress. Supported on:

Using

Include native-platform.jar and native-platform-${os}-${arch}.jar in your classpath. From Gradle, you can do this:

repositories {
    jcenter()
}

dependencies {
    compile "net.rubygrapefruit:native-platform:0.21"
}

You can also download the Jars from bintray

A test application is also available from bintray

Some sample code to use the terminal:

import net.rubygrapefruit.platform.Native;
import net.rubygrapefruit.platform.terminal.Terminals;
import net.rubygrapefruit.platform.terminal.TerminalOutput;
import static net.rubygrapefruit.platform.terminal.Terminals.Output.*;

Terminals terminals = Native.get(Terminals.class);

// check if terminal
terminals.isTerminal(Stdout);

// use terminal
TerminalOutput stdout = terminals.getTerminal(Stdout);
stdout.bold();
System.out.println("bold text");

Changes

0.22 (unreleased)

0.21

0.20

0.19

0.18

0.17

0.16

0.15

0.14

0.13

0.12

0.11

0.10

0.9

You should avoid using this release, and use 0.10 or later instead.

0.8

0.7

0.6

You should avoid using this release, and use 0.7 or later instead.

0.5

0.4

0.3

0.2

0.1

Development

Building

This project uses (Gradle)[https://www.gradle.org] to build. Just run gradlew in the root of the source repo. You will need Java 8 or later to run the tests.

Ubuntu

The g++ compiler is required to build the native library. You will need to install the g++ package for this. Alternatively, you can use the Clang C++ compiler.

You need to install the libncurses5-dev package to pick up the ncurses header files. Also worth installing the ncurses-doc package too.

64-bit machines with multi-arch support

Where multi-arch support is available (e.g. recent Ubuntu releases), you can build the i386 and amd64 versions of the library on the same machine.

You need to install the gcc-multilib and g++-multilib packages to pick up i386 support.

You need to install the lib32ncurses5-dev package to pick up the ncurses i386 version.

Windows

You need to install Visual studio 2012 or later, plus the Windows SDK to allow you to build both x86 and x64 binaries.

OS X

The clang compiler is required to build the native library. You will need to install the XCode command-line tools for this.

Solaris

For Solaris 11, you need to install the development/gcc-45 and system/header packages.

Running

Run gradlew installDist to install the test application into test-app/build/install/native-platform-test. Or gradle distZip to create an application distribution in test-app/build/distributions/native-platform-test-$version.zip.

You can run $INSTALL_DIR/bin/native-platform-test to run the test application.

Testing integration with another project

When developing a new feature in native platform, you often want to test the features in a real-world project which uses native platform. There are various ways how to test the changes of native platform in the consuming project.

Use composite build on a developer machine

From the command line

From the checkout directory of the consuming project you can run:

./gradlew --include-build ../native-platform ...

This assumes that native-platform is checked out in ../native-platform relative to the consuming project.

From IDEA

In IDEA, open the consuming project. Then link the native-platform project. Finally, add the linked native-platform project as a participant to the Gradle build and sync the consuming project.

WARNING: You need to use IDEA 2020.1 for the composite build to work. See https://youtrack.jetbrains.com/issue/IDEA-228368 and https://youtrack.jetbrains.com/issue/IDEA-206799.

Use a published snapshot on a developer machine/CI

Use mavenLocal() on a developer machine

Releasing

See this issue first.

In the meantime, this TC job should be used to publish a milestone. Add a tag afterward.

To publish manually:

  1. Check the version number in build.gradle.
  2. Create a tag
  3. Build each variant.
    1. Checkout tag.
    2. ./gradlew clean :native-platform:test :native-platform:uploadJni -Prelease -PpublishUserName=<> -PpublishApiKey=<>.
  4. Build Java library:
    1. Checkout tag.
    2. ./gradlew clean :native-platform:test :native-platform:uploadMain -Prelease -PpublishUserName=<> -PpublishApiKey=<>
  5. Build the test app:
    1. Checkout tag.
    2. ./gradlew clean :test-app:uploadMain -Prelease -PpublishUserName=<> -PpublishApiKey=<>
  6. Publish on bintray
  7. Checkout master
  8. Increment version number in gradle.properties and this readme.
  9. Push changes.

Use -Pmilestone instead of -Prelease to publish a milestone version.

Testing

TODO

Fixes

Improvements

Ideas