compatibility.md.vm

# Compatibility Considerations

#[[##]]# Versioning and Update Policy

junixsocket versions consist of three parts: major, minor and patch (for example, 2.5.1).

"Minor version" updates (e.g., 2.4.0 -> 2.5.0) can still bring "major" new features but they
should be backwards compatible to releases of the same "major version" (e.g., 2.x).

The existing API should always be backwards compatible between minor releases (e.g., 2.4.0 -> 2.5.1)
unless explicitly mentioned in the changelog below (e.g., dropping Java 7 support in 2.5.0).

Bugs that are found in an older version (e.g., 2.6.1) may be fixed in a minor release (e.g., 2.7.0)
or a patch release (e.g., 2.6.2). There is no guarantee of a new patch release if there is a minor
release coming up (as a particular example, there won't be a 2.6.3 for bugs found in 2.6.2 and
earlier).

`-SNAPSHOT` builds are not considered releases, but merely previews of a future release.

If you have certain business reasons to not upgrade but still need something fixed, please
[ask for an enterprise support plan](mailto:christian@kohlschutter.com).

#[[##]]# Supported Java versions

junixsocket ${project.version} is fully compatible with Java 8 and newer (tested up to Java 24).

#[[##]]# Supported Java VMs

junixsocket has been tested to work with Oracle's Java 8 JDK, and OpenJDK (and its flavors, as well
as IBM Semeru) for newer versions, and other platform-specific VMs listed below. 

junixsocket also works with GraalVM (tested with *graalvm-ce-java17-22.2.0*) both in OpenJDK mode
and (since version 2.6.0, partially) in Native Image mode with Substrate VM.
More [details here](graalvm.html).

Since version 2.7.0, junixsocket runs on Android, too.

#[[##]]# Java 24 warnings

Java 24 introduced a warning when a library calls System.loadLibrary to load some native JNI code,
something like:

    WARNING: A restricted method in java.lang.System has been called
    WARNING: java.lang.System::loadLibrary has been called by org.newsclub.net.unix.NativeLibraryLoader$StandardLibraryCandidate in an unnamed module
    WARNING: Use --enable-native-access=ALL-UNNAMED to avoid a warning for callers in this module
    WARNING: Restricted methods will be blocked in a future release unless native access is enabled

For now, you can ignore this warning, but can also explicitly allow native access by adding a
corresponding `--enable-native-access=` statement when invoking your JVM that uses junixsocket.

If junixsocket is referenced by a modularized project, you could add
`--enable-native-access=org.newsclub.net.unix`. Otherwise (and this includes the selftest jar),
simplify specify `--enable-native-access=ALL-UNNAMED`

#[[##]]# Supported Platforms

The minimum set of supported (out of the box) platforms and processor architectures currently is:

* macOS Intel 64-bit
* macOS ARM 64-bit / Apple Silicon
* Linux x86_64
* Linux ARM 32-bit (armhf)
* Linux ARM 64-bit (aarch64)
* Linux s390x ("Linux on IBM Z", "Linux on zSystems")
* Linux RISC-V 64-bit (rv64ifd / lp64d)
* Linux ppc64le (POWER 64-bit Little Endian)
* Linux loongarch64 (Loongson 64-bit)
* Solaris x86 64-bit / OpenIndiana
* Windows 10 Intel 64-bit and ARM 64-bit
* Windows Server 2019
* Windows Server 2022
* FreeBSD (amd64)
* OpenBSD (amd64)
* NetBSD (amd64)
* DragonFlyBSD (amd64)
* IBM AIX 7 (POWER 64-bit)
* IBM i 7 (POWER 64-bit) via PASE
* Android (SDK version 26 or newer), aarch64/x86_64/i686/arm

Additional platforms known to work (after the JNI library has been compiled manually):

