278 lines
11 KiB
Plaintext
278 lines
11 KiB
Plaintext
Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
|
|
University Research and Technology
|
|
Corporation. All rights reserved.
|
|
Copyright (c) 2004-2005 The University of Tennessee and The University
|
|
of Tennessee Research Foundation. All rights
|
|
reserved.
|
|
Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
|
|
University of Stuttgart. All rights reserved.
|
|
Copyright (c) 2004-2005 The Regents of the University of California.
|
|
All rights reserved.
|
|
Copyright (c) 2008-2012 Cisco Systems, Inc. All rights reserved.
|
|
Copyright (c) 2013 Intel, Inc. All rights reserved.
|
|
$COPYRIGHT$
|
|
|
|
Additional copyrights may follow
|
|
|
|
$HEADER$
|
|
|
|
Overview
|
|
========
|
|
|
|
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
|
|
Subversion or Mercurial checkout).
|
|
|
|
|
|
Debugging vs. Optimized Builds
|
|
==============================
|
|
|
|
If you are building Open MPI from a Subversion checkout, the default
|
|
build includes a lot of debugging features. This happens
|
|
automatically when when configure detects the hidden ".svn" Subversion
|
|
meta directory (that is present in all Subversion checkouts) in your
|
|
source tree, and therefore activates a number of developer-only
|
|
debugging features in the Open MPI code base.
|
|
|
|
The same debugging features are activated if you build in a Git or
|
|
Mercurial clone (with the hidden ".git" or ".hg" meta directory).
|
|
|
|
By definition, debugging builds will perform [much] slower than
|
|
optimized builds of Open MPI. You should *NOT* conduct timing tests
|
|
or try to run production performance numbers with debugging builds.
|
|
|
|
If you wish to build an optimized version of Open MPI from a
|
|
developer's checkout, you have three main options:
|
|
|
|
1. Use the "--with-platform=optimized" switch to configure. This is
|
|
the preferred (and probably easiest) method. For example:
|
|
|
|
shell$ svn co http://svn.open-mpi.org/svn/ompi/trunk ompi
|
|
shell$ cd ompi
|
|
shell$ ./autogen.pl
|
|
shell$ mkdir build
|
|
shell$ cd build
|
|
shell$ ./configure --with-platform=optimized ...
|
|
[...lots of output...]
|
|
shell$ make all install
|
|
|
|
2. Use a VPATH build. Simply build Open MPI from a different
|
|
directory than the source tree -- one where the .svn / .git / .hg
|
|
subdirectory is not present. For example:
|
|
|
|
shell$ svn co http://svn.open-mpi.org/svn/ompi/trunk ompi
|
|
shell$ cd ompi
|
|
shell$ ./autogen.pl
|
|
shell$ mkdir build
|
|
shell$ cd build
|
|
shell$ ../configure ...
|
|
[...lots of output...]
|
|
shell$ make all install
|
|
|
|
3. Manually specify configure options to disable all the debugging
|
|
options (note that this is exactly what "--with-platform=optimized"
|
|
does behind the scenes). You'll need to carefully examine the
|
|
output of "./configure --help" to see which options to disable.
|
|
They are all listed, but some are less obvious than others (they
|
|
are not listed here because it is a changing set of flags; by
|
|
Murphy's Law, listing them here will pretty much guarantee that
|
|
this file will get out of date):
|
|
|
|
shell$ ./configure --disable-debug ...
|
|
[...lots of output...]
|
|
shell$ make all install
|
|
|
|
|
|
Use of GNU Autoconf, Automake, and Libtool (and m4)
|
|
===================================================
|
|
|
|
This procedure is *ONLY* necessary if you are building from a
|
|
developer's tree. If you have an Open MPI distribution tarball, this
|
|
procedure is unnecessary -- you can (and 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 trunk or a release branch (and
|
|
which release branch you are using). The specific versions can be
|
|
found at:
|
|
|
|
http://www.open-mpi.org/svn/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:
|
|
|
|
http://www.open-mpi.org/svn/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.
|
|
|
|
If you need newer versions, you are *strongly* encouraged to heed the
|
|
following advice:
|
|
|
|
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).
|
|
|
|
1. Unless your OS distribution has easy-to-use binary installations,
|
|
the sources can be can be downloaded from:
|
|
|
|
ftp://ftp.gnu.org/gnu/autoconf/
|
|
ftp://ftp.gnu.org/gnu/automake/
|
|
ftp://ftp.gnu.org/gnu/libtool/
|
|
and if you need it:
|
|
ftp://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.
|
|
|
|
2. Build and install the tools in the following order:
|
|
|
|
2a. m4
|
|
2b. Autoconf
|
|
2c. Automake
|
|
2d. Libtool
|
|
|
|
3. 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.
|
|
|
|
3a. 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.
|
|
3b. 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:
|
|
|
|
# For bash/sh:
|
|
export PATH=$HOME/local/bin:$PATH
|
|
# For csh/tcsh:
|
|
set path = ($HOME/local/bin $path)
|
|
|
|
3c. Ensure to set your $path *BEFORE* you configure/build/install
|
|
the four packages.
|
|
|
|
4. 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
|
|
|
|
--> 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
|
|
|
|
--> 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
|
|
|
|
--> 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
|
|
|
|
--> 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.
|
|
|
|
5. 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. :-)
|
|
|
|
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):
|
|
|
|
# For bash/sh:
|
|
export AUTOMAKE_JOBS=4
|
|
# For csh/tcsh:
|
|
set AUTOMAKE_JOBS 4
|
|
|
|
5a. 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 OMPI's configure script
|
|
live).
|
|
|
|
5b. 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, it can be downloaded from the
|
|
following URL:
|
|
|
|
http://flex.sourceforge.net/
|