intro_craype-api

intro_craype-api - Introduces the Cray PE API

IMPLEMENTATION

Cray Linux Environment (CLE)

DESCRIPTION

The CrayPE API enables software package integrators to build multiple versions of a software product modulefile, from a single set of source files, for a variety of target hardware platforms and software environments, and to define within each modulefile the dependencies and environmental considerations under which the build is applicable. This is done through the use of environment variables, which are used to predefine information specific to the build before using the craypkg-gen or pkg-config utilities to build the modulefile.

ENVIRONMENT VARIABLES

Product-specific Variables

Where $PE_PRODUCT is the specific product adding the library.

PE_PKGCONFIG_PRODUCTS

A colon-separated list of PE products to be applied.

$PE_PRODUCT_REQUIRED_PRODUCTS

Dependencies: if set, specifies a colon-separated list of PE_PKGCONFIG_PRODUCTS that the product needs.

$PE_PRODUCT_PKGCONFIG_LIBS

Specifies a colon-separated list of the top-level pkg-config files that are common to all compiler-drivers.

$PE_PRODUCT_C_PKGCONFIG_LIBS

Specifies a colon-separated list of the top-level C-specific pkg-config files.

$PE_PRODUCT_FORTRAN_PKGCONFIG_LIBS

Specifies a colon-separated list of the top-level Fortran-specific pkg-config files.

$PE_PRODUCT_CXX_PKGCONFIG_LIBS

Specifies a colon-separated list of the top-level C++-specific pkg-config files.

$PE_PRODUCT_MODULE_NAME

The name of the modulefile that will use $PE_PRODUCT. This is optional and is used for more-informative error messages.

pkg-config Path

PKG_CONFIG_PATH

The default search path for pkg-config.

If there is only one pkg-config directory and it should be used by all compilers, use this environment variable to define it. If desired, this can be used with $PE_PRODUCT_PKGCONFIG_LIBS to give users access to the API. If the module is loaded, pkg-config will have access to the .pc files of the product. Cray conventions dictate that all paths be appended before pkg-config is invoked.

Fixed Paths

PE_$PRGENV_FIXED_PKGCONFIG_PATH

Used when there is only one gen-compiler for a given programming environment.

$PE_PRODUCT_FIXED_PRGENV

A colon-separated list of programming environments that have fixed paths. If unset, defaults to no fixed programming environments.

Volatile Paths

Volatile paths can use the following elements, if driver decisions are required:

@PRGENV@ @PE_PRODUCT_DIR@ @PE_PRODUCT_GENCOMPILERS@ @PE_PRODUCT_TARGET@

$PE_PRODUCT_VOLATILE_PKGCONFIG_PATH

The path searched by the driver.

$PE_PRODUCT_VOLATILE_PRGENV

A colon-separated list of programming environments that use volatile paths.

If $PE_PRODUCT_VOLATILE_PKGCONFIG_PATH is set but $PE_PRODUCT_VOLATILE_PRGENV is unset, $PE_PRODUCT_VOLATILE_PRGENV defaults to all programming environments.

Directory Replacement Options

The directory replacement environment variables are the primary means by which targets and builds are differentiated. Any of the following can be used to replace the @$PE_PRODUCT_DIR@ element in a volatile path.

$PE_PRODUCT_DIR

This can be set to any string. It is used for default resolution when $PE_PRODUCT_DIR_$PRGENV is not set for the $PRGENV that is currently loaded.

$PE_PRODUCT_DIR_$PRGENV

This depends on the $PRGENV, can be set to any string, is used for specific programming environment resolution, and is used when $PE_PRODUCT_DIR_$PRGENV_$CPU_TARGET is not set for the $PRGENV that is currently loaded.

$PE_PRODUCT_DIR_$PRGENV_$CPU_TARGET

This can be set to any string and is used to replace non-standard CPU-dependent directories. If one compiler differs from standard names, this must be set for all programming environments.

Arbitrary Package Configuration Variables

$PE_PRODUCT_PKGCONFIG_VARIABLES

This environment variable enables the modulefile to define the pkg-config variables it needs.

