Skip to content

Commit b4c1795

Browse files
jsquyresjsquyres
committed
Lots more updates, including two new FAQ sections.
Signed-off-by: Jeff Squyres <[email protected]>
1 parent fb3e6fd commit b4c1795

17 files changed

+2201
-421
lines changed

‎docs/developer-gnu-autotools.rst

Lines changed: 349 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,349 @@
1+
.. This is a separate file just for manageability: it's kinda long in
2+
itself, and the developers.rst file is already pretty long.
3+
4+
Installing the GNU Autootools
5+
-----------------------------
6+
7+
.. _gnu-autotools-section-label:
8+
9+
There is enough detail in building the GNU Autotools that it warrants
10+
its own section.
11+
12+
.. note:: As noted above, you only need to read/care about this
13+
section if you are building Open MPI from a Git clone. End
14+
users installing an Open MPI distribution tarball do *not*
15+
need to have the GNU Autotools installed.
16+
17+
Autotools versions
18+
^^^^^^^^^^^^^^^^^^
19+
20+
The following tools are required for developers to compile Open MPI
21+
from its repository sources (users who download Open MPI tarballs do
22+
not need these tools - they are only required for developers working
23+
on the internals of Open MPI itself):
24+
25+
.. list-table::
26+
:header-rows: 1
27+
28+
* - Software package
29+
- Notes
30+
- URL
31+
32+
* - GNU m4
33+
- See version chart below
34+
- https://ftp.gnu.org/gnu/m4/
35+
* - GNU Autoconf
36+
- See version chart below
37+
- https://ftp.gnu.org/gnu/autoconf/
38+
* - GNU Automake
39+
- See version chart below
40+
- https://ftp.gnu.org/gnu/automake/
41+
* - GNU Libtool
42+
- See version chart below
43+
- https://ftp.gnu.org/gnu/libtool/
44+
45+
The table below lists the versions that are used to make nightly
46+
snapshot and official release Open MPI tarballs. Other versions of the
47+
tools may work for some (but almost certainly not all) platforms, but
48+
the ones listed below are the versions that we know work across an
49+
extremely wide variety of platforms and environments.
50+
51+
To strengthen the above point: the core Open MPI developers typically
52+
use very, very recent versions of the GNU tools. There are known bugs
53+
in older versions of the GNU tools that Open MPI no longer compensates
54+
for (it seemed senseless to indefinitely support patches for ancient
55+
versions of Autoconf, for example).
56+
57+
.. warning:: You **will** have problems if you do not use recent
58+
versions of the GNU Autotools.
59+
60+
That being said, ``autogen.pl`` and ``configure.ac`` scripts tend to
61+
be a bit lenient and enforce slightly older minimum versions than the
62+
ones listed below. This is because such older versions still make
63+
usable Open MPI builds on many platforms - especially Linux on x86_64
64+
with GNU compilers - and are convenient for developers whose Linux
65+
distro may not have as recent as the versions listed below (but are
66+
recent enough to produce a working version for their platform).
67+
68+
To be clear: the versions listed below are required to support a wide
69+
variety of platforms and environments, and are used to make nightly
70+
and official release tarballs. When building Open MPI, YMMV when using
71+
versions older than those listed below |mdash| especially if you are
72+
not building on Linux x86_64 with the GNU compilers.
73+
74+
Using older versions is unsupported. If you run into problems, upgrade
75+
to at least the versions listed below.
76+
77+
.. note:: You may need to scroll right in the following table.
78+
79+
.. list-table::
80+
:header-rows: 1
81+
82+
* - Open MPI
83+
- M4
84+
- Autoconf
85+
- Automake
86+
- Libtool
87+
- Flex
88+
- Pandoc
89+
- Sphinx
90+
91+
* - v1.0.x
92+
- NA
93+
- 2.58 - 2.59
94+
- 1.7 - 1.9.6
95+
- 1.5.16 - 1.5.22
96+
- 2.5.4
97+
- NA
98+
- NA
99+
* - v1.1.x
100+
- NA
101+
- 2.59
102+
- 1.9.6
103+
- 1.5.16 - 1.5.22
104+
- 2.5.4
105+
- NA
106+
- NA
107+
* - v1.2.x
108+
- NA
109+
- 2.59
110+
- 1.9.6
111+
- 1.5.22 - 2.1a
112+
- 2.5.4
113+
- NA
114+
- NA
115+
* - v1.3.x
116+
- 1.4.11
117+
- 2.63
118+
- 1.10.1
119+
- 2.2.6b
120+
- 2.5.4
121+
- NA
122+
- NA
123+
* - v1.4.x
124+
- 1.4.11
125+
- 2.63
126+
- 1.10.3
127+
- 2.2.6b
128+
- 2.5.4
129+
- NA
130+
- NA
131+
* - v1.5.x for x=0-4
132+
- 1.4.13
133+
- 2.65
134+
- 1.11.1
135+
- 2.2.6b
136+
- 2.5.4
137+
- NA
138+
- NA
139+
* - v1.5.x for x>=5
140+
- 1.4.16
141+
- 2.68
142+
- 1.11.3
143+
- 2.4.2
144+
- 2.5.35
145+
- NA
146+
- NA
147+
* - v1.6.x
148+
- 1.4.16
149+
- 2.68
150+
- 1.11.3
151+
- 2.4.2
152+
- 2.5.35
153+
- NA
154+
- NA
155+
* - v1.7.x
156+
- 1.4.16
157+
- 2.69
158+
- 1.12.2
159+
- 2.4.2
160+
- 2.5.35
161+
- NA
162+
- NA
163+
* - v1.8.x
164+
- 1.4.16
165+
- 2.69
166+
- 1.12.2
167+
- 2.4.2
168+
- 2.5.35
169+
- NA
170+
- NA
171+
* - v1.10.x
172+
- 1.4.16
173+
- 2.69
174+
- 1.12.2
175+
- 2.4.2
176+
- 2.5.35
177+
- NA
178+
- NA
179+
* - v2.0.x through v4.y
180+
- 1.4.17
181+
- 2.69
182+
- 1.15
183+
- 2.4.6
184+
- 2.5.35
185+
- NA
186+
- NA
187+
* - Git master
188+
- 1.4.17
189+
- 2.69
190+
- 1.15
191+
- 2.4.6
192+
- 2.5.35
193+
- 1.12
194+
- 3.4.1
195+
196+
.. error:: **JMS Remove Pandoc, above?**
197+
198+
Here are some random notes about the GNU Autotools:
199+
200+
#. Other version combinations may work, but are untested and
201+
unsupported. In particular, developers tend to use higher versions
202+
of Autotools for master/development work, and they usually work
203+
fine.
204+
205+
#. The v1.4 and v1.5 series had their Automake versions updated on 10
206+
July 2011 (from 1.10.1 to 1.10.3, and 1.11 to 1.11.1, respectively)
207+
due to CVE-2009-4029. This applies to all new snapshot tarballs
208+
produced after this date, and the v1.4 series as of v1.4.4, and the
209+
v1.5 series as of 1.5.4.
210+
211+
#. If Autoconf 2.60 (and higher) is used, Automake 1.10 (and higher)
212+
must be used.
213+
214+
#. The ``master`` branch and all release branches starting with v1.2
215+
require the use of Libtool 2.x (or higher) so that Open MPI can
216+
build the Fortran 90 module as a shared library. If (and only if)
217+
you intend to not build the Fortran 90 library or your Fortran 77
218+
and Fortran 90 compilers have the same name (e.g., gfortran), you
219+
can use Libtool 1.5.22 to build Open MPI v1.0 through v1.2.x.
220+
221+
#. There was a period of time where Open MPI nightly snapshot tarballs
222+
were made with `a Libtool 2.0 development snapshot
223+
<https://www.open-mpi.org/source/libtool.tar.gz>`_. This has
224+
long-since been deprecated; Open MPI uses official Libtool releases
225+
(no official Open MPI releases used the Libtool 2.0 development
226+
snapshot).
227+
228+
229+
Checking your versions
230+
^^^^^^^^^^^^^^^^^^^^^^
231+
232+
You can check what versions of the Autotools you have installed with
233+
the following:
234+
235+
.. code-block:: sh
236+
:linenos:
237+
238+
shell$ m4 --version
239+
shell$ autoconf --version
240+
shell$ automake --version
241+
shell$ libtoolize --version
242+
243+
Installing the GNU Autotools from source
244+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
245+
246+
.. note:: Most operating system packaging systems (to include Homebrew
247+
and MacPorts on MacOS) install recent-enough versions of the
248+
GNU Autotools. You should generally only install the GNU
249+
Autotools manually if you can't use your operating system
250+
packaging system to install them for you.
251+
252+
The GNU Autotools sources can be can be downloaded from:
253+
254+
* https://ftp.gnu.org/gnu/autoconf/
255+
* https://ftp.gnu.org/gnu/automake/
256+
* https://ftp.gnu.org/gnu/libtool/
257+
* And if you need it: https://ftp.gnu.org/gnu/m4/
258+
259+
It is certainly easiest to download/build/install all four of these
260+
tools together. But note that Open MPI has no specific m4
261+
requirements; it is only listed here because Autoconf requires minimum
262+
versions of GNU m4. Hence, you may or may not *need* to actually
263+
install a new version of GNU m4. That being said, if you are confused
264+
or don't know, just install the latest GNU m4 with the rest of the GNU
265+
Autotools and everything will work out fine.
266+
267+
268+
Build and Install Ordering
269+
^^^^^^^^^^^^^^^^^^^^^^^^^^
270+
271+
You must build and install the GNU Autotools in the following order:
272+
273+
#. m4
274+
#. Autoconf
275+
#. Automake
276+
#. Libtool
277+
278+
You *must* install the last three tools (Autoconf, Automake, Libtool)
279+
into the same prefix directory. These three tools are somewhat
280+
inter-related, and if they're going to be used together, they MUST
281+
share a common installation prefix.
282+
283+
You can install m4 anywhere as long as it can be found in the path;
284+
it may be convenient to install it in the same prefix as the other
285+
three. Or you can use any recent-enough m4 that is in your path.
286+
287+
.. warning:: It is *strongly* encouraged that you do **not** install
288+
your new versions over the OS-installed versions. This could cause
289+
other things on your system to break. Instead, install into
290+
``$HOME/local``, or ``/usr/local``, or wherever else you tend to
291+
install "local" kinds of software.
292+
293+
In doing so, be sure to prefix your ``$PATH`` with the directory
294+
where they are installed. For example, if you install into
295+
``$HOME/local``, you may want to edit your shell startup file
296+
(``.bashrc``, ``.cshrc``, ``.tcshrc``, etc.) to have something
297+
like:
298+
299+
.. code-block:: sh
300+
:linenos:
301+
302+
# For bash/sh:
303+
export PATH=$HOME/local/bin:$PATH
304+
# For csh/tcsh:
305+
set path = ($HOME/local/bin $path)
306+
307+
Ensure to set your ``$PATH`` *BEFORE* you configure/build/install
308+
the four packages.
309+
310+
All four packages require two simple commands to build and
311+
install (where ``PREFIX`` is the prefix discussed in 3, above).
312+
313+
.. code-block:: sh
314+
:linenos:
315+
316+
shell$ cd M4_DIRECTORY
317+
shell$ ./configure --prefix=PREFIX
318+
shell$ make all install
319+
320+
.. important:: If you are using a shell that does not automatically
321+
re-index the ``$PATH`` (e.g., the ``csh`` or ``tcsh``
322+
shells), be sure to run the ``rehash`` command before
323+
you install the next package so that the executables
324+
that were just installed can be found by the next
325+
package.
326+
327+
.. code-block:: sh
328+
:linenos:
329+
330+
# Make $PATH be re-indexed if necessary, e.g., via "rehash"
331+
shell$ cd AUTOCONF_DIRECTORY
332+
shell$ ./configure --prefix=PREFIX
333+
shell$ make all install
334+
335+
.. code-block:: sh
336+
:linenos:
337+
338+
# Make $PATH be re-indexed if necessary, e.g., via "rehash"
339+
shell$ cd AUTOMAKE_DIRECTORY
340+
shell$ ./configure --prefix=PREFIX
341+
shell$ make all install
342+
343+
.. code-block:: sh
344+
:linenos:
345+
346+
# Make $PATH be re-indexed if necessary, e.g., via "rehash"
347+
shell$ cd LIBTOOL_DIRECTORY
348+
shell$ ./configure --prefix=PREFIX
349+
shell$ make all install

0 commit comments

Comments
 (0)