Hardware Locality (hwloc): Installation

Hardware Locality (hwloc) 2.14.0rc1

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 SMI library for RSMI device discovery. The relevant development package is usually amd-smi-lib or libamd-smi-dev. If AMD SMI isn't available, the old ROCm SMI library may be used instead (rocm-smi-lib or librocm-smi-dev package). See How do I enable AMD/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. The implementation must be recent enough to support zesDriverGetDeviceByUuidExp()
- 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 on Unix systems 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.