[cmake-developers] [CMake 0013594]: ADD_SUBDIRECTORY to look for CMakeSubLists.txt in addition to CMakeLists.txt

[Mantis Bug Tracker]

The following issue has been SUBMITTED. 
====================================================================== 
http://public.kitware.com/Bug/view.php?id=13594 
====================================================================== 
Reported By:                tfry
Assigned To:                
====================================================================== 
Project:                    CMake
Issue ID:                   13594
Category:                   CMake
Reproducibility:            N/A
Severity:                   feature
Priority:                   normal
Status:                     new
====================================================================== 
Date Submitted:             2012-10-17 07:40 EDT
Last Modified:              2012-10-17 07:40 EDT
====================================================================== 
Summary:                    ADD_SUBDIRECTORY to look for CMakeSubLists.txt in
addition to CMakeLists.txt
Description: 
Wish:
If ADD_SUBDIRECTORY() fails to locate a CMakeLists.txt-file in the specified
directory, it should look for CMakeSubLists.txt, instead.

Documentation will encourage to use the file name "CMakeLists.txt" for cmake
files which are valid as a top-level build file, and "CMakeSubLists.txt" for
cmake files which rely on being included from a parent directory.

Rationale:
One common build error that users of my project run into is that they point
cmake to a subdirectory of the sources, rather than the top-level directory
containing the main CMakeLists.txt. Admittedly, this type of error is
"encouraged" by a somewhat unlucky directory naming scheme. However, it can
easily be hit in many projects. Users running into this will hit rather
unhelpful error messages, typically about undefined macros.

One way around this is to guard the CMakeLists.txt in each subdirectory, e.g. by
checking whether the PROJECT_NAME, or some other indicative variable has been
set. However, this check would need to be added to each CMakeLists.txt,
decreasing the signal-to-noise-ratio in the build files.

With the change as outlined, above, I could rename those CMakeLists.txt-files,
which are not meant to be used as top-level cmake files to CMakeSubLists.txt.
Cmake files, which *can* be used as top-level cmake files will continue to be
named CMakeLists.txt. Thus, only those cmake files which can stand for
themselves will be considered by the cmake-command, while
CMakeSubLists.txt-files will only be considered when included using
ADD_SUBDIRECTORY().

Projects not updating the naming scheme for cmake files will not be affected by
this change (but will not benefit from the new feature, either).
====================================================================== 

Issue History 
Date Modified    Username       Field                    Change               
====================================================================== 
2012-10-17 07:40 tfry           New Issue                                    
======================================================================