Skip to content

Commit

Permalink
docs: Convert Open MPI docs to reStructured Text
Browse files Browse the repository at this point in the history 
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>
  • Loading branch information
@jsquyres @hkuno
@gpaulsen @abouteiller @bosilca @jjhursey @bwbarrett
7 people committed Mar 7, 2022
1 parent 3990b3f commit 5bb64fe
Show file tree
Hide file tree
Showing 1,548 changed files with 76,665 additions and 56,306 deletions.
20 changes: 9 additions & 11 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -355,19 +355,12 @@ ompi/tools/ompi_info/ompi_info.1
ompi/tools/wrappers/mpic++-wrapper-data.txt
ompi/tools/wrappers/mpicc-wrapper-data.txt
ompi/tools/wrappers/mpifort-wrapper-data.txt
ompi/tools/wrappers/mpicc.1
ompi/tools/wrappers/mpic++.1
ompi/tools/wrappers/mpicxx.1
ompi/tools/wrappers/mpifort.1
ompi/tools/wrappers/mpijavac.1
ompi/tools/wrappers/ompi_wrapper_script
ompi/tools/wrappers/ompi.pc
ompi/tools/wrappers/ompi-c.pc
ompi/tools/wrappers/ompi-cxx.pc
ompi/tools/wrappers/ompi-fort.pc
ompi/tools/wrappers/mpijavac.pl
ompi/tools/wrappers/mpif90.1
ompi/tools/wrappers/mpif77.1
ompi/tools/wrappers/mpicxx-wrapper-data.txt
ompi/tools/wrappers/mpif77-wrapper-data.txt
ompi/tools/wrappers/mpif90-wrapper-data.txt
Expand Down Expand Up @@ -471,10 +464,6 @@ opal/tools/wrappers/opalcc-wrapper-data.txt
opal/tools/wrappers/opalc++-wrapper-data.txt
opal/tools/wrappers/opalCC-wrapper-data.txt
opal/tools/wrappers/opal_wrapper
opal/tools/wrappers/opalcc.1
opal/tools/wrappers/opalc++.1
opal/tools/wrappers/generic_wrapper.1
opal/tools/wrappers/opal_wrapper.1
opal/tools/wrappers/opal.pc

opal/util/show_help_lex.c
Expand Down Expand Up @@ -704,3 +693,12 @@ opal/test/reachable/reachable_netlink
opal/test/reachable/reachable_weighted
opal/mca/threads/argobots/threads_argobots.h
opal/mca/threads/qthreads/threads_qthreads.h

docs/_build
docs/_static
docs/_static/css/custom.css
docs/_templates

# Common Python virtual environment directory names
venv
py??
10 changes: 10 additions & 0 deletions .readthedocs.yaml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Build documentation in the docs/ directory with Sphinx
sphinx:
configuration: docs/conf.py
272 changes: 6 additions & 266 deletions HACKING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,271 +6,11 @@ This file is here for those who are building/exploring OMPI in its
source code form, most likely through a developer's tree (i.e., a
Git clone).

## This file has moved

## Obtaining Open MPI
Please see the content of this file in its new location:
https://ompi.readthedocs.io/en/latest/developers/

Open MPI is available from many distributions, however some users
prefer to obtain it directly from the Open MPI community via
prepackaged tarball (see: https://www.open-mpi.org/software/ompi/).
The Open MPI tarball includes manpages, and openpmix and openprrte
components, along with an auto-generated configure script.

Some developers prefer to obtain Open MPI by directly cloning it
from https://github.com/open-mpi/ompi. It is recommended that users
who choose to clone the source directly, use the git clone flag
`--recurse-submodules`, to also obtain the openpmix, and openprrte.

Regardless of how openpmix and openprrte are obtained, the
configure logic in Open MPI v5.0+ prefer externally installed
components. Please see `configure --help` for more details.


## Developer Builds: Compiler Pickyness by Default

If you are building Open MPI from a Git clone (i.e., there is a `.git`
directory in your build tree), the default build includes extra
compiler pickyness, which will result in more compiler warnings than
in non-developer builds. Getting these extra compiler warnings is
helpful to Open MPI developers in making the code base as clean as
possible.

Developers can disable this picky-by-default behavior by using the
`--disable-picky` configure option. Also note that extra-picky compiles
do *not* happen automatically when you do a VPATH build (e.g., if
`.git` is in your source tree, but not in your build tree).

Prior versions of Open MPI would automatically activate a lot of
(performance-reducing) debugging code by default if `.git` was found
in your build tree. This is no longer true. You can manually enable
these (performance-reducing) debugging features in the Open MPI code
base with these configure options:

* `--enable-debug`
* `--enable-mem-debug`
* `--enable-mem-profile`

***NOTE:*** These options are really only relevant to those who are
developing Open MPI itself. They are not generally helpful for
debugging general MPI applications.


## Use of GNU Autoconf, Automake, and Libtool (and m4)

You need to read/care about this section *ONLY* if you are building
from a developer's tree (i.e., a Git clone of the Open MPI source
tree). If you have an Open MPI distribution tarball, the contents of
this section are optional -- you can (and probably should) skip
reading this section.

