hpclink is used to link HPCToolkit's performance measurement library (hpcrun(1) ) into a statically linked application.
hpclink [options] link-command
hpclink links HPCToolkit's performance measurement library into a statically linked application. (hpcrun(1) 's method for injecting its library into a dynamically linked application will not work with a statically linked applications.) Although hpclink does require a special link step, it requires neither source code modifications nor changes to compiling individual object files and libraries.
To link with hpclink, first locate the last step in your application's build, that is, the command that produces the final, statically linked binary. Then, use this command as link-command. One simple way of accomplishing this is to simply prepend the hpclink command to the front of a Makefile's link line. You may also wish to rename the binary name (-o app-hpclink).
To control HPCToolkit's performance measurement library during an application's execution, use 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.cLink an hpcrun-enabled application from object files and the math library.
hpclink gcc -o myprog -static main.o foo.o ... -lmMake 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, eg, IBM's XL compilers and the Pathscale compilers, interprocedural optimization interferes with hpclink's ability to link, causing hpclink to fail. In this case, it is necessary to disable interprocedural optimization. It is not necessary to disable all optimization, just interprocedural analysis.
Version: 2017.11 of 2011/09/19.
Rice HPCToolkit Research Group
Email: hpctoolkit-forum =at= rice.edu