[CMake] Difference between ADD_SUBDIRECTORY and INCLUDE

[Pau Garcia i Quiles]

Quoting Mike Jackson <imikejackson at gmail.com>:

> Could someone suggest when to use ADD_SUBDIRECTORY and when to use
> INCLUDE? I think I am just missing something with my projects..

They are very different.

Think of INCLUDE as an #include in C or C++. It is useful when you  
have defined custom commands, custom targets, all your CMakeLists.txt  
have parts in common, etc and you want to write them only once.  
INCLUDE helps you to re-use CMake "code". For instance, I have an  
arisnova.cmake file where I have the following custom targets and  
commands: GENERATE_DOCUMENTATION(Doxyfile),  
GENERATE_DISTCLEAN_TARGET() and GENERATE_UNINSTALL_TARGET(). As I want  
to use these commands in all my projects, I have an  
INCLUDE(arisnova.cmake) in the "root" CMakeLists.txt of every project.

You would use ADD_SUBDIRECTORY and its sibling SUBDIRS when your  
project has multiple directories. For instance, imagine you have these  
source tree:
alarmclock
      |
      \--- libwakeup
      \--- clock

Usually, you'd have three CMakeLists.txt here: one in the 'alarmclock'  
directory (the "root" CMakeLists.txt), one in the 'libwakeup'  
directory and one in the 'clock' directory. For instance:

* alarmclock/CMakeLists.txt

PROJECT( alarmclock )
ADD_SUBDIRECTORY( libwakeup )
ADD_SUBDIRECTORY( clock )

* alarmclock/libwakeup/CMakeLists.txt
PROJECT( libwakeup )
SET( wakeup_SRCS wakeup.cpp )
ADD_LIBRARY( wakeup SHARED ${wakeup_SRCS} )

* alarmclock/clock/CMakeLists.txt
PROJECT( clock )
SET( clock_SRCS clock.cpp )
ADD_EXECUTABLE( clock ${clock_SRCS} )
TARGET_LINK_LIBRARIES( clock wakeup )

You can of course combine INCLUDE and ADD_SUBDIRECTORY/SUBDIRS in the  
same CMakeLists.txt, as they have very different purposes.

-- 
Pau Garcia i Quiles
http://www.elpauer.org
(Due to my workload, I may need 10 days to answer)