From cd3a1a7afa46bb8e747dd482e978955917a65feb Mon Sep 17 00:00:00 2001
From: Brice Goglin <Brice.Goglin@inria.fr>
Date: Wed, 20 Dec 2023 14:04:15 +0100
Subject: [PATCH] doxy: add a section about building with GNU Make and CMake

The GNU Make stuff is moved from the API example,
and CMake is added thanks to Florent Pruvost's example at
https://gitlab.inria.fr/solverstack/distrib/-/tree/master/cmake/test/hwloc

Refs #565

Signed-off-by: Brice Goglin <Brice.Goglin@inria.fr>
---
 README         | 10 ++----
 doc/hwloc.doxy | 82 ++++++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 74 insertions(+), 18 deletions(-)

diff --git a/README b/README
index 3be80e29bd..0db5ea0a95 100644
--- a/README
+++ b/README
@@ -417,14 +417,8 @@ return 0;
 }
 
 hwloc provides a pkg-config executable to obtain relevant compiler and linker
-flags. For example, it can be used thusly to compile applications that utilize
-the hwloc library (assuming GNU Make):
-
-CFLAGS += $(shell pkg-config --cflags hwloc)
-LDLIBS += $(shell pkg-config --libs hwloc)
-
-hwloc-hello: hwloc-hello.c
-     $(CC) hwloc-hello.c $(CFLAGS) -o hwloc-hello $(LDLIBS)
+flags. See Compiling software on top of hwloc's C API for details on building
+program on top of hwloc's API using GNU Make or CMake.
 
 On a machine 2 processor packages -- each package of which has two processing
 cores -- the output from running hwloc-hello could be something like the
diff --git a/doc/hwloc.doxy b/doc/hwloc.doxy
index 6e5a8158fe..931aca61b8 100644
--- a/doc/hwloc.doxy
+++ b/doc/hwloc.doxy
@@ -28,6 +28,7 @@
 <li> Chapters
  <ul>
  <li> \ref installation
+ <li> \ref useapi
  <li> \ref termsanddefs
  <li> \ref tools
  <li> \ref envvar
@@ -352,16 +353,8 @@ tree.
 \include examples/hwloc-hello.c
 
 hwloc provides a \c pkg-config executable to obtain relevant compiler
-and linker flags.  For example, it can be used thusly to compile
-applications that utilize the hwloc library (assuming GNU Make):
-
-\verbatim
-CFLAGS += $(shell pkg-config --cflags hwloc)
-LDLIBS += $(shell pkg-config --libs hwloc)
-
-hwloc-hello: hwloc-hello.c
-        $(CC) hwloc-hello.c $(CFLAGS) -o hwloc-hello $(LDLIBS)
-\endverbatim
+and linker flags. See \ref useapi for details on building program
+on top of hwloc's API using GNU Make or CMake.
 
 On a machine 2 processor packages -- each package of
 which has two processing cores -- the output from running \c
@@ -558,6 +551,75 @@ or GNU Autotools.
 
 
 
+\page useapi Compiling software on top of hwloc's C API
+
+A program using the hwloc C API (for instance with <tt>hwloc-hello.c</tt>
+presented in \ref interface_example) may be built with standard
+development tools.
+<tt>pkg-config</tt> provides easy ways to retrieve the required compiler
+and linker flags as described below, but it is not mandatory.
+
+
+\section useapi_gnumake Compiling on top of hwloc's C API with GNU Make
+
+Here's an example of Makefile for building <tt>hwloc-hello.c</tt>
+with GNU Make:
+
+\verbatim
+CFLAGS += $(shell pkg-config --cflags hwloc)
+LDLIBS += $(shell pkg-config --libs hwloc)
+
+hwloc-hello: hwloc-hello.c
+        $(CC) hwloc-hello.c $(CFLAGS) -o hwloc-hello $(LDLIBS)
+\endverbatim
+
+
+\section useapi_cmake Compiling on top of hwloc's C API with CMake
+
+Here's an example de <tt>CMakeLists.txt</tt> which shows variables
+obtained from <tt>pkg-config</tt> and how to use them:
+
+\verbatim
+cmake_minimum_required(VERSION 3.5)
+project(TEST_HWLOC C)
+include(FindPkgConfig)
+if(PKG_CONFIG_EXECUTABLE)
+  unset(HWLOC_FOUND CACHE)
+  pkg_search_module(HWLOC hwloc)
+  if(HWLOC_FOUND)
+    message(STATUS "HWLOC_LIBRARIES=${HWLOC_LIBRARIES}")
+    message(STATUS "HWLOC_LINK_LIBRARIES=${HWLOC_LINK_LIBRARIES}")
+    message(STATUS "HWLOC_LIBRARY_DIRS=${HWLOC_LIBRARY_DIRS}")
+    message(STATUS "HWLOC_LDFLAGS=${HWLOC_LDFLAGS}")
+    message(STATUS "HWLOC_LDFLAGS_OTHERS=${HWLOC_LDFLAGS_OTHERS}")
+    message(STATUS "HWLOC_INCLUDE_DIRS=${HWLOC_INCLUDE_DIRS}")
+    message(STATUS "HWLOC_CFLAGS=${HWLOC_CFLAGS}")
+    message(STATUS "HWLOC_CFLAGS_OTHER=${HWLOC_CFLAGS_OTHER}")
+  else()
+    message(FATAL_ERROR "HWLOC not found with pkg-config, add the path to hwloc.pc in PKG_CONFIG_PATH.")
+  endif()
+else()
+  message(FATAL_ERROR "PKG_CONFIG_EXECUTABLE: not found.")
+endif()
+
+add_executable(hwloc-hello hwloc-hello.c)
+target_include_directories(hwloc-hello PRIVATE ${HWLOC_INCLUDE_DIRS})
+target_compile_options(hwloc-hello PRIVATE ${HWLOC_CFLAGS})
+target_link_libraries(hwloc-hello PRIVATE ${HWLOC_LINK_LIBRARIES})
+target_link_options(hwloc-hello PRIVATE ${HWLOC_LDFLAGS})
+\endverbatim
+
+The project may be built with:
+\verbatim
+cmake -B build
+cmake --build build --verbose
+\endverbatim
+
+The built binary is then available under <tt>build/hwloc-hello</tt>.
+
+
+
+
 \page termsanddefs Terms and Definitions
  
 \section termsanddefs_objects Objects