diff --git a/HACKING b/HACKING index 7a26e3611f..5ea8fc2889 100644 --- a/HACKING +++ b/HACKING @@ -17,7 +17,51 @@ 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). +Subversion 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. + +By definition, debugging builds will perform 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 two main options: + +1. Use a VPATH build. This is the preferred (and usually easiest) + method. Simply build Open MPI from a different directory than the + source tree -- one where the .svn subdirectory is not present. For + example: + + shell$ svn co https://svn.open-mpi.org/svn/ompi/trunk ompi + shell$ cd ompi + shell$ ./autogen.sh + shell$ mkdir build + shell$ cd build + shell$ ../configure ... + [...lots of output...] + shell$ make all install + +2. Manually specify configure options to disable all the debugging + options. 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 guarnatee 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 @@ -25,16 +69,20 @@ 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. +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. 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: +and Libtool. As of the initial writing of this document (early 2004), +you needed *at least* Autoconf v2.58, Automake v1.8.5, and Libtool +v1.5. It is possible that since then, the lowest acceptable versions +of these tools have increased. + +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 @@ -47,11 +95,18 @@ AUTOMAKE NOTE: It seems that Automake 1.7 (or better) is ok for determine the lowest version number where "make dist" works). +To strengthen the above point: the core Open MPI developers typically +use very recent versions of the GNU tools. Little checking is done to +ensure that the code base is compatible with older versions of these +tools. If you have a problem, try upgrading your GNU tools to the +latest versions and try again. + 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. + GNU libtool. You must download and install the GNU version (via + Fink or any other mechanism). 1. Unless your OS distribution has easy-to-use binary installations, the sources can be can be downloaded from: diff --git a/INSTALL b/INSTALL index 28a597c2e1..4a1ff83ed0 100644 --- a/INSTALL +++ b/INSTALL @@ -13,18 +13,21 @@ Additional copyrights may follow $HEADER$ If you have checked out a DEVELOPER'S COPY of Open MPI (i.e., you -checked out from subversion), you must first run: +checked out from subversion), you should read the HACKING file before +attempting to build Open MPI. You must also first run: shell$ ./autogen.sh You will need very recent versions of GNU Autoconf, Automake, and Libtool. If autogen.sh fails, read the HACKING file. + Everyone must run "configure" and "make" to build Open MPI. Execute the following commands to install the Open MPI system from within the directory at the top of the tree: shell$ ./configure --prefix=/where/to/install +[...lots of output...] shell$ make all install If you need special access to install, then you can execute "make @@ -32,6 +35,18 @@ all" as a user with write permissions in the build tree, and a separate "make install" as a user with write permissions to the install tree. + +Note that VPATH builds are fully supported. For example: + +shell$ gtar zxf openmpi-1.2.3.tar.gz +shell$ cd openmpi-1.2.3 +shell$ mkdir build +shell$ cd build +shell$ ../configure ... +[...lots of output...] +shell$ make all install + + To compile an MPI program: C programs: mpicc your-code.c