[ Home | Overview | Publications ] • [ Examples ] • [ Software/Downloads | Documentation/Questions ] • [ People | Acks ]

Building and Installing HPCToolkit




To reduce our maintenance efforts, we have opted to distribute HPCToolkit primarily in source form. The following prerequisites apply to our default source code distribution.

  1. HPCToolkit can be installed on the following platforms:

    Platform (Supported) Notes
    Linux + x86_64
    Linux + x86 (32-bit)
    Linux + ppc64
    Cray XT/XE/XK/XC (CNL + x86_64) Compute Node Linux ≥ 2.1
    IBM Blue Gene/Q (BG/Q kernel + ppc64)
    IBM Blue Gene/P (BG/P kernel + ppc32) BG/P kernel ≥ V1R3M0
    Platform (Legacy and Not Supported)
    Linux + IA64 testing (uses libunwind)
    Linux + MIPS-le (64 and n32) for SiCortex clusters; little endian MIPS (no longer tested)
  2. Compiler: HPCToolkit requires GNU GCC version 4.4 or later. Some vendor compilers that support GNU extensions may also work, but we recommend building with GNU gcc/g++. HPCToolkit also requires GNU make, preferably version 3.81 or later.

  3. To use hpcviewer and hpctraceviewer (HPCToolkit's graphical interface) on MacOS, Windows, or Linux, a Java runtime environment (JRE) ≥ 1.6 is required. Use the Oracle or IBM version; we have had problems with OpenJDK.

    To use hpcviewer and hpctraceviewer on Linux, GTK+ is also required.

    Note: Since HPCToolkit's databases are portable, we often install hpcviewer and hpctraceviewer on local laptops/desktops to avoid sending display traffic over relatively slow network connections.

  4. Highly recommended: To collect measurements based on hardware performance monitoring unit (PMU) information, PAPI ≥ 4.1 is required. Without PAPI, HPCToolkit can only collect measurements based on an operating system timer. (Exception: On IBM Blue Gene/P, PAPI is not required. On this system, HPCToolkit uses IBM's native Universal Performance Counters directly.)

    There are currently three ways to support PAPI on Linux-based OSs:

  5. Minor requirement: To use hpcsummary (a relatively minor tool), Python 2.x is required.

  6. Minor requirement: To build HPCToolkit's man pages, a variant of Perl 5 is required. We have successfully used versions 5.6.x - 5.10.x.

Downloading Source Code


Download HPCToolkit components as follows:

  1. Download hpctoolkit from GitHub.

    git clone https://github.com/HPCToolkit/hpctoolkit.git
  2. Download hpctoolkit-externals from GitHub.

    git clone https://github.com/HPCToolkit/hpctoolkit-externals.git

    Think of hpctoolkit-externals as a "package manager" that automatically configures and builds support libraries that hpctoolkit needs. It contains several external libraries. (Some of these libraries, like libelf and libxml2 are commonly found on Linux systems, but not always. Others, like OpenAnalysis and SymtabAPI are almost never available. Finally, a few packages, like GNU binutils have been heavily patched.) In some cases it may be possible to use versions of these packages that are already installed on your system. However, we do not support such configurations.

  3. Download binary releases of hpcviewer and hpctraceviewer for the platform on which your are building HPCToolkit.

    Note: It is perfectly reasonable to install hpcviewer and hpctraceviewer in multiple locations. Since HPCToolkit's databases are portable, we often install hpcviewer and hpctraceviewer on local laptops/desktops to avoid sending display traffic over relatively slow network connections from systems where we collect measurement data.

Building and Installing


The build and install follows autotools conventions (./configure && make && make install). In each case, more options are available by executing ./configure --help. See the README file for more details.

The typical build is as follows. Please note that a list of examples below provides configure commands for selected platforms.

  1. Configuring the perf_events sample source:

    HPCToolkit's configure command will automatically check the availability of the Linux perf_events interface on the build system. The test includes checking the existence of /usr/include/linux/perf_event.h and /proc/sys/kernel/perf_event_paranoid files. If the two files do not exist, it assumes the system does not support the perf_events interface.

    To profile on a remote machine that has different system or architecture configuration, one must download and build the libpfm4 library (http://perfmon2.sourceforge.net) and indicate its install directory by specifying the option --with-perfmon=<libpfm4_install_directory> to HPCToolkit's configure command.
  2. Build and install HPCToolkit's Externals, which typically does not require any special options; we recommend using the GCC compilers:

    cd hpctoolkit-externals
    mkdir BUILD && cd BUILD
    ../configure [CC=<c-compiler>] [CXX=<c++-compiler>] \
    make install
    make clean

    Externals is not persistent as HPCToolkit will copy everything it needs from the installation. Thus, the installation path <hpctoolkit-externals-install> should be a local path and not something like /usr. If --prefix is not supplied it will automatically be set to ./<Autoconf-host>.

    To specify a C and C++ compiler other than gcc and g++, use CC and CXX.

    Please be sure the Externals build completes before configuring HPCToolkit. (Note: After building Externals once, HPCToolkit can be configured and built several times using the same Externals installation.)

  3. Build and install HPCToolkit using commands similar to the following; we recommend using the GCC compilers:

    cd hpctoolkit
    mkdir BUILD && cd BUILD
    ../configure [CC=<c-compiler>] [CXX=<c++-compiler>] [MPICXX=<mpi-c++-compiler>] \
         --prefix=<hpctoolkit-install> \
         --with-externals=<hpctoolkit-externals-install> \

    make install

    The above commands will build HPCToolkit and install it into <hpctoolkit-install>.

    To specify a C and C++ compiler other than gcc and g++, use CC and CXX. To enable MPI support, (1) ensure a working mpicxx or mpiCC is in your shell's path; or (2) use MPICXX. (Naturally, CXX and MPICXX should be compatible; typically MPICXX is a wrapper for CXX.) To enable PAPI-based measurements, use the --with-papi option; it takes as an argument the path of your PAPI installation, <papi-install>.

    Because the HPCToolkit installation is self-contained, it may be renamed or moved to another location. All HPCToolkit Externals source code, build files and installations may be removed; all HPCToolkit source code and build files may be removed.

  4. Install hpcviewer and hpctraceviewer .

Selected Examples

The list below gives example HPCToolkit Externals and HPCToolkit configure commands (respectively) for selected platforms.

N.B.: These commands are designed to replace the respective commands in the above build instructions.

Infrequently Used Build Options


The following options may be useful in exceptional circumstances.

[Page last updated: 2017/01/20]

©2000-2018 Rice UniversityRice Computer Science