cmake: Allow configuration of default script names

Adds the ``--project-file`` command-line option to modify the default script
name loaded by CMake and ``add_subdirectory`` to values other than
``CMakeLists.txt``.

Fixes: #21570

Help/manual/OPTIONS_BUILD.txt

@@ -119,6 +119,25 @@
  Specify the installation directory, used by the
  :variable:`CMAKE_INSTALL_PREFIX` variable. Must be an absolute path.
 
+.. option:: --project-file <project-file-name>
+
+ .. versionadded:: 3.32
+
+ Specify an alternate project file name.
+
+ This determines the top-level file processed by CMake when configuring a
+ project, and the file processed by :command:`add_subdirectory`.
+
+ By default, this is ``CMakeLists.txt``. If set to anything else,
+ ``CMakeLists.txt`` will be used as a fallback whenever the specified file
+ cannot be found within a project subdirectory.
+
+ .. note::
+
+  This feature is intended for temporary use by developers during an incremental
+  transition and not for publication of a final product. CMake will always emit
+  a warning when the project file is anything other than ``CMakeLists.txt``.
+
 .. option:: -Wno-dev
 
  Suppress developer warnings.

Help/manual/cmake-variables.7.rst

@@ -82,6 +82,7 @@ Variables that Provide Information
    /variable/CMAKE_LINK_LIBRARY_SUFFIX
    /variable/CMAKE_LINK_SEARCH_END_STATIC
    /variable/CMAKE_LINK_SEARCH_START_STATIC
+   /variable/CMAKE_LIST_FILE_NAME
    /variable/CMAKE_MAJOR_VERSION
    /variable/CMAKE_MAKE_PROGRAM
    /variable/CMAKE_MATCH_COUNT

Help/release/dev/rename-cmakelists.rst

@@ -0,0 +1,12 @@
+Option to specify alternate CMakeLists filename
+-----------------------------------------------
+
+* Adds :option:`cmake --project-file` option to specify an alternate filename
+  for CMakeLists files.  This determines the top-level file processed when CMake
+  is configured, and the file processed by :command:`add_subdirectory`. By
+  default, this is ``CMakeLists.txt``. If set to anything else,
+  ``CMakeLists.txt`` will be used as a fallback if the given file cannot be
+  found within a project subdirectory. The use of alternate project file names
+  is intended for temporary use by developers during an incremental transition
+  and not for publication of a final product. CMake will always emit a warning
+  when the project file is anything other than ``CMakeLists.txt``.

Help/variable/CMAKE_LIST_FILE_NAME.rst

@@ -0,0 +1,23 @@
+CMAKE_LIST_FILE_NAME
+--------------------
+
+ .. versionadded:: 3.32
+
+The name of the CMake project files. This determines the top-level file
+processed when CMake is configured, and the file processed by
+:command:`add_subdirectory`.
+
+By default, this is ``CMakeLists.txt``. If set to anything else,
+``CMakeLists.txt`` will be used as a fallback whenever the specified file
+cannot be found within a project subdirectory.
+
+This variable reports the value set via the :option:`cmake --project-file`
+option. The value of this variable should never be set directly by projects or
+users.
+
+.. warning::
+
+  The use of alternate project file names is intended for temporary use by
+  developers during an incremental transition and not for publication of a final
+  product. CMake will always emit a warning when the project file is anything
+  other than ``CMakeLists.txt``.

Source/CTest/cmCTestConfigureCommand.cxx

@@ -61,7 +61,9 @@ cmCTestConfigureCommand::InitializeHandler(HandlerArguments& arguments,
         return nullptr;
       }
 
