document some examples on how to interface StarPU in a CMake-based application

doc/doxygen/chapters/101_building.doxy

@@ -2,7 +2,7 @@
  *
  * Copyright (C) 2010-2018                                CNRS
  * Copyright (C) 2009-2011,2013-2016                      Université de Bordeaux
- * Copyright (C) 2011-2012                                Inria
+ * Copyright (C) 2011-2012,2018                           Inria
  *
  * StarPU is free software; you can redistribute it and/or modify
  * it under the terms of the GNU Lesser General Public License as published by
@@ -210,6 +210,100 @@ CFLAGS          +=      $$(pkg-config --cflags starpu-1.3)
 LDFLAGS         +=      $$(pkg-config --libs starpu-1.3)
 \endverbatim
 
+\subsection IntegratingStarPUInABuildSystem Integrating StarPU in a Build System
+
+\subsubsection StarPUInCMake Integrating StarPU in a CMake Build System
+
+This section shows a minimal example integrating StarPU in an existing application's CMake build system.
+
+Let's assume we want to build an executable from the following source code using CMake:
+\code{.c}
+#include <starpu.h>
+int main(void)
+{
+    int ret;
+    ret = starpu_init(NULL);
+    if (ret != 0)
+    {
+        return 1;
+    }
+    starpu_shutdown();
+
+    return 0;
+}
+\endcode
+
+The \c CMakeLists.txt file below uses the Pkg-Config support from CMake to
+autodetect the StarPU installation and library dependences (such as
+<c>libhwloc</c>) provided that the <c>PKG_CONFIG_PATH</c> variable is set, and
+is sufficient to build a statically-linked executable. This example has been
+successfully tested with CMake 3.2, though it may work with earlier CMake 3.x
+versions. 
+
+\code{CMakeLists.txt}
+cmake_minimum_required (VERSION 3.2)
+project (hello_starpu)
+
+find_package(PkgConfig)
+pkg_check_modules(STARPU REQUIRED starpu-1.3)
+if (STARPU_FOUND)
+    include_directories (${STARPU_INCLUDE_DIRS})
+    link_directories    (${STARPU_STATIC_LIBRARY_DIRS})
+    link_libraries      (${STARPU_STATIC_LIBRARIES})
+else (STARPU_FOUND)
+    message(FATAL_ERROR "StarPU not found")
+endif()
+
+add_executable(hello_starpu hello_starpu.c)
+\endcode
+
+The following \c CMakeLists.txt implements an alternative, more complex
+strategy, still relying on PkgConfig, but also taking into account additional
+flags. While more complete, this approach makes CMake's build types (Debug,
+Release, ...) unavailable because of the direct affectation to variable
+<c>CMAKE_C_FLAGS</c>. If both the full flags support and the build types
+support are needed, the \c CMakeLists.txt below may be altered to work with
+<c>CMAKE_C_FLAGS_RELEASE</c>, <c>CMAKE_C_FLAGS_DEBUG</c>, and others as needed.
+This example has been successfully tested with CMake 3.2, though it may work
+with earlier CMake 3.x versions. 
+
+\code{CMakeLists.txt}
+cmake_minimum_required (VERSION 3.2)
+project (hello_starpu)
+
+find_package(PkgConfig)
+pkg_check_modules(STARPU REQUIRED starpu-1.3)
+
+# This section must appear before 'add_executable'
+if (STARPU_FOUND)
+    # CFLAGS other than -I
+    foreach(CFLAG ${STARPU_CFLAGS_OTHER})
+        set (CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${CFLAG}")
+    endforeach()
+
+    # Static LDFLAGS other than -L
+    foreach(LDFLAG ${STARPU_STATIC_LDFLAGS_OTHER})
+        set (CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${LDFLAG}")
+    endforeach()
+
+    # -L directories
+    link_directories(${STARPU_STATIC_LIBRARY_DIRS})
+else (STARPU_FOUND)
+    message(FATAL_ERROR "StarPU not found")
+endif()
+
+add_executable(hello_starpu hello_starpu.c)
+
+# This section must appear after 'add_executable'
+if (STARPU_FOUND)
+    # -I directories
+    target_include_directories(hello_starpu PRIVATE ${STARPU_INCLUDE_DIRS})
+
+    # Static -l libs
+    target_link_libraries(hello_starpu PRIVATE ${STARPU_STATIC_LIBRARIES})
+endif()
+\endcode
+
 \subsection RunningABasicStarPUApplication Running a Basic StarPU Application
 
 Basic examples using StarPU are built in the directory