target_include_directories: Support AFTER option

Fixes: #20134

Help/command/target_include_directories.rst

@@ -5,7 +5,7 @@ Add include directories to a target.
 
 .. code-block:: cmake
 
-  target_include_directories(<target> [SYSTEM] [BEFORE]
+  target_include_directories(<target> [SYSTEM] [AFTER|BEFORE]
     <INTERFACE|PUBLIC|PRIVATE> [items1...]
     [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
 
@@ -14,8 +14,8 @@ The named ``<target>`` must have been created by a command such
 as :command:`add_executable` or :command:`add_library` and must not be an
 :ref:`ALIAS target <Alias Targets>`.
 
-If ``BEFORE`` is specified, the content will be prepended to the property
+By using ``AFTER`` or ``BEFORE`` explicitly, you can select between appending
-instead of being appended.
+and prepending, independent of the default.
 
 The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify
 the scope of the following arguments.  ``PRIVATE`` and ``PUBLIC`` items will

Help/release/dev/after-option-in-target_include-directories.rst

@@ -0,0 +1,5 @@
+after-option-in-target_include-directories.rst
+----------------------------------------------
+
+* The :command:`target_include_directories` command gained a new option
+  ``AFTER``.

Source/cmTargetIncludeDirectoriesCommand.cxx

@@ -101,5 +101,6 @@ bool cmTargetIncludeDirectoriesCommand(std::vector<std::string> const& args,
     args, "INCLUDE_DIRECTORIES",
     TargetIncludeDirectoriesImpl::ArgumentFlags(
       TargetIncludeDirectoriesImpl::PROCESS_BEFORE |
+      TargetIncludeDirectoriesImpl::PROCESS_AFTER |
       TargetIncludeDirectoriesImpl::PROCESS_SYSTEM));
 }

Source/cmTargetPropCommandBase.cxx

@@ -87,6 +87,13 @@ bool cmTargetPropCommandBase::HandleArguments(
     }
     prepend = true;
     ++argIndex;
+  } else if ((flags & PROCESS_AFTER) && args[argIndex] == "AFTER") {
+    if (args.size() < 3) {
+      this->SetError("called with incorrect number of arguments");
+      return false;
+    }
+    prepend = false;
+    ++argIndex;
   }
 
   if ((flags & PROCESS_REUSE_FROM) && args[argIndex] == "REUSE_FROM") {

Source/cmTargetPropCommandBase.h

@@ -23,8 +23,9 @@ public:
   {
     NO_FLAGS = 0x0,
     PROCESS_BEFORE = 0x1,
-    PROCESS_SYSTEM = 0x2,
+    PROCESS_AFTER = 0x2,
-    PROCESS_REUSE_FROM = 0x3
+    PROCESS_SYSTEM = 0x3,
+    PROCESS_REUSE_FROM = 0x4
   };
 
   bool HandleArguments(std::vector<std::string> const& args,

Tests/RunCMake/target_include_directories/RunCMakeTest.cmake

@@ -1,3 +1,6 @@
 include(RunCMake)
 
 run_cmake(empty_keyword_args)
+run_cmake(include_before)
+run_cmake(include_after)
+run_cmake(include_default)

Tests/RunCMake/target_include_directories/include_after.cmake

@@ -0,0 +1,18 @@
+enable_language(C)
+file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/main.c" "int main() { return 0;}")
+
+set(include_dir "${CMAKE_CURRENT_BINARY_DIR}/dir")
+set(after_include_dir "${CMAKE_CURRENT_BINARY_DIR}/dirAfter")
+file(MAKE_DIRECTORY "${include_dir}")
+file(MAKE_DIRECTORY "${after_include_dir}")
+
+add_executable(main "${CMAKE_CURRENT_BINARY_DIR}/main.c")
+include_directories("${include_dir}")
+target_include_directories(main AFTER PRIVATE "${after_include_dir}")
+
+get_target_property(actual_include_dirs main INCLUDE_DIRECTORIES)
+set(desired_include_dirs "${include_dir}" "${after_include_dir}")
+
+if (NOT "${actual_include_dirs}" MATCHES "${desired_include_dirs}")
+    message(SEND_ERROR "include after does not work")
+endif()

Tests/RunCMake/target_include_directories/include_before.cmake

@@ -0,0 +1,18 @@
+enable_language(C)
+file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/main.c" "int main() { return 0;}")
+
+set(include_dir "${CMAKE_CURRENT_BINARY_DIR}/dir")
+set(before_include_dir "${CMAKE_CURRENT_BINARY_DIR}/dirBefore")
+file(MAKE_DIRECTORY "${include_dir}")
+file(MAKE_DIRECTORY "${before_include_dir}")
+
+add_executable(main "${CMAKE_CURRENT_BINARY_DIR}/main.c")
+include_directories("${include_dir}")
+target_include_directories(main BEFORE PRIVATE "${before_include_dir}")
+
+get_target_property(actual_include_dirs main INCLUDE_DIRECTORIES)
+set(desired_include_dirs "${before_include_dir}" "${include_dir}")
+
+if (NOT "${actual_include_dirs}" MATCHES "${desired_include_dirs}")
+    message(SEND_ERROR "include before does not work")
+endif()

Tests/RunCMake/target_include_directories/include_default.cmake

@@ -0,0 +1,18 @@
+enable_language(C)
+file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/main.c" "int main() { return 0;}")
+
+set(include_dir "${CMAKE_CURRENT_BINARY_DIR}/dir")
+set(default_include_dir "${CMAKE_CURRENT_BINARY_DIR}/dirDefault")
+file(MAKE_DIRECTORY "${include_dir}")
+file(MAKE_DIRECTORY "${default_include_dir}")
+
+add_executable(main "${CMAKE_CURRENT_BINARY_DIR}/main.c")
+include_directories("${include_dir}")
+target_include_directories(main AFTER PRIVATE "${default_include_dir}")
+
+get_target_property(actual_include_dirs main INCLUDE_DIRECTORIES)
+set(desired_include_dirs "${include_dir}" "${default_include_dir}")
+
+if (NOT "${actual_include_dirs}" MATCHES "${desired_include_dirs}")
+    message(SEND_ERROR "include default does not work")
+endif()