The HPCToolkit Performance Tools


Version 2023.03.01-develop

hpclink is used to link HPCToolkit's performance measurement library (hpcrun(1) ) into a statically linked application.

Table of Contents


hpclink [options] link-command


hpclink is a wrapper around the system linker which injects the HPCToolkit performance measurement library when statically linking an application. If your application is statically linked you must use hpclink at link time instead of hpcrun(1) at run time because hpcrun's dynamic mechanism for injecting the library only works for dynamically linked applications. Although using hpclink does require changing your link step, it does not require changes to your source code or to the way you compile individual files and libraries.

To link with hpclink, first locate the last step in your application's build system (the command that produces the final, statically linked binary). Then prepend hpclink to the front of the link line. It may be convenient to use two link lines, the original native one and an hpclink line with an alternate output name (eg, appname.hpc).

To control HPCToolkit's performance measurement during application execution, set one or more of the following environment variables:


The link command line for producing a statically linked application binary. It typically has the following form:
      compiler [link-options] object-files libraries

Options: Informational

-v, --verbose
Verbose: display the full link line as generated by hpclink.

-V, --version
Print version information.

-h, --help
Print help.

Options: Linking

-dw, --double-wrap
Double quote the linker wrap options introduced by hpclink, i.e.emit -Wl,-Wl instead of -Wl. Use this to work around problems with the Berkeley UPC compiler script (rarely necessary).

Override and disable gprof instrumentation This option is only useful when using hpclink to add HPCToolkit's measurement subsystem to a statically-linked application that has been compiled with -pg. One can't measure performance with HPCToolkit when gprof instrumentation is active in the same execution.

-fe dir, --front-end dir
In a cross-compile link, use the current install tree for back-end libraries and use dir for the install directory (prefix) of front-end tools (hpcfnbounds).

Include a library to track and report the number of io bytes read and written.

Include wrappers for the Global Arrays library.

Include HPCToolkit's memory leak detection libraries.

--plugin name
Add the libraries and wrapped symbols specified by plugin name in the plugins directory.

-u symbol, --undefined symbol
Pass symbol to the linker as an undefined symbol. This option is rarely needed, but if hpclink fails with an undefined reference to __real_foo then the option ``-u foo'' may induce the linker to correctly link this symbol. May be used multiple times.


Compile the "hello, world" program with gcc and link in the hpcrun code statically.

    hpclink gcc -o hello -g -O -static hello.c
Link an hpcrun-enabled application from object files and the math library.

    hpclink gcc -o myprog -static main.o foo.o ... -lm
Make both native and hpcrun-enabled versions of an application from object files and system libraries with the mpixlc compiler. Note that the argument list to the hpclink command is exactly the command to build the native version except for the name of the output file.

    mpixlc -o myprog main.o foo.o ... -lm -lpthread
    hpclink mpixlc -o myprog.hpc main.o foo.o ... -lm -lpthread

Launching Static Programs

For dynamically linked binaries, the hpcrun script is used to launch programs and set environment variables, but on systems with separate compute nodes, this is often not available. In this case, the HPCRUN_EVENT_LIST environment variable is used to pass the profiling events to the hpcrun code.

    export HPCRUN_EVENT_LIST="PAPI_TOT_CYC@4000000"
    myprog arg ...
For example, on a Cray XT system, you might launch a job with a PBS script such as the following.

    #PBS -l size=64
    #PBS -l walltime=01:00:00
    export HPCRUN_EVENT_LIST="PAPI_TOT_CYC@4000000 PAPI_L2_TCM@400000"
    aprun -n 64 ./myprog arg ...
The IBM Blue Gene system uses the --env option to pass environment variables, so you might launch a job with a command such as the following.

    qsub -t 60 -n 64 --env HPCRUN_EVENT_LIST="WALLCLOCK@1000" \
        /path/to/myprog arg ...


The command line passed to hpclink must produce a statically linked binary and the hpclink script will fail if it does not.

With some compilers, e.g. IBM's XL family, interprocedural optimization interferes with hpclink and causes failure. If this occurs interprocedural optimization must be disabled. All other optimizations can remain enabled.

See Also

hpctoolkit(1) .
hpcrun(1) .


Version: 2023.03.01-develop

License and Copyright

© 2002-2023, Rice University.


Mark Krentel
Rice HPCToolkit Research Group
Email: hpctoolkit-forum =at= rice.edu
WWW: http://hpctoolkit.org.