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