project: Add variable CMAKE_PROJECT_INCLUDE_BEFORE

Help/command/project.rst

@@ -31,6 +31,10 @@ Further variables are set by the optional arguments described in the following.
 If any of these arguments is not used, then the corresponding variables are
 set to the empty string.
 
+If the variable :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` exists, the file
+pointed to by that variable will be included as the first step of the project
+command.
+
 If the variable :variable:`CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`
 or :variable:`CMAKE_PROJECT_INCLUDE` exists, the file pointed to by that
 variable will be included as the last step of the project command.

Help/manual/cmake-variables.7.rst

@@ -196,6 +196,7 @@ Variables that Change Behavior
    /variable/CMAKE_PREFIX_PATH
    /variable/CMAKE_PROGRAM_PATH
    /variable/CMAKE_PROJECT_INCLUDE
+   /variable/CMAKE_PROJECT_INCLUDE_BEFORE
    /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE
    /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY
    /variable/CMAKE_STAGING_PREFIX

Help/release/dev/project-include-before.rst

+cmake_project_include_before
+----------------------------
+
+* A variable :variable:`CMAKE_PROJECT_INCLUDE_BEFORE` was added to allow
+  injection of custom code into the project.

Help/variable/CMAKE_PROJECT_INCLUDE_BEFORE.rst

+CMAKE_PROJECT_INCLUDE_BEFORE
+----------------------------
+
+A CMake language file or module to be included before processing the
+:command:`project` command. This is intended for injecting custom code into
+project builds without modifying their source.

Source/cmProjectCommand.cxx

@@ -25,6 +25,10 @@ bool cmProjectCommand::InitialPass(std::vector<std::string> const& args,
     return false;
   }
 
+  if (!this->IncludeByVariable("CMAKE_PROJECT_INCLUDE_BEFORE")) {
+    return false;
+  }
+
   std::string const& projectName = args[0];
 
   this->Makefile->SetProjectName(projectName);

Tests/CMakeOnly/CMakeLists.txt

@@ -62,6 +62,12 @@ add_test(CMakeOnly.ProjectIncludeAny ${CMAKE_CMAKE_COMMAND}
   -P ${CMAKE_CURRENT_BINARY_DIR}/Test.cmake
   )
 
+add_test(CMakeOnly.ProjectIncludeBefore ${CMAKE_CMAKE_COMMAND}
+  -DTEST=ProjectIncludeBefore
+  -DCMAKE_ARGS=-DCMAKE_PROJECT_INCLUDE_BEFORE=${CMAKE_CURRENT_SOURCE_DIR}/ProjectIncludeBefore/include.cmake
+  -P ${CMAKE_CURRENT_BINARY_DIR}/Test.cmake
+  )
+
 include(CMakeParseArguments)
 
 function(add_major_test module)

Tests/CMakeOnly/ProjectIncludeBefore/CMakeLists.txt

+set(FOO TRUE)
+project(ProjectInclude LANGUAGES NONE)
+if(NOT AUTO_INCLUDE)
+  message(FATAL_ERROR "include file not found")
+endif()

Tests/CMakeOnly/ProjectIncludeBefore/include.cmake

+if(NOT FOO)
+  message(FATAL_ERROR "FOO is not set")
+endif()
+
+if(NOT "${PROJECT_NAME}" STREQUAL "")
+  message(FATAL_ERROR "PROJECT_NAME should be empty")
+endif()
+
+set(AUTO_INCLUDE TRUE)