Add build.ps1 support for external system OpenSSL 3.5+

CMakeLists.txt

@@ -118,6 +118,18 @@ set(QUIC_OPENSSL_LIB_DIR "" CACHE PATH "Path to OpenSSL library directory")
 set(QUIC_OPENSSL_SYMBOL_PREFIX "" CACHE STRING "If non-empty, namespace-prefix every symbol in the bundled OpenSSL static archives (Linux only) so the resulting binary can coexist in the same process with another OpenSSL copy. See docs/OpenSSLSymbolPrefix.md")
 set(QUIC_OPENSSL_ROOT_DIR "" CACHE PATH "Path to OpenSSL root directory")
 
+# QUIC_USE_EXTERNAL_OPENSSL skips the submodule build
+# entirely and dynamically links both libssl and libcrypto from the system, so
+# QUIC_USE_SYSTEM_LIBCRYPTO would be silently ignored. Reject the combination
+# loudly instead of letting it appear to take effect.
+if(QUIC_USE_EXTERNAL_OPENSSL AND QUIC_USE_SYSTEM_LIBCRYPTO)
+    message(FATAL_ERROR
+        "QUIC_USE_SYSTEM_LIBCRYPTO is incompatible with QUIC_USE_EXTERNAL_OPENSSL. "
+        "External OpenSSL already dynamically links both libssl and libcrypto from "
+        "the system; QUIC_USE_SYSTEM_LIBCRYPTO only applies to the bundled submodule "
+        "build. Set only one of them.")
+endif()
+
 # Outer-most validation for QUIC_OPENSSL_SYMBOL_PREFIX so a value combined with
 # a non-quictls/openssl TLS_LIB (e.g. schannel) errors loudly instead of being
 # silently ignored, and so the prefix value is rejected before it is

docs/BUILD.md

@@ -147,6 +147,15 @@ Supported only by Windows currently.
 
 `-Tls <schannel/openssl>` Allows for building with different TLS providers. The default is platform dependent (Windows = schannel, Linux = openssl).
 
+`-UseExternalOpenSSL` Links against an external/system OpenSSL (**3.5.0 or newer**) instead of building OpenSSL from the submodules. Only valid together with `-Tls openssl`. By default both `libssl` and `libcrypto` are dynamically linked from the system, so neither the `openssl` nor `quictls` submodule is required. If `-Static` is also specified, the external OpenSSL is linked statically instead (when the corresponding static libraries are available). If the system OpenSSL is older than 3.5.0 the build fails during CMake configuration with an "unsuitable version" error. When OpenSSL is installed outside the default system locations, add `-OpenSSLRootDir <path>` to point at it. For example, on a distro that ships OpenSSL 3.5+ (e.g. Ubuntu 26.04):
+
+```PowerShell
+./scripts/build.ps1 -Tls openssl -UseExternalOpenSSL
+```
+
+For finer-grained control (for example when the OpenSSL headers and libraries live in separate directories), invoke CMake directly with `-DQUIC_USE_EXTERNAL_OPENSSL=on` plus `-DQUIC_OPENSSL_INCLUDE_DIR=<path>` and `-DQUIC_OPENSSL_LIB_DIR=<path>`. The `build.ps1` helper intentionally exposes only the common `-OpenSSLRootDir` case.
+
+
 `-Clean` Forces a clean build of everything.
 
 For more info, take a look at the [build.ps1](../scripts/build.ps1) script.

scripts/build.ps1

@@ -93,6 +93,12 @@ This script provides helpers for building msquic.
 .PARAMETER UseSystemOpenSSLCrypto
     Use system provided OpenSSL crypto libraries. On Linux OpenSSL builds, both libssl and libcrypto are dynamically linked.
 
+.PARAMETER UseExternalOpenSSL
+    Link against an external/system OpenSSL (3.5.0+) instead of building OpenSSL from the submodules. Only valid with '-Tls openssl'. Both libssl and libcrypto are dynamically linked from the system.
+
+.PARAMETER OpenSSLRootDir
+    Path to the root directory of an external OpenSSL installation to use (implies -UseExternalOpenSSL). Passed to CMake as QUIC_OPENSSL_ROOT_DIR. Only needed when OpenSSL is not in a default system location. Only valid with '-Tls openssl'.
+
 .PARAMETER EnableHighResolutionTimers
     Configures the system to use high resolution timers.
 
@@ -216,6 +222,12 @@ param (
     [Parameter(Mandatory = $false)]
     [switch]$UseSystemOpenSSLCrypto = $false,
 
+    [Parameter(Mandatory = $false)]
+    [switch]$UseExternalOpenSSL = $false,
+
+    [Parameter(Mandatory = $false)]
+    [string]$OpenSSLRootDir = "",
+
     [Parameter(Mandatory = $false)]
     [switch]$EnableHighResolutionTimers = $false,
 
@@ -288,6 +300,17 @@ if ($Arch -eq "arm64ec") {
     }
 }
 
+# External OpenSSL selection is only supported by the 'openssl' TLS provider.
+$UseExternalOpenSSLRequested = $UseExternalOpenSSL -Or ($OpenSSLRootDir -ne "")
+if ($UseExternalOpenSSLRequested) {
+    if ($Tls -ne "openssl") {
+        Write-Error "External OpenSSL selection (-UseExternalOpenSSL/-OpenSSLRootDir) requires '-Tls openssl'. The 'quictls' provider must be built from submodules."
+    }
+    if ($UseSystemOpenSSLCrypto) {
+        Write-Error "-UseSystemOpenSSLCrypto is incompatible with external OpenSSL selection. External OpenSSL already dynamically links both libssl and libcrypto from the system; -UseSystemOpenSSLCrypto only applies to the bundled submodule build."
+    }
+}
+
 if ($Platform -eq "ios" -and !$Static) {
     $Static = $true
     Write-Host "iOS can only be built as static"
@@ -440,6 +463,13 @@ function CMake-Generate {
     $Arguments += " -DQUIC_TLS_LIB=" + $Tls
     $Arguments += " -DQUIC_OUTPUT_DIR=""$ArtifactsDir"""
 
+    if ($UseExternalOpenSSLRequested) {
+        $Arguments += " -DQUIC_USE_EXTERNAL_OPENSSL=on"
+        if ($OpenSSLRootDir -ne "") {
+            $Arguments += " -DQUIC_OPENSSL_ROOT_DIR=""$OpenSSLRootDir"""
+        }
+    }
+
     if (!$DisableLogs) {
         $Arguments += " -DQUIC_ENABLE_LOGGING=on"
     }