| 文件 | 最后提交记录 | 最后更新时间 |
|---|---|---|
docs: fix spelling and grammar throughout RST docs Correct clear spelling mistakes, repeated words, and grammatical issues across the RST documentation tree. This includes developer and user guides, tuning and installation docs, release notes, and MPI/OpenSHMEM man-page sources. Also fix misspelled RST labels and update their references so the documentation links continue to resolve correctly. Validation performed: - aspell scan over docs/**/*.rst with false positives manually filtered - targeted rg sweeps for common misspellings, repeated words, and grammar patterns - git diff --cached --check Signed-off-by: Jeff Squyres <jeff@squyres.com> | 3 个月前 | |
Document Open MPI's MPI Forum ABI support Open MPI v6.0.0 adds support for the MPI Forum (standard) ABI defined by MPI-5.0 for C applications, alongside Open MPI's own long-standing ABI. The user-facing documentation did not yet describe this new, separate binary interface: how to build against it, its current limitations, or how it relates to Open MPI's existing ABI-compatibility guarantees. This adds and reorganizes that documentation. High points of the documentation in this commit: * A new "Building MPI applications using the MPI Forum ABI" page (docs/building-apps/mpi-forum-abi.rst) explaining what the MPI Forum ABI is, that it is new in v6.0.0 and distinct from the Open MPI ABI, and its limitations: the application must be dynamically linked, run with a matching launcher, and written in C. * How to build and run standard-ABI C applications with the mpicc_abi wrapper and libmpi_abi -- the wrapper adds the standard ABI header directory ($prefix/include/standard_abi) and links libmpi_abi -- plus the --showme flags and the effect of configuring with --disable-standard-abi. * How to check ABI support at run time with MPI_Abi_get_version, which reports version 1.0 from libmpi_abi but -1, -1 from the normal libmpi, because the normal library uses Open MPI's own ABI rather than the standard ABI. * A clean separation of the two ABIs across the existing pages: the abi-compatibility.rst page is rescoped to the Open MPI ABI and cross-references the new page; version-numbering.rst distinguishes the Open MPI ABI from the MPI Forum ABI and moves its release-series ABI details into abi-compatibility.rst; and both pages state that the two ABIs are not interchangeable. * A "danger" warning that object files or libraries built against different MPI ABIs must not be mixed in one executable, with the concrete unsupported mpicc_abi / mpicc / mpifort combinations and the rule to use one ABI consistently for every MPI-using object. * The intentional decision not to ship a Fortran standard ABI yet (no mpifort_abi wrapper, no libmpifort_abi): a documented wait-and-see approach taken while no other implementation supports the Fortran ABI and the MPI Forum is still converging on it. * Reference documentation for the Open MPI MPI_Abi_* query/helper routines: man pages for MPI_Abi_get_version, MPI_Abi_get_info, MPI_Abi_{get,set}_fortran_booleans, and MPI_Abi_{get,set}_fortran_info describing their Open MPI behavior; the mpicc_abi wrapper in the wrapper-compiler man page; and the standard-ABI configure option in the configure CLI options. * Release-notes and v6.0.x changelog entries announcing MPI-5.0 standard ABI support for C applications and noting the absence of a Fortran ABI wrapper. Signed-off-by: Jeff Squyres <jeff@squyres.com> | 1 个月前 | |
docs: warn agents about misuse of OMPI_HIDDEN 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> | 1 个月前 | |
Document Open MPI's MPI Forum ABI support Open MPI v6.0.0 adds support for the MPI Forum (standard) ABI defined by MPI-5.0 for C applications, alongside Open MPI's own long-standing ABI. The user-facing documentation did not yet describe this new, separate binary interface: how to build against it, its current limitations, or how it relates to Open MPI's existing ABI-compatibility guarantees. This adds and reorganizes that documentation. High points of the documentation in this commit: * A new "Building MPI applications using the MPI Forum ABI" page (docs/building-apps/mpi-forum-abi.rst) explaining what the MPI Forum ABI is, that it is new in v6.0.0 and distinct from the Open MPI ABI, and its limitations: the application must be dynamically linked, run with a matching launcher, and written in C. * How to build and run standard-ABI C applications with the mpicc_abi wrapper and libmpi_abi -- the wrapper adds the standard ABI header directory ($prefix/include/standard_abi) and links libmpi_abi -- plus the --showme flags and the effect of configuring with --disable-standard-abi. * How to check ABI support at run time with MPI_Abi_get_version, which reports version 1.0 from libmpi_abi but -1, -1 from the normal libmpi, because the normal library uses Open MPI's own ABI rather than the standard ABI. * A clean separation of the two ABIs across the existing pages: the abi-compatibility.rst page is rescoped to the Open MPI ABI and cross-references the new page; version-numbering.rst distinguishes the Open MPI ABI from the MPI Forum ABI and moves its release-series ABI details into abi-compatibility.rst; and both pages state that the two ABIs are not interchangeable. * A "danger" warning that object files or libraries built against different MPI ABIs must not be mixed in one executable, with the concrete unsupported mpicc_abi / mpicc / mpifort combinations and the rule to use one ABI consistently for every MPI-using object. * The intentional decision not to ship a Fortran standard ABI yet (no mpifort_abi wrapper, no libmpifort_abi): a documented wait-and-see approach taken while no other implementation supports the Fortran ABI and the MPI Forum is still converging on it. * Reference documentation for the Open MPI MPI_Abi_* query/helper routines: man pages for MPI_Abi_get_version, MPI_Abi_get_info, MPI_Abi_{get,set}_fortran_booleans, and MPI_Abi_{get,set}_fortran_info describing their Open MPI behavior; the mpicc_abi wrapper in the wrapper-compiler man page; and the standard-ABI configure option in the configure CLI options. * Release-notes and v6.0.x changelog entries announcing MPI-5.0 standard ABI support for C applications and noting the absence of a Fortran ABI wrapper. Signed-off-by: Jeff Squyres <jeff@squyres.com> | 1 个月前 | |
Document Open MPI's MPI Forum ABI support Open MPI v6.0.0 adds support for the MPI Forum (standard) ABI defined by MPI-5.0 for C applications, alongside Open MPI's own long-standing ABI. The user-facing documentation did not yet describe this new, separate binary interface: how to build against it, its current limitations, or how it relates to Open MPI's existing ABI-compatibility guarantees. This adds and reorganizes that documentation. High points of the documentation in this commit: * A new "Building MPI applications using the MPI Forum ABI" page (docs/building-apps/mpi-forum-abi.rst) explaining what the MPI Forum ABI is, that it is new in v6.0.0 and distinct from the Open MPI ABI, and its limitations: the application must be dynamically linked, run with a matching launcher, and written in C. * How to build and run standard-ABI C applications with the mpicc_abi wrapper and libmpi_abi -- the wrapper adds the standard ABI header directory ($prefix/include/standard_abi) and links libmpi_abi -- plus the --showme flags and the effect of configuring with --disable-standard-abi. * How to check ABI support at run time with MPI_Abi_get_version, which reports version 1.0 from libmpi_abi but -1, -1 from the normal libmpi, because the normal library uses Open MPI's own ABI rather than the standard ABI. * A clean separation of the two ABIs across the existing pages: the abi-compatibility.rst page is rescoped to the Open MPI ABI and cross-references the new page; version-numbering.rst distinguishes the Open MPI ABI from the MPI Forum ABI and moves its release-series ABI details into abi-compatibility.rst; and both pages state that the two ABIs are not interchangeable. * A "danger" warning that object files or libraries built against different MPI ABIs must not be mixed in one executable, with the concrete unsupported mpicc_abi / mpicc / mpifort combinations and the rule to use one ABI consistently for every MPI-using object. * The intentional decision not to ship a Fortran standard ABI yet (no mpifort_abi wrapper, no libmpifort_abi): a documented wait-and-see approach taken while no other implementation supports the Fortran ABI and the MPI Forum is still converging on it. * Reference documentation for the Open MPI MPI_Abi_* query/helper routines: man pages for MPI_Abi_get_version, MPI_Abi_get_info, MPI_Abi_{get,set}_fortran_booleans, and MPI_Abi_{get,set}_fortran_info describing their Open MPI behavior; the mpicc_abi wrapper in the wrapper-compiler man page; and the standard-ABI configure option in the configure CLI options. * Release-notes and v6.0.x changelog entries announcing MPI-5.0 standard ABI support for C applications and noting the absence of a Fortran ABI wrapper. Signed-off-by: Jeff Squyres <jeff@squyres.com> | 1 个月前 | |
docs: resolve stale TODO markers in launching and getting-help pages Three documentation TODO notes referenced things that have since been resolved or replaced: * getting-help.rst: the "update link to IB FAQ entry" TODO sat above a cross-reference that already points at the current InfiniBand/RoCE troubleshooting section (faq-ib-troubleshoot-label). Remove the TODO. * troubleshooting.rst: replace the "NONEXISTENT FAQ entry" placeholder with real cross-references to the --disable-dlopen and --enable-mca-dso / --enable-mca-static configure-option descriptions. * prerequisites.rst: remove the internal "future to-do" note about OMPIHOME / PRRTE's .ini file. That note rendered as a user-facing error box; the anticipated .ini-file support never materialized in that form (PRRTE's OMPIHOME support instead reads $OMPIHOME/etc/openmpi-mca-params.conf, which is an MCA-parameter mechanism unrelated to this section's --prefix topic). Signed-off-by: Jeff Squyres <jeff@squyres.com> | 2 个月前 | |
contributing: update license to be more specific about BSD 3- clause open mpi variant add link to spdx in license/index.rst Signed-off-by: Howard Pritchard <howardp@lanl.gov> | 1 个月前 | |
docs: add LLM-friendly documentation artifacts Publish machine-readable, LLM-friendly documentation for the public Open MPI MPI API alongside the existing human-facing HTML and Unix man pages, so that LLMs, retrieval systems, and coding assistants can obtain concise, authoritative, version-correct API information without scraping themed HTML -- and without introducing a second, hand-maintained API reference that could drift from the real documentation. Everything is derived from the existing RST man pages and the MPI Forum binding metadata (docs/mpi-standard-apis.json, read via the embedded pympistandard library); none of the API content is independently authored. Generated artifacts. Written into a build-tree staging directory and carried inside the per-version HTML output tree, so they inherit the existing tarball, install, and Read the Docs publishing machinery: * llms.txt -- a short, self-describing index for each documentation version. * llms/openmpi-mpi-api.jsonl -- one structured JSON record per documented MPI procedure (standard, extension, deprecated, removed). * llms/openmpi-mpi-api.md and four per-interface corpora (C, mpif.h, use mpi, use mpi_f08). * llms/man-openmpi/man3/MPI_<name>.3.md -- one Markdown page per man3 page, 1:1 with the human man pages. * llms/man-openmpi/man1/<command>.1.md -- a Markdown corpus for the section-1 command man pages (mpirun, ompi_info, the wrapper compilers, ...); commands rather than APIs, so Markdown but no JSONL records. * llms/openmpi-docs-manifest.json -- the artifact inventory, and the only artifact that carries build identity. Curated, committed sources under docs/llms-src/: an interface-selection guide, a small examples corpus (reusing the top-level examples/ tree where it already covers a case), and the two JSON Schema files, which serve as both the published contract and the CI validator. Data model and invariants. * Two API populations. Standard procedures are metadata-driven (C, mpif.h / use mpi, and use mpi_f08 signatures, including large-count variants, from pympistandard). Extensions (MPIX_*, OMPI_*) are best-effort: signatures preserved verbatim from the RST, structured fields marked unknown. A "kind" field distinguishes them. * Each artifact's content hash is a pure function of its semantic content: build identity (git_commit, git_describe, generated_at) lives only in the manifest, so a per-artifact hash changes if and only if that artifact's documentation content changes. * Reproducible under the project's existing SOURCE_DATE_EPOCH model: the semantic artifacts are wall-clock-free and byte-identical across reruns at a given commit. As part of this, a pre-existing gap is closed by deriving the docs copyright year from SOURCE_DATE_EPOCH. * Link strategy follows the build type. A local git or release-tarball build emits links relative to each file (a self-contained, offline tree); a Read the Docs build emits absolute, slug-correct links. Because Read the Docs serves the version-neutral /llms.txt from the default version, llms.txt self-describes the .../en/VERSION_SLUG/ URL scheme so a consumer can reach any version. Build integration and shared infrastructure. * Shared metadata logic (pympistandard loading, C/Fortran binding rendering, VERSION parsing, ".. mpi-bindings:" directive parsing, and build-identity helpers) is factored into docs/ompi_docs_common.py and used by both the new generator and the existing man3 bindings generator. * docs/generate-llm-docs.py runs from a Makefile sentinel for "make" builds and from .readthedocs-pre-create-environment.sh for Read the Docs builds; a conf.py "build-finished" hook copies the staging tree into the Sphinx HTML output, so publication is identical under make and on Read the Docs. Validation. docs/validate-llm-docs.py runs as part of "make check" and verifies JSON Schema conformance of the catalog and manifest, cross-field invariants, that every record links back to the human docs, that the manifest inventories every artifact with matching hash and size, that the generated Markdown contains no unresolved RST, that the committed sample records match the generated catalog, and a determinism (no-diff) rerun at a fixed SOURCE_DATE_EPOCH. Two robustness fixes are included: "make check" now depends on the generation sentinel, so validation actually runs instead of being silently skipped on a clean tree; and a coverage gate fails the build if any MPI Forum procedure that Open MPI implements has no man page (detected from the public C header and the use-mpi-f08 sources), so an implemented MPI API can no longer be silently undocumented. Documentation and specification. The effort is documented for maintainers in docs/developers/llm-friendly-docs.rst -- intent, the llms.txt convention and external references, the design rationale, regeneration and the per-release manifest, and how to update the docs when MPI APIs change. The full design record, JSON Schemas, sample records, and task list live under specs/llms-friendly-docs/. A one-time feature release note is added to the changelog. Signed-off-by: Jeff Squyres <jeff@squyres.com> | 3 个月前 | |
Merge pull request #14317 from hppritcha/masaqif-feature/hw-resource-info mpi: implement MPI_Get_hw_resource_info version two | 24 天前 | |
docs: fix shmem_wait argument descriptions The shmem_wait man page documents target, value, and pe arguments that are not part of the shmem_wait or shmem_wait_until interfaces. Remove those copied argument descriptions and keep the documentation focused on ivar, cmp, and cmp_value. Fixes #7148. Signed-off-by: FranCDoc <fchiesadoc@gmail.com> | 3 个月前 | |
osc/rdma: do not claim cpu atomics for a lone local peer allocate_state_single() honours use_cpu_atomics for the window state (installing state_handle when it is false) and for base_handle, but set the base flags unconditionally: my_peer->flags |= OMPI_OSC_RDMA_PEER_LOCAL_BASE; my_peer->flags |= OMPI_OSC_RDMA_PEER_CPU_ATOMICS; allocate_state_shared() gates exactly those two on use_cpu_atomics. The single-local-peer path did not, so with use_cpu_atomics false the peer came out self-contradictory: a base_handle installed for btl access, and CPU_ATOMICS claiming the memory may be touched directly. This is reachable. With one process per node local_size is 1, so allocate_state_shared() hands straight off to allocate_state_single(), and use_cpu_atomics is false whenever the accelerated btl does not advertise MCA_BTL_ATOMIC_SUPPORTS_GLOB. The consequence is the atomic mixing that flag exists to forbid, and it is not conditional on anything the user asks for. The accumulate lock at the top of ompi_osc_rdma_compare_and_swap() is guarded by win->w_acc_ops <= OMPI_WIN_ACCUMULATE_OPS_SAME_OP and ompi_win_accumulate_ops_t holds only SAME_OP_NO_OP (0) and SAME_OP (1), so that test is always true and the lock is never taken there for any window, whatever the accumulate_ops info key says. A remote rank then computes use_shared_mem false and issues a network atomic through ompi_osc_rdma_cas_atomic(), returning before the second, unconditional acquisition further down, so it holds no lock. Meanwhile this rank - believing it has cpu atomics - takes ompi_osc_rdma_cas_local() and touches the same memory with an opal_atomic_*(). Acquiring the lock on the local path does not serialize the two, because the remote fast path never takes it. With the flag cleared this rank computes use_shared_mem false as well, and both sides use network atomics, which is consistent. Reported by George Bosilca while reviewing the shared-state series, whose allocate_state_shared() rework is what makes the GLOB flag readable and so makes this path reachable. Signed-off-by: Yin Li <yinliq@amazon.com> | 9 天前 | |
docs: update the large-cluster tuning pages for current behavior These three "reduce startup/wireup time" and "static cluster configuration" pages carried TODO markers noting they might be out of date. Checking their claims against the current code base: * reduce-startup-time: the pmix_base_async_modex, async_mpi_init, and async_mpi_finalize MCA parameters and the usnic BTL all still exist and behave as described, so the page was accurate; its TODO is simply removed. * reduce-wireup: the oob_tcp_listen_mode=listen_thread MCA parameter no longer exists. The OOB now lives in PRRTE, and mpirun always services connection requests on a dedicated listener thread by default, so the old tuning advice is obsolete. The page also claimed that every daemon opens a socket back to mpirun, which is not how PRRTE works: the daemons are arranged in a radix tree (routed_radix.c), each connects only to its parent (the RML lifeline), and mpirun-bound traffic is relayed up the tree hop by hop. The fan-out is rml_base_radix, which defaults to 64, so mpirun accepts direct connections from at most 64 daemons regardless of job size. Likewise, the ssh launcher tree-spawns the daemons by default (plm_ssh_no_tree_spawn is false), so mpirun does not launch them all itself. Rewrite the page to describe this behavior and to introduce PMIx "Instant On" (pre-positioning network endpoint information at launch so no global modex/wireup exchange is needed at MPI_Init), which the previous TODO asked for. * static-cluster-config: the PRRTE "routed" framework and its "debruijn" component were removed (routing is now a fixed radix tree tuned only via rml_base_radix), so the routed=debruijn example no longer works. Replace it with a current, equivalent example using the pml framework (build all components, default to ob1). The --enable-mca-no-build option and the ob1 PML still exist as described. Signed-off-by: Jeff Squyres <jeff@squyres.com> | 2 个月前 | |
Add SPDX Identifiers to OMPI Tree Signed-off-by: Brian Barrett <bbarrett@amazon.com> | 18 天前 | |
Add SPDX Identifiers to OMPI Tree Signed-off-by: Brian Barrett <bbarrett@amazon.com> | 18 天前 | |
contributing: update license to be more specific about BSD 3- clause open mpi variant add link to spdx in license/index.rst Signed-off-by: Howard Pritchard <howardp@lanl.gov> | 1 个月前 | |
Add SPDX Identifiers to OMPI Tree Signed-off-by: Brian Barrett <bbarrett@amazon.com> | 18 天前 | |
Add SPDX Identifiers to OMPI Tree Signed-off-by: Brian Barrett <bbarrett@amazon.com> | 18 天前 | |
Add SPDX Identifiers to OMPI Tree Signed-off-by: Brian Barrett <bbarrett@amazon.com> | 18 天前 | |
docs: resolve stale TODO markers in launching and getting-help pages Three documentation TODO notes referenced things that have since been resolved or replaced: * getting-help.rst: the "update link to IB FAQ entry" TODO sat above a cross-reference that already points at the current InfiniBand/RoCE troubleshooting section (faq-ib-troubleshoot-label). Remove the TODO. * troubleshooting.rst: replace the "NONEXISTENT FAQ entry" placeholder with real cross-references to the --disable-dlopen and --enable-mca-dso / --enable-mca-static configure-option descriptions. * prerequisites.rst: remove the internal "future to-do" note about OMPIHOME / PRRTE's .ini file. That note rendered as a user-facing error box; the anticipated .ini-file support never materialized in that form (PRRTE's OMPIHOME support instead reads $OMPIHOME/etc/openmpi-mca-params.conf, which is an MCA-parameter mechanism unrelated to this section's --prefix topic). Signed-off-by: Jeff Squyres <jeff@squyres.com> | 2 个月前 | |
Update history.rst (spelling) Signed-off-by: charlesgwaldman <120225331+charlesgwaldman@users.noreply.github.com> | 10 个月前 | |
docs: add LLM-friendly documentation artifacts Publish machine-readable, LLM-friendly documentation for the public Open MPI MPI API alongside the existing human-facing HTML and Unix man pages, so that LLMs, retrieval systems, and coding assistants can obtain concise, authoritative, version-correct API information without scraping themed HTML -- and without introducing a second, hand-maintained API reference that could drift from the real documentation. Everything is derived from the existing RST man pages and the MPI Forum binding metadata (docs/mpi-standard-apis.json, read via the embedded pympistandard library); none of the API content is independently authored. Generated artifacts. Written into a build-tree staging directory and carried inside the per-version HTML output tree, so they inherit the existing tarball, install, and Read the Docs publishing machinery: * llms.txt -- a short, self-describing index for each documentation version. * llms/openmpi-mpi-api.jsonl -- one structured JSON record per documented MPI procedure (standard, extension, deprecated, removed). * llms/openmpi-mpi-api.md and four per-interface corpora (C, mpif.h, use mpi, use mpi_f08). * llms/man-openmpi/man3/MPI_<name>.3.md -- one Markdown page per man3 page, 1:1 with the human man pages. * llms/man-openmpi/man1/<command>.1.md -- a Markdown corpus for the section-1 command man pages (mpirun, ompi_info, the wrapper compilers, ...); commands rather than APIs, so Markdown but no JSONL records. * llms/openmpi-docs-manifest.json -- the artifact inventory, and the only artifact that carries build identity. Curated, committed sources under docs/llms-src/: an interface-selection guide, a small examples corpus (reusing the top-level examples/ tree where it already covers a case), and the two JSON Schema files, which serve as both the published contract and the CI validator. Data model and invariants. * Two API populations. Standard procedures are metadata-driven (C, mpif.h / use mpi, and use mpi_f08 signatures, including large-count variants, from pympistandard). Extensions (MPIX_*, OMPI_*) are best-effort: signatures preserved verbatim from the RST, structured fields marked unknown. A "kind" field distinguishes them. * Each artifact's content hash is a pure function of its semantic content: build identity (git_commit, git_describe, generated_at) lives only in the manifest, so a per-artifact hash changes if and only if that artifact's documentation content changes. * Reproducible under the project's existing SOURCE_DATE_EPOCH model: the semantic artifacts are wall-clock-free and byte-identical across reruns at a given commit. As part of this, a pre-existing gap is closed by deriving the docs copyright year from SOURCE_DATE_EPOCH. * Link strategy follows the build type. A local git or release-tarball build emits links relative to each file (a self-contained, offline tree); a Read the Docs build emits absolute, slug-correct links. Because Read the Docs serves the version-neutral /llms.txt from the default version, llms.txt self-describes the .../en/VERSION_SLUG/ URL scheme so a consumer can reach any version. Build integration and shared infrastructure. * Shared metadata logic (pympistandard loading, C/Fortran binding rendering, VERSION parsing, ".. mpi-bindings:" directive parsing, and build-identity helpers) is factored into docs/ompi_docs_common.py and used by both the new generator and the existing man3 bindings generator. * docs/generate-llm-docs.py runs from a Makefile sentinel for "make" builds and from .readthedocs-pre-create-environment.sh for Read the Docs builds; a conf.py "build-finished" hook copies the staging tree into the Sphinx HTML output, so publication is identical under make and on Read the Docs. Validation. docs/validate-llm-docs.py runs as part of "make check" and verifies JSON Schema conformance of the catalog and manifest, cross-field invariants, that every record links back to the human docs, that the manifest inventories every artifact with matching hash and size, that the generated Markdown contains no unresolved RST, that the committed sample records match the generated catalog, and a determinism (no-diff) rerun at a fixed SOURCE_DATE_EPOCH. Two robustness fixes are included: "make check" now depends on the generation sentinel, so validation actually runs instead of being silently skipped on a clean tree; and a coverage gate fails the build if any MPI Forum procedure that Open MPI implements has no man page (detected from the public C header and the use-mpi-f08 sources), so an implemented MPI API can no longer be silently undocumented. Documentation and specification. The effort is documented for maintainers in docs/developers/llm-friendly-docs.rst -- intent, the llms.txt convention and external references, the design rationale, regeneration and the per-release manifest, and how to update the docs when MPI APIs change. The full design record, JSON Schemas, sample records, and task list live under specs/llms-friendly-docs/. A one-time feature release note is added to the changelog. Signed-off-by: Jeff Squyres <jeff@squyres.com> | 3 个月前 | |
docs: correct the ORTE-to-PRRTE deprecated parameter mapping table Audited the "MCA Parameter Changes Between Open MPI 4.x and newer releases" mapping table against the current PRRTE source. Most of the table is accurate (the output/display tokens, ppr/node/core/slot/package mapping words, the nolocal/oversubscribe/nooversubscribe/hwtcpus/pe= modifiers, rankfile:file=, and the core/package binding values all verified), but a few entries were wrong: * hwloc_base_cpu_set / hwloc_base_cpu_list do NOT map to a pe-list=<value> mapping policy: PRRTE rejects a "pe-list=" value on the default-parameter path. The correct replacement is the dedicated hwloc_default_cpu_list parameter (PRTE_MCA_hwloc_default_cpu_list). Fixed the two table rows and the two affected examples (splitting the combined cpu-set + oversubscribe example into two parameters). * The ompi_stream_buffering replacement is an Open MPI parameter, so its environment variable is OMPI_MCA_ompi_stream_buffering, not PRTE_MCA_ompi_stream_buffering. Fixed the example and noted the exception in the section's prefix note. * The old orte_* parameter names have been fully removed (they are not accepted as deprecated synonyms), so the "may be removed in future releases" framing was stale; reworded to say they no longer exist. Also renamed the mapping and binding parameters used throughout the table and examples from rmaps_default_mapping_policy and hwloc_default_binding_policy to their current names, mapby and bindto. The old names are now deprecated synonyms; a note records that they still work but that new configurations should use mapby / bindto. Signed-off-by: Jeff Squyres <jeff@squyres.com> | 2 个月前 | |
docs: Render C/F90/F08 bindings in man pages Use the pympistandard Python module and associated MPI-4.1 MPI Standard JSON definition file to generate bindings -- regular and embiggened -- in the MPI man pages. In the generation code, had to handle a variety of cases: * When there is no C binding * When there is no mpif.h / use mpi binding * When there is no use mpi_f08 binding * When there are embiggened C and/or F08 bindings * When a single man page includes documentation for multiple MPI APIs * When we do not have man pages for MPI APIs described in the official MPI Forum API JSON Also, this commit adds a new submodule: the pympistandard Python module from the MPI Forum repository. Some other cleanups were also necessary as part of this commit: * Add some missing man pages * Fix some random RST formatting errors in existing man pages Signed-off-by: Jeff Squyres <jeff@squyres.com> | 1 年前 | |
ABI: switch to using MPI Standard ABI values This mod switches from using "synthetic" defined values and handles to the ones specified in the MPI 5.1 standard, and bumps the MPI standard version reported by Open MPI to 5.0. The python infrastructure included here generates a "canonical" MPI standard ABI compatible mpi.h using two json files: 1) mpi-standard-abi.json 2) mpi-standard-apis.json 2 is generated as part of building the MPI standard. We import that into our project for use in generating both the mpi.h as well as interface definitions in the man pages. 1 is generated using a separate script that processes the tables in Appendix A of the standard. Ideally this script will be merged into the MPI standard code base at some point. This script is currently at https://github.com/Joe-Downs/mpi-standard/tree/pr/handle-constant-tool/const-tool . It is used to generate the portion of mpi.h where defined values and handles are specified. This commit also enables generation of the abi interfaces and header files by default. Signed-off-by: Joseph Downs <joe.downs@lanl.gov> Co-authored-by: Howard Pritchard <howardp@lanl.gov> Signed-off-by: Jeff Squyres <jeff@squyres.com> | 1 个月前 | |
ABI: switch to using MPI Standard ABI values This mod switches from using "synthetic" defined values and handles to the ones specified in the MPI 5.1 standard, and bumps the MPI standard version reported by Open MPI to 5.0. The python infrastructure included here generates a "canonical" MPI standard ABI compatible mpi.h using two json files: 1) mpi-standard-abi.json 2) mpi-standard-apis.json 2 is generated as part of building the MPI standard. We import that into our project for use in generating both the mpi.h as well as interface definitions in the man pages. 1 is generated using a separate script that processes the tables in Appendix A of the standard. Ideally this script will be merged into the MPI standard code base at some point. This script is currently at https://github.com/Joe-Downs/mpi-standard/tree/pr/handle-constant-tool/const-tool . It is used to generate the portion of mpi.h where defined values and handles are specified. This commit also enables generation of the abi interfaces and header files by default. Signed-off-by: Joseph Downs <joe.downs@lanl.gov> Co-authored-by: Howard Pritchard <howardp@lanl.gov> Signed-off-by: Jeff Squyres <jeff@squyres.com> | 1 个月前 | |
ABI: switch to using MPI Standard ABI values This mod switches from using "synthetic" defined values and handles to the ones specified in the MPI 5.1 standard, and bumps the MPI standard version reported by Open MPI to 5.0. The python infrastructure included here generates a "canonical" MPI standard ABI compatible mpi.h using two json files: 1) mpi-standard-abi.json 2) mpi-standard-apis.json 2 is generated as part of building the MPI standard. We import that into our project for use in generating both the mpi.h as well as interface definitions in the man pages. 1 is generated using a separate script that processes the tables in Appendix A of the standard. Ideally this script will be merged into the MPI standard code base at some point. This script is currently at https://github.com/Joe-Downs/mpi-standard/tree/pr/handle-constant-tool/const-tool . It is used to generate the portion of mpi.h where defined values and handles are specified. This commit also enables generation of the abi interfaces and header files by default. Signed-off-by: Joseph Downs <joe.downs@lanl.gov> Co-authored-by: Howard Pritchard <howardp@lanl.gov> Signed-off-by: Jeff Squyres <jeff@squyres.com> | 1 个月前 | |
ABI: switch to using MPI Standard ABI values This mod switches from using "synthetic" defined values and handles to the ones specified in the MPI 5.1 standard, and bumps the MPI standard version reported by Open MPI to 5.0. The python infrastructure included here generates a "canonical" MPI standard ABI compatible mpi.h using two json files: 1) mpi-standard-abi.json 2) mpi-standard-apis.json 2 is generated as part of building the MPI standard. We import that into our project for use in generating both the mpi.h as well as interface definitions in the man pages. 1 is generated using a separate script that processes the tables in Appendix A of the standard. Ideally this script will be merged into the MPI standard code base at some point. This script is currently at https://github.com/Joe-Downs/mpi-standard/tree/pr/handle-constant-tool/const-tool . It is used to generate the portion of mpi.h where defined values and handles are specified. This commit also enables generation of the abi interfaces and header files by default. Signed-off-by: Joseph Downs <joe.downs@lanl.gov> Co-authored-by: Howard Pritchard <howardp@lanl.gov> Signed-off-by: Jeff Squyres <jeff@squyres.com> | 1 个月前 | |
docs: slurp PRTE's RST files into mpirun.1 This commit introduce a fundamentally new concept: have configure search PRRTE for RST files to include in Open MPI's documentation (regardless of whether we're using the internal/bundled PRRTE or an external PRRTE). If we're building against an external PRRTE that is old enough that it doesn't have any RST files installed, we'll make up some dummy RST files that basically say "you don't get help/content here because your PRRTE is too old." To simplify the configury for this scheme, this commit also makes another change: the pre-built HTML docs and nroff man pages included in distribution tarballs are now located at docs/html/ and docs/man/, respectively (vs. the location where we'll build them: docs/_build/html/ and docs/_build/man/, respectively). There are two cases here: 1. If the user has Sphinx available, we'll build the docs under docs/_build/, and install those (effectively ignoring the pre-built docs). 2. If the user does not have Sphinx available, we'll just install the pre-built docs. This simplified things like "make clean" and "make distcheck". Including RST content from PRTE required another major change: when we build the RST docs in a VPATH scenario, we copy the entire docs/ source tree to the build tree. This allows us to modify the RST sources a bit (e.g., to include the PRRTE RST files or generate dummy PRRTE RST files). mpirun.1.rst is updated to include the RST content from PRRTE about CLI options. More work needs to be done here to remove old, now-redundant content. Finally, we also amend the advice to implementors to have Sphinx installed when building their package so that Open MPI's build system can properly slurp in their PRRTE's RST docs. Signed-off-by: Jeff Squyres <jeff@squyres.com> | 2 年前 | |
Add SPDX Identifiers to OMPI Tree Signed-off-by: Brian Barrett <bbarrett@amazon.com> | 18 天前 | |
docs: Convert Open MPI docs to reStructured Text Convert several Open MPI README/text-like files into reStructured text under the docs/ subdirectory: * README.md * README.FT.ULFM.md * README.JAVA.md * HACKING * LICENSE * NEWS Also converted the Open MPI and OpenSHMEM man pages to RST. This was a lengthy process that involved a zillion intermediate commits. All this work has been squashed down to a single commit for brevity in Git history. Co-authored-by: Harumi Kuno <harumi.kuno@hpe.com> Co-authored-by: Geoffrey Paulsen <gpaulsen@us.ibm.com> Co-authored-by: Aurelien Bouteiller <bouteill@icl.utk.edu> Co-authored-by: George Bosilca <bosilca@icl.utk.edu> Co-authored-by: Joshua Hursey <jhursey@us.ibm.com> Co-authored-by: Brian Barrett <bbarrett@amazon.com> Signed-off-by: Jeff Squyres <jsquyres@cisco.com> | 4 年前 | |
docs: A variety of updates Shuffle the docs organization around per discussion on github. Signed-off-by: Jeff Squyres <jsquyres@cisco.com> | 3 年前 | |
docs: add LLM-friendly documentation artifacts Publish machine-readable, LLM-friendly documentation for the public Open MPI MPI API alongside the existing human-facing HTML and Unix man pages, so that LLMs, retrieval systems, and coding assistants can obtain concise, authoritative, version-correct API information without scraping themed HTML -- and without introducing a second, hand-maintained API reference that could drift from the real documentation. Everything is derived from the existing RST man pages and the MPI Forum binding metadata (docs/mpi-standard-apis.json, read via the embedded pympistandard library); none of the API content is independently authored. Generated artifacts. Written into a build-tree staging directory and carried inside the per-version HTML output tree, so they inherit the existing tarball, install, and Read the Docs publishing machinery: * llms.txt -- a short, self-describing index for each documentation version. * llms/openmpi-mpi-api.jsonl -- one structured JSON record per documented MPI procedure (standard, extension, deprecated, removed). * llms/openmpi-mpi-api.md and four per-interface corpora (C, mpif.h, use mpi, use mpi_f08). * llms/man-openmpi/man3/MPI_<name>.3.md -- one Markdown page per man3 page, 1:1 with the human man pages. * llms/man-openmpi/man1/<command>.1.md -- a Markdown corpus for the section-1 command man pages (mpirun, ompi_info, the wrapper compilers, ...); commands rather than APIs, so Markdown but no JSONL records. * llms/openmpi-docs-manifest.json -- the artifact inventory, and the only artifact that carries build identity. Curated, committed sources under docs/llms-src/: an interface-selection guide, a small examples corpus (reusing the top-level examples/ tree where it already covers a case), and the two JSON Schema files, which serve as both the published contract and the CI validator. Data model and invariants. * Two API populations. Standard procedures are metadata-driven (C, mpif.h / use mpi, and use mpi_f08 signatures, including large-count variants, from pympistandard). Extensions (MPIX_*, OMPI_*) are best-effort: signatures preserved verbatim from the RST, structured fields marked unknown. A "kind" field distinguishes them. * Each artifact's content hash is a pure function of its semantic content: build identity (git_commit, git_describe, generated_at) lives only in the manifest, so a per-artifact hash changes if and only if that artifact's documentation content changes. * Reproducible under the project's existing SOURCE_DATE_EPOCH model: the semantic artifacts are wall-clock-free and byte-identical across reruns at a given commit. As part of this, a pre-existing gap is closed by deriving the docs copyright year from SOURCE_DATE_EPOCH. * Link strategy follows the build type. A local git or release-tarball build emits links relative to each file (a self-contained, offline tree); a Read the Docs build emits absolute, slug-correct links. Because Read the Docs serves the version-neutral /llms.txt from the default version, llms.txt self-describes the .../en/VERSION_SLUG/ URL scheme so a consumer can reach any version. Build integration and shared infrastructure. * Shared metadata logic (pympistandard loading, C/Fortran binding rendering, VERSION parsing, ".. mpi-bindings:" directive parsing, and build-identity helpers) is factored into docs/ompi_docs_common.py and used by both the new generator and the existing man3 bindings generator. * docs/generate-llm-docs.py runs from a Makefile sentinel for "make" builds and from .readthedocs-pre-create-environment.sh for Read the Docs builds; a conf.py "build-finished" hook copies the staging tree into the Sphinx HTML output, so publication is identical under make and on Read the Docs. Validation. docs/validate-llm-docs.py runs as part of "make check" and verifies JSON Schema conformance of the catalog and manifest, cross-field invariants, that every record links back to the human docs, that the manifest inventories every artifact with matching hash and size, that the generated Markdown contains no unresolved RST, that the committed sample records match the generated catalog, and a determinism (no-diff) rerun at a fixed SOURCE_DATE_EPOCH. Two robustness fixes are included: "make check" now depends on the generation sentinel, so validation actually runs instead of being silently skipped on a clean tree; and a coverage gate fails the build if any MPI Forum procedure that Open MPI implements has no man page (detected from the public C header and the use-mpi-f08 sources), so an implemented MPI API can no longer be silently undocumented. Documentation and specification. The effort is documented for maintainers in docs/developers/llm-friendly-docs.rst -- intent, the llms.txt convention and external references, the design rationale, regeneration and the per-release manifest, and how to update the docs when MPI APIs change. The full design record, JSON Schemas, sample records, and task list live under specs/llms-friendly-docs/. A one-time feature release note is added to the changelog. Signed-off-by: Jeff Squyres <jeff@squyres.com> | 3 个月前 | |
Add SPDX Identifiers to OMPI Tree Signed-off-by: Brian Barrett <bbarrett@amazon.com> | 18 天前 | |
docs: trivial: s/--/|mdash|/ in man pages No other text or content changes. Signed-off-by: Jeff Squyres <jeff@squyres.com> | 2 年前 | |
Document Open MPI's MPI Forum ABI support Open MPI v6.0.0 adds support for the MPI Forum (standard) ABI defined by MPI-5.0 for C applications, alongside Open MPI's own long-standing ABI. The user-facing documentation did not yet describe this new, separate binary interface: how to build against it, its current limitations, or how it relates to Open MPI's existing ABI-compatibility guarantees. This adds and reorganizes that documentation. High points of the documentation in this commit: * A new "Building MPI applications using the MPI Forum ABI" page (docs/building-apps/mpi-forum-abi.rst) explaining what the MPI Forum ABI is, that it is new in v6.0.0 and distinct from the Open MPI ABI, and its limitations: the application must be dynamically linked, run with a matching launcher, and written in C. * How to build and run standard-ABI C applications with the mpicc_abi wrapper and libmpi_abi -- the wrapper adds the standard ABI header directory ($prefix/include/standard_abi) and links libmpi_abi -- plus the --showme flags and the effect of configuring with --disable-standard-abi. * How to check ABI support at run time with MPI_Abi_get_version, which reports version 1.0 from libmpi_abi but -1, -1 from the normal libmpi, because the normal library uses Open MPI's own ABI rather than the standard ABI. * A clean separation of the two ABIs across the existing pages: the abi-compatibility.rst page is rescoped to the Open MPI ABI and cross-references the new page; version-numbering.rst distinguishes the Open MPI ABI from the MPI Forum ABI and moves its release-series ABI details into abi-compatibility.rst; and both pages state that the two ABIs are not interchangeable. * A "danger" warning that object files or libraries built against different MPI ABIs must not be mixed in one executable, with the concrete unsupported mpicc_abi / mpicc / mpifort combinations and the rule to use one ABI consistently for every MPI-using object. * The intentional decision not to ship a Fortran standard ABI yet (no mpifort_abi wrapper, no libmpifort_abi): a documented wait-and-see approach taken while no other implementation supports the Fortran ABI and the MPI Forum is still converging on it. * Reference documentation for the Open MPI MPI_Abi_* query/helper routines: man pages for MPI_Abi_get_version, MPI_Abi_get_info, MPI_Abi_{get,set}_fortran_booleans, and MPI_Abi_{get,set}_fortran_info describing their Open MPI behavior; the mpicc_abi wrapper in the wrapper-compiler man page; and the standard-ABI configure option in the configure CLI options. * Release-notes and v6.0.x changelog entries announcing MPI-5.0 standard ABI support for C applications and noting the absence of a Fortran ABI wrapper. Signed-off-by: Jeff Squyres <jeff@squyres.com> | 1 个月前 |
| 文件 | 最后提交记录 | 最后更新时间 |
|---|---|---|
| 3 个月前 | ||
| 1 个月前 | ||
| 1 个月前 | ||
| 1 个月前 | ||
| 1 个月前 | ||
| 2 个月前 | ||
| 1 个月前 | ||
| 3 个月前 | ||
| 24 天前 | ||
| 3 个月前 | ||
| 9 天前 | ||
| 2 个月前 | ||
| 18 天前 | ||
| 18 天前 | ||
| 1 个月前 | ||
| 18 天前 | ||
| 18 天前 | ||
| 18 天前 | ||
| 2 个月前 | ||
| 10 个月前 | ||
| 3 个月前 | ||
| 2 个月前 | ||
| 1 年前 | ||
| 1 个月前 | ||
| 1 个月前 | ||
| 1 个月前 | ||
| 1 个月前 | ||
| 2 年前 | ||
| 18 天前 | ||
| 4 年前 | ||
| 3 年前 | ||
| 3 个月前 | ||
| 18 天前 | ||
| 2 年前 | ||
| 1 个月前 |
