pat_opts

Display compile and link options that prepare files for performance instrumentation

Author:: Hewlett Packard Enterprise Development LP.
Copyright:: Copyright 2019-2024 Hewlett Packard Enterprise Development LP.
Manual section:: 1

SYNOPSIS

pat_opts [-a] option-type [compiler-designator [lite-mode]]

pat_opts -V

DESCRIPTION

The pat_opts utility displays the compiler and linker options necessary to properly prepare relocatable object files and the resulting executable file for instrumentation by performance utilities. The pat_opts utility is provided so that compiler commands that are not managed by the programming environment module can still take advantage of the instrumentation analysis provided by the perftools modules.

The pat_opts utility supports the following options and operands:

-V

Write the CrayPat version number to standard error

-a

The program created as a result of the link step may be executed on GPU hardware

The option-type specifies the position in the compiler command invocation in which the additional options are placed. Valid operands that write out the options to standard output are:

all, list

all option-types and their values

include

prepend -Icraypat-include-dir to existing compiler options

pre_compile

prepend to existing compiler options

post_compile

append to existing compiler options

pre_link

prepend to existing link options

post_link

append to existing link options

The compiler-designator specifies the name of the compiler environment for which the options apply. The following are valid operands:

amd

AMD compiler suite

aocc

AMD Optimizing C/C++ compiler suite

aomp

AMD Optimizing C/C++ compiler suite with OpenMP API support for AMD GPUs

cray

CCE compiler suite, as determined by the loaded cce module file

cray-clang

CCE C and C++ compiler suite

cray-ftn

CCE Fortran compiler suite

gnu

GCC compiler suite

hipcc

AMD GPU HIP compiler suite

intel

Intel compiler suite

intel-ftn

Intel Fortran compiler suite

nvidia

Nvidia compiler suite

If no compiler-designator is specified, the value of the environment variable PAT_OPTS_COMPILER is used. If PAT_OPTS_COMPILER is not defined, the compiler-designator is set to reflect what compiling environment module file is loaded. If no valid compiling environment module file is loaded, the compiler-designator used is cray-clang.

The lite-mode operand specifies the name of the perftools-lite module for which supporting options are generated. The following values are supported: events, gpu, hbm, lite, loops and samples. See the perftools-lite(4) man page for more information.

Inserting the options into the respective location in the compile and link steps facilitates the generation of relocatable object files and an executable file properly formatted for instrumentation processing by the pat_build utility. While not mandatory, using these options also benefit runtime instrumentation performed by the pat_run utility.

WARNINGS

The pat_opts utility exits with an error if an invalid option-type, compiler-designator or lite-mode is specified as an operand.

Load the perftools-base module file to gain access to the pat_opts utility.

Select the compiler-designator cray-ftn when compiling and linking using the ftn command and when the cce module file is loaded.

Select the compiler-designator intel-ftn when compiling and linking using the ftn command and when the intel or intel-oneapi module file is loaded.

Do not use the pat_opts utility with the cc, CC or ftn compiler commands available after loading a PrgEnv module file.

The link options returned by the pat_opts utility are not required when creating a shared object file.

ENVIRONMENT VARIABLES

PAT_OPTS_ARGS

Arguments that are supported by the compiler driver represented by the compiler-designator. Some arguments supported by the compiler-designator influence the options generated for supporting optimal runtime performance instrumentation.

PAT_OPTS_COMPILER

Specifies the name of the compiler-designator used by default.

EXAMPLES

Write to standard output the options to prepend to existing options used in compiling source code using the Intel compiler suite:

$ pat_opts pre_compile intel

Write to standard output the options to add as part of the link step using the compiler-designator as defined by having specified the GNU compiler suite:

$ export PAT_OPTS_COMPILER=gnu

$ pat_opts pre_link

$ pat_opts post_link

Use sh(1) command substitution to inject options into the command line for compiling source code using the CCE compiler suite:

$ craycc $(pat_opts pre_compile cray-clang) -c $(pat_opts post_compile cray-clang) pgm.c

If the environment variable PAT_OPTS_COMPILER is set to cray-clang before the command is executed, the compiler-designator operand cray-clang is not necessary.

Write to standard output the options to add to the compilation and link steps using the compiler-designator cray-clang that creates a program that when executed performs loop analysis.

$ pat_opts list cray-clang loops