Hardware Locality (hwloc): Installation

Hardware Locality (hwloc) 2.11.2

Installation

hwloc (https://www.open-mpi.org/projects/hwloc/) is available under the BSD license. It is hosted as a sub-project of the overall Open MPI project (https://www.open-mpi.org/). Note that hwloc does not require any functionality from Open MPI – it is a wholly separate (and much smaller!) project and code base. It just happens to be hosted as part of the overall Open MPI project.

# Basic Installation

Installation is the fairly common GNU-based process:

    shell$ ./configure --prefix=...
    shell$ make
    shell$ make install

The hwloc command-line tool "lstopo" produces human-readable topology maps, as mentioned above. Running the "lstopo" tool is a good way to check as a graphical output whether hwloc properly detected the architecture of your node.

# Optional Dependencies

lstopo may also export graphics to the SVG and "fig" file formats. Support for PDF, Postscript, and PNG exporting is provided if the "Cairo" development package (usually `cairo-devel` or `libcairo2-dev`) can be found in "lstopo" when hwloc is configured and build.

The hwloc core may also benefit from the following development packages:

- libpciaccess for full I/O device discovery (`libpciaccess-devel` or `libpciaccess-dev` package). On Linux, PCI discovery may still be performed (without vendor/device names) even if libpciaccess cannot be used.
- AMD or NVIDIA OpenCL implementations for OpenCL device discovery.
- the NVIDIA CUDA Toolkit for CUDA device discovery. See How do I enable CUDA and select which CUDA version to use?.
- the NVIDIA Management Library (NVML) for NVML device discovery. It is included in CUDA since version 8.0. Older NVML releases were available within the NVIDIA GPU Deployment Kit from https://developer.nvidia.com/gpu-deployment-kit .
- the NV-CONTROL X extension library (NVCtrl) for NVIDIA display discovery. The relevant development package is usually `libXNVCtrl-devel` or `libxnvctrl-dev`. It is also available within nvidia-settings from ftp://download.nvidia.com/XFree86/nvidia-settings/ and https://github.com/NVIDIA/nvidia-settings/ .
- the AMD ROCm SMI library for RSMI device discovery. The relevant development package is usually `rocm-smi-lib64` or `librocm-smi-dev`. See How do I enable ROCm SMI and select which version to use?.
- the oneAPI Level Zero library. The relevant development package is usually `level-zero-dev` or `level-zero-devel`.
- libxml2 for full XML import/export support (otherwise, the internal minimalistic parser will only be able to import XML files that were exported by the same hwloc release). See Importing and exporting topologies from/to XML files for details. The relevant development package is usually `libxml2-devel` or `libxml2-dev`.
- libudev on Linux for easier discovery of OS device information (otherwise hwloc will try to manually parse udev raw files). The relevant development package is usually `libudev-devel` or `libudev-dev`.
- libtool's ltdl library for dynamic plugin loading if the native dlopen cannot be used. The relevant development package is usually `libtool-ltdl-devel` or `libltdl-dev`.

PCI and XML support may be statically built inside the main hwloc library, or as separate dynamically-loaded plugins (see the Components and plugins section).

Also note that if you install supplemental libraries in non-standard locations, hwloc's configure script may not be able to find them without some help. You may need to specify additional CPPFLAGS, LDFLAGS, or PKG_CONFIG_PATH values on the configure command line.

For example, if libpciaccess was installed into /opt/pciaccess, hwloc's configure script may not find it by default. Try adding PKG_CONFIG_PATH to the ./configure command line, like this:

    ./configure PKG_CONFIG_PATH=/opt/pciaccess/lib/pkgconfig ...

Note that because of the possibility of GPL taint, the `pciutils` library `libpci` will not be used (remember that hwloc is BSD-licensed).

# Installing from a Git clone

Additionally, the code can be directly cloned from Git:

    shell$ git clone https://github.com/open-mpi/hwloc.git
    shell$ cd hwloc
    shell$ ./autogen.sh

Note that GNU Autoconf >=2.63, Automake >=1.11 and Libtool >=2.2.6 are required when building from a Git clone.

Nightly development snapshots are available on the web site, they can be configured and built without any need for Git or GNU Autotools.