From 32500f12c444536f2f73b08e678fc67175335cd9 Mon Sep 17 00:00:00 2001 From: Viktor Szakats Date: Mon, 16 Mar 2026 20:00:44 +0100 Subject: [PATCH] HTTP3.md: minor improvements - document building curl with CMake. - mention all supported forks in the OpenSSL section. Delete dedicated quictls section. - add TLS-backend pkgconfig dir to `PKG_CONFIG_PATH` for correctness. OpenSSL-based ones often work without this, by finding system `openssl.pc`. For GnuTLS and wolfSSL this has a lesser chance. Best to point to them explicitly. (configure may technically be able to do this automatically, but it isn't implemented.) - use `--with-ngtcp2=` again, where possible. GnuTLS is the exception, pending fix in #20910. Same for BoringSSL, but not documented in `HTTP3.md`. - replace `` with `/path/to/depname` for clarity. - move `LDFLAGS` after `./configure` for curl, to match dep builds. - move `--with-ngtcp2` next to the TLS-backend option. Follow-up to 1e3c2bec7eb735736755e15a48701f5b2d5b5979 #20926 Follow-up to 3c64ffaff4cd8c8275627dd2e17b6879a1d32262 #18415 #18188 Cherry-picked from #20920 Closes #20947 --- docs/HTTP3.md | 98 ++++++++++++++++++++------------------------------- 1 file changed, 39 insertions(+), 59 deletions(-) diff --git a/docs/HTTP3.md b/docs/HTTP3.md index 2086e11986..6f82d4200e 100644 --- a/docs/HTTP3.md +++ b/docs/HTTP3.md @@ -47,16 +47,16 @@ improvements. The build examples use `$NGHTTP3_VERSION` and `$NGTCP2_VERSION` as placeholders for the version you build. -## Build with OpenSSL +## Build with OpenSSL or fork -OpenSSL v3.5.0+ offers APIs for integration with *ngtcp2* v1.12.0+. Earlier -versions do not work. +OpenSSL v3.5.0+ requires *ngtcp2* v1.12.0+. Earlier versions do not work. -Build OpenSSL (version 3.5.0 or newer): +Build OpenSSL (v3.5.0+) or fork AWS-LC, BoringSSL, LibreSSL or quictls: + # Instructions for OpenSSL v3.5.0+ % git clone --depth 1 -b openssl-$OPENSSL_VERSION https://github.com/openssl/openssl % cd openssl - % ./config --prefix= --libdir=lib + % ./config --prefix=/path/to/openssl --libdir=lib % make % make install @@ -67,7 +67,7 @@ Build nghttp3: % cd nghttp3 % git submodule update --init % autoreconf -fi - % ./configure --prefix= --enable-lib-only + % ./configure --prefix=/path/to/nghttp3 --enable-lib-only % make % make install @@ -77,64 +77,28 @@ Build ngtcp2: % git clone -b $NGTCP2_VERSION https://github.com/ngtcp2/ngtcp2 % cd ngtcp2 % autoreconf -fi - % ./configure PKG_CONFIG_PATH=/lib/pkgconfig:/lib/pkgconfig LDFLAGS="-Wl,-rpath,/lib" --prefix= --enable-lib-only --with-openssl + # Change --with-openssl to --with-boringssl for AWS-LC and BoringSSL + % ./configure PKG_CONFIG_PATH=/path/to/openssl/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig LDFLAGS="-Wl,-rpath,/path/to/openssl/lib" --prefix=/path/to/ngtcp2 --enable-lib-only --with-openssl % make % make install -Build curl: +Build curl (with autotools): % cd .. % git clone https://github.com/curl/curl % cd curl % autoreconf -fi - % LDFLAGS="-Wl,-rpath,/lib" ./configure PKG_CONFIG_PATH=/lib/pkgconfig --with-openssl= --with-nghttp3= --with-ngtcp2 + % ./configure PKG_CONFIG_PATH=/path/to/openssl/lib/pkgconfig LDFLAGS="-Wl,-rpath,/path/to/openssl/lib" --with-openssl=/path/to/openssl --with-ngtcp2=/path/to/ngtcp2 --with-nghttp3=/path/to/nghttp3 % make % make install -## Build with quictls - -OpenSSL before version 3.5 does not offer the required APIs for building a -QUIC client. You need to use a TLS library that has such APIs and that works -with *ngtcp2*. - -Build quictls (any `+quic` tagged version works): - - % git clone --depth 1 -b openssl-3.1.4+quic https://github.com/quictls/openssl - % cd openssl - % ./config enable-tls1_3 --prefix= --libdir=lib - % make - % make install - -Build nghttp3: - - % cd .. - % git clone -b $NGHTTP3_VERSION https://github.com/ngtcp2/nghttp3 - % cd nghttp3 - % git submodule update --init - % autoreconf -fi - % ./configure --prefix= --enable-lib-only - % make - % make install - -Build ngtcp2: - - % cd .. - % git clone -b $NGTCP2_VERSION https://github.com/ngtcp2/ngtcp2 - % cd ngtcp2 - % autoreconf -fi - % ./configure PKG_CONFIG_PATH=/lib/pkgconfig:/lib/pkgconfig LDFLAGS="-Wl,-rpath,/lib" --prefix= --enable-lib-only - % make - % make install - -Build curl: +Build curl (with CMake): % cd .. % git clone https://github.com/curl/curl % cd curl - % autoreconf -fi - % LDFLAGS="-Wl,-rpath,/lib" ./configure PKG_CONFIG_PATH=/lib/pkgconfig --with-openssl= --with-nghttp3= --with-ngtcp2 - % make - % make install + % PKG_CONFIG_PATH=/path/to/openssl/lib/pkgconfig:/path/to/ngtcp2/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig cmake -B bld -DOPENSSL_ROOT_DIR=/path/to/openssl -DUSE_NGTCP2=ON + % cmake --build bld ## Build with GnuTLS @@ -143,7 +107,7 @@ Build GnuTLS: % git clone --depth 1 https://gitlab.com/gnutls/gnutls % cd gnutls % ./bootstrap - % ./configure --prefix= + % ./configure --prefix=/path/to/gnutls % make % make install @@ -154,7 +118,7 @@ Build nghttp3: % cd nghttp3 % git submodule update --init % autoreconf -fi - % ./configure --prefix= --enable-lib-only + % ./configure --prefix=/path/to/nghttp3 --enable-lib-only % make % make install @@ -164,20 +128,28 @@ Build ngtcp2: % git clone -b $NGTCP2_VERSION https://github.com/ngtcp2/ngtcp2 % cd ngtcp2 % autoreconf -fi - % ./configure PKG_CONFIG_PATH=/lib/pkgconfig:/lib/pkgconfig LDFLAGS="-Wl,-rpath,/lib" --prefix= --enable-lib-only --with-gnutls + % ./configure PKG_CONFIG_PATH=/path/to/gnutls/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig LDFLAGS="-Wl,-rpath,/path/to/gnutls/lib" --prefix=/path/to/ngtcp2 --enable-lib-only --with-gnutls % make % make install -Build curl: +Build curl (with autotools): % cd .. % git clone https://github.com/curl/curl % cd curl % autoreconf -fi - % ./configure PKG_CONFIG_PATH=/lib/pkgconfig --with-gnutls= --with-nghttp3= --with-ngtcp2 + % ./configure PKG_CONFIG_PATH=/path/to/gnutls/lib/pkgconfig:/path/to/ngtcp2/lib/pkgconfig --with-gnutls=/path/to/gnutls --with-ngtcp2 --with-nghttp3=/path/to/nghttp3 % make % make install +Build curl (with CMake): + + % cd .. + % git clone https://github.com/curl/curl + % cd curl + % PKG_CONFIG_PATH=/path/to/gnutls/lib/pkgconfig:/path/to/ngtcp2/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig cmake -B bld -DCURL_USE_GNUTLS=ON -DUSE_NGTCP2=ON + % cmake --build bld + ## Build with wolfSSL Build wolfSSL: @@ -185,7 +157,7 @@ Build wolfSSL: % git clone https://github.com/wolfSSL/wolfssl % cd wolfssl % autoreconf -fi - % ./configure --prefix= --enable-quic --enable-session-ticket --enable-earlydata --enable-psk --enable-harden --enable-altcertchains + % ./configure --prefix=/path/to/wolfssl --enable-quic --enable-session-ticket --enable-earlydata --enable-psk --enable-harden --enable-altcertchains % make % make install @@ -196,7 +168,7 @@ Build nghttp3: % cd nghttp3 % git submodule update --init % autoreconf -fi - % ./configure --prefix= --enable-lib-only + % ./configure --prefix=/path/to/nghttp3 --enable-lib-only % make % make install @@ -206,20 +178,28 @@ Build ngtcp2: % git clone -b $NGTCP2_VERSION https://github.com/ngtcp2/ngtcp2 % cd ngtcp2 % autoreconf -fi - % ./configure PKG_CONFIG_PATH=/lib/pkgconfig:/lib/pkgconfig LDFLAGS="-Wl,-rpath,/lib" --prefix= --enable-lib-only --with-wolfssl + % ./configure PKG_CONFIG_PATH=/path/to/wolfssl/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig LDFLAGS="-Wl,-rpath,/path/to/wolfssl/lib" --prefix=/path/to/ngtcp2 --enable-lib-only --with-wolfssl % make % make install -Build curl: +Build curl (with autotools): % cd .. % git clone https://github.com/curl/curl % cd curl % autoreconf -fi - % ./configure PKG_CONFIG_PATH=/lib/pkgconfig --with-wolfssl= --with-nghttp3= --with-ngtcp2 + % ./configure PKG_CONFIG_PATH=/path/to/wolfssl/lib/pkgconfig --with-wolfssl=/path/to/wolfssl --with-ngtcp2=/path/to/ngtcp2 --with-nghttp3=/path/to/nghttp3 % make % make install +Build curl (with CMake): + + % cd .. + % git clone https://github.com/curl/curl + % cd curl + % PKG_CONFIG_PATH=/path/to/wolfssl/lib/pkgconfig:/path/to/ngtcp2/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig cmake -B bld -DCURL_USE_WOLFSSL=ON -DUSE_NGTCP2=ON + % cmake --build bld + # quiche version quiche support is **EXPERIMENTAL**