openmpi/HACKING

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-2014 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
Git clone).


Debugging vs. Optimized Builds
==============================

If you are building Open MPI from a Git clone, the default build
includes a lot of debugging features.  This happens automatically when
when configure detects the hidden ".git" Git meta directory (that is
present in all Git clones) in your source tree, and therefore
activates a number of developer-only debugging features in the Open
MPI code base.

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$ git clone git@github.com:open-mpi/ompi.git
     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 .git subdirectory
   is not present.  For example:

     shell$ git clone git@github.com:open-mpi/ompi.git
     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/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:

http://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.

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/