forked from open-mpi/ompi
-
Notifications
You must be signed in to change notification settings - Fork 1
/
HACKING
244 lines (187 loc) · 9.19 KB
/
HACKING
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
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).
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 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.sh
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 subdirectory
is not present. For example:
shell$ svn co http://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
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
==========================================
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. As of October 2005, the following versions are known to
work:
Autoconf: v2.59
Automake: v1.9.6
Libtool: v1.5.20
More generally, we have found that using the most recent versions of
these tools usually results in the greatest probability of a
successful configure / build. 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$ libtoolize --version
To strengthen the above point: the core Open MPI developers typically
use very, 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 (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:
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.59
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.9.6
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.20
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 (and that component has a
"configure.stub" file), cd into that component's directory and
run autogen.sh in there directly:
shell$ cd src/mca/pml/teg
shell$ ../../../../autogen.sh
This does *not* work if the component has a "configure.m4"
file. If a component's configure.m4 file changes, you will
need to run "autogen.sh" from the top-level directory.
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/