[v6.0.x] docs: warn agents about misuse of OMPI_HIDDEN - #14320
Merged
Conversation
Add guidance explaining when it is (and is not) safe to annotate a symbol with OMPI_HIDDEN, so that contributors -- and AI coding agents in particular -- do not reintroduce the class of build breakage that need to be fixed in the initial version of code present in PR #14317. As of Open MPI v6.0 the MPI interface is split across libmpi (Open MPI ABI) and libmpi_abi (standard MPI ABI), both of which link against the internal libopen_mpi. Many ompi_* symbols are defined in libopen_mpi but used from the bindings compiled into libmpi and libmpi_abi (for example, predefined handle objects like ompi_mpi_comm_parent and helpers like ompi_comm_split_type_hw_guided_support). Marking such a symbol OMPI_HIDDEN prevents it from being exported from libopen_mpi, so the links of both libmpi and libmpi_abi fail with unresolved symbols. Two files are updated: - AGENTS.md: add a "Golden rules" bullet describing the hazard and the rule of thumb -- if a symbol crosses a library boundary, use OMPI_DECLSPEC (or leave it un-annotated), never OMPI_HIDDEN. Only hide symbols that are certainly private to a single DSO. - docs/developers/source-code.rst: add a "Hiding symbols with OMPI_HIDDEN" subsection under Symbol Visibility that documents the v6.0 library structure and includes a warning admonition covering the unresolved-symbol failure mode and the same rule of thumb. These are documentation-only changes. CLAUDE.md is a symlink to AGENTS.md and is covered automatically. Signed-off-by: Howard Pritchard <howardp@lanl.gov> (cherry picked from commit d330d8e)
ompi-backport-bot
Bot
added
the
target:v6.0.x
hppritcha
approved these changes
Aug 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Backport of #14318 to
v6.0.x.Add guidance explaining when it is (and is not) safe to annotate a symbol with OMPI_HIDDEN, so that contributors -- and AI coding agents in particular -- do not reintroduce the class of build breakage that need to be fixed in the initial version of code present in PR #14317.
As of Open MPI v6.0 the MPI interface is split across libmpi (Open MPI ABI) and libmpi_abi (standard MPI ABI), both of which link against the internal libopen_mpi. Many ompi_* symbols are defined in libopen_mpi but used from the bindings compiled into libmpi and libmpi_abi (for example, predefined handle objects like ompi_mpi_comm_parent and helpers like ompi_comm_split_type_hw_guided_support). Marking such a symbol OMPI_HIDDEN prevents it from being exported from libopen_mpi, so the links of both libmpi and libmpi_abi fail with unresolved symbols.
Two files are updated:
AGENTS.md: add a "Golden rules" bullet describing the hazard and the rule of thumb -- if a symbol crosses a library boundary, use OMPI_DECLSPEC (or leave it un-annotated), never OMPI_HIDDEN. Only hide symbols that are certainly private to a single DSO.
docs/developers/source-code.rst: add a "Hiding symbols with OMPI_HIDDEN" subsection under Symbol Visibility that documents the v6.0 library structure and includes a warning admonition covering the unresolved-symbol failure mode and the same rule of thumb.
These are documentation-only changes. CLAUDE.md is a symlink to AGENTS.md and is covered automatically.