pat_opts

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

NAME

pat_opts - Display compile and link options that prepare files for performance instrumentation

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:

allinea: Allinea compiler suite
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