cmke: add *_USE_STATIC_LIBS options for 9 dependencies

[vszakats]

Via options:

• BROTLI_USE_STATIC_LIBS
• CARES_USE_STATIC_LIBS
• LIBSSH_USE_STATIC_LIBS
• LIBSSH2_USE_STATIC_LIBS
• MBEDTLS_USE_STATIC_LIBS
• NGHTTP2_USE_STATIC_LIBS
• NGHTTP3_USE_STATIC_LIBS
• NGTCP2_USE_STATIC_LIBS
• ZSTD_USE_STATIC_LIBS

When enabled, make a "best effort" finding static libs first and set
the "build static" macro (on Windows) as required by the dependency.

When doing pkg-config-based detections, make curl select the static
configuration, which shall set the "build static" macro also.

These options resemble CMake's OPENSSL_USE_STATIC_LIBS and
ZLIB_USE_STATIC_LIBS (the latter does not support pkg-config as of
CMake v4.2.2).

Shared/static library selection based on loose filename conventions is
fragile and prone to break if the non-static-suffixed library is found
and happens to be a shared library, or, if the linker decides to pick up
a shared copy (e.g. .a.dll) that shadows the static one. It may help
to provide either static or shared, but not both, on the disk, and match
that with this setting.

Experimental.

Ref: #20013

---

https://github.com/curl/curl/pull/20015/files?w=1

• potentially extend to brotli, libssh2, mbedtls, zstd. These may
  have static-suffix lib names, but have no (AFAIK) macro to set.
