native/README.md

@@ -1,31 +1,55 @@
 # velocity-natives
 
-This directory contains native acceleration code for Velocity, along with
-traditional Java fallbacks.
+This directory contains native acceleration code for Velocity, along with traditional Java fallbacks.
 
-## Compression
+Compression is based on the `libdeflate` library, which is wire-compatible with zlib but significantly faster.
 
-* **Supported platforms**: Linux x86_64 and aarch64, with Java 11 `ByteBuffer` API support as a fallback.
-  Compiled on CentOS 7.
-* **Rationale**: Using a native zlib wrapper, we can avoid multiple trips into Java just to copy memory around.
+Encryption is based on OpenSSL for Linux, which is the most widely-used encryption library in the world.
+OpenSSL has had several different ABIs over the years, so we provide multiple versions of the native
+library. Currently we compile against OpenSSL 1.1.x and OpenSSL 3.x.x. For macOS, we use the built-in
+CommonCrypto library.
 
-## Encryption
+## Supported Platforms
 
-* **Supported platforms**: Linux x86_64 (OpenSSL 1.0.x and OpenSSL 1.1.x) and aarch64 (OpenSSL 1.1.x only)
-* **Rationale**: Using a C library for encryption means we can limit memory copies. Prior to Java 7, this was the only
-  way to use AES-NI extensions on modern processors, but this is less important since JDK 8 has native support.
-* OpenSSL is not included in Velocity. Every distribution provides it now. To deal with ABI incompatibilities,
-  the native library (which only calls into OpenSSL and contains no cryptographic code) are available for
-  CentOS 7 (OpenSSL 1.0.0-based), Debian 9 (OpenSSL 1.1.0-based) and Debian Bookworm (OpenSSL 3.0.0-based) 
-  to provide the widest, most reasonable compatibility with most modern distributions.
+`velocity-natives` is built for the following platforms:
 
-## OS support
+- Linux x86_64
+- Linux aarch64
+- macOS aarch64 ("Apple Silicon")
 
-The natives intend to have the widest possible range of compatibility with modern Linux distributions
-(defined as those being released in or after 2014).
+For Linux platforms, we provide two versions of the native library: one built against OpenSSL 1.1.x and one built against OpenSSL 3.x.x.
+All native libraries are built on various versions of Ubuntu:
 
-In theory, these libraries can be compiled for any Unix-like system (in the past, we supported macOS),
-but interest in other systems is minimal at best, thus we focus on Linux x86_64 and aarch64 as they
-are commonly used platforms.
+- Ubuntu 20.04 for OpenSSL 1.1.x support and for compression
+- Ubuntu 22.04 for OpenSSL 3.x.x support
 
-Alpine Linux support is on a "best-effort" basis only. Using `apk add libc6-compat` may enable native support.
+Currently, we do not provide native libraries for distributions based on musl libc, like Alpine Linux. You might be able to use `apk add libc6-compat` to fake it, but this is not officially supported.
+In the future we may provide a musl libc build.
+
+## Building
+
+### On Linux
+
+To build the native libraries, you need to have Docker installed and have it set up to perform [multi-platform builds](https://docs.docker.com/build/building/multi-platform/). Then, run the following command:
+
+```bash
+./build-support/build-all-linux-natives.sh
+```
+
+This will build the native libraries for both OpenSSL 1.1.x and OpenSSL 3.x.x on both x86_64 and aarch64.
+
+### On macOS
+
+To build the native libraries on macOS, you need to have `cmake` installed. You can install it using Homebrew:
+
+```bash
+brew install cmake
+```
+
+Then, run the following command:
+
+```bash
+./build-support/compile-macos.sh
+```
+
+This will build the native libraries for macOS aarch64. x86_64 has not been tested, but it should work.