@@ -6,271 +6,11 @@ This file is here for those who are building/exploring OMPI in its
66source code form, most likely through a developer's tree (i.e., a
77Git clone).
88
9+ ## This file has moved
910
10- ## Obtaining Open MPI
11+ Please see the content of this file in its new location:
12+ https://ompi.readthedocs.io/en/latest/developers/
1113
12- Open MPI is available from many distributions, however some users
13- prefer to obtain it directly from the Open MPI community via
14- prepackaged tarball (see: https://www.open-mpi.org/software/ompi/ ).
15- The Open MPI tarball includes manpages, and openpmix and openprrte
16- components, along with an auto-generated configure script.
17-
18- Some developers prefer to obtain Open MPI by directly cloning it
19- from https://github.com/open-mpi/ompi . It is recommended that users
20- who choose to clone the source directly, use the git clone flag
21- ` --recurse-submodules ` , to also obtain the openpmix, and openprrte.
22-
23- Regardless of how openpmix and openprrte are obtained, the
24- configure logic in Open MPI v5.0+ prefer externally installed
25- components. Please see ` configure --help ` for more details.
26-
27-
28- ## Developer Builds: Compiler Pickyness by Default
29-
30- If you are building Open MPI from a Git clone (i.e., there is a ` .git `
31- directory in your build tree), the default build includes extra
32- compiler pickyness, which will result in more compiler warnings than
33- in non-developer builds. Getting these extra compiler warnings is
34- helpful to Open MPI developers in making the code base as clean as
35- possible.
36-
37- Developers can disable this picky-by-default behavior by using the
38- ` --disable-picky ` configure option. Also note that extra-picky compiles
39- do * not* happen automatically when you do a VPATH build (e.g., if
40- ` .git ` is in your source tree, but not in your build tree).
41-
42- Prior versions of Open MPI would automatically activate a lot of
43- (performance-reducing) debugging code by default if ` .git ` was found
44- in your build tree. This is no longer true. You can manually enable
45- these (performance-reducing) debugging features in the Open MPI code
46- base with these configure options:
47-
48- * ` --enable-debug `
49- * ` --enable-mem-debug `
50- * ` --enable-mem-profile `
51-
52- *** NOTE:*** These options are really only relevant to those who are
53- developing Open MPI itself. They are not generally helpful for
54- debugging general MPI applications.
55-
56-
57- ## Use of GNU Autoconf, Automake, and Libtool (and m4)
58-
59- You need to read/care about this section * ONLY* if you are building
60- from a developer's tree (i.e., a Git clone of the Open MPI source
61- tree). If you have an Open MPI distribution tarball, the contents of
62- this section are optional -- you can (and probably should) skip
63- reading this section.
64-
65- If you are building Open MPI from a developer's tree, you must first
66- install fairly recent versions of the GNU tools Autoconf, Automake,
67- and Libtool (and possibly GNU m4, because recent versions of Autoconf
68- have specific GNU m4 version requirements). The specific versions
69- required depend on if you are using the Git master branch or a release
70- branch (and which release branch you are using). [ The specific
71- versions can be found
72- here] ( https://www.open-mpi.org/source/building.php ) .
73-
74- You can check what versions of the autotools you have installed with
75- the following:
76-
77- ```
78- shell$ m4 --version
79- shell$ autoconf --version
80- shell$ automake --version
81- shell$ libtoolize --version
82- ```
83-
84- [ Required version levels for all the OMPI releases can be found
85- here] ( https://www.open-mpi.org/source/building.php ) .
86-
87- To strengthen the above point: the core Open MPI developers typically
88- use very, very recent versions of the GNU tools. There are known bugs
89- in older versions of the GNU tools that Open MPI no longer compensates
90- for (it seemed senseless to indefinitely support patches for ancient
91- versions of Autoconf, for example). You * WILL* have problems if you
92- do not use recent versions of the GNU tools.
93-
94- *** NOTE:*** On MacOS/X, the default ` libtool ` program is different
95- than the GNU libtool. You must download and install the GNU version
96- (e.g., via MacPorts, Homebrew, or some other mechanism).
97-
98- If you need newer versions, you are * strongly* encouraged to heed the
99- following advice:
100-
101- 1 . Unless your OS distribution has easy-to-use binary installations,
102- the sources can be can be downloaded from:
103- * https://ftp.gnu.org/gnu/autoconf/
104- * https://ftp.gnu.org/gnu/automake/
105- * https://ftp.gnu.org/gnu/libtool/
106- * And if you need it: https://ftp.gnu.org/gnu/m4/
107-
108- *** NOTE:*** It is certainly easiest to download/build/install all
109- four of these tools together. But note that Open MPI has no
110- specific m4 requirements; it is only listed here because Autoconf
111- requires minimum versions of GNU m4. Hence, you may or may not
112- * need* to actually install a new version of GNU m4. That being
113- said, if you are confused or don't know, just install the latest
114- GNU m4 with the rest of the GNU Autotools and everything will work
115- out fine.
116-
117- 1 . Build and install the tools in the following order:
118- 1 . m4
119- 1 . Autoconf
120- 1 . Automake
121- 1 . Libtool
122-
123- 1 . You MUST install the last three tools (Autoconf, Automake, Libtool)
124- into the same prefix directory. These three tools are somewhat
125- inter-related, and if they're going to be used together, they MUST
126- share a common installation prefix.
127-
128- You can install m4 anywhere as long as it can be found in the path;
129- it may be convenient to install it in the same prefix as the other
130- three. Or you can use any recent-enough m4 that is in your path.
131-
132- 1 . It is * strongly* encouraged that you do not install your new
133- versions over the OS-installed versions. This could cause
134- other things on your system to break. Instead, install into
135- ` $HOME/local ` , or ` /usr/local ` , or wherever else you tend to
136- install "local" kinds of software.
137- 1 . In doing so, be sure to prefix your $path with the directory
138- where they are installed. For example, if you install into
139- ` $HOME/local ` , you may want to edit your shell startup file
140- (` .bashrc ` , ` .cshrc ` , ` .tcshrc ` , etc.) to have something like:
141-
142- ``` sh
143- # For bash/sh:
144- export PATH=$HOME /local/bin:$PATH
145- # For csh/tcsh:
146- set path = ($HOME /local/bin $path )
147- ```
148-
149- 1. Ensure to set your ` $PATH ` * BEFORE* you configure/build/install
150- the four packages.
151-
152- 1. All four packages require two simple commands to build and
153- install (where PREFIX is the prefix discussed in 3, above).
154-
155- ```
156- shell$ cd <m4 directory >
157- shell$ ./configure --prefix=PREFIX
158- shell$ make; make install
159- ```
160-
161- ***NOTE:*** If you are using the `csh` or `tcsh` shells, be sure to
162- run the `rehash` command after you install each package.
163-
164- ```
165- shell$ cd <autoconf directory >
166- shell$ ./configure --prefix=PREFIX
167- shell$ make; make install
168- ```
169-
170- ***NOTE:*** If you are using the `csh` or `tcsh` shells, be sure to
171- run the `rehash` command after you install each package.
172-
173- ```
174- shell$ cd <automake directory >
175- shell$ ./configure --prefix=PREFIX
176- shell$ make; make install
177- ```
178-
179- ***NOTE:*** If you are using the `csh` or `tcsh` shells, be sure to
180- run the `rehash` command after you install each package.
181-
182- ```
183- shell$ cd <libtool directory >
184- shell$ ./configure --prefix=PREFIX
185- shell$ make; make install
186- ```
187-
188- ***NOTE:*** If you are using the `csh` or `tcsh` shells, be sure to
189- run the `rehash` command after you install each package.
190-
191- m4, Autoconf and Automake build and install very quickly; Libtool
192- will take a minute or two.
193-
194- 1. You can now run OMPI's top-level `autogen.pl` script. This script
195- will invoke the GNU Autoconf, Automake, and Libtool commands in the
196- proper order and setup to run OMPI's top-level `configure` script.
197-
198- Running `autogen.pl` may take a few minutes, depending on your
199- system. It's not very exciting to watch. :smile:
200-
201- If you have a multi-processor system, enabling the multi-threaded
202- behavior in Automake 1.11 (or newer) can result in `autogen.pl`
203- running faster. Do this by setting the `AUTOMAKE_JOBS` environment
204- variable to the number of processors (threads) that you want it to
205- use before invoking `autogen`.pl. For example (you can again put
206- this in your shell startup files):
207-
208- ```sh
209- # For bash/sh:
210- export AUTOMAKE_JOBS=4
211- # For csh/tcsh:
212- set AUTOMAKE_JOBS 4
213- ```
214-
215- 1. You generally need to run autogen.pl whenever the top-level file
216- `configure.ac` changes, or any files in the `config/` or
217- `<project>/config/` directories change (these directories are
218- where a lot of "include" files for Open MPI's `configure` script
219- live).
220-
221- 1. You do *NOT* need to re-run `autogen.pl` if you modify a
222- `Makefile.am`.
223-
224- ## Use of Flex
225-
226- Flex is used during the compilation of a developer's checkout (it is
227- not used to build official distribution tarballs). Other flavors of
228- lex are *not* supported: given the choice of making parsing code
229- portable between all flavors of lex and doing more interesting work on
230- Open MPI, we greatly prefer the latter.
231-
232- Note that no testing has been performed to see what the minimum
233- version of Flex is required by Open MPI. We suggest that you use
234- v2.5.35 at the earliest.
235-
236- ***NOTE:*** Windows developer builds of Open MPI *require* Flex version
237- 2.5.35. Specifically, we know that v2.5.35 works and 2.5.4a does not.
238- We have not tested to figure out exactly what the minimum required
239- flex version is on Windows; we suggest that you use 2.5.35 at the
240- earliest. It is for this reason that the
241- `contrib/dist/make_dist_tarball` script checks for a Windows-friendly
242- version of Flex before continuing.
243-
244- For now, Open MPI will allow developer builds with Flex 2.5.4. This
245- is primarily motivated by the fact that RedHat/Centos 5 ships with
246- Flex 2.5.4. It is likely that someday Open MPI developer builds will
247- require Flex version >=2.5.35.
248-
249- Note that the `flex`-generated code generates some compiler warnings
250- on some platforms, but the warnings do not seem to be consistent or
251- uniform on all platforms, compilers, and flex versions. As such, we
252- have done little to try to remove those warnings.
253-
254- If you do not have Flex installed, see [the Flex Github
255- repository](https://github.com/westes/flex).
256-
257- ## Use of Pandoc
258-
259- Similar to prior sections, you need to read/care about this section
260- *ONLY* if you are building from a developer's tree (i.e., a Git clone
261- of the Open MPI source tree). If you have an Open MPI distribution
262- tarball, the contents of this section are optional -- you can (and
263- probably should) skip reading this section.
264-
265- The Pandoc tool is used to generate Open MPI's man pages.
266- Specifically: Open MPI's man pages are written in Markdown; Pandoc is
267- the tool that converts that Markdown to nroff (i.e., the format of man
268- pages).
269-
270- You must have Pandoc >=v1.12 when building Open MPI from a developer's
271- tree. If configure cannot find Pandoc >=v1.12, it will abort.
272-
273- If you need to install Pandoc, check your operating system-provided
274- packages (to include MacOS Homebrew and MacPorts). [The Pandoc
275- project web site](https://pandoc.org/) itself also offers binaries for
276- their releases.
14+ Additionally, see
15+ https://ompi.readthedocs.io/en/latest/developers/prerequisites.html#sphinx
16+ if you want to edit and build the documentation locally.
0 commit comments