# FindCURL

Finds the native curl installation (include directories and libraries) for transferring data with URLS.

Added in version 3.17: If curl is built using its CMake-based build system, it will provide its own CMake Package Configuration file (`CURLConfig.cmake`) for use with the `find_package()` command in config mode. By default, this module searches for this file and, if found, returns the results without further action. If the upstream configuration file is not found, this module falls back to module mode and searches standard locations.

Added in version 3.13: Debug and Release library variants are found separately.

## Components

Added in version 3.14.

This module supports optional components to detect the protocols and features available in the installed curl (these can vary based on the curl version):

    Protocols: DICT FILE FTP FTPS GOPHER GOPHERS HTTP HTTPS IMAP IMAPS IPFS IPNS
               LDAP LDAPS MQTT POP3 POP3S RTMP RTMPS RTSP SCP SFTP SMB SMBS SMTP
               SMTPS TELNET TFTP WS WSS
    Features:  alt-svc asyn-rr AsynchDNS brotli CAcert Debug ECH gsasl GSS-API
               HSTS HTTP2 HTTP3 HTTPS-proxy HTTPSRR IDN IPv6 Kerberos Largefile
               libz MultiSSL NTLM NTLM_WB PSL SPNEGO SSL SSLS-EXPORT SSPI
               threadsafe TLS-SRP TrackMemory Unicode UnixSockets zstd

Components can be specified with the `find_package()` command as required for curl to be considered found:

    find_package(CURL [COMPONENTS <protocols>... <features>...])

Or to check for them optionally, allowing conditional handling in the code:

    find_package(CURL [OPTIONAL_COMPONENTS <protocols>... <features>...])

Refer to the curl documentation for more information on supported protocols and features. Component names are case-sensitive and follow the upstream curl naming conventions.

## Imported Targets

This module provides the following Imported Targets:

`CURL::libcurl`

  Added in version 3.12.

  Target encapsulating the curl usage requirements, available if curl is found.

## Result Variables

This module defines the following variables:

`CURL_FOUND`

  Boolean indicating whether the (requested version of) curl and all required components are found.

`CURL_VERSION`

  Added in version 4.0.

  The version of curl found. This supersedes `CURL_VERSION_STRING`.

`CURL_<component>_FOUND`

  Added in version 3.14.

  Boolean indicating whether the specified component (curl protocol or feature) is found.

`CURL_INCLUDE_DIRS`

  Include directories containing the `curl/curl.h` and other headers needed to use curl.

  Note

  When curl is found via config mode, this variable is available only with curl version 8.9 or newer.

`CURL_LIBRARIES`

  List of libraries needed to link against to use curl.

  Note

  When curl is found via module mode, this is a list of library file paths. In config mode, this variable is available only with curl version 8.9 or newer and contains a list of imported targets.

## Hints

This module accepts the following variables:

`CURL_NO_CURL_CMAKE`

  Added in version 3.17.

  Set this variable to `TRUE` to disable searching for curl via config mode.

`CURL_USE_STATIC_LIBS`

  Added in version 3.28.

  Set this variable to `TRUE` to use static libraries. This is meaningful only when curl is not found via config mode.

## Deprecated Variables

The following variables are provided for backward compatibility:

`CURL_VERSION_STRING`

  Deprecated since version 4.0: Superseded by `CURL_VERSION`.

  The version of curl found.

## Examples

Finding the curl library and specifying the required minimum version:

    find_package(CURL 7.61.0)

Finding the curl library and linking it to a project target:

    find_package(CURL)
    target_link_libraries(project_target PRIVATE CURL::libcurl)

Using components to check if the found curl supports specific protocols or features:

    find_package(CURL OPTIONAL_COMPONENTS HTTPS SSL)

    if(CURL_HTTPS_FOUND)
      # curl supports the HTTPS protocol
    endif()

    if(CURL_SSL_FOUND)
      # curl has SSL feature enabled
    endif()