Load the bridge library from outside the VUnit output path

[ru551n]

The bridge library ended up in the VUnit output path: the prebuilt Windows DLL was copied to <output path>/python_bridge/..., and Linux/macOS and Windows gcc builds were compiled there. Where the output path doesn't allow executing files (a noexec mount, AppLocker or similar), the simulator can't load the library.

Changes

• All bridge libraries go to the user's cache directory instead of the output path: the prebuilt Windows DLLs, copied under the short name vunit_python_bridge.dll as before, and the libraries built for Linux/macOS, Windows gcc and Questa FLI. The default locations are:

  • ~/.cache/vunit-python-bridge on Linux, or under XDG_CACHE_HOME if set,
  • ~/Library/Caches/vunit-python-bridge on macOS,
  • %LOCALAPPDATA%\vunit-python-bridge on Windows.

  Builds are keyed by what they were built from, so projects can share the cache.

• VUNIT_PYTHON_BRIDGE_LIBRARY_DIR selects another directory on every platform.

• Configuration. The library used to read vunit_python_bridge.cfg from its own directory, which is why it had to live in the output path. The config is per project, so it stays in <output path>/python_bridge. New run_env hooks for NVC, GHDL and Questa/ModelSim pass its path in VUNIT_PYTHON_BRIDGE_CONFIG. config.c reads that variable, with _wgetenv on Windows so non-ASCII paths survive, and falls back to the library's directory when it isn't set.

• Why the DLL is still copied. The first version of this PR loaded the DLL straight from the package. GHDL's VHPIDIRECT library token then became the versioned file name, which is longer than the 32 characters GHDL accepts, and Windows GHDL CI crashed.

• Docs and release note. README, the "How it works" section of the user guide, and release_notes/0.2.0.md.

• Unwritable library directory. When the library directory cannot be created or written (e.g. HOME=/ with a random UID in a container), the setup fails with a PythonBridgeError naming the directory, whether it is the default or set by VUNIT_PYTHON_BRIDGE_LIBRARY_DIR, and asking for that variable to be set to a writable directory. There is no fallback to the output path.

• Windows load check. Windows has no noexec mount, but an execution policy (AppLocker, Windows Defender Application Control, Smart App Control) can block libraries in a directory, and NVC and GHDL then only report that loading failed. The setup loads the VHPIDIRECT library once, with winmode=0 so dependencies are searched like the simulators' LoadLibrary does, and unloads it again. Errors 1260, 577 and 4551 (blocked by policy, invalid image hash, integrity policy violation) fail with a message pointing to VUNIT_PYTHON_BRIDGE_LIBRARY_DIR. Any other load error fails with its reason. The FLI variant is not checked, since it needs vsim's libraries. Overhead: one load and unload per setup, well under a millisecond (measured 0.16 ms for the Linux equivalent).

