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
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
|
<!DOCTYPE html>
<html class="writer-html5" lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>13.7. Source code — Open MPI 5.0.8 documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css" />
<!--[if lt IE 9]>
<script src="../_static/js/html5shiv.min.js"></script>
<![endif]-->
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/sphinx_highlight.js"></script>
<script src="../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="13.8. Internal frameworks" href="frameworks.html" />
<link rel="prev" title="13.6. Open MPI terminology" href="terminology.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home">
Open MPI
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../quickstart.html">1. Quick start</a></li>
<li class="toctree-l1"><a class="reference internal" href="../getting-help.html">2. Getting help</a></li>
<li class="toctree-l1"><a class="reference internal" href="../release-notes/index.html">3. Release notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../installing-open-mpi/index.html">4. Building and installing Open MPI</a></li>
<li class="toctree-l1"><a class="reference internal" href="../features/index.html">5. Open MPI-specific features</a></li>
<li class="toctree-l1"><a class="reference internal" href="../validate.html">6. Validating your installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../version-numbering.html">7. Version numbers and compatibility</a></li>
<li class="toctree-l1"><a class="reference internal" href="../mca.html">8. The Modular Component Architecture (MCA)</a></li>
<li class="toctree-l1"><a class="reference internal" href="../building-apps/index.html">9. Building MPI applications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../launching-apps/index.html">10. Launching MPI applications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tuning-apps/index.html">11. Run-time operation and tuning MPI applications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../app-debug/index.html">12. Debugging Open MPI Parallel Applications</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">13. Developer’s guide</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="prerequisites.html">13.1. Prerequisites</a></li>
<li class="toctree-l2"><a class="reference internal" href="git-github.html">13.2. GitHub, Git, and related topics</a></li>
<li class="toctree-l2"><a class="reference internal" href="compiler-pickyness.html">13.3. Compiler Pickyness by Default</a></li>
<li class="toctree-l2"><a class="reference internal" href="autogen.html">13.4. Running <code class="docutils literal notranslate"><span class="pre">autogen.pl</span></code></a></li>
<li class="toctree-l2"><a class="reference internal" href="building-open-mpi.html">13.5. Building Open MPI</a></li>
<li class="toctree-l2"><a class="reference internal" href="terminology.html">13.6. Open MPI terminology</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">13.7. Source code</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#code-style">13.7.1. Code style</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#all-languages">13.7.1.1. All languages</a></li>
<li class="toctree-l4"><a class="reference internal" href="#c-c">13.7.1.2. C / C++</a></li>
<li class="toctree-l4"><a class="reference internal" href="#fortran">13.7.1.3. Fortran</a></li>
<li class="toctree-l4"><a class="reference internal" href="#shell-scripting">13.7.1.4. Shell scripting</a></li>
<li class="toctree-l4"><a class="reference internal" href="#m4">13.7.1.5. m4</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#tree-layout">13.7.2. Tree layout</a></li>
<li class="toctree-l3"><a class="reference internal" href="#symbol-visibility">13.7.3. Symbol Visibility</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="frameworks.html">13.8. Internal frameworks</a></li>
<li class="toctree-l2"><a class="reference internal" href="gnu-autotools.html">13.9. Manually installing the GNU Autootools</a></li>
<li class="toctree-l2"><a class="reference internal" href="sphinx.html">13.10. Installing and running Sphinx (building the Open MPI docs)</a></li>
<li class="toctree-l2"><a class="reference internal" href="rst-for-markdown-expats.html">13.11. ReStructured Text for those who know Markdown</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../contributing.html">14. Contributing to Open MPI</a></li>
<li class="toctree-l1"><a class="reference internal" href="../license/index.html">15. License</a></li>
<li class="toctree-l1"><a class="reference internal" href="../history.html">16. History of Open MPI</a></li>
<li class="toctree-l1"><a class="reference internal" href="../man-openmpi/index.html">17. Open MPI manual pages</a></li>
<li class="toctree-l1"><a class="reference internal" href="../man-openshmem/index.html">18. OpenSHMEM manual pages</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">Open MPI</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item"><a href="index.html"><span class="section-number">13. </span>Developer’s guide</a></li>
<li class="breadcrumb-item active"><span class="section-number">13.7. </span>Source code</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/developers/source-code.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<style>
.wy-table-responsive table td,.wy-table-responsive table th{white-space:normal}
</style><div class="section" id="source-code">
<h1><span class="section-number">13.7. </span>Source code<a class="headerlink" href="#source-code" title="Permalink to this heading"></a></h1>
<div class="section" id="code-style">
<h2><span class="section-number">13.7.1. </span>Code style<a class="headerlink" href="#code-style" title="Permalink to this heading"></a></h2>
<p>We intentionally do not have too many code conventions in the Open MPI
code base.</p>
<div class="section" id="all-languages">
<h3><span class="section-number">13.7.1.1. </span>All languages<a class="headerlink" href="#all-languages" title="Permalink to this heading"></a></h3>
<ul class="simple">
<li><p>4 space tabs. No more, no less.</p></li>
<li><p><strong>NEVER</strong> use actual tab characters; always use spaces. Both emacs
and vim have secret mojo that can automatically use spaces when you
hit the <code class="docutils literal notranslate"><span class="pre"><TAB></span></code> key. This makes the code look the same in every
browser, regardless of individual tab display settings.</p></li>
</ul>
</div>
<div class="section" id="c-c">
<h3><span class="section-number">13.7.1.2. </span>C / C++<a class="headerlink" href="#c-c" title="Permalink to this heading"></a></h3>
<ul>
<li><p>When comparing constants for equality or inequality, always put the
constant on the left. This is defensive programming: if you have a
typo in the test and miss a <code class="docutils literal notranslate"><span class="pre">!</span></code> or <code class="docutils literal notranslate"><span class="pre">=</span></code>, you’ll get a compiler error.
For example:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cm">/* Do this */</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nb">NULL</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="n">foo</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="p">}</span>
<span class="cm">/* Because if you have a typo (i.e., = instead of ==), this will</span>
<span class="cm"> be a compile error rather than a subtle bug */</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="nb">NULL</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">foo</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">...</span><span class="w"> </span><span class="p">}</span>
</pre></div>
</div>
</li>
<li><p>More defensive programming: <em>always</em> include blocks in curly braces
<code class="docutils literal notranslate"><span class="pre">{</span> <span class="pre">}</span></code>, even if they are only one line long. For example:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cm">/* Do this */</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">whatever</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="n">OMPI_SUCCESS</span><span class="p">;</span>
<span class="p">}</span>
<span class="cm">/* Not this */</span>
<span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">whatever</span><span class="p">)</span>
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="n">OMPI_SUCCESS</span><span class="p">;</span>
</pre></div>
</div>
</li>
<li><p>Starting with Open MPI 1.7, Open MPI requires a C99-compliant
compiler.</p>
<ul class="simple">
<li><p>C++-style comments are now allowed (and preferred).</p></li>
<li><p>C99-style mixing declarations are allow allowable (and preferred).</p></li>
</ul>
</li>
<li><p><strong>ALWAYS</strong> include <code class="docutils literal notranslate"><span class="pre"><level>_config.h</span></code> as your first #include file,
where <code class="docutils literal notranslate"><span class="pre"><level></span></code> is one of <code class="docutils literal notranslate"><span class="pre">ompi</span></code>, <code class="docutils literal notranslate"><span class="pre">oshmem</span></code>, or <code class="docutils literal notranslate"><span class="pre">opal</span></code> — the
level that you’re writing in. There are very, very few cases where
this is not true (E.g., some bizarre Windows scenarios). But in
99.9999% of cases, this file should be included <strong>first</strong> so that it
can affect system-level #include files if necessary.</p></li>
<li><p>Filenames and symbols must follow the <strong>prefix rule</strong> (see [e-mail
thread](<a class="reference external" href="http://www.open-mpi.org/community/lists/devel/2009/07/6389.php">http://www.open-mpi.org/community/lists/devel/2009/07/6389.php</a>)):</p>
<ul class="simple">
<li><p>Filenames must be prefixed with <code class="docutils literal notranslate"><span class="pre"><framework>_<component></span></code>.</p></li>
<li><p>Public symbols must be prefixed in components with
<code class="docutils literal notranslate"><span class="pre"><project>_<framework>_<component></span></code>, where <code class="docutils literal notranslate"><span class="pre"><project></span></code> is one
of <code class="docutils literal notranslate"><span class="pre">mca</span></code>, <code class="docutils literal notranslate"><span class="pre">ompi</span></code>, <code class="docutils literal notranslate"><span class="pre">oshmem</span></code>, or <code class="docutils literal notranslate"><span class="pre">opal</span></code>. Note that <cite>mca</cite>
used to be the most common, but it has fallen out of favor
compared to the other <code class="docutils literal notranslate"><span class="pre"><project></span></code> prefixes. When in doubt about
whether a symbol is public, be safe and add the prefix.</p></li>
<li><p>Non-public symbols must be declared <code class="docutils literal notranslate"><span class="pre">static</span></code> or otherwise made to
not appear in the global scope.</p></li>
</ul>
</li>
<li><p><strong>ALWAYS</strong> #define macros, even for logical values.</p>
<ul>
<li><p>The GNU Way is to <code class="docutils literal notranslate"><span class="pre">#define</span></code> a macro when it is “true” and to
<code class="docutils literal notranslate"><span class="pre">#undef</span></code> it when it is “false”.</p></li>
<li><p>In Open MPI, we <strong>always</strong> <code class="docutils literal notranslate"><span class="pre">#define</span></code> a logical macro to be
either 0 or 1 — we never <code class="docutils literal notranslate"><span class="pre">#undef</span></code> it.</p></li>
<li><p>The reason for this is defensive programming: if you are only
checking if a preprocessor macro is defined (via <code class="docutils literal notranslate"><span class="pre">#ifdef</span> <span class="pre">FOO</span></code> or
<code class="docutils literal notranslate"><span class="pre">#if</span> <span class="pre">defined(FOO)</span></code>), you will get no warning when compiling if
you accidentally misspell the macro name. However, if you use the
logic test <code class="docutils literal notranslate"><span class="pre">#if</span> <span class="pre">FOO</span></code> with an undefined macro (e.g., because you
misspelled it), you’ll get a compiler warning or error.</p>
<div class="tip admonition">
<p class="admonition-title">Rationale</p>
<p>Misspelled macro names can be tremendously difficult to find
when they are buried in thousands of lines of code; we will
take all the help from the preprocessor/compiler that we can
get!</p>
</div>
</li>
</ul>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cm">/* GNU Way - you will get no warning from the compiler if you</span>
<span class="cm"> misspell "FOO"; the test will simply be false */</span>
<span class="cp">#ifdef FOO</span>
<span class="p">...</span>
<span class="cp">#else</span>
<span class="p">...</span>
<span class="cp">#endif</span>
<span class="cm">/* Open MPI Way - you will get a warning from the compiler if you</span>
<span class="cm"> misspell "FOO"; the result of the test is a different value</span>
<span class="cm"> than whether you spelled the macro name right or not */</span>
<span class="cp">#if FOO</span>
<span class="p">...</span>
<span class="cp">#else</span>
<span class="p">...</span>
<span class="cp">#endif</span>
</pre></div>
</div>
</li>
</ul>
</div>
<div class="section" id="fortran">
<h3><span class="section-number">13.7.1.3. </span>Fortran<a class="headerlink" href="#fortran" title="Permalink to this heading"></a></h3>
<p>We do not have specific coding style guidelines for Fortran. Please
read some of the existing Fortran code in the source code tree and try
to use a similar style.</p>
</div>
<div class="section" id="shell-scripting">
<h3><span class="section-number">13.7.1.4. </span>Shell scripting<a class="headerlink" href="#shell-scripting" title="Permalink to this heading"></a></h3>
<p>Please read some of the existing shell code in the source code tree
and try to use a similar style.</p>
<ul>
<li><p>Always enclose evaluated shell variables in quotes to ensure that
multi-token values are handled properly.</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># This is bad</span>
<span class="k">if</span><span class="w"> </span><span class="nb">test</span><span class="w"> </span><span class="nv">$foo</span><span class="w"> </span><span class="o">=</span><span class="w"> </span>bar<span class="p">;</span><span class="w"> </span><span class="k">then</span>
<span class="c1"># This is good</span>
<span class="k">if</span><span class="w"> </span><span class="nb">test</span><span class="w"> </span><span class="s2">"</span><span class="nv">$foo</span><span class="s2">"</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"bar"</span><span class="p">;</span><span class="w"> </span><span class="k">then</span>
</pre></div>
</div>
<ul>
<li><p>The one exception to this is that when doing an assignment to a
shell variable from another shell variable, it is not necessary to
use quotes on the right hand side:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># This is harmless, but unnecessary</span>
<span class="nv">foo</span><span class="o">=</span><span class="s2">"</span><span class="nv">$bar</span><span class="s2">"</span>
<span class="c1"># This is actually sufficient, even for multi-token values of $bar</span>
<span class="nv">foo</span><span class="o">=</span><span class="nv">$bar</span>
</pre></div>
</div>
</li>
</ul>
</li>
<li><p>Do not use the <code class="docutils literal notranslate"><span class="pre">==</span></code> operator for <code class="docutils literal notranslate"><span class="pre">test</span></code> — this is a GNU
extension and can cause portability problems on BSD systems.
Instead, use the single <code class="docutils literal notranslate"><span class="pre">=</span></code> operator.</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># This is bad</span>
<span class="k">if</span><span class="w"> </span><span class="nb">test</span><span class="w"> </span><span class="s2">"</span><span class="nv">$foo</span><span class="s2">"</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="s2">"bar"</span><span class="p">;</span><span class="w"> </span><span class="k">then</span>
<span class="c1"># This is good</span>
<span class="k">if</span><span class="w"> </span><span class="nb">test</span><span class="w"> </span><span class="s2">"</span><span class="nv">$foo</span><span class="s2">"</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s2">"bar"</span><span class="p">;</span><span class="w"> </span><span class="k">then</span>
</pre></div>
</div>
</li>
</ul>
</div>
<div class="section" id="m4">
<h3><span class="section-number">13.7.1.5. </span>m4<a class="headerlink" href="#m4" title="Permalink to this heading"></a></h3>
<p>We do not have specific coding style guidelines for m4 (the language
used to create the <code class="docutils literal notranslate"><span class="pre">configure</span></code> script). Please read some of the
existing m4 code in the source code tree and try to use a similar
style.</p>
</div>
</div>
<div class="section" id="tree-layout">
<h2><span class="section-number">13.7.2. </span>Tree layout<a class="headerlink" href="#tree-layout" title="Permalink to this heading"></a></h2>
<p>There are a few notable top-level directories in the source
tree:</p>
<ul>
<li><p>The main sub-projects:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">oshmem</span></code>: Top-level OpenSHMEM code base</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">ompi</span></code>: The Open MPI code base</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">opal</span></code>: The OPAL code base</p></li>
</ul>
</div></blockquote>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">config</span></code>: M4 scripts supporting the top-level <code class="docutils literal notranslate"><span class="pre">configure</span></code> script
<code class="docutils literal notranslate"><span class="pre">mpi.h</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">etc</span></code>: Some miscellaneous text files</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">docs</span></code>: Source code for Open MPI documentation</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">examples</span></code>: Trivial MPI / OpenSHMEM example programs</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">3rd-party</span></code>: Included copies of required core libraries (either
via Git submodules in Git clones or via binary tarballs).</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>While it may be considered unusual, we include binary
tarballs (instead of Git submodules) for 3rd party projects that
are:</p>
<ol class="arabic simple">
<li><p>Needed by Open MPI for correct operation, and</p></li>
<li><p>Not universally included in OS distributions, and</p></li>
<li><p>Rarely updated.</p></li>
</ol>
</div>
</li>
</ul>
<p>Each of the three main source directories (<code class="docutils literal notranslate"><span class="pre">oshmem</span></code>, <code class="docutils literal notranslate"><span class="pre">ompi</span></code>, and
<code class="docutils literal notranslate"><span class="pre">opal</span></code>) generate at least a top-level library named <code class="docutils literal notranslate"><span class="pre">liboshmem</span></code>,
<code class="docutils literal notranslate"><span class="pre">libmpi</span></code>, and <code class="docutils literal notranslate"><span class="pre">libopen-pal</span></code>, respectively. They can be built as
either static or shared libraries. Executables are also produced in
subdirectories of some of the trees.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">libopen-pal</span></code> top-level library is built internally in two parts:</p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">libopen-pal_core</span></code> Internal “core” portion of OPAL containing the essential source and MCA needed for tools like mpicc/mpirun to link against. The “core” library is not installed.</p>
<blockquote>
<div><ul class="simple">
<li><p>Includes the following MCA frameworks: <code class="docutils literal notranslate"><span class="pre">backtrace</span></code>, <code class="docutils literal notranslate"><span class="pre">dl</span></code>, <code class="docutils literal notranslate"><span class="pre">installdirs</span></code>, <code class="docutils literal notranslate"><span class="pre">threads</span></code>, <code class="docutils literal notranslate"><span class="pre">timer</span></code></p></li>
<li><p>Includes all of the source under <code class="docutils literal notranslate"><span class="pre">opal/class</span></code> and most of <code class="docutils literal notranslate"><span class="pre">opal/util</span></code></p></li>
<li><p>Includes the files suffixed with <code class="docutils literal notranslate"><span class="pre">_core</span></code> in <code class="docutils literal notranslate"><span class="pre">opal/runtime</span></code></p></li>
</ul>
</div></blockquote>
</li>
<li><p><code class="docutils literal notranslate"><span class="pre">libopen-pal</span></code> Includes “core” plus all of the other OPAL project sources. This is installed.</p></li>
</ul>
<p>Each of the sub-project source directories have similar (but not
identical) directory structures under them:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">class</span></code>: C++-like “classes” (using the OPAL class system)
specific to this project</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">include</span></code>: Top-level include files specific to this project</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">mca</span></code>: MCA frameworks and components specific to this project</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">runtime</span></code>: Startup and shutdown of this project at runtime</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">tools</span></code>: Executables specific to this project</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">util</span></code>: Random utility code</p></li>
</ul>
<p>There are other top-level directories in each of the sub-projects,
each having to do with specific logic and code for that project. For
example, the MPI API implementations can be found under
<code class="docutils literal notranslate"><span class="pre">ompi/mpi/LANGUAGE</span></code>, where <code class="docutils literal notranslate"><span class="pre">LANGUAGE</span></code> is <code class="docutils literal notranslate"><span class="pre">c</span></code>, <code class="docutils literal notranslate"><span class="pre">fortran</span></code>, or
<code class="docutils literal notranslate"><span class="pre">java</span></code>.</p>
<p>The layout of the <code class="docutils literal notranslate"><span class="pre">mca</span></code> trees are strictly defined. They are of the
form:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>PROJECT/mca/FRAMEWORK/COMPONENT
</pre></div>
</div>
<p>To be explicit: it is forbidden to have a directory under the <code class="docutils literal notranslate"><span class="pre">mca</span></code>
trees that does not meet this template (with the exception of <code class="docutils literal notranslate"><span class="pre">base</span></code>
directories, explained below). Hence, only framework and component
code can be in the <code class="docutils literal notranslate"><span class="pre">mca</span></code> trees.</p>
<p>That is, framework and component names must be valid directory names
(and C variables; more on that later). For example, the TCP BTL
component is located in <code class="docutils literal notranslate"><span class="pre">opal/mca/btl/tcp/</span></code>.</p>
<p>The name <code class="docutils literal notranslate"><span class="pre">base</span></code> is reserved; there cannot be a framework or component
named <code class="docutils literal notranslate"><span class="pre">base</span></code>. Directories named <code class="docutils literal notranslate"><span class="pre">base</span></code> are reserved for the
implementation of the MCA and frameworks. Here are a few examples (as
of the v5.0.x source tree):</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="c1"># Main implementation of the MCA</span>
opal/mca/base
<span class="c1"># Implementation of the btl framework</span>
opal/mca/btl/base
<span class="c1"># Implementation of the sysv framework</span>
oshmem/mcs/sshmem/sysv
<span class="c1"># Implementation of the pml framework</span>
ompi/mca/pml/base
</pre></div>
</div>
<p>Under these mandated directories, frameworks and/or components may have
arbitrary directory structures, however.</p>
</div>
<div class="section" id="symbol-visibility">
<h2><span class="section-number">13.7.3. </span>Symbol Visibility<a class="headerlink" href="#symbol-visibility" title="Permalink to this heading"></a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">*_DECLSPEC</span></code> macros provide a method to annotate symbols to indicate
their intended visibility when compiling dynamically shared object files
(e.g., <code class="docutils literal notranslate"><span class="pre">libmpi.so</span></code>). The macros are defined on a per project basis:</p>
<ul class="simple">
<li><p>Open MPI: <code class="docutils literal notranslate"><span class="pre">OMPI_DECLSPEC</span></code></p></li>
<li><p>Open PAL: <code class="docutils literal notranslate"><span class="pre">OPAL_DECLSPEC</span></code></p></li>
<li><p>OpenSHMEM: <code class="docutils literal notranslate"><span class="pre">OSHMEM_DECLSPEC</span></code></p></li>
</ul>
<p>The macros expand to the appropriate compiler and platform flags for marking
whether a symbol should be explicitly made public in the target project’s
library namespace.
The <code class="docutils literal notranslate"><span class="pre">*_DECLSPEC</span></code> attributes are used to declare that a symbol is to be
visible outside of that library/DSO’s scope. For example, <code class="docutils literal notranslate"><span class="pre">OMPI_DECLSPEC</span></code>
is used to control what symbols are visible in the <code class="docutils literal notranslate"><span class="pre">libmpi.so</span></code> scope.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This is entirely related to dynamic library compilation and does not
apply to static compilation.</p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The macros were originally introduced when Open MPI supported
Windows (circa Open MPI v1.0.0) and are motivated by the Windows
<a class="reference external" href="https://docs.microsoft.com/en-us/cpp/cpp/declspec?view=msvc-170">__declspec</a>.
While support for Windows has been dropped from Open MPI, the symbol
visibility macros remain.</p>
</div>
</div>
</div>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="terminology.html" class="btn btn-neutral float-left" title="13.6. Open MPI terminology" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="frameworks.html" class="btn btn-neutral float-right" title="13.8. Internal frameworks" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2003-2025, The Open MPI Community.
<span class="lastupdated">Last updated on 2025-05-30 16:41:43 UTC.
</span></p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
|