• possibly limit existing static-only system lib dependencies to the *_USE_STATIC_LIBS option.
  This may potentially be breaking, though technically the accurate thing to do. (in c-ares, libssh, wolfSSL, Rustls, librtmp)
  [SKIP, let's rather overlink than underlink]
• maybe add a global option to enable this option for all deps? That seems closer to how this is actually used in practice. It also makes it easier to document. → NO, until we know it's solving a real problem.
• perhaps extend to all deps, for the pkg-config track? [FUTURE]
• once/if added to all deps, maybe document it just once in INSTALL-CMAKE.md.
  Skip for now. Not all dependencies have this. (Those that have no clear
  distinct name for static libs (or I couldn't spot it), don't.)
• allow setting a custom static suffix via -D*_USE_STATIC_LIBS=_mystatic? (some deps support it out of the box) → Looks like a lot of complication to address niche cases. For customization it's simpler to just point to the exact library name via <name>_LIBRARY. Skip this.
• pick <name>_STATIC_<var> variables returned by pkg-config
  when this option is set.
• possibly prefix the config name with CURL_ to stay within the
  namespace. (that ship had sailed? maybe fix it in future for all, otherwise
  these new vars would confusingly be misaligned with the existing ones.)
• replace COMPILE_DEFINITIONS with CFLAGS and limit it for non-pkg-config track. pkg-config already does that via the STATIC options, and shall do it more accurately.

[jay]

I don't think this is our responsibility and (like anything else) it adds to maintenance.

Something like below may? work, at least on Windows. I don't think you can or would want static glibc

CPPFLAGS="-DNGHTTP2_STATICLIB" LDFLAGS="-static" PKG_CONFIG="pkg-config --static" ./configure ...

[vszakats]

I don't think this is our responsibility and (like anything else) it adds to maintenance.

In this case my doubt is if this would actually help people trying
to build statically, to justify the tiny maintenance it needs. I already
deal with half of this in curl-for-win anyway, and this stuff rarely
changes.

edit: after extending it to pkg-config and more deps, the maintenance
angle is more relevant. Though this may be justified if this is actually
useful.

Hence marked experimental, so if it causes more problems, or
doesn't seem to help anyone, we can back off from it.

[ An aside I find insteresting is that some libs do not require the annoying
"build static" macro (including libssh2, which I'm familiar with).
libssh2 requires the opposite, which is somehow working out more
smoothly when consuming the lib. The declspec thing is one of
the many Windows decisions that keep haunting and puzzling decades in. ]

Something like below may? work, at least on Windows. I don't think you can or would want static glibc

CPPFLAGS="-DNGHTTP2_STATICLIB" LDFLAGS="-static" PKG_CONFIG="pkg-config --static" ./configure ...

How to choose static with the pkg-config integrated to CMake,
I haven't looked closely yet. It could be picking the static lib name,
extra lib deps, and adding the macro when necessary. This is
little bit more than this patch does for the non-pkg-config path, and yes,
both still miss the other half of the problem, aka telling the linker to
pick the static lib if both flavors exist on disk, and do that on a
per-lib-basis, not with a global -static which may break other things.

(enclosing each lib in -Wl,-Bstatic / -Wl,-Bdynamic could help
(but can break the global default), but getting little exposure. There
is a rarer, per-lib, solution, which I can't recall ATM, oops.)

edit: it's -l:<name>, but still can't recally its drawbacks and why
it remains almost unknown and unused.

On a quick look, even the oldest CMake version supported now, loads
--static results into <name>_STATIC_<var> variables, so these
curl options may be able to use them, with more added logic of course.

The issue remains that it's ultimately the linker what decides what gets
actually linked.

[Copilot]

Pull request overview

This PR adds *_USE_STATIC_LIBS options for several CMake Find modules (brotli, c-ares, libssh, libssh2, mbedtls, nghttp2, nghttp3, ngtcp2, zstd) to enable "best effort" detection and configuration of static libraries. The implementation attempts to find static library variants by checking for static-suffixed library names first, and sets appropriate compile-time macros when required by the dependency (similar to existing OPENSSL_USE_STATIC_LIBS and ZLIB_USE_STATIC_LIBS options).

• Adds new *_USE_STATIC_LIBS CMake input variables for 9 dependencies
• Modifies each Find module to prioritize static library variants when the option is set
• Sets required *_STATICLIB compile definitions for libraries that need them (c-ares, libssh, nghttp2, nghttp3, ngtcp2)
• Updates pkg-config integration to use STATIC_* variables when static libs are requested

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/INSTALL-CMAKE.md	Documents the new *_USE_STATIC_LIBS options for each affected dependency
CMake/FindZstd.cmake	Adds ZSTD_USE_STATIC_LIBS option with static library name variants and pkg-config static variable support
CMake/FindNGTCP2.cmake	Adds NGTCP2_USE_STATIC_LIBS option, sets -DNGTCP2_STATICLIB macro, searches for static library variants
CMake/FindNGHTTP3.cmake	Adds NGHTTP3_USE_STATIC_LIBS option, sets -DNGHTTP3_STATICLIB macro, searches for static library variants
CMake/FindNGHTTP2.cmake	Adds NGHTTP2_USE_STATIC_LIBS option, sets -DNGHTTP2_STATICLIB macro, reorders library search to prioritize static variants
CMake/FindMbedTLS.cmake	Adds MBEDTLS_USE_STATIC_LIBS option with static library name variants for all three mbedTLS libraries
CMake/FindLibssh2.cmake	Adds LIBSSH2_USE_STATIC_LIBS option with static library name variants
CMake/FindLibssh.cmake	Adds LIBSSH_USE_STATIC_LIBS option, sets -DLIBSSH_STATIC macro, searches for static library variants
CMake/FindCares.cmake	Adds CARES_USE_STATIC_LIBS option, sets -DCARES_STATICLIB macro, searches for static library variants
CMake/FindBrotli.cmake	Adds BROTLI_USE_STATIC_LIBS option with static library name variants for both brotli libraries

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[vszakats]

I'm still on the fence with this one. The maintenance burden is IMO
manageable at 10-12 lines of fairly trivial code per dependency,
which I expect to rarely change.

We've seen requests, reports and PRs to this intended effect, but
it's hard to say if this change would actually work in practice, in
actual use-cases. If it does, it's useful, but if it doesn't, it's just
extra weight to carry.

My impression during the last few decades is that the
static/shared-lib-selection "story" is a use-case that sees no love
from platforms, toolchains and build tools alike. It's an afterthought,
leaving this to chance or as a puzzle to solve build-case by
build-case. Short of toolchain support to tell ones shared/static
lib preference on a per-lib basis, I found best not to have both
shared and static lib for the same dependency next to each other
on the disk. In which case this PR has a chance to help to setup
the necessary macro and pull in lib dependencies, assuming
the *_USE_STATIC_LIBS setting matches what's on the disk.

In other cases, not so much.

I can't assess if this scenario is common enough to justify this PR,
or perhaps extending it to the other Find* modules in the future.
I may also be missing other useful scenarios.

Feel free to comment what you think.

(edit: the PR is ready to merge as-is, in case it's useful.)

[vszakats]

Merged as experimental.