diff --git a/README b/README
index 3be80e29b..0db5ea0a9 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 6e5a8158f..931aca61b 100644
--- a/doc/hwloc.doxy
+++ b/doc/hwloc.doxy
@@ -28,6 +28,7 @@
Chapters
- \ref installation
+
- \ref useapi
- \ref termsanddefs
- \ref tools
- \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 hwloc-hello.c
+presented in \ref interface_example) may be built with standard
+development tools.
+pkg-config 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 hwloc-hello.c
+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 CMakeLists.txt which shows variables
+obtained from pkg-config 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 build/hwloc-hello.
+
+
+
+
\page termsanddefs Terms and Definitions
\section termsanddefs_objects Objects