From: Daniel McCarney <daniel@binaryparadox.net>
Date: Sun, 16 Mar 2025 16:38:24 +0000 (-0400)
Subject: docs: rework RUSTLS install instructions
X-Git-Tag: curl-8_13_0~56
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=14761d8b61a3377655105d738f5cda2379eb7d82;p=thirdparty%2Fcurl.git

docs: rework RUSTLS install instructions

Describes using a package manager or pre-built binaries and adopts the
0.15 installation from source instructions.

Previously the rustls docs described installing rustls-ffi from source
using the GNU Makefile. The upstream project has switched to using
cargo-c as a cross-platform solution that works well with the rust
toolchain, pkg-config, and Windows and so this needs an update.

Similarly, for folks that want to avoid the extra cargo-c tool
requirement, rustls-ffi provides binary releases for common platforms,
and some Linux distributions/package managers offer pre-built packages.

The install instructions are expanded to cover these options since
they're generally better for end users than building the dep. from
source (no `rustc` required).
---

diff --git a/.github/scripts/spellcheck.words b/.github/scripts/spellcheck.words
index d0eda71016..deb68d6cff 100644
--- a/.github/scripts/spellcheck.words
+++ b/.github/scripts/spellcheck.words
@@ -722,6 +722,7 @@ Ruslan
 rustc
 Rustls
 rustls
+rustup
 Sagula
 SanDisk
 SAS
diff --git a/docs/RUSTLS.md b/docs/RUSTLS.md
index 55c7260548..e46e1d8025 100644
--- a/docs/RUSTLS.md
+++ b/docs/RUSTLS.md
@@ -9,20 +9,65 @@ SPDX-License-Identifier: curl
 [Rustls is a TLS backend written in Rust](https://docs.rs/rustls/). curl can
 be built to use it as an alternative to OpenSSL or other TLS backends. We use
 the [rustls-ffi C bindings](https://github.com/rustls/rustls-ffi/). This
-version of curl is compatible with `rustls-ffi` v0.14.x.
+version of curl is compatible with `rustls-ffi` v0.15.x.
 
-# Building with Rustls
+## Getting rustls-ffi
 
-First, [install Rust](https://rustup.rs/).
+To build `curl` with `rustls` support you need to have `rustls-ffi` available first.
+There are three options for this:
 
-Next, check out, build, and install the appropriate version of rustls-ffi:
+1. Install it from your package manager, if available.
+2. Download pre-built binaries.
+3. Build it from source.
 
-    % git clone https://github.com/rustls/rustls-ffi -b v0.14.1
-    % cd rustls-ffi
+### Installing rustls-ffi from a package manager
+
+See the [rustls-ffi README] for packaging status. Availability and details for installation
+differ between distributions.
+
+Once installed, build `curl` using `--with-rustls`.
+
+    % git clone https://github.com/curl/curl
+    % cd curl
+    % autoreconf -fi
+    % ./configure --with-rustls
     % make
-    % make DESTDIR=${HOME}/rustls-ffi-built/ install
 
-Now configure and build curl with Rustls:
+[rustls-ffi README]: https://github.com/rustls/rustls-ffi?tab=readme-ov-file
+
+### Downloading pre-built rustls-ffi binaries
+
+Pre-built binaries are available on the [releases page] on GitHub for releases since 0.15.0.
+Download the appropriate archive for your platform and extract it to a directory of your choice
+(e.g. `${HOME}/rustls-ffi-built`).
+
+Once downloaded, build `curl` using `--with-rustls` and the path to the extracted binaries.
+
+    % git clone https://github.com/curl/curl
+    % cd curl
+    % autoreconf -fi
+    % ./configure --with-rustls=${HOME}/rustls-ffi-built
+    % make
+
+[releases page]: https://github.com/rustls/rustls-ffi/releases
+
+### Building rustls-ffi from source
+
+Building `rustls-ffi` from source requires both a rust compiler, and the [cargo-c] cargo plugin.
+
+To install a Rust compiler, use [rustup] or your package manager to install
+the **1.73+** or newer toolchain.
+
+To install `cargo-c`, use your [package manager][cargo-c pkg], download
+[a pre-built archive][cargo-c prebuilt], or build it from source with `cargo install cargo-c`.
+
+Next, check out, build, and install the appropriate version of `rustls-ffi` using `cargo`:
+
+    % git clone https://github.com/rustls/rustls-ffi -b v0.15.0
+    % cd rustls-ffi
+    % cargo capi install --release --prefix=${HOME}/rustls-ffi-built
+
+Now configure and build `curl` using `--with-rustls`:
 
     % git clone https://github.com/curl/curl
     % cd curl
@@ -30,7 +75,11 @@ Now configure and build curl with Rustls:
     % ./configure --with-rustls=${HOME}/rustls-ffi-built
     % make
 
-See the [rustls-ffi README] for more information on cryptography providers and
+See the [rustls-ffi README][cryptography provider] for more information on cryptography providers and
 their build/platform requirements.
 
-[rustls-ffi README]: https://github.com/rustls/rustls-ffi/blob/main/README.md#cryptography-provide
+[cargo-c]: https://github.com/lu-zero/cargo-c
+[rustup]: https://rustup.rs/
+[cargo-c pkg]: https://github.com/lu-zero/cargo-c?tab=readme-ov-file#availability
+[cargo-c prebuilt]: https://github.com/lu-zero/cargo-c/releases
+[cryptography provider]: https://github.com/cpu/rustls-ffi?tab=readme-ov-file#cryptography-provider