cmake: Add include directory policy documentation
Signed-off-by: Ronald Cron <ronald.cron@arm.com>
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 61f149f..7838525 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1,3 +1,21 @@
+#
+# CMake build system design considerations:
+#
+# - Include directories:
+# + Do not define include directories globally using the include_directories
+# command but rather at the target level using the
+# target_include_directories command. That way, it is easier to guarantee
+# that targets are built using the proper list of include directories.
+# + Use the PUBLIC and PRIVATE keywords to specifiy the scope of include
+# directories. That way, a target linking to a library (using the
+# target_link_librairies command) inherits from the library PUBLIC include
+# directories and not from the PRIVATE ones.
+# + Note: there is currently one remaining include_directories command in the
+# CMake files. It is related to ZLIB support which is planned to be removed.
+# When the support is removed, the associated include_directories command
+# will be removed as well as this note.
+#
+
cmake_minimum_required(VERSION 2.6)
if(TEST_CPP)
project("mbed TLS" C CXX)