This is a colon-separated list of variables. Each variable consists of two elements: the name element, which is the variable as it exists in the .pc files, and the action element, which is a predefined keyword to determine if or how the variable is set. For example: varname_@accelerator@

The valid action elements are:

@accelerator@ @cpu@ @network@ @prgrenv@ @default64@

Compiler and Target Selection

These environment variables are used to specify gencomps and CPU or accelerator targets. Gencomps and targets are special cases, because library directories that were compiled with older gen-compilers or CPU/accelerator targets will be selected if they are deemed compatible. For example, if the user is targeting the Intel Haswell CPU and the library directory was optimized for the older Intel Ivy Bridge CPU (and the directory follows CrayRSQUOs naming scheme and is labeled LDQUOivybridgeRDQUO), the driver will fill-in the CPU portion of the volatile path with LDQUOivybridge.RDQUO

Gencomps assume backward compatibility and will generate an error if the only library available is newer.

$PE_PRODUCT_GENCOMPILERS_$PRGENV

Specifies the gen compiler to be used for $PRGENV. This is compiler-dependent and must be a list of Cray-formatted gen-compiler directories, in descending version-number order. Driver selection will be based on the compiler module. This can be put into a volatile path as @$PE_PRODUCT_GENCOMPILERS@.

$PE_PRODUCT_GENCOMPILERS_$PRGENV_$CPU_TARGET

Specifies both the gencomp and CPU to be used for $PRGENV, with primary dependency on CPU and secondarily on compiler. This must be a list of Cray-formatted gen-compiler directories, in descending version-number order. Driver selection is CPU-fallback based. If specified, this can be put into a volatile path to replace both @$PE_PRODUCT_GENCOMPILERS@ and @$PE_PRODUCT_TARGET@.

$PE_PRODUCT_ACCEL_GENCOMPILERS_$PRGENV_$ACCELERATOR

Specifies both the gencomp and the accelerator to be used for $PRGENV, with primary dependency on the accelerator and secondarily on compiler. This must be a list of Cray-formatted gen-compiler directories, in descending version-number order. Driver selection is CPU-fallback based. If specified, this can be put into a volatile path to replace both @$PE_PRODUCT_GENCOMPILERS@ and @$PE_PRODUCT_ACCEL@.

$PE_PRODUCT_TARGET

Specifies the CPU/accelerator target module to be used for all programming environments and gen compilers. This must be the name of the directory to be used if the specific target is selected by the user. Driver selection is based on the target module. If specified, this can be put into a volatile path to replace @PE_PRODUCT_TARGET@.

$PE_PRODUCT_DIR_$PRGENV_DEFAULT64

This modulefile option maps to the default64 compiler flag and can be put into a volatile path if driver (flag) decisions are required. It can be set to any string, and $PRGENV can be omitted if it applies to all programming environments. If specified, this can be put into a volatile path to replace @PE_PRODUCT_DIR_DEFAULT64@.

$PE_PRODUCT_DIR_$PRGENV_OPENMP

This modulefile option maps to the openmp compiler flag and can be put into a volatile path if driver (flag) decisions are required. It can be set to any string, and $PRGENV can be omitted if it applies to all programming environments. If specified, this can be put into a volatile path to replace @PE_PRODUCT_DIR_OPENMP@.

EXAMPLES

This module is built for every programming environment with multiple cray/gcc compilers.

  1. Name that the driver will check for:

    prepend-path PE_PKGCONFIG_PRODUCTS PE_HDF5

  2. pkg-config files that the driver will need to reference:

    prepend-path PE_C_PKGCONFIG_LIBS hdf5_hl
prepend-path PE_FORTRAN_PKGCONFIG_LIBS hdf5hl_fortran
prepend-path PE_CXX_PKGCONFIG_LIBS hdf5_hl_cpp

  3. Programming environments that have only one library directory (and fully qualified paths that can be appended).

    setenv PE_HDF5_FIXED_PRGENV NVIDIA INTEL