* Solaris SPARC64
* IBM z/OS OS/390 64-bit
* Haiku, recommended R1/beta5 or newer. AF_UNIX datagram support is available since Haiku hrev57155,
  but you should use hrev57200 or newer:
  - Thanks to junixsocket selftests, a bug related to socket addresses/connection state was found
    and [fixed in hrev57189](https://dev.haiku-os.org/ticket/18534).
  - A use-after-free bug in the kernel related to datagrams was found and
    [fixed in hrev57194](https://dev.haiku-os.org/ticket/18535).
  - An unexpected blocking situation was found and
    [fixed in hrev57200](https://dev.haiku-os.org/ticket/18539).

Additional platforms that should work (after the JNI library has been compiled manually):

* Any other processor architecture with Linux, FreeBSD, OpenBSD, NetBSD, DragonFlyBSD

Additional platforms known to compile (but untested):

* IBM z/TPF OS/390 with s390x-ibm-tpf-gcc version tpf-17r1-6
* Minix

#[[###]]# Remarks

Linux builds should be compatible with all major distributions, including the
ones using musl (e.g., Alpine Linux).

The native-common binaries for the above platforms are built on recent release versions of
either platform.

AIX support verified with IBM AIX 7.1 (7100-05-09), IBM AIX 7.2 (7200-05-03) and IBM AIX 7.3
(7300-00-01) on s922 and e980, using IBM J9 VMs (Java 8 and Java 11).

IBM i support verified with 7.1 (IBM i 7R1 / 71-11-2984-4), 7.2 (IBM i 7R2 / 72-09-2984-5),
7.3 (IBM i 7R3 / 73-07-001), 7.4 (IBM i 7R4 / 74-05-2984-1) on s922 and e980, using IBM J9 64-bit
VMs (Java 8, and Java 11 where available).

IBM z/OS is supported, but you have to compile junixsocket-native from source with XLC.
Alternatively, a binary build may be [requested here])(mailto:christian@kohlschutter.com?subject=junixsocket+z%2FOS+binary). Verified with
z/OS V2.4 and Java 8 SR8.

IBM z/TPF is potentially supported (it compiles with s390x-ibm-tpf-gcc version tpf-17r1-6), but it
hasn't been tested yet. If you would like to help test it, you may [request it here])(mailto:christian@kohlschutter.com?subject=junixsocket+z%2FTPF+binary).

Intel x86 32-bit and ARM 32-bit are supported, but binaries are not included by default. Please file
an issue if you think that's a bad idea.

Support for [custom architectures](customarch.html) can be added by compiling a custom native binary
on the target machine, or by [cross-compiling](crosscomp.html) using clang/LLVM on a suitable host.

#[[##]]# Marginally supported platforms

The following platforms can successfully load the JNI library, but since they do not provide
support for AF_UNIX, the functionality is currently too limited to call these platforms "supported":

* Windows 8.1 64-bit
* Windows 10 before build 17061
* OSv Unikernel (tested with v0.56 on qemu and firecracker); socketpair works.

This classification may change with the addition of new features beyond Unix domain sockets.
Please reach out if you have some feature in mind that may be supported on these platforms.

#[[##]]# Additional Platforms and Architectures

Upon request, support for additional systems, platforms and architectures may be added,
such as OpenVMS, FUJITSU BS2000/OSD, Unisys ClearPath OS 2200, QNX, VxWorks, HP-UX,
Guardian / NonStop OSS, WebAssembly WASI, etc.

If you are interested in using junixsocket on another platform, or willing to sponsor development
(by providing access to such platforms, covering licensing costs, etc.), feel free to
[file a ticket](https://github.com/kohlschutter/junixsocket/issues/new/choose)
or [contact Christian Kohlschütter via email](mailto:christian@kohlschutter.com).

#[[##]]# Selftest

A reliable way to ensure that junixsocket works in your environment is to run the "[selftest](selftest.html)".

    java -jar junixsocket-selftest-${project.version}-jar-with-dependencies.jar

The last line should say "Selftest PASSED" (or "Selftest PASSED WITH ISSUES"), then you're good to go.

If not, please [file a bug report](https://github.com/kohlschutter/junixsocket/issues) with the
output of the selftest.

> **NOTE:** If your target platform supports both 32-bit and 64-bit Java VMs, make sure to use the
64-bit version first.

For Android, there is a custom selftest app, `junixsocket-selftest-android`, which can be built
with Android Studio, for example.

#[[##]]# Workarounds/testing for broken setups

There is a chance that something is subtly wrong with the combination of junixsocket and your system.

To completely disable junixsocket (as if you were on a system for which no native library is available),
you can set the following System property: 

    -Dorg.newsclub.net.unix.library.disable=true
  
To selectively disable a junixsocket capability, you can specify a System property as follows:

    -Dorg.newsclub.net.unix.library.disable.CAPABILITY_XYZ=true
  
For example, in order to disable the support for passing file descriptors via ancillary messages,
specify:

    -Dorg.newsclub.net.unix.library.disable.CAPABILITY_FILE_DESCRIPTORS=true

The set of available capabilities is enumerated in the [AFSocketCapability](https://kohlschutter.github.io/junixsocket/apidocs/org.newsclub.net.unix/org/newsclub/net/unix/AFSocketCapability.html) enum.

#[[##]]# Bugs in other systems

If you're curious about bugs in other systems we could find thanks to junixsocket, take a look
[here](otherbugs.html).