Skip to content

pkgconfig.md

Latest commit

 

History

History
110 lines (89 loc) · 3.74 KB

pkgconfig.md

File metadata and controls

110 lines (89 loc) · 3.74 KB

pkg-config and .pc Files

This document explains what pkg-config does, why the AFAR modules rely on it, and how to maintain or repair .pc files when something breaks.

What is pkg-config?

pkg-config is a small tool that reports compile and link flags for libraries. Build systems (CMake, Autotools, Meson, Makefiles) call it to discover:

  • Include paths (-I...)
  • Library paths (-L...) and link flags (-l...)
  • Version information

The flags come from .pc files. Each .pc file describes a library.

What is a .pc file?

A .pc file is a small text file with key/value metadata. Example:

prefix=/opt/cray/pe/mpich/9.0.1/ofi/amd/6.0
libdir=${prefix}/lib
includedir=${prefix}/include

Name: mpichf90
Description: Cray MPICH Fortran module
Version: 9.0.1
Libs: -L${libdir} -lmpifort_amd -lmpi_amd
Cflags: -I${includedir}/mpich4.3.1

pkg-config reads this and prints flags:

pkg-config --cflags mpichf90
pkg-config --libs mpichf90

How pkg-config finds .pc files

pkg-config searches:

  1. Its built-in default directories.
  2. Directories listed in PKG_CONFIG_PATH (colon-separated).

AFAR uses Cray's PE_AMD_FIXED_PKGCONFIG_PATH and mirrors it into PKG_CONFIG_PATH at wrapper invocation time so build systems find the right MPI metadata even if modules are swapped after afar-prgenv is loaded.

Why AFAR relies on pkg-config

AFAR needs stable, compiler-agnostic metadata for:

  • MPI Fortran module includes (mpichf90.pc chooses mpich3.4a2 vs mpich4.3.1).
  • Cray libraries (HDF5, FFTW, DSMML, LibSci, PnetCDF) that may not ship complete or AFAR-compatible .pc files.

When .pc files are missing or wrong, pkg-config returns empty flags, and configure/build steps fail.

AFAR-provided .pc files

Generated by scripts/generate_afar_modules.sh:

  • pkgconfig/rocm-afar-<ver>.pc
  • pkgconfig/<ver>/mpich3.4a2/mpichf90.pc
  • pkgconfig/<ver>/mpich4.3.1/mpichf90.pc

The wrappers pick the correct MPICH flavor at compile time and prepend the matching directory to PE_AMD_FIXED_PKGCONFIG_PATH.

Local shim .pc files

Some Cray modules do not provide usable .pc files. AFAR can generate shims from the loaded module environment:

afar_modules/scripts/generate_pkgconfig_shims.sh

The script writes shims under afar_modules/pkgconfig/shims/<AFAR_VERSION> and prints that directory. The wrappers append AFAR_PKGCONFIG_SHIM_DIR to PKG_CONFIG_PATH, so shims are discovered without overriding vendor files.

Automatic shim refresh

The wrappers can regenerate shim files automatically, which keeps builds working regardless of whether a library module is loaded before or after afar-prgenv. When AFAR_PKGCONFIG_SHIM_AUTO is unset or set to 1, the wrappers compute a key from the active module environment and rerun generate_pkgconfig_shims.sh whenever that key changes.

To disable the automatic refresh:

export AFAR_PKGCONFIG_SHIM_AUTO=0

The last computed key is stored in AFAR_PKGCONFIG_SHIM_KEY for diagnostics.

How to debug pkg-config

Useful checks:

pkg-config --modversion mpichf90
pkg-config --cflags mpichf90
pkg-config --libs mpichf90
pkg-config --debug --cflags hdf5 2>&1 | head -n 20

If the output is empty:

  • Confirm the module is loaded.
  • Check PKG_CONFIG_PATH and PE_AMD_FIXED_PKGCONFIG_PATH.
  • Regenerate shims if needed.

Manual maintenance tips

When editing or creating .pc files:

  • Keep prefix, libdir, and includedir consistent.
  • Use Libs: for link flags and Cflags: for include flags.
  • Prefer relative variables (${prefix}) so paths move cleanly.
  • Validate with pkg-config --cflags and a quick compile.

If a library ships Fortran .mod files that are incompatible with AFAR, prefer a local shim module compiled with AFAR and point -I to that shim directory before the vendor path.