-      const std::string cmakelists_file = source_dir + "/CMakeLists.txt";
+      const std::string cmlName = mf.GetSafeDefinition("CMAKE_LIST_FILE_NAME");
+      const std::string cmakelists_file = cmStrCat(
+        source_dir, "/", cmlName.empty() ? "CMakeLists.txt" : cmlName);
       if (!cmSystemTools::FileExists(cmakelists_file)) {
         std::ostringstream e;
         e << "CMakeLists.txt file does not exist [" << cmakelists_file << "]";

Source/cmGlobalXCodeGenerator.cxx

@@ -1068,9 +1068,8 @@ cmXCodeObject* cmGlobalXCodeGenerator::CreateXCodeSourceFile(
 void cmGlobalXCodeGenerator::AddXCodeProjBuildRule(
   cmGeneratorTarget* target, std::vector<cmSourceFile*>& sources) const
 {
-  std::string listfile =
-    cmStrCat(target->GetLocalGenerator()->GetCurrentSourceDirectory(),
-             "/CMakeLists.txt");
+  std::string listfile = this->GetCMakeInstance()->GetCMakeListFile(
+    target->GetLocalGenerator()->GetCurrentSourceDirectory());
   cmSourceFile* srcCMakeLists = target->Makefile->GetOrCreateSource(
     listfile, false, cmSourceFileLocationKind::Known);
   if (!cm::contains(sources, srcCMakeLists)) {
@@ -4400,9 +4399,8 @@ bool cmGlobalXCodeGenerator::CreateGroups(
 
       // Add CMakeLists.txt file for user convenience.
       {
-        std::string listfile =
-          cmStrCat(gtgt->GetLocalGenerator()->GetCurrentSourceDirectory(),
-                   "/CMakeLists.txt");
+        std::string listfile = this->GetCMakeInstance()->GetCMakeListFile(
+          gtgt->GetLocalGenerator()->GetCurrentSourceDirectory());
         cmSourceFile* sf = gtgt->Makefile->GetOrCreateSource(
           listfile, false, cmSourceFileLocationKind::Known);
         addSourceToGroup(sf->ResolveFullPath());

Source/cmLocalVisualStudio7Generator.cxx

@@ -229,8 +229,8 @@ cmSourceFile* cmLocalVisualStudio7Generator::CreateVCProjBuildRule()
     return nullptr;
   }
 
-  std::string makefileIn =
-    cmStrCat(this->GetCurrentSourceDirectory(), "/CMakeLists.txt");
+  std::string makefileIn = this->GetCMakeInstance()->GetCMakeListFile(
+    this->GetCurrentSourceDirectory());
   if (cmSourceFile* file = this->Makefile->GetSource(makefileIn)) {
     if (file->GetCustomCommand()) {
       return file;

Source/cmMakefile.cxx

@@ -1675,8 +1675,8 @@ public:
     : Makefile(mf)
   {
     std::string currentStart =
-      cmStrCat(this->Makefile->StateSnapshot.GetDirectory().GetCurrentSource(),
-               "/CMakeLists.txt");
+      this->Makefile->GetCMakeInstance()->GetCMakeListFile(
+        this->Makefile->StateSnapshot.GetDirectory().GetCurrentSource());
     this->Makefile->StateSnapshot.SetListFile(currentStart);
     this->Makefile->StateSnapshot =
       this->Makefile->StateSnapshot.GetState()->CreatePolicyScopeSnapshot(
@@ -1719,8 +1719,8 @@ private:
 
 void cmMakefile::Configure()
 {
-  std::string currentStart = cmStrCat(
-    this->StateSnapshot.GetDirectory().GetCurrentSource(), "/CMakeLists.txt");
+  std::string currentStart = this->GetCMakeInstance()->GetCMakeListFile(
+    this->StateSnapshot.GetDirectory().GetCurrentSource());
 
   // Add the bottom of all backtraces within this directory.
   // We will never pop this scope because it should be available
@@ -1873,8 +1873,8 @@ void cmMakefile::ConfigureSubDirectory(cmMakefile* mf)
     cmSystemTools::Message(msg);
   }
 
-  std::string const currentStartFile =
-    cmStrCat(currentStart, "/CMakeLists.txt");
+  std::string currentStartFile =
+    this->GetCMakeInstance()->GetCMakeListFile(currentStart);
   if (!cmSystemTools::FileExists(currentStartFile, true)) {
     // The file is missing.  Check policy CMP0014.
     auto e = cmStrCat("The source directory\n  ", currentStart,

Source/cmake.cxx

@@ -259,7 +259,7 @@ bool cmakeCheckStampList(const std::string& stampList)
 
 } // namespace
 
-cmDocumentationEntry cmake::CMAKE_STANDARD_OPTIONS_TABLE[18] = {
+cmDocumentationEntry cmake::CMAKE_STANDARD_OPTIONS_TABLE[19] = {
   { "-S <path-to-source>", "Explicitly specify a source directory." },
   { "-B <path-to-build>", "Explicitly specify a build directory." },
   { "-C <initial-cache>", "Pre-load a script to populate the cache." },
@@ -271,6 +271,8 @@ cmDocumentationEntry cmake::CMAKE_STANDARD_OPTIONS_TABLE[18] = {
   { "--toolchain <file>", "Specify toolchain file [CMAKE_TOOLCHAIN_FILE]." },
   { "--install-prefix <directory>",
     "Specify install directory [CMAKE_INSTALL_PREFIX]." },
+  { "--project-file <project-file-name>",
+    "Specify an alternate project file name." },
   { "-Wdev", "Enable developer warnings." },
   { "-Wno-dev", "Suppress developer warnings." },
   { "-Werror=dev", "Make developer warnings errors." },
@@ -930,6 +932,7 @@ void cmake::SetArgs(const std::vector<std::string>& args)
   bool haveToolset = false;
   bool havePlatform = false;
   bool haveBArg = false;
+  bool haveCMLName = false;
   std::string possibleUnknownArg;
   std::string extraProvidedPath;
 #if !defined(CMAKE_BOOTSTRAP)
@@ -988,6 +991,17 @@ void cmake::SetArgs(const std::vector<std::string>& args)
     return true;
   };
 
+  auto CMakeListsFileLambda = [&](std::string const& value,
+                                  cmake* state) -> bool {
+    if (haveCMLName) {
+      cmSystemTools::Error("Multiple --project-file options not allowed");
+      return false;
+    }
+    state->SetCMakeListName(value);
+    haveCMLName = true;
+    return true;
+  };
+
   std::vector<CommandArgument> arguments = {
     CommandArgument{ "", CommandArgument::Values::Zero, EmptyStringArgLambda },
     CommandArgument{ "-S", "No source directory specified for -S",
@@ -1120,6 +1134,9 @@ void cmake::SetArgs(const std::vector<std::string>& args)
                        state->SetShowLogContext(true);
                        return true;
                      } },
+    CommandArgument{ "--project-file",
+                     "No filename specified for --project-file",
+                     CommandArgument::Values::One, CMakeListsFileLambda },
     CommandArgument{
       "--debug-find", CommandArgument::Values::Zero,
       [](std::string const&, cmake* state) -> bool {
@@ -1773,8 +1790,9 @@ void cmake::SetTraceRedirect(cmake* other)
 
 bool cmake::SetDirectoriesFromFile(const std::string& arg)
 {
-  // Check if the argument refers to a CMakeCache.txt or
-  // CMakeLists.txt file.
+  // Check if the argument refers to a CMakeCache.txt or CMakeLists.txt file.
+  // Do not check for the custom project filename CMAKE_LIST_FILE_NAME, as it
+  // cannot be determined until after reading the CMakeCache.txt
   std::string listPath;
   std::string cachePath;
   bool is_source_dir = false;
@@ -1782,7 +1800,7 @@ bool cmake::SetDirectoriesFromFile(const std::string& arg)
   if (cmSystemTools::FileIsDirectory(arg)) {
     std::string path = cmSystemTools::ToNormalizedPathOnDisk(arg);
     std::string cacheFile = cmStrCat(path, "/CMakeCache.txt");
-    std::string listFile = cmStrCat(path, "/CMakeLists.txt");
+    std::string listFile = this->GetCMakeListFile(path);
 
     is_empty_directory = true;
     if (cmSystemTools::FileExists(cacheFile)) {
@@ -2177,12 +2195,13 @@ void cmake::SetGlobalGenerator(std::unique_ptr<cmGlobalGenerator> gg)
 int cmake::DoPreConfigureChecks()
 {
   // Make sure the Source directory contains a CMakeLists.txt file.
-  std::string srcList = cmStrCat(this->GetHomeDirectory(), "/CMakeLists.txt");
+  std::string srcList =
+    cmStrCat(this->GetHomeDirectory(), "/", this->CMakeListName);
   if (!cmSystemTools::FileExists(srcList)) {
     std::ostringstream err;
     if (cmSystemTools::FileIsDirectory(this->GetHomeDirectory())) {
       err << "The source directory \"" << this->GetHomeDirectory()
-          << "\" does not appear to contain CMakeLists.txt.\n";
+          << "\" does not appear to contain " << this->CMakeListName << ".\n";
     } else if (cmSystemTools::FileExists(this->GetHomeDirectory())) {
       err << "The source directory \"" << this->GetHomeDirectory()
           << "\" is a file, not a directory.\n";
@@ -2200,7 +2219,7 @@ int cmake::DoPreConfigureChecks()
   if (this->State->GetInitializedCacheValue("CMAKE_HOME_DIRECTORY")) {
     std::string cacheStart =
       cmStrCat(*this->State->GetInitializedCacheValue("CMAKE_HOME_DIRECTORY"),
-               "/CMakeLists.txt");
+               "/", this->CMakeListName);
     if (!cmSystemTools::SameFile(cacheStart, srcList)) {
       std::string message =
         cmStrCat("The source \"", srcList, "\" does not match the source \"",
@@ -2375,6 +2394,33 @@ int cmake::ActualConfigure()
   cmSystemTools::RemoveADirectory(this->GetHomeOutputDirectory() +
                                   "/CMakeFiles/CMakeScratch");
 
+  std::string cmlNameCache =
+    this->State->GetInitializedCacheValue("CMAKE_LIST_FILE_NAME");
+  if (!cmlNameCache.empty() && !this->CMakeListName.empty() &&
+      cmlNameCache != this->CMakeListName) {
+    std::string message =
+      cmStrCat("CMakeLists filename : \"", this->CMakeListName,
+               "\"\nDoes not match the previous: \"", cmlNameCache,
+               "\"\nEither remove the CMakeCache.txt file and CMakeFiles "
+               "directory or choose a different binary directory.");
+    cmSystemTools::Error(message);
+    return -2;
+  }
+  if (this->CMakeListName.empty()) {
+    this->CMakeListName =
+      cmlNameCache.empty() ? "CMakeLists.txt" : cmlNameCache;
+  }
+  if (this->CMakeListName != "CMakeLists.txt") {
+    this->IssueMessage(
+      MessageType::WARNING,
+      "This project has been configured with a project file other than "
+      "CMakeLists.txt. This feature is intended for temporary use during "
+      "development and not for publication of a final product.");
+  }
+  this->AddCacheEntry("CMAKE_LIST_FILE_NAME", this->CMakeListName,
+                      "Name of CMakeLists files to read",
+                      cmStateEnums::INTERNAL);
+
   int res = this->DoPreConfigureChecks();
   if (res < 0) {
     return -2;
@@ -4230,6 +4276,21 @@ bool cmake::GetDebugFindPkgOutput(std::string const& pkg) const
   return this->DebugFindPkgs.count(pkg);
 }
 
+void cmake::SetCMakeListName(const std::string& name)
+{
+  this->CMakeListName = name;
+}
+
+std::string cmake::GetCMakeListFile(const std::string& dir) const
+{
+  std::string listFile = cmStrCat(dir, '/', this->CMakeListName);
+  if (this->CMakeListName.empty() ||
+      !cmSystemTools::FileExists(listFile, true)) {
+    return cmStrCat(dir, "/CMakeLists.txt");
+  }
+  return listFile;
+}
+
 #if !defined(CMAKE_BOOTSTRAP)
 cmMakefileProfilingData& cmake::GetProfilingOutput()
 {

Source/cmake.h

@@ -664,6 +664,9 @@ public:
 
   bool GetRegenerateDuringBuild() const { return this->RegenerateDuringBuild; }
 
+  void SetCMakeListName(const std::string& name);
+  std::string GetCMakeListFile(const std::string& dir) const;
+
 #if !defined(CMAKE_BOOTSTRAP)
   cmMakefileProfilingData& GetProfilingOutput();
   bool IsProfilingEnabled() const;
@@ -788,6 +791,7 @@ private:
   bool DebugTryCompile = false;
   bool FreshCache = false;
   bool RegenerateDuringBuild = false;
+  std::string CMakeListName;
   std::unique_ptr<cmFileTimeCache> FileTimeCache;
   std::string GraphVizFile;
   InstalledFilesMap InstalledFiles;
@@ -857,7 +861,7 @@ public:
   void SetScriptModeExitCode(int code) { ScriptModeExitCode = code; }
   int GetScriptModeExitCode() const { return ScriptModeExitCode.value_or(-1); }
 
-  static cmDocumentationEntry CMAKE_STANDARD_OPTIONS_TABLE[18];
+  static cmDocumentationEntry CMAKE_STANDARD_OPTIONS_TABLE[19];
 };
 
 #define FOR_EACH_C90_FEATURE(F) F(c_function_prototypes)

Tests/RunCMake/CMakeListFileName/CMakeLists.txt

@@ -0,0 +1,3 @@
+cmake_minimum_required(VERSION 3.29)
+project(${RunCMake_TEST} NONE)
+include(${RunCMake_TEST}.cmake)

Tests/RunCMake/CMakeListFileName/RunCMakeTest.cmake

@@ -0,0 +1,15 @@
+include(RunCMake)
+
+block()
+  set(source ${RunCMake_SOURCE_DIR}/project)
+  run_cmake_command(dont-set-file ${CMAKE_COMMAND} -S ${source})
+  run_cmake_command(set-file-dne ${CMAKE_COMMAND} -S ${source} --project-file dne.cmake)
+  run_cmake_command(set-file-multi ${CMAKE_COMMAND} -S ${source} --project-file 1 --project-file 2)
+  run_cmake_command(set-file-none ${CMAKE_COMMAND} -S ${source} --project-file)
+
+  set(RunCMake_TEST_NO_CLEAN 1)
+  set(RunCMake_TEST_BINARY_DIR ${RunCMake_BINARY_DIR}/other)
+  run_cmake_command(set-file ${CMAKE_COMMAND} -S ${source} --project-file other.cmake)
+  run_cmake_command(remembers-file ${CMAKE_COMMAND} -S ${source})
+  run_cmake_command(cant-change-file ${CMAKE_COMMAND} -S ${source} --project-file another.cmake)
+endblock()

Tests/RunCMake/CMakeListFileName/cant-change-file-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/CMakeListFileName/cant-change-file-stderr.txt

@@ -0,0 +1,3 @@
+CMake Error: CMakeLists filename : \"another.cmake\"
+Does not match the previous: \"other.cmake\"
+Either remove the CMakeCache.txt file and CMakeFiles directory or choose a different binary directory.

Tests/RunCMake/CMakeListFileName/dont-set-file-stdout.txt

@@ -0,0 +1,3 @@
+\-\- Processing: CMakeLists.txt
+\-\- Processing: subdir-1/CMakeLists.txt
+\-\- Processing: subdir-2/CMakeLists.txt

Tests/RunCMake/CMakeListFileName/project/CMakeLists.txt

@@ -0,0 +1,5 @@
+cmake_minimum_required(VERSION 3.31)
+project(test)
+message(STATUS "Processing: CMakeLists.txt")
+add_subdirectory(subdir-1)
+add_subdirectory(subdir-2)

Tests/RunCMake/CMakeListFileName/project/other.cmake

@@ -0,0 +1,5 @@
+cmake_minimum_required(VERSION 3.31)
+project(test)
+message(STATUS "Processing: other.cmake")
+add_subdirectory(subdir-1)
+add_subdirectory(subdir-2)

Tests/RunCMake/CMakeListFileName/project/subdir-1/CMakeLists.txt

@@ -0,0 +1 @@
+message(STATUS "Processing: subdir-1/CMakeLists.txt")

Tests/RunCMake/CMakeListFileName/project/subdir-1/other.cmake

@@ -0,0 +1 @@
+message(STATUS "Processing: subdir-1/other.cmake")

Tests/RunCMake/CMakeListFileName/project/subdir-2/CMakeLists.txt

@@ -0,0 +1 @@
+message(STATUS "Processing: subdir-2/CMakeLists.txt")

Tests/RunCMake/CMakeListFileName/remembers-file-stderr.txt

@@ -0,0 +1,4 @@
+CMake Warning:
+  This project has been configured with a project file other than
+  CMakeLists.txt.  This feature is intended for temporary use during
+  development and not for publication of a final product.

Tests/RunCMake/CMakeListFileName/remembers-file-stdout.txt

@@ -0,0 +1,3 @@
+\-\- Processing: other.cmake
+\-\- Processing: subdir-1/other.cmake
+\-\- Processing: subdir-2/CMakeLists.txt

Tests/RunCMake/CMakeListFileName/set-file-dne-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/CMakeListFileName/set-file-dne-stderr.txt

@@ -0,0 +1,9 @@
+CMake Warning:
+  This project has been configured with a project file other than
+  CMakeLists.txt.  This feature is intended for temporary use during
+  development and not for publication of a final product.
+
+
+CMake Error: The source directory [^
+]* does not appear to contain dne.cmake.
+Specify --help for usage, or press the help button on the CMake GUI.

Tests/RunCMake/CMakeListFileName/set-file-multi-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/CMakeListFileName/set-file-multi-stderr.txt

@@ -0,0 +1,2 @@
+CMake Error: Multiple --project-file options not allowed
+CMake Error: Run 'cmake --help' for all supported options

Tests/RunCMake/CMakeListFileName/set-file-none-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/CMakeListFileName/set-file-none-stderr.txt

@@ -0,0 +1,2 @@
+CMake Error: No filename specified for --project-file
+CMake Error: Run 'cmake --help' for all supported options.

Tests/RunCMake/CMakeListFileName/set-file-stderr.txt

@@ -0,0 +1,4 @@
+CMake Warning:
+  This project has been configured with a project file other than
+  CMakeLists.txt.  This feature is intended for temporary use during
+  development and not for publication of a final product.

Tests/RunCMake/CMakeListFileName/set-file-stdout.txt

@@ -0,0 +1,3 @@
+\-\- Processing: other.cmake
+\-\- Processing: subdir-1/other.cmake
+\-\- Processing: subdir-2/CMakeLists.txt

Tests/RunCMake/CMakeLists.txt

@@ -1258,6 +1258,8 @@ add_RunCMake_test(CMakePresetsWorkflow
 add_RunCMake_test(VerifyHeaderSets)
 add_RunCMake_test(set_tests_properties)
 
+add_RunCMake_test(CMakeListFileName)
+
 if(CMAKE_GENERATOR MATCHES "Make|Ninja")
   add_RunCMake_test(Codegen)
   add_RunCMake_test(TransformDepfile)