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.
These bindings work for the UNIX terminal, the Windows console and Mintty from Cygwin and MSys on Windows.
- Determine whether stdin/stdout/stderr are attached to a terminal.
- Query the terminal size. Not supported for Mintty
- Change foreground color on the terminal.
- Switch between bold and normal text mode on the terminal.
- Switch between dim, bright and normal text intensity on the terminal.
- Move terminal cursor up, down, left, right, start of line.
- Clear to end of line.
- Show and hide the cursor.
- Read raw input from the terminal. Not support for Mintty.
- Read arrow keys and other function keys from the terminal. Not support for Mintty.
See Terminals
- Utility class to display various kinds of prompts to the user on the terminal.
See Prompter
- Query kernel name and version.
- Query machine architecture.
- Query hostname.
- Query total and available memory (OS X and Windows only).
- Query system commit total and limit (Windows only).
See SystemInfo
- Query the PID of the current process.
- Query and set the process working directory.
- Query and set the process environment variables.
- Detach process from its controlling console
See Process
- Query and set UNIX file mode.
- Create and read symbolic links on UNIX and Windows.
- Query UNIX file uid and gid.
- Query file type, size and timestamps.
- Query directory contents.
See Files
- List the available file systems on the machine and details of each file system.
- Query file system mount point.
- Query file system type.
- Query file system device name.
- Query whether a file system is local or remote.
- Query whether a file system is case-sensitive and case preserving.
See FileSystems
- Query registry value.
- Query the subkeys and values of a registry key.
See WindowsRegistry
Currently ported to OS X, Linux, FreeBSD and Windows. Support for Solaris is a work in progress. Supported on:
- OS X, version 10.13 and later (x86_64)
- Fedora 23 and later (amd64).
- Ubuntu 8.04 and later (amd64).
- Ubuntu 18.04 and later (aarch64).
- FreeBSD 10 and later (amd64).
- Windows XP and later (amd64, i386). Console integration works with cmd.exe, powershell, ConEmu, Mintty from Cygwin, Mintty from Msys (includes Git for Windows).
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");
- Remove support for 32bit Linux & FreeBSD, as well as support for FreeBSD < 10.
- Implement
Memoryand addWindowsMemoryfor Windows.
- Some preparation for a new API to watch the file system for changes.
- Removed
FileEventsAPI for watching the file system for changes.
- Added
SystemInfo. 8000 getHostname(). Thanks to Tom Dunstan - Fixed terminal integration on Arch linux.
- Fixed terminal integration on Amazon linux 2 aarch64.
- Support for symlinks on Windows. Thanks to Renaud Paquay.
- Fixed handling of long paths on Windows. Thanks to Renaud Paquay.
- Support for Linux on aarch64. Thanks to Amey.
- Fixed handling of supplementary characters in environment variable values. Thanks to Gary Hale.
- Added
TerminalInput.supportsRawMode()to determine whether terminal supports raw mode. - Improve
Prompterto show an alternate UI when the terminal input does not support raw mode.
- Change
Terminalsto support running under Mintty from Cygwin and MSYS on Windows. Supported for Windows 2008 and later.TerminalOutputis supported, howeverTerminalInputis not.
- Fixed
Files.stat()when the path points to a descendent of a file. Thanks to Gary Hale. - Renamed
TerminaltoTerminalOutput. - Moved some types to subpackages.
- Added
TerminalInputto read text from the terminal. Supports raw mode and arrow keys. - Added method to
Terminalsto determine whether stdin is attached to a terminal. - Added method to
Terminalsto force the use of ANSI escape sequences to write the terminal output. - Added methods to
TerminalOutputto show and hide the cursor. - Added methods to
TerminalOutputto set foreground text color to its default value. - Added methods to
TerminalOutputto set bright and dim foreground text intensity. - Added methods to
TerminalOutputto write text to the terminal. Anything written toSystem.outorSystem.erris no longer automatically flushed before cursor or text attributes are changed. - Added
Prompterutility class to display prompts on the terminal to ask the user various questions. - Moved releases to JCenter.
- Added
Memory, for OS X only. Thanks to Paul Merlin NativeIntegrationLinkageExceptionis thrown byNative.get()when a particular native library cannot be loaded due to a linkage error.
- Added overloads of
Files.stat()andFiles.listDir()that follow links. - Improvements to error handling for
Files.stat()andlistDir(). - Fixes for build time detection of ncurses 6. Thanks to Marcin Zajączkowski
- Added
Files.listDir(). - Fixes for terminal integration for Linux distributions that use ncurses 6, such as Fedora 24 and later.
- Fixes for running on FreeBSD 10 and later without requiring GCC to be installed on the machine.
- Added support to detach the current process from its controlling console. Thanks to Gary Hale.
- Fixes for handling Windows shares from Linux. Thanks to Thierry Guérin.
- Added initial implementation of
FileEvents, which allows an application to listen for changes to a file system directory. - Added more properties to
PosixFile. - Added
FilesandWindowsFiles. - Added
FileSystem.isCaseSensitive()andFileSystem.isCasePreserving(). - Fixes running under GCJ.
- Fixes for broken 0.9 release.
- Fixes for non-ascii file names on OS X when running under the Apple JVM.
You should avoid using this release, and use 0.10 or later instead.
- Ported to FreeBSD. Thanks to Zsolt Kúti.
- Some fixes for a broken 0.6 release.
- Some fixes for Windows 7 and OS X 10.6.
You should avoid using this release, and use 0.7 or later instead.
- Query the available values of a Windows registry key. Thanks to Michael Putters.
- Get file type.
- Query Windows registry value and subkeys.
- Fixes to work on 64-bit Windows XP.
- Get and set process working directory.
- Get and set process environment variables.
- Launch processes.
- Fixed character set issue on Linux and Mac OS X.
- Fixes to work with 64-bit OpenJDK 7 on Mac OS X. Thanks to Rene Groeschke.
- Fixes to make native library extraction multi-process safe.
- Fixes to windows terminal detection and reset.
- Initial release.
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.
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.
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.
You need to install Visual studio 2012 or later, plus the Windows SDK to allow you to build both x86 and x64 binaries.
The clang compiler is required to build the native library. You will need to install the XCode command-line tools for this.
For Solaris 11, you need to install the development/gcc-45 and system/header packages.
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.
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.
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.
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.
- Publish a snapshot from the branch you want to test by using this Teamcity build.
- Change the version of native platform in the consuming project to match the version you just published, e.g.
0.22-snapshot-20200128143135+0000, and push the changes to a branch. - Run some tests on CI on the branch of the consuming project you just pushed.
- Test what you want to test on the consuming project.
- Install a dev version of native platform to your local Maven repository by running
./gradlew publishToMavenLocal -PonlyLocalVariants
- Add
mavenLocal()as a repository in the consuming project. - Change the version of native platform in the consuming project to match the version you just built, e.g.
0.22-dev. - Test what you want to test on the consuming project.
See this issue first.
In the meantime, this TC job should be used to publish a milestone. Add a tag afterward.
To publish manually:
- Check the version number in
build.gradle. - Create a tag
- Build each variant.
- Checkout tag.
./gradlew clean :native-platform:test :native-platform:uploadJni -Prelease -PpublishUserName=<> -PpublishApiKey=<>.
- Build Java library:
- Checkout tag.
./gradlew clean :native-platform:test :native-platform:uploadMain -Prelease -PpublishUserName=<> -PpublishApiKey=<>
- Build the test app:
- Checkout tag.
./gradlew clean :test-app:uploadMain -Prelease -PpublishUserName=<> -PpublishApiKey=<>
- Publish on bintray
- Checkout master
- Increment version number in
gradle.propertiesand this readme. - Push changes.
Use -Pmilestone instead of -Prelease to publish a milestone version.
- Test on IBM JVM.
- Test on Java 5, 6, 7.
- Test on Windows 7, Windows XP
- OS X: Watch for changes to files in directory.
- FreeBSD: Watch for changes to files in directory.
- Linux: Fix spurious change event on close.
- All: Handle deletion and recreation of watched file/directory.
- All: Watch for creation and changes to missing file/directory.
- Windows: Watch for changes to a file (directory works, file does not).
- All:
FileWatchtests: file truncated, last modified changed, content changed, recreated as file/dir, file renamed - All: Thread safety for
FileWatch. - All: Bulk read of multiple file change events, coalesce events, use background thread to drain queue.
- Linux: Fix detection of multiarch support
- FreeBSD: Fix detection of multiarch support
- All:
Process.getPid()should return a long - All: fail subsequent calls to
Native.get()whenNative.initialize()fails. - Posix: allow terminal to be detected when ncurses cannot be loaded
- Windows: fix detection of shared drive under VMWare fusion and Windows XP
- Windows: restore std handles after launching child process
- Linux: detect remote filesystems.
- All: cache reflective lookup in native functions.
- Solaris: fix unicode file name handling.
- Solaris: fail for unsupported architecture.
- Solaris: build 32 bit and 64 bit libraries.
- All: fall back to WrapperProcessLauncher + DefaultProcessLauncher for all platforms, regardless of whether a native integration is available or not.
- All: change the terminal API to handle the fact that stdout/stderr/stdin can all be attached to the same or to different terminals.
- All: have
TerminalextendAppendableandFlushable - All: add a method to
Terminalthat returns aPrintStreamthat can be used to write to the terminal, regardless of whatSystem.outorSystem.errpoint to. - Windows: use
wchar_to_java()for system and file system info. - All: test network file systems
- Windows: test mount points
- All: cache class, method and field lookups
- Unix: change
readLink()implementation so that it does not need to NULL terminate the encoded content - All: don't use
NewStringUTF()anywhere - Mac: change
java_to_char()to convert java string directly to utf-8 char string. - Mac: change
char_to_java()to assume utf-8 encoding and convert directly to java string. - Linux: change
char_to_java()to useiconv()to convert from C char string to UTF-16 then to java string. - Windows: support for cygwin terminal input
- Solaris: use
TERM=xtermcinstead ofTERM=xterm. - All: add diagnostics for terminal.
- All: version each native interface separately.
- Windows: string names for errno values.
- All: split into multiple projects.
- Mac: use fully decomposed form for unicode file names on hfs+ filesystems.
- All: extend FileSystem to deal with removable media.
- Unix: add a Terminal implementation that uses ANSI control codes. Use this when TERM != 'dumb' and libncurses cannot be loaded.
- All: add a method to Terminal that indicates whether the cursor wraps to the next line when a character is written to the rightmost character position.
- All: check for null parameters.
- Normalise a unicode file name for a given file system (eg hfs+ uses fully decomposed form).
- Expose meta-data about an NTFS volume:
- Does the volume support 8.3 file names: Query FILE_FS_PERSISTENT_VOLUME_INFORMATION using DeviceIoControl()
- Expose native desktop notification services:
- OS X message center
- Growl
- Snarl
- dnotify
- Locate various system directories (eg program files on windows).
- Expose platform-specific HTTP proxy configuration. Query registry on windows to determine IE settings.
- Expose native named semaphores, mutexes and condition variables (CreateMutex, CreateSemaphore, CreateEvent, semget, sem_open, etc).
- Expose information about network interfaces.
- Windows networking: https://msdn.microsoft.com/en-us/library/windows/desktop/ee663286(v=vs.85).aspx
- Windows ip functions: https://msdn.microsoft.com/en-us/library/windows/desktop/aa366071(v=vs.85).aspx
- Windows notification on change: https://msdn.microsoft.com/en-us/library/windows/desktop/aa366329(v=vs.85).aspx
- Expose information about memory size and usage:
- Expose system monotonic clock, for timing:
- clock_gettime(CLOCK_MONOTONIC) on Linux
- mach_absolute_time() and mach_timebase_info() on OS X.
- Fire events when filesystems or network interfaces change in some way.
- Fire events when terminal size changes.
- Expose system keystores and authentication services.
- Expose a mechanism for generating a temporary directory.