hpclink

The HPCToolkit Performance Tools

2018/07/10

Version 2017.11

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

Table of Contents

Synopsis

hpclink [options] link-command

Description

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 hopclink 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 just use hpclink instead of the system linker in that command. One simple way of accomplishing this is to prepend hpclink to your makefile's link line. You may also wish to rename your binary (e.g. -o appname-hpclink}).

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

Arguments

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

Options: Informational

-v, --verbose
Emit verbose messages: display both the original and the modified link command lines.

-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).

-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).

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

--ga
Include wrappers for the Global Arrays library.

--memleak
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.

Examples

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.

    #!/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 ...

Notes

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

Version: 2017.11

License and Copyright

Copyright
© 2002-2018, Rice University.
License
See README.License.

Authors

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