Copyright (c) 2004-2005 The Trustees of Indiana University. All rights reserved. Copyright (c) 2004-2005 The Trustees of the University of Tennessee. 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$ 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 checkout). Use of GNU Autoconf, Automake, and Libtool ========================================== 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 even 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. As of this writing, you need at least Autoconf v2.58, Automake v1.8.5 (or better), and Libtool v1.5. More generally, we have never found that the most recent versions of these tools cause problems with our configure / build process. When in doubt, it is safe to upgrade these tools (at least for Open MPI!). You can check what versions you have installed with the following: shell$ autoconf --version shell$ automake --version shell$ libtool --version AUTOMAKE NOTE: It seems that Automake 1.7 (or better) is ok for *building* Open MPI, but you really need later versions for "make dist" to work properly (1.8.5 is known to work; no real testing has been conducted to determine the lowest version number where "make dist" works). 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. 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/ 2. Build and install the tools in the following order: 2a. Autoconf 2b. Automake 2c. Libtool 3. You MUST install all three tools 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. 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 three packages. 4. All three packages require two simple commands to build and install (where PREFIX is the prefix discussed in 3, above). shell$ cd autoconf-2.58 shell$ ./configure --prefix=PREFIX shell$ make all install --> NOTE: The builds are so short that parallel builds really aren't worth it (and cause problems in some cases). --> If you are using the csh or tcsh shells, be sure to run the "rehash" command after you install each package. shell$ cd ../automake-1.7 shell$ ./configure --prefix=PREFIX shell$ make all 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-1.5 shell$ ./configure --prefix=PREFIX shell$ make all install --> If you are using the csh or tcsh shells, be sure to run the "rehash" command after you install each package. 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.sh" 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.sh may take several minutes. It's not very exciting to watch. :-) 5a. You generally need to run autogen.sh whenever the top-level file "configure.ac" changes, or any files in the config/ directory change (the config/ directory is where a lot of "include" files for OMPI's configure script live). 5b. You do *NOT* need to re-run autogen.sh if you modify a Makefile.am. 5c. Note that "autogen.sh" automatically traverses the entire OMPI tree, running the GNU tools in all MCA component directories. This is not always necessary. As you become more familiar with the OMPI sources, you will come to understand the when you only need to re-generate the top-level configure script, and when you need to re-generate *all* configure scripts (it's complicated -- not described here -- when in doubt, do them all). If you only need to re-generate the top-level configure script, you can run: shell$ autogen.sh -l (i.e., "local" mode) which will prevent autogen.sh from traversing all the MCA component directories. 5d. Similarly, if you only need to regenerate the configure script in a single MCA component directory, cd into that component's directory and run autogen.sh in there directly: shell$ cd src/mca/pml/teg shell$ ../../../../autogen.sh Use of Flex =========== Flex is used during the compilation of a developer's checkout (it is not used in 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. Flex is a mature software package, and as of this writing, it has not changed since v2.5.4a in July of 1997. This version seems to work fine with Open MPI; no testing has been performed to see what the minimum version of Flex is required by Open MPI. If you do not have Flex installed, it can be downloaded from the following URL: ftp://ftp.gnu.org/non-gnu/flex/