cmake: clear package version after `pkg-config` detection

`pkg_check_modules()` seems to leave `<PACKAGE>_VERSION` defined with an
empty value, if the package is not found.

When

cmake: clear package version after `pkg-config` detection

`pkg_check_modules()` seems to leave `<PACKAGE>_VERSION` defined with an
empty value, if the package is not found.

When the package is also not found in the fallback branch,
`find_package_handle_standard_args()` logs and error message. In this
message it includes the bogus empty value as: `(found version "")`:
```
Could NOT find Libssh2 (missing: LIBSSH2_INCLUDE_DIR LIBSSH2_LIBRARY) (found version "")
```
https://github.com/curl/curl/actions/runs/11509727553/job/32040378958?pr=15408#step:31:99

Clear the version number to avoid the confusion:
```
Could NOT find Libssh2 (missing: LIBSSH2_INCLUDE_DIR LIBSSH2_LIBRARY)
```
https://github.com/curl/curl/actions/runs/11510022503/job/32041149129?pr=15408#step:31:99

Seen with CMake v3.30.5.

Follow-up to 7bab201abe3915a0167c002f9308950cb8a06e4b #15193
Closes #15409

show more ...

cmake: document `-D` and env build options

Extend `INSTALL-CMAKE` document with the list of available options,
a short description and default values.

The list may not be 100% c

cmake: document `-D` and env build options

Extend `INSTALL-CMAKE` document with the list of available options,
a short description and default values.

The list may not be 100% complete.

There are no component boundaries in CMake, so the line is blurry
between curl options, CMake options, CMake Find modules options.
I included certain CMake options that seemed useful, and/or have
dedicated use withing curl's CMake source. But, all CMake built-in
options are usable, as documented upstream in CMake.

The naming of the options has a heritage and the inconsistencies with
it, including a lack of clear namespace. This may be subject to future
updates, also after figuring out which name has special meaning within
CMake and/or CMake projects out of unwritten convention or something
more tangible.

CMake allows to initialize any internal variable via `-D`. This may be
useful to pre-initialize/override feature check results. The list
doesn't contain these, and they remain officially undocumented.

Also:
- make adjustments to keep the spellchecker happy.
- retrofit description changes to the cmake sources.
- stop documenting deprecated `Find*` variables.

Reported-by: Daniel Stenberg
Fixes https://github.com/curl/curl/discussions/14885
Closes #15388

show more ...

cmake: respect cflags/libdirs of native pkg-config detections

In Find modules with native pkg-config detection (libgsasl, libidn2,
libssh, libuv, nettle) use the C compiler flags returne

cmake: respect cflags/libdirs of native pkg-config detections

In Find modules with native pkg-config detection (libgsasl, libidn2,
libssh, libuv, nettle) use the C compiler flags returned by pkg-config.
Also use the library paths, and return the pathless library names.

Also:
- add these library paths to `libcurl.pc`/`curl-config`.
- fix libgsasl detection to use the detected header directory.

FindGSS already did this before this patch.

Fixes #14641

Closes #14652

show more ...

cmake: pkg-config 'found' message sync with native CMake

Cherry-picked from #14610

cmake: migrate dependency detections to Find modules

For: libgsasl, libidn2, libssh, libuv.

The new Find modules retain using `pkg-config` natively, not as a "hint"
for the CMak

cmake: migrate dependency detections to Find modules

For: libgsasl, libidn2, libssh, libuv.

The new Find modules retain using `pkg-config` natively, not as a "hint"
for the CMake-native detection. Of the pre-existing Find modules, only
FindNettle, and FindGSS (with customized code) work this way. Align
detection code for the new modules and add version detection for the
CMake-native paths.

Also, add CMake-native detection for `libgsasl`.

The remaining outlier in `CMakeLists.txt` is GnuTLS, which has
a CMake built-in Find module, but which lacks `pkg-config` support,
required for vcpkg. It remains unchanged.

Another part-outlier is `libssh`, which keeps requiring the trick
`find_package(libssh CONFIG QUIET)` for reasons I could not yet figure
out.

Closes #14555

show more ...