hpclink is used to link HPCToolkit's performance measurement library (hpcrun(1) ) into a statically linked application.
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:
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
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.
#!/bin/sh
#PBS -l size=64
#PBS -l walltime=01:00:00
cd $PBS_O_WORKDIR
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.
Version: 2023.03.01-develop
Mark Krentel
Rice HPCToolkit Research Group
Email: hpctoolkit-forum =at= rice.edu
WWW: http://hpctoolkit.org.