prepend-path PE_NVIDIA_FIXED_PKGCONFIG_PATH /opt/cray/hdf5/1.12.1.1/NVIDIA/20.7/lib/pkg-config
prepend-path PE_INTEL_FIXED_PKGCONFIG_PATH /opt/cray/hdf5/1.12.1.1/INTEL/19.0/lib/pkgconfig

  4. A list of programing environments that have more than one compiler:

    setenv PE_HDF5_VOLATILE_PRGENV GNU CRAY
setenv PE_HDF5_GENCOMPILERS_GNU 47 46
setenv PE_HDF5_GENCOMPILERS_CRAY 81 74

  5. The volatile path with all variable elements:

    setenv PE_HDF5_VOLATILE_PKGCONFIG_PATH
/opt/cray/hdf5/1.8.10.773/@PRGENV@/@PE_HDF5_GENCOMPILERS@/lib/pkgconfig

This module is built for every programming environment with multiple cpu targets and gcc compilers

  1. Name that the driver will check for:

    prepend-path PE_PKGCONFIG_PRODUCTS PE_LIBSCI

  2. pkg-config files that the driver will need to reference:

    prepend-path PE_C_PKGCONFIG_LIBS libsci_mp:libsci
prepend-path PE_CXX_PKGCONFIG_LIBS libscicpp

  3. A list of programing environments that have more than one compiler. (PE_LIBSCI_VOLATILE_PRGENV is not set, therefore it defaults to all programming environments.)

    setenv PE_LIBSCI_GENCOMPILERS_CRAY_interlagos 74
setenv PE_LIBSCI_GENCOMPILERS_CRAY_mc12 74
setenv PE_LIBSCI_GENCOMPILERS_CRAY_sandybridge 81
setenv PE_LIBSCI_GENCOMPILERS_GNU_interlagos 46 47
setenv PE_LIBSCI_GENCOMPILERS_GNU_mc12 46 47
setenv PE_LIBSCI_GENCOMPILERS_GNU_sandybridge 47
setenv PE_LIBSCI_GENCOMPILERS_INTEL_interlagos 120
setenv PE_LIBSCI_GENCOMPILERS_INTEL_mc12 120
setenv PE_LIBSCI_GENCOMPILERS_NVIDIA_interlagos 20.7
setenv PE_LIBSCI_GENCOMPILERS_NVIDIA_mc12 20.7

  4. The volatile path with all variable elements:

    setenv PE_LIBSCI_VOLATILE_PKGCONFIG_PATH /opt/cray/libsci/12.0.01.3/@PRGENV@/@PE_LIBSCI_GENCOMPILER@/@PE_LIBSCI_TARGET@/lib/pkgconfig

  1. Name that the driver will check for:

    prepend-path PE_PKGCONFIG_PRODUCTS PE_MPICH

  2. pkg-config files that the driver will need to reference:

    prepend-path PE_C_PKGCONFIG_LIBS mpich
prepend-path PE_FORTRAN_PKGCONFIG_LIBS mpichf90
prepend-path PE_CXX_PKGCONFIG_LIBS mpichcxx

  3. Programming environments that have only one library directory (and fully qualified paths that can be appended).

    setenv PE_MPICH_FIXED_PRGENV INTEL
prepend-path PE_INTEL_FIXED_PKGCONFIG_PATH /opt/cray/mpt/5.6.2/gni/mpich-intel/120/lib/pkgconfig

  4. Programing environments that have more than one default64/default32 directory or gen-compiler.

    setenv PE_MPICH_VOLATILE_PRGENV GNU CRAY NVIDIA
setenv PE_MPICH_GENCOMPILERS_GNU 46 47
setenv PE_MPICH_GENCOMPILERS_NVIDIA 20.7
setenv PE_MPICH_GENCOMPILERS_CRAY 74

  5. The volatile path with all variable elements:

    prepend-path PE_MPICH_VOLATILE_PKGCONFIG_PATH /opt/cray/mpt/5.6.2/gni/mpich-@PRGENV@@PE_PRODUCT_DIR_DEFAULT64@/@PE_PRODUCTS_GENCOMPILERS@/lib/pkgconfig

SEE ALSO

craypkg-gen(1), pkg-config(1)