cmake: add BUILD_EXAMPLES option to build examples

You can enable it with `-DBUILD_EXAMPLES=ON`.

To match autotools' `make examples` feature.
Windows (static) builds not tested.

Also enable examples in a pair of CI jobs.

Apply related updates to the macOS CI workflow:
- drop unused `CXX` envs.
- drop no longer needed `-Wno-error=undef -Wno-error=conversion` flags.
- pass `-Wno-deprecated-declarations` to GCC too (for `BUILD_EXAMPLES`).
- document why `-Wno-deprecated-declarations` is necessary.

Closes #13491

.github/workflows/macos.yml

@@ -208,24 +208,23 @@ jobs:
   cmake:
     name: cmake ${{ matrix.compiler.CC }} ${{ matrix.build.name }}
     runs-on: 'macos-latest'
-    env: ${{ matrix.compiler }}
+    env:
+      CC: ${{ matrix.compiler.CC }}
+      # '-Wno-deprecated-declarations' required for LDAP and BUILD_EXAMPLES
+      CFLAGS: '-DCMAKE_C_FLAGS=-mmacosx-version-min=10.15 -Wno-deprecated-declarations'
     strategy:
       fail-fast: false
       matrix:
         compiler:
           - CC: clang
-            CXX: clang++
-            CFLAGS: "-mmacosx-version-min=10.15 -Wno-deprecated-declarations"
           - CC: gcc-12
-            CXX: g++-12
-            CFLAGS: "-mmacosx-version-min=10.15 -Wno-error=undef -Wno-error=conversion"
         build:
           - name: OpenSSL
             install: nghttp2 openssl
             generate: -DOPENSSL_ROOT_DIR=$(brew --prefix)/opt/openssl -DCMAKE_OSX_DEPLOYMENT_TARGET=10.9
           - name: LibreSSL
             install: nghttp2 libressl
-            generate: -DOPENSSL_ROOT_DIR=$(brew --prefix)/opt/libressl -DCURL_DISABLE_LDAP=ON -DCURL_DISABLE_LDAPS=ON
+            generate: -DOPENSSL_ROOT_DIR=$(brew --prefix)/opt/libressl -DCURL_DISABLE_LDAP=ON -DCURL_DISABLE_LDAPS=ON -DBUILD_EXAMPLES=ON
           - name: libssh2
             install: nghttp2 openssl libssh2
             generate: -DOPENSSL_ROOT_DIR=$(brew --prefix)/opt/openssl -DCURL_USE_LIBSSH2=ON -DBUILD_SHARED_LIBS=ON -DBUILD_STATIC_LIBS=ON

CMakeLists.txt

@@ -1575,6 +1575,11 @@ if(BUILD_CURL_EXE)
   add_subdirectory(src)
 endif()
 
+option(BUILD_EXAMPLES "Build libcurl examples" OFF)
+if(BUILD_EXAMPLES)
+  add_subdirectory(docs/examples)
+endif()
+
 cmake_dependent_option(BUILD_TESTING "Build tests"
   ON "PERL_FOUND;NOT CURL_DISABLE_TESTS"
   OFF)

docs/examples/CMakeLists.txt

@@ -0,0 +1,44 @@
+#***************************************************************************
+#                                  _   _ ____  _
+#  Project                     ___| | | |  _ \| |
+#                             / __| | | | |_) | |
+#                            | (__| |_| |  _ <| |___
+#                             \___|\___/|_| \_\_____|
+#
+# Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
+#
+# This software is licensed as described in the file COPYING, which
+# you should have received as part of this distribution. The terms
+# are also available at https://curl.se/docs/copyright.html.
+#
+# You may opt to use, copy, modify, merge, publish, distribute and/or sell
+# copies of the Software, and permit persons to whom the Software is
+# furnished to do so, under the terms of the COPYING file.
+#
+# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+# KIND, either express or implied.
+#
+# SPDX-License-Identifier: curl
+#
+###########################################################################
+
+transform_makefile_inc("Makefile.inc"
+  "${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.cmake")
+include(${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.cmake)
+# Get 'check_PROGRAMS' variable
+
+foreach(example IN LISTS check_PROGRAMS)
+  set(example_target "curl-example-${example}")
+  add_executable(${example_target} "${example}.c")
+  target_include_directories(${example_target} PRIVATE
+    "${CURL_SOURCE_DIR}/lib"      # for "curl_setup_once.h"
+    "${CURL_BINARY_DIR}/lib"      # for "curl_config.h"
+    "${CURL_BINARY_DIR}/include"  # for "curl/curl.h"
+  )
+  target_link_libraries(${example_target} ${LIB_SELECTED} ${CURL_LIBS})
+  target_compile_definitions(${example_target} PRIVATE "CURL_NO_OLDIES")
+  if(LIB_SELECTED STREQUAL LIB_STATIC AND WIN32)
+    set_property(TARGET ${example_target} APPEND PROPERTY COMPILE_DEFINITIONS "CURL_STATICLIB")
+  endif()
+  set_target_properties(${example_target} PROPERTIES OUTPUT_NAME "${example}" UNITY_BUILD OFF)
+endforeach()