[cmake-developers] Convention driven CMAKE_USE_PACKAGE macro

[Alexander Neundorf]

On Friday 24 February 2012, Stephen Kelly wrote:
> Hi there,
> 
> When building Qt5 projects with CMake, you will use something like this:
> find_package(Qt5Widgets REQUIRED)
> find_package(Qt5Xml REQUIRED)
> 
> The result is that several variables are populated with information needed
> to build your project with Qt5, such as in this case
> * ${Qt5Widgets_INCLUDE_DIRS}
> * ${Qt5Xml_INCLUDE_DIRS}
> * ${Qt5Widgets_DEFINITONS}
> * ${Qt5Xml_DEFINITONS}
> * ${Qt5Widgets_EXECUTABLE_COMPILE_FLAGS}
> * ${Qt5Xml_EXECUTABLE_COMPILE_FLAGS}
> and several others.
> 
> When building Qt4 applications with CMake, it is common to use
> 
> include(${QT_USE_FILE})
> 
> This caused the include directories and the definitions to be used by CMake
> at directory level scope, meaning that all targets in this directory and in
> lower subdirectories would be built with those definitions and includes
> available.
> 
> One common problem with that was that when creating unit tests which do not
> link to QtGui, the QT_GUI_LIB macro was defined, and so linker errors
> occured.
> 
> The way around that was one or more of:
> * Don't use the USE file (KDE doesn't use it)
> * remove_definitions(-DQT_GUI_LIB)
> * be very careful about which Qt4 components are passed to find_package
> (Grantlee does this - it finds Qt multiple times - templates/CMakeLists and
> textdocument/CMakeLists because the templates library and tests do not use
> QtGui).
> 
> When building with Qt5, we want to change the convention away from USE
> files, and towards a concept of using packages whose variables have
> conventional names, mostly those conventions in the Modules/readme.txt, so
> that after find_package(Foo), Foo_INCLUDE_DIRS contains the include
> directories that targets using Foo need to use, and Foo_COMPILE_DEFINITIONS

The question whether the standard-conforming name is FOO_INCLUDE_DIRS or 
Foo_INCLUDE_DIRS, i.e. ExactCase or UPPERCASE, is not decided.
readme.txt is ambiguous in this point, since it uses as example 
"FindXXX.cmake", i.e. an UPPERCASE package name.

There was a thread here in August 2010:
http://www.mail-archive.com/cmake-developers@cmake.org/msg00128.html
and results for what casing is used in cmake and in kdelibs here:
http://www.mail-archive.com/cmake-developers@cmake.org/msg00157.html

cmake: 91/101 UPPERCASE, 46/101 ExactCase
kdelibs: 83/89 UPPERCASE, 22/89 ExactCase

So I argued that the defacto standard is UPPERCASE (in both projects >= 90%), 
while ExactCase is in both projects < 50%), and we shouldn't change it.

ExactCase looks nicer, but I would prefer to stick with the existing majority, 
instead of changing it now and creating even more inconsistencies.

Alex