If you are building Open MPI from a developer's tree, you must first
install fairly recent versions of the GNU tools Autoconf, Automake,
and Libtool (and possibly GNU m4, because recent versions of Autoconf
have specific GNU m4 version requirements). The specific versions
required depend on if you are using the Git master branch or a release
branch (and which release branch you are using). [The specific
versions can be found
here](https://www.open-mpi.org/source/building.php).

You can check what versions of the autotools you have installed with
the following:

```
shell$ m4 --version
shell$ autoconf --version
shell$ automake --version
shell$ libtoolize --version
```

[Required version levels for all the OMPI releases can be found
here](https://www.open-mpi.org/source/building.php).

To strengthen the above point: the core Open MPI developers typically
use very, very recent versions of the GNU tools. There are known bugs
in older versions of the GNU tools that Open MPI no longer compensates
for (it seemed senseless to indefinitely support patches for ancient
versions of Autoconf, for example). You *WILL* have problems if you
do not use recent versions of the GNU tools.

***NOTE:*** On MacOS/X, the default `libtool` program is different
than the GNU libtool. You must download and install the GNU version
(e.g., via MacPorts, Homebrew, or some other mechanism).

If you need newer versions, you are *strongly* encouraged to heed the
following advice:

1. Unless your OS distribution has easy-to-use binary installations,
the sources can be can be downloaded from:
* https://ftp.gnu.org/gnu/autoconf/
* https://ftp.gnu.org/gnu/automake/
* https://ftp.gnu.org/gnu/libtool/
* And if you need it: https://ftp.gnu.org/gnu/m4/

***NOTE:*** It is certainly easiest to download/build/install all
four of these tools together. But note that Open MPI has no
specific m4 requirements; it is only listed here because Autoconf
requires minimum versions of GNU m4. Hence, you may or may not
*need* to actually install a new version of GNU m4. That being
said, if you are confused or don't know, just install the latest
GNU m4 with the rest of the GNU Autotools and everything will work
out fine.

1. Build and install the tools in the following order:
1. m4
1. Autoconf
1. Automake
1. Libtool

1. You MUST install the last three tools (Autoconf, Automake, Libtool)
into the same prefix directory. These three tools are somewhat
inter-related, and if they're going to be used together, they MUST
share a common installation prefix.

You can install m4 anywhere as long as it can be found in the path;
it may be convenient to install it in the same prefix as the other
three. Or you can use any recent-enough m4 that is in your path.

1. It is *strongly* encouraged that you do not install your new
versions over the OS-installed versions. This could cause
other things on your system to break. Instead, install into
`$HOME/local`, or `/usr/local`, or wherever else you tend to
install "local" kinds of software.
1. In doing so, be sure to prefix your $path with the directory
where they are installed. For example, if you install into
`$HOME/local`, you may want to edit your shell startup file
(`.bashrc`, `.cshrc`, `.tcshrc`, etc.) to have something like:

```sh
# For bash/sh:
export PATH=$HOME/local/bin:$PATH
# For csh/tcsh:
set path = ($HOME/local/bin $path)
```

1. Ensure to set your `$PATH` *BEFORE* you configure/build/install
the four packages.

1. All four packages require two simple commands to build and
install (where PREFIX is the prefix discussed in 3, above).

```
shell$ cd <m4 directory>
shell$ ./configure --prefix=PREFIX
shell$ make; make install
```
***NOTE:*** If you are using the `csh` or `tcsh` shells, be sure to
run the `rehash` command after you install each package.
```
shell$ cd <autoconf directory>
shell$ ./configure --prefix=PREFIX
shell$ make; make install
```
***NOTE:*** If you are using the `csh` or `tcsh` shells, be sure to
run the `rehash` command after you install each package.
```
shell$ cd <automake directory>
shell$ ./configure --prefix=PREFIX
shell$ make; make install
```
***NOTE:*** If you are using the `csh` or `tcsh` shells, be sure to
run the `rehash` command after you install each package.
```
shell$ cd <libtool directory>
shell$ ./configure --prefix=PREFIX
shell$ make; make install
```
***NOTE:*** If you are using the `csh` or `tcsh` shells, be sure to
run the `rehash` command after you install each package.
m4, Autoconf and Automake build and install very quickly; Libtool
will take a minute or two.
1. You can now run OMPI's top-level `autogen.pl` script. This script
will invoke the GNU Autoconf, Automake, and Libtool commands in the
proper order and setup to run OMPI's top-level `configure` script.
Running `autogen.pl` may take a few minutes, depending on your
system. It's not very exciting to watch. :smile:
If you have a multi-processor system, enabling the multi-threaded
behavior in Automake 1.11 (or newer) can result in `autogen.pl`
running faster. Do this by setting the `AUTOMAKE_JOBS` environment
variable to the number of processors (threads) that you want it to
use before invoking `autogen`.pl. For example (you can again put
this in your shell startup files):
```sh
# For bash/sh:
export AUTOMAKE_JOBS=4
# For csh/tcsh:
set AUTOMAKE_JOBS 4
```
1. You generally need to run autogen.pl whenever the top-level file
`configure.ac` changes, or any files in the `config/` or
`<project>/config/` directories change (these directories are
where a lot of "include" files for Open MPI's `configure` script
live).
1. You do *NOT* need to re-run `autogen.pl` if you modify a
`Makefile.am`.
## Use of Flex
Flex is used during the compilation of a developer's checkout (it is
not used to build official distribution tarballs). Other flavors of
lex are *not* supported: given the choice of making parsing code
portable between all flavors of lex and doing more interesting work on
Open MPI, we greatly prefer the latter.
Note that no testing has been performed to see what the minimum
version of Flex is required by Open MPI. We suggest that you use
v2.5.35 at the earliest.
***NOTE:*** Windows developer builds of Open MPI *require* Flex version
2.5.35. Specifically, we know that v2.5.35 works and 2.5.4a does not.
We have not tested to figure out exactly what the minimum required
flex version is on Windows; we suggest that you use 2.5.35 at the
earliest. It is for this reason that the
`contrib/dist/make_dist_tarball` script checks for a Windows-friendly
version of Flex before continuing.
For now, Open MPI will allow developer builds with Flex 2.5.4. This
is primarily motivated by the fact that RedHat/Centos 5 ships with
Flex 2.5.4. It is likely that someday Open MPI developer builds will
require Flex version >=2.5.35.
Note that the `flex`-generated code generates some compiler warnings
on some platforms, but the warnings do not seem to be consistent or
uniform on all platforms, compilers, and flex versions. As such, we
have done little to try to remove those warnings.
If you do not have Flex installed, see [the Flex Github
repository](https://github.com/westes/flex).
## Use of Pandoc
Similar to prior sections, you need to read/care about this section
*ONLY* if you are building from a developer's tree (i.e., a Git clone
of the Open MPI source tree). If you have an Open MPI distribution
tarball, the contents of this section are optional -- you can (and
probably should) skip reading this section.
The Pandoc tool is used to generate Open MPI's man pages.
Specifically: Open MPI's man pages are written in Markdown; Pandoc is
the tool that converts that Markdown to nroff (i.e., the format of man
pages).
You must have Pandoc >=v1.12 when building Open MPI from a developer's
tree. If configure cannot find Pandoc >=v1.12, it will abort.
If you need to install Pandoc, check your operating system-provided
packages (to include MacOS Homebrew and MacPorts). [The Pandoc
project web site](https://pandoc.org/) itself also offers binaries for
their releases.
Additionally, see
https://ompi.readthedocs.io/en/latest/developers/prerequisites.html#sphinx
if you want to edit and build the documentation locally.
Loading

0 comments on commit 5bb64fe

Please sign in to comment.