how to order include directories best ?

[Alexander Neundorf]

Hi,

in the KDE cmake files we a variable called KDE4_INCLUDES.
It contains the directory where the KDE headers are installed, the Qt include 
dirs, with X11 also the X11 include dirs, under Windows also the kdewin32 
include dir.

In cmake include dirs are added using INCLUDE_DIRECTORIES(the include dirs)
By default they are appended, since cmake 2.4.0 the default can also be 
changed to prepend them. Using the "BEFORE" or "AFTER" keywords in 
INCLUDE_DIRECTORIES it can be specified whether the following dirs should be 
prepended or appended.

Now to the problem.

When building a KDE module, it is required that it prefers the headers in the 
module sources over the installed headers.

This would mean we could do the following in the toplevel CMakeLists.txt :

# default to prepending
set (CMAKE_INCLUDE_DIRECTORIES_BEFORE ON)

include_directories( ${KDE4_INCLUDES} )

and then in the subdirs:

include_directories( ${CMAKE_SOURCE_DIR}/foo ${CMAKE_SOURCE_DIR}/foo/bar )


This would work for this case, but there's also the case that include dirs of 
other software package have to be added, like:

include_directories( ${PNG_INCLUDE_DIR} )

While this would probably work in most cases, there is also a good chance that 
with some packages it might break the build.
AFAIK e.g. on FreeBSD the Qt3 headers are installed in the X11 include dir, 
maybe other things too.So let's say somebody needs to the include dir of a 
package whose headers are also installed in the X11 include dir:

include_directories( ${FOO_INCLUDE_DIR})

This would lead to 
-I/usr/X11/include -I/opt/kde4/include -I/usr/lib/qt4/include 
-I/usr/X11/include

Which would have the effect that if including <qstring.h> then the Qt3 
qstring.h sitting in /usr/X11/include would be found -> build broken.

So, I'd suggest:
-keep the default ordering, i.e. appending
-for include dirs, which are inside the source/build tree, always use the 
BEFORE keyword
-for all other include dirs, always use the AFTER keyword

I think this should work for most cases. And I think we should even go that 
far to add a commit hook, which complains if INCLUDE_DIRECTORIES() is used 
without BEFORE or AFTER, giving a warning right now (is this possible ?) and 
reject the commit once everything builds reliably with cmake.

What do you think about this ?

Bye
Alex
-- 
Work: alexander.neundorf AT jenoptik.com - http://www.jenoptik-los.de
Home: neundorf AT kde.org                - http://www.kde.org
      alex AT neundorf.net               - http://www.neundorf.net