cmake: cleanup header paths

- sync build-dir/source-dir header path order with autotools, by
  including build-dir first, then source-dir.
  This prevents out-of-tree builds breaking due to leftover generated
  headers in the source tree.

- tests/unit: move `src` ahead of `libtest` in header path, syncing with
  autotools.

- stop adding non-existing generated `include` dir to header path.
  There are no generated `include` headers and this directory is either
  missing in out-of-tree builds or the same as the one already added
  globally via the root `CMakeLists.txt`.

- lib: stop adding a duplicate source include directory to the header
  path.
  It's already added globally via the root `CMakeLists.txt`.

- lib: stop adding the project root to the header path.

- docs/examples: drop internal header paths.
  Examples do not and should not use internal headers.

- replace `curl_setup_once.h` in comments with `curl_setup.h`,
  the header actually used, and also referred to in autotools comments.

- add comment why we need `src` in include path for `tests/server`.

- add quotes around header directories.

Closes #14416

tests/http/clients/CMakeLists.txt

@@ -31,9 +31,8 @@ foreach(_client IN LISTS check_PROGRAMS)
   add_executable(${_client_target} "${_client}.c")
   add_dependencies(testdeps ${_client_target})
   target_include_directories(${_client_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"
+    "${CURL_BINARY_DIR}/lib"  # for "curl_config.h"
+    "${CURL_SOURCE_DIR}/lib"  # for "curl_setup.h"
   )
   target_link_libraries(${_client_target} ${LIB_SELECTED} ${CURL_LIBS})
   target_compile_definitions(${_client_target} PRIVATE "CURL_NO_OLDIES")

tests/libtest/CMakeLists.txt

@@ -35,10 +35,9 @@ function(setup_test test_name)  # ARGN are the files in the test
   string(TOUPPER ${test_name} UPPER_TEST_NAME)
 
   include_directories(
-    ${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"
-    ${CURL_SOURCE_DIR}/tests/libtest  # to be able to build generated tests
+    "${CURL_BINARY_DIR}/lib"            # for "curl_config.h"
+    "${CURL_SOURCE_DIR}/lib"            # for "curl_setup.h"
+    "${CURL_SOURCE_DIR}/tests/libtest"  # to be able to build generated tests
   )
   if(USE_ARES)
     include_directories(${CARES_INCLUDE_DIR})

tests/server/CMakeLists.txt

@@ -32,10 +32,9 @@ function(setup_executable test_name)  # ARGN are the files in the test
   add_dependencies(testdeps ${test_name})
 
   include_directories(
-    ${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"
-    ${CURL_SOURCE_DIR}/src      # for "tool_xattr.h"
+    "${CURL_BINARY_DIR}/lib"  # for "curl_config.h"
+    "${CURL_SOURCE_DIR}/lib"  # for "curl_setup.h"
+    "${CURL_SOURCE_DIR}/src"  # for "tool_xattr.h" in disabled_SOURCES
   )
   if(USE_ARES)
     include_directories(${CARES_INCLUDE_DIR})

tests/unit/CMakeLists.txt

@@ -27,11 +27,10 @@ transform_makefile_inc("Makefile.inc" "${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.
 include(${CMAKE_CURRENT_BINARY_DIR}/Makefile.inc.cmake)
 
 include_directories(
-  ${CURL_SOURCE_DIR}/lib          # for "curl_setup_once.h"
-  ${CURL_SOURCE_DIR}/tests/libtest
-  ${CURL_SOURCE_DIR}/src
-  ${CURL_BINARY_DIR}/lib          # for "curl_config.h"
-  ${CURL_BINARY_DIR}/include      # for "curl/curl.h"
+  "${CURL_BINARY_DIR}/lib"            # for "curl_config.h"
+  "${CURL_SOURCE_DIR}/lib"            # for "curl_setup.h"
+  "${CURL_SOURCE_DIR}/src"
+  "${CURL_SOURCE_DIR}/tests/libtest"
 )
 
 foreach(_testfile IN LISTS UNITPROGS)