Compiling software on top of hwloc's C API

A program using the hwloc C API (for instance with `hwloc-hello.c` presented in API 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.

# 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:

    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)

# 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:

    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})

The project may be built with:

    cmake -B build
    cmake --build build --verbose

The built binary is then available under `build/hwloc-hello`.