macOS: investigate Python module discovery fragility

[tallpsmith]

Problem

The macOS CI currently includes this hack in .github/workflows/macOS.yml (line 256):

export PYTHONPATH="/usr/local/lib/python3.13/site-packages:${PYTHONPATH:-}"

This papers over a deeper issue: when PCP installs its Python module (pcp) via setup.py install, the module lands in a location determined by the build-time --prefix flag. At runtime, the Python executable specified by PCP_PYTHON_PROG in /etc/pcp.conf may not have that location in its sys.path.

This is a tracking issue to document the problem and investigate solutions when ready. No code changes proposed at this time.

Known fragility points

Area	File	Issue
Config path burning	src/include/pcp.conf.in:210	PCP_PYTHON_PROG absolute path baked at build time — breaks if Python moves (e.g., Homebrew upgrade)
Fallback to bare python	src/pmcd/pmdaproc.sh:840	python=${PCP_PYTHON_PROG:-python} — on modern macOS /usr/bin/python doesn't exist
Module install prefix	src/include/builddefs.in:713,718	--prefix fixed at build time, no runtime discovery
Silent import failures	src/pmcd/pmdaproc.sh:850	$python -c 'from pcp import pmda' 2>/dev/null — failures hidden, Install proceeds anyway
CI version pinning	.github/workflows/macOS.yml:18	Hardcoded Python 3.13
Manual PYTHONPATH	.github/workflows/macOS.yml:256	Hardcoded /usr/local/lib/python3.13/site-packages

The runtime chain

pmpython (shebang: #!/usr/bin/env pmpython)
  → pcp-python.sh
    → sources /etc/pcp.conf (reads PCP_PYTHON_PROG)
      → exec $PCP_PYTHON_PROG script.py
        → script does: from pcp import pmapi
          → needs pcp module in sys.path of THAT Python

Every link in this chain is fragile on macOS because Homebrew moves Python between minor versions and the build-time assumptions about paths become stale.

Why we're deferring

These are upstream PCP architectural decisions affecting all platforms. The pmpython wrapper, pcp.conf path burning, and setup.py prefix handling are deeply embedded in the build system. Fixing them properly may require coordination with the broader PCP project.

The current workarounds (PYTHONPATH hacks) are functional. #2539 improves the build-time story but doesn't change the runtime discovery chain.

What to investigate when ready

• Whether PCP_PYTHON_PROG could use #!/usr/bin/env python3 style discovery instead of an absolute path
• Whether PCP's Python module could install to a location always in the target Python's sys.path
• Whether the pmpython wrapper could add PCP's module directory to sys.path before exec
• Impact on other platforms (Linux, FreeBSD) of any changes
• Whether there's existing PCP build system magic handling this on Linux that we're missing on macOS