| 文件 | 最后提交记录 | 最后更新时间 |
|---|---|---|
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> | 4 个月前 | |
DOCS: add more explicit info about fortran interfaces text generated largely by claude based off of recent commits done by human to add new mpif-h, mpi f90, mpi f08 interfaces. docs: update Fortran bindings documentation for current implementation The mpif.h binding instructions referenced the deleted profile/ subdirectory and described the old two-compilation model. Update to reflect the current single-compilation approach using OMPI_GENERATE_F77_BINDINGS and OMPI_GENERATE_WEAK_F77_BINDINGS macros. Add a section distinguishing weak symbols from weak aliases and explaining platform differences (ELF vs Mach-O). Update the use-mpi (ignore TKR) section to note that interfaces are now generated by the Python binding generator rather than hand-written. Add note about automatic parameter naming validation via check_fortran_param_names.py. Remove explicit commit references throughout; describe current behavior rather than historical changes. Signed-off-by: Howard Pritchard <howardp@lanl.gov> | 11 天前 | |
docs: document bindings generator auto-regeneration behavior Commit 726e66e85c added automatic regeneration of generated bindings when the Python bindings generator is modified. This commit documents that behavior for developers. Updates to AGENTS.md explain that: - Generated bindings automatically regenerate when generator files are edited; no manual deletion or regeneration is needed - When adding or removing generator files, developers must update OMPI_BINDINGS_GENERATOR in Makefile.ompi-rules and EXTRA_DIST in ompi/mpi/Makefile.am to maintain proper dependency tracking - Makefile.ompi-rules is a special include file requiring only "make", not full autogen.pl + ./configure Updates to docs/developers/building-open-mpi.rst add a new "Working on the Bindings Generator" subsection with similar guidance, including an important admonition block highlighting the requirement to update both Makefile.ompi-rules and EXTRA_DIST when modifying the generator's file structure. Signed-off-by: Howard Pritchard <howardp@lanl.gov> | 2 个月前 | |
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: updates to the developers guide * Removed a bunch of redundant text and replaced it with links to elsewhere in the docs. * Added developer-level rules of thumb for levels 1-9 of MCA params. * Added code style documentation; consolidated this and "source code tree layout" into a single source-code.rst file. Signed-off-by: Jeff Squyres <jsquyres@cisco.com> | 4 年前 | |
A variety of docs updates: * Typo fixes * Add :ref: links to man pages (mostly `mpirun` and `ompi_info`) * Add notes for contributors about PR'ing to `main` first and then cherry-picking to release branches later. Thanks to @jolivain suggesting that we add this policy to the docs. * Include contributor suggestion to submit fixes to the docs. * Renamed Developers -> Git to "GitHub, Git, and related topics". Added info about: * Git commits and a reference to the contributors declaration (in contributors.rst) * Branching scheme * Details about PR to main first and cherry-picking to release branches * A few words about Github PR CI / MTT * Added information about running Sphinx, and how to view the Sphinx docs locally * Added notes about how to view man pages locally * Added a placeholder oshrun.1 man page (it just refers to mpirun.1) * Per https://github.com/open-mpi/ompi/pull/10772#discussion_r964872603, discuss PMIx and PRRTE MCA * Mention Perl and Python as tools required by Open MPI developers * Expanded on some "advice for packagers" from the "required support dependencies" section, and moved it to its own section: * Don't use Open MPI's bundled sub-packages (Libevent, Hwloc, PMIx, PRTE) * Discussion of components: included in project libraries vs. DSOs * Add short "prerequisites" section for running MPI apps Signed-off-by: Jeff Squyres <jsquyres@cisco.com> | 3 年前 | |
docs: use the dist tarball Autotools versions from VERSION Export the new *_dist_version fields from VERSION as Sphinx substitutions (|m4_dist_version|, |autoconf_dist_version|, and so on), and use them where the docs describe the tools that official tarballs are made with: - rpath-and-runpath.rst said tarballs are made with the Autoconf, Automake, and Libtool *minimum* versions (|autoconf_min_version| etc.), which are not what make_dist_tarball uses: it currently listed Autoconf 2.69.0 and Automake 1.13.4 instead of 2.71 and 1.16.5. - The Git main row of the Autotools table in gnu-autotools.rst now follows VERSION instead of being hard-coded, so it cannot drift from make_dist_tarball again. The rows for release branches remain literal: they are history. - The Flex section of prerequisites.rst suggested 2.5.35 and justified the minimum by RedHat/CentOS 5. Point at the Flex version used for tarballs instead. Signed-off-by: Jeff Squyres <jeff@squyres.com> | 7 天前 | |
Add MPI_T events singleton tests and documentation Add the MPI_T singleton tests (errcodes, smoke, producers, examples, inert, reinit, async-only, and the #14019 reproducer) wired into make check, and the documentation: the updated MPI_T_event_get_num / source_get_num man pages with a "discovering available events" section, a changelog entry, and a developer guide on writing an event producer. Signed-off-by: Jeff Squyres <jeff@squyres.com> | 2 个月前 | |
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 MPI_T events singleton tests and documentation Add the MPI_T singleton tests (errcodes, smoke, producers, examples, inert, reinit, async-only, and the #14019 reproducer) wired into make check, and the documentation: the updated MPI_T_event_get_num / source_get_num man pages with a "discovering available events" section, a changelog entry, and a developer guide on writing an event producer. Signed-off-by: Jeff Squyres <jeff@squyres.com> | 2 个月前 | |
docs: use the dist tarball Autotools versions from VERSION Export the new *_dist_version fields from VERSION as Sphinx substitutions (|m4_dist_version|, |autoconf_dist_version|, and so on), and use them where the docs describe the tools that official tarballs are made with: - rpath-and-runpath.rst said tarballs are made with the Autoconf, Automake, and Libtool *minimum* versions (|autoconf_min_version| etc.), which are not what make_dist_tarball uses: it currently listed Autoconf 2.69.0 and Automake 1.13.4 instead of 2.71 and 1.16.5. - The Git main row of the Autotools table in gnu-autotools.rst now follows VERSION instead of being hard-coded, so it cannot drift from make_dist_tarball again. The rows for release branches remain literal: they are history. - The Flex section of prerequisites.rst suggested 2.5.35 and justified the minimum by RedHat/CentOS 5. Point at the Flex version used for tarballs instead. Signed-off-by: Jeff Squyres <jeff@squyres.com> | 7 天前 | |
Remove the Open MPI Java MPI bindings The Java MPI bindings were always experimental, were never part of the MPI standard, and are no longer maintained. Remove them in their entirety. Deleted: - the ompi/mpi/java tree (Java sources and the JNI C glue) - the mpijavac wrapper compiler (mpijavac.pl.in) - the Java example programs (Hello/Ring/Connectivity.java) - the LANL macosx-dynamic-java contrib platform files, whose sole purpose was building the Java bindings Removed the Java build machinery: the --enable-mpi-java configure option, the ompi_setup_java / ompi_setup_mpi_java m4 macros, the OMPI_WANT_JAVA_BINDINGS automake conditional and preprocessor define, the libmpi_java shared-library versioning, and the related Makefile.am hooks. Removed the now-dead Java op-callback infrastructure from ompi/op (the java_data union member, the OMPI_OP_FLAGS_JAVA_FUNC flag, the ompi_op_set_java_callback() setter, and the reduction dispatch branch). The "Java bindings" line in ompi_info is retained but hard-coded to "no" so anything parsing that field keeps working. Updated all documentation to drop references to the Java bindings, and added a v6.0.0 changelog entry recording the removal. Signed-off-by: Jeff Squyres <jeff@squyres.com> | 3 个月前 | |
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 个月前 | |
Add the MPI standard ABI test suite and its make check targets Open MPI now builds a standard-ABI C library (libmpi_abi) alongside its traditional library, together with an mpicc_abi wrapper and a standard ABI header. That ABI layer is a distinct surface: it exposes the MPI Forum ABI header and constants, advertises ABI include and link paths through its wrapper, translates between standard ABI integer handle/sentinel values and Open MPI's internal handle representation, and forwards public MPI_* calls into the existing implementation. None of that was covered by Open MPI's general MPI correctness tests, which exercise the traditional library and assume the implementation beneath the ABI layer is already tested. This adds a dedicated test suite under ompi/test/mpi-abi/ that checks the ABI-facing surface from several directions -- metadata authority, installed artifacts, symbol reachability, handle translation, complete public-API call paths, callback conversion, and cross-implementation compatibility -- without re-testing the underlying MPI algorithms. Passing these tests does not prove every underlying MPI algorithm is correct; it proves the ABI surface is consistent with the standard ABI metadata derived from the MPI standard and can drive the already-tested Open MPI implementation through the ABI path. The runner is a Python program (mpi_abi_tests.py) split across sibling _abi_*.py modules for discovery, manifest, probe generation, fast checks, installed checks, cross-implementation checks, lookup tables, and reporting. Every module, template, and generated test case is listed in EXTRA_DIST so VPATH and distribution-tarball builds can import and run the suite from a read-only source tree; the runner is invoked with "python -B" so it never writes __pycache__ next to the modules in the source tree. Probe bodies are generated from .cbody.in and .prologue.in templates, and each logical probe is compiled into its own executable because MPI process state is undefined after many runtime failures. Reports are written as JSON and text into mode-specific build-tree directories. The suite is wired into Automake so its checks run in CI, and it remains Python 3.7 compatible like the rest of Open MPI's Python tooling. A new top-level requirements.txt unions the per-area docs/requirements.txt and ompi/test/mpi-abi/requirements.txt files, so installing that one file provides every Python package needed both to build the documentation and man pages with Sphinx and to run all of the MPI ABI checks. Three make targets drive the suite, each with different prerequisites and its own results directory: * "make check" runs the fast metadata, manifest, and source checks (the runner's check-fast mode, reached through check-local). These run entirely from the source and build trees and require neither an installed Open MPI nor mpicc_abi nor mpirun, so they are safe in any build environment and participate in the normal recursive make check. They compare the MPI-standard-derived ABI metadata under docs/ against the runner's manifest, classification rules, generated-source contracts, C header constants, and Fortran helper source contracts, catching drift between the ABI description and what the suite believes is implemented, skipped, or still uncovered before anything is installed or launched. Output goes to check-results/. * "make check-abi" runs the installed standard ABI checks against an installed Open MPI. It uses the installed mpicc_abi wrapper, the installed standard ABI header, and installed mpirun, expected on PATH unless overridden by the OMPI_ABI_TEST_* environment or make variables. It verifies that the wrapper advertises the ABI include and link paths, that the installed header declares exactly the implemented standard ABI C APIs with signatures matching the binding metadata (and does not declare non-ABI APIs), and that the ABI library exports the expected MPI_* / PMPI_* symbols. It then exercises the ABI helper conversion functions (MPI_Comm_toint / _fromint, MPI_Type_toint, and their PMPI forms) by round-tripping predefined, null, and dynamic handles, status sentinels, error classes, keyval sentinels, and configured datatype constants; runs real MPI programs built with mpicc_abi and launched with mpirun that validate return codes, output handles, statuses, counts, data movement, object state, request completion, RMA, and MPI-IO results through the ABI entry points; isolates callback and retained-lifetime probes so one callback failure cannot poison other probes; and runs Fortran binding regression checks. Open MPI does not yet provide an ABI-capable Fortran wrapper, so the Fortran checks deliberately record current behavior -- for example MPI_Abi_get_version reporting -1, -1 -- rather than claiming MPI-5 Fortran ABI coverage. That absence is an intentional wait-and-see decision whose rationale is documented in docs/building-apps/mpi-forum-abi.rst. Output goes to check-abi-results/. * "make check-abi-mpich" runs the optional cross-implementation compatibility checks against MPICH, and is the most demanding target. It requires both an installed Open MPI with standard ABI support and an installed MPICH built with MPI Forum ABI support (for MPICH 5.0.x, configured with --enable-mpi-abi so it installs mpicc_abi, mpi_abi.h, and libmpi_abi). MPICH's normal internal ABI is not the MPI Forum ABI, and neither implementation's plain mpicc is a substitute, so the runner discovers and classifies the MPI Forum ABI wrappers and launchers before selecting them; explicit MPICH_ABI_TEST_* and OMPI_ABI_TEST_* overrides are honored as operator intent and validated rather than silently falling back to another tool on PATH. Because invoking this target is an explicit request for compatibility results, missing or invalid prerequisites are reported as failures, not skips. The target records both ABI directions -- compile with MPICH and run against Open MPI's ABI runtime, and compile with Open MPI's mpicc_abi and run against MPICH -- after first compiling and launching a one-rank MPI_Init / MPI_Finalize sanity program with each implementation's own wrapper, launcher, and ABI library so that broken local launchers are not misreported as ABI mismatches. For each cross-direction executable it sanitizes the platform runtime library path (LD_LIBRARY_PATH on Linux; DYLD_LIBRARY_PATH plus rewriting the embedded ABI dylib load commands on macOS) so a binary compiled against one implementation cannot load a stale libmpi from the shell environment at run time, and it applies MPICH transport defaults (FI_PROVIDER=tcp with a non-loopback, non-tunnel IPv4 interface for ch4:ofi builds; UCX_TLS=self,sm for ch4:ucx builds) for local one- and two-rank jobs. It treats libmpi_abi as the sole MPI Forum ABI library per MPI-5.0 section 21.2.1 and validates the PMPI alternate entry points required by section 16.2.1 as symbols and as calls through libmpi_abi. Output goes to check-abi-mpich-results/. The check-abi and check-abi-mpich targets are also defined at the top of the tree, where they recurse into ompi/test/mpi-abi for the OMPI project and otherwise print a SKIP message. All three targets additionally skip cleanly when configure did not find a usable Python. Signed-off-by: Jeff Squyres <jeff@squyres.com> Co-authored-by: Howard Pritchard <howardp@lanl.gov> | 2 个月前 | |
docs: A variety of updates Shuffle the docs organization around per discussion on github. Signed-off-by: Jeff Squyres <jsquyres@cisco.com> | 3 年前 |
| 文件 | 最后提交记录 | 最后更新时间 |
|---|---|---|
| 4 个月前 | ||
| 11 天前 | ||
| 2 个月前 | ||
| 4 年前 | ||
| 4 年前 | ||
| 3 年前 | ||
| 7 天前 | ||
| 2 个月前 | ||
| 3 个月前 | ||
| 2 个月前 | ||
| 7 天前 | ||
| 3 个月前 | ||
| 1 个月前 | ||
| 2 个月前 | ||
| 3 年前 |