hpclink

The HPCToolkit Performance Tools

2011/09/19

Version 5.4.2

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 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:

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
Verbose. Displays the original and modified command lines.

-V, --version
Print version information.

-h, --help
Print help.

Options: Linking

--memleak
Include HPCToolkit's memory leak detection libraries.

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

See Also

hpctoolkit(1) .
hpcrun(1) .

Version

Version: 5.4.2 of 2011/09/19.

License and Copyright

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

Authors

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