forked from openpmix/prrte
-
Notifications
You must be signed in to change notification settings - Fork 0
/
HACKING
260 lines (200 loc) · 10.3 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
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
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-2020 Cisco Systems, Inc. All rights reserved.
Copyright (c) 2013-2019 Intel, Inc. All rights reserved.
$COPYRIGHT$
Additional copyrights may follow
$HEADER$
Overview
========
This file is here for those who are building/exploring the PMIx
Reference Server (hereafter referred to as the "Server") in its
source code form, most likely through a developer's tree (i.e., a Git clone).
Developer Builds: Compiler Pickyness by Default
===============================================
If you are building the PMIx Reference Server from a Git clone
(i.e., there is a ".git" directory in your build tree), the default
build includes extra compiler pickyness, which will result in more
compiler warnings than in non-developer builds. Getting these extra
compiler warnings is helpful to developers in making the code base
as clean as possible.
Developers can disable this picky-by-default behavior by using the
--disable-picky configure option. Also note that extra-picky compiles
do *not* happen automatically when you do a VPATH build (e.g., if
".git" is in your source tree, but not in your build tree).
Prior versions of the Server would automatically activate a lot of
(performance-reducing) debugging code by default if ".git" was found
in your build tree. This is no longer true. You can manually enable
these (performance-reducing) debugging features in the Server code
base with these configure options:
--enable-debug
--enable-mem-debug
--enable-mem-profile
NOTE: These options are really only relevant to those who are
developing the Server itself. They are not generally helpful for
debugging general applications.
Use of GNU Autoconf, Automake, and Libtool (and m4)
===================================================
You need to read/care about this section *ONLY* if you are building
from a developer's tree (i.e., a Git clone of the Server source
tree). If you have a Server distribution tarball, the contents of
this section are optional -- you can (and probably should) skip
reading this section.
If you are building the Server 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 Git master branch or a release
branch (and which release branch you are using). The specific
versions can be found here:
https://pmix.github.io/pmix/faq/building
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
To strengthen the above point: the core Server developers typically
use very, very recent versions of the GNU tools. There are known bugs
in older versions of the GNU tools that the Server 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 the Server 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 the Server'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
the Server, we greatly prefer the latter.
Note that no testing has been performed to see what the minimum
version of Flex is required by the Server. We suggest that you use
v2.5.35 at the earliest.
For now, the Server 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 Server 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:
https://github.com/westes/flex
Use of Pandoc
=============
Similar to prior sections, you need to read/care about this section
*ONLY* if you are building from a developer's tree (i.e., a Git clone
of the Open MPI source tree). If you have an Open MPI distribution
tarball, the contents of this section are optional -- you can (and
probably should) skip reading this section.
The Pandoc tool is used to generate Open MPI's man pages.
Specifically: Open MPI's man pages are written in Markdown; Pandoc is
the tool that converts that Markdown to nroff (i.e., the format of man
pages).
You must have Pandoc >=v1.12 when building Open MPI from a developer's
tree. If configure cannot find Pandoc >=v1.12, it will abort.
If you need to install Pandoc, check your operating system-provided
packages (to include MacOS Homebrew and MacPorts). The Pandoc project
itself also offers binaries for their releases:
https://pandoc.org/