How to figure out what -D options there are for a cmake build?

[bagder]

When a user wants to build curl with cmake, how do they figure out what available -D variables there are to tweak the build?

For example switching dependencies on/off or passing a custom path to check for a dependency?

We don't have any of those documented so I figure there has to be a way to list them?

With configure --help, I can get a list of all --with-* and --enable-* options the configure script supports. Is there a similar thing for cmake?

[vszakats]

There is no configure --help with CMake. It's mostly just loose conventions and digging the sources.

• The easiest is to find the official toggle options (102 as of now):

  $ git grep -F 'option(' | grep -i cmake
  

  Compared to configure the defaults are easier to figure out.

• Then there are non-toggle settings. There is no easy grep for them.

  $ git grep -E '\${CURL_[A-Z_]+}' | grep -i cmake | grep -v -F 'option(' | grep -o -E '\${CURL_[A-Z_]+}' | sort -u
  $ git grep curl_dependency_option | grep -o -E '\([A-Z_]+' | sed 's/(/CURL_/g'
  $ git grep -F 'set(' | grep -i cmake | grep CACHE 
  

  Most of these are internal, only a few are meant as public options:
  CURL_CA_BUNDLE,
  CURL_CA_EMBED,
  CURL_CA_PATH,
  CURL_DEFAULT_SSL_BACKEND,
  CURL_LIBCURL_VERSIONED_SYMBOLS_PREFIX, CURL_TARGET_WINDOWS_VERSION.
  Some are missed by this grep:
  IMPORT_LIB_SUFFIX, STATIC_LIB_SUFFIX

• Then there are the officially supported input variables to control dependencies
  in each CMake/Find*.cmake under Input variables:. With 8.10.0 they are uniform
  across modules:
  <UPPERCASE_DEP_NAME>_{INCLUDE_DIR|LIBRARY}
  except GSS, which uses GSS_ROOT_DIR. And BROTLI and MBEDTLS
  which have multiple libraries and separate options for each.
  *_LIBRARY can be set to a full path to the filename, either static or shared.

  $ git grep -E '^# [A-Za-z0-9_]+ ' | grep -E '(LIBRARY |INCLUDE_DIR |deprecated)' | grep CMake/Find
  

• For dependencies with built-in CMake support, the list of config
  variables can more adventurous to figure out, but curl uses just two
  of these: OpenSSL and ZLIB. ZLIB supports the scheme above,
  and there is OPENSSL_ROOT_DIR. (for possibly more the
  source of the find module can be read in:
  <sysroot>/share/cmake/Modules/Find*.cmake

• Since component boundaries are loosely set in CMake, basically any
  variable that isn't explicitly initialized can be passed from the outside.
  This allows to pre-cache or override detection results, for example:
  -DHAVE_WRITABLE_ARGV=1 skips the feature check and force-enables it.
  It works for all HAVE_* variables. (Except for Windows, which sets
  them automatically in most cases)

• Finally there are numerous CMake-level options that can be passed, e.g.
  CMAKE_UNITY_BUILD, CMAKE_UNITY_BUILD_BATCH_SIZE,
  CMAKE_C_FLAGS, CMAKE_EXE_LINKER_FLAGS,
  CMAKE_SHARED_LINKER_FLAGS,
  CMAKE_DEBUG_POSTFIX, CMAKE_STATIC_LIBRARY_SUFFIX,
  CMAKE_IMPORT_LIBRARY_SUFFIX, CMAKE_INSTALL_INCLUDEDIR,
  CMAKE_INSTALL_LIBDIR.
  and so on. There are also variables controlling pkg-config detection
  and use (e.g. PKG_CONFIG_EXECUTABLE), and other CMake-level stuff.

• CMake, its modules and even our GSS module may also pick up env or registry
  settings as a means to control behavior. But those are the exceptions:

  $ git grep -F '$ENV{' | grep -i cmake
  

There may be some I forgot about.

curl-for-win covers a fair amount of these options, perhaps it can serve
as a template or guide:
https://github.com/curl/curl-for-win/blob/8b8909e1206de1dcca356a8dd33eb1e4ffeea7fd/curl.sh

[vszakats]

PR → #15388