• Linux/macOS load check (taken from Test on RHEL 9 and 10 with every GHDL backend and NVC, and report why the bridge does not load #20). After the noexec check, the setup loads the VHPIDIRECT library with ctypes.CDLL, the counterpart of the Windows check. Any other load failure, for example a missing libpython, fails with the loader's reason, which NVC and GHDL leave out of "cannot load VHPIDIRECT shared library". The FLI variant is not checked, since it needs vsim's symbols. It does not catch a LD_LIBRARY_PATH that is dropped between VUnit and GHDL mcode/llvm-jit, since it loads the library by absolute path; that case is documented below.

• noexec check. On Linux and macOS, a library directory on a file system mounted noexec (e.g. a tmpfs in a rootless podman container) now fails the setup with a PythonBridgeError naming the directory and VUNIT_PYTHON_BRIDGE_LIBRARY_DIR. Without it, GHDL only says cannot load VHPIDIRECT shared library 'libvunit_python_bridge.so'.

• rpath for GHDL llvm and gcc. The elaboration hook also passes -Wl,-Wl,-rpath,<library dir> (GHDL hands what follows -Wl, to the compiler driver). A linked simulation then finds the bridge without the LD_LIBRARY_PATH of the run environment, so a ghdl wrapper that drops it, or a re-run by hand, works. It still needs VUNIT_PYTHON_BRIDGE_CONFIG, and fails with a message naming it when that is missing. mcode and llvm-jit can't be helped this way: GHDL stores the VHPIDIRECT library name in a 32-character field, too short for an absolute path. The user guide documents that a wrapper must keep LD_LIBRARY_PATH and VUNIT_PYTHON_BRIDGE_CONFIG.

Tests

• pytest:

  • default library directory per platform, and the override,
  • the config path in the output path,
  • the run_env hook for every simulator.

  The suite sets VUNIT_PYTHON_BRIDGE_LIBRARY_DIR to temporary directories, so it never writes to the real user cache.

• CI:

  • The Windows feature tests use the override, with a space in the path, and check that the gcc build lands there and nothing lands in the output path.
  • The wheel tests check that no library is in the output path, and on Windows that the prebuilt DLL was copied to the cache directory and nothing was compiled.

• Locally (Linux):

  • Full suite on NVC with the default location: the library is in ~/.cache/vunit-python-bridge and the output path only holds the config and generated VHDL.
  • Suite and example on NVC and GHDL (mcode) with the override.
  • pytest: 88 passed.

• AlmaLinux 9.6, rootless podman, GHDL mcode, dnf python3.11:

  • unittest: 89 passed, including the new noexec test.
  • Output path on a noexec tmpfs: the bridge now loads (107 of 108 feature tests; the remaining failure, "Test importing a module with a relative file name", also fails on main).
  • Library directory on a noexec tmpfs: the setup fails with the new message.

• Linux/macOS load check: a new unit test puts a broken library in a fresh library directory and checks the message names it with the loader's reason. The two tests with a stub compiler mock the load. In podman, AlmaLinux 9.6 with Python 3.11 and GHDL 6.0.0 mcode, and Ubuntu 24.04 with Python 3.12 and NVC 1.22.1: pytest 95 passed and feature tests 108 of 108 on both, and a corrupt cached library fails the setup with does not load: ... file too short.

• Windows load check: three unit tests with ctypes mocked (policy errors, other errors, unload with a 64-bit handle). The 13 Windows CI jobs (prebuilt DLL and gcc build, NVC and GHDL, wheel tests) pass, so the check does not reject a library that loads. The policy-blocked case is not tested on a real machine.

• AlmaLinux 9.6, GHDL mcode, unwritable library directory:

  • UID 1001 with HOME=/: Cannot build the Python bridge library in /.cache/vunit-python-bridge (the default): [Errno 13] Permission denied: '/.cache'. Set VUNIT_PYTHON_BRIDGE_LIBRARY_DIR to a writable directory.
  • UID 1001 with the variable in a root-only directory: the same message with (set by VUNIT_PYTHON_BRIDGE_LIBRARY_DIR).
  • UID 1001 with the variable set to a writable directory: passes.
  • Two new unit tests (an uncreatable directory whose parent is a file, so they also hold as root).

• AlmaLinux 9.6, GHDL master llvm (LLVM 19):

  • Full suite: 107 of 108 before and after (same unrelated failure).
  • The linked simulation has the RPATH of the library directory.
  • ghdl wrapper dropping LD_LIBRARY_PATH: before, error while loading shared libraries: libvunit_python_bridge.so; after, passes.
  • ghdl wrapper running env -i: fails with Failed to open the Python bridge configuration file (VUNIT_PYTHON_BRIDGE_CONFIG is not set).
  • Not tested: the gcc backend (same GHDL driver code for -Wl,), left to CI.

• Not tested locally: the Windows code in config.c (left to the Windows CI jobs), and GHDL llvm/gcc (left to CI).

Not in this PR

The Riviera-PRO/Active-HDL VHPI application is still built under <output path>/<simulator>/libraries by foreign_application.py, so it has the same problem. It needs a separate change.

🤖 Generated with Claude Code