-
Notifications
You must be signed in to change notification settings - Fork 4
/
Compiler-properties.html
438 lines (401 loc) · 18.3 KB
/
Compiler-properties.html
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
<!DOCTYPE html>
<html lang="en">
<head>
<base href=".">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Compiler properties</title>
<link rel="stylesheet" href="assets/css/dark-frontend.css" type="text/css" title="dark">
<link rel="alternate stylesheet" href="assets/css/light-frontend.css" type="text/css" title="light">
<link rel="stylesheet" href="assets/css/bootstrap-toc.min.css" type="text/css">
<link rel="stylesheet" href="assets/css/jquery.mCustomScrollbar.min.css">
<link rel="stylesheet" href="assets/js/search/enable_search.css" type="text/css">
<link rel="stylesheet" href="assets/css/prism-tomorrow.css" type="text/css" title="dark">
<link rel="alternate stylesheet" href="assets/css/prism.css" type="text/css" title="light">
<script src="assets/js/mustache.min.js"></script>
<script src="assets/js/jquery.js"></script>
<script src="assets/js/bootstrap.js"></script>
<script src="assets/js/scrollspy.js"></script>
<script src="assets/js/typeahead.jquery.min.js"></script>
<script src="assets/js/search.js"></script>
<script src="assets/js/compare-versions.js"></script>
<script src="assets/js/jquery.mCustomScrollbar.concat.min.js"></script>
<script src="assets/js/bootstrap-toc.min.js"></script>
<script src="assets/js/jquery.touchSwipe.min.js"></script>
<script src="assets/js/anchor.min.js"></script>
<script src="assets/js/tag_filtering.js"></script>
<script src="assets/js/language_switching.js"></script>
<script src="assets/js/styleswitcher.js"></script>
<script src="assets/js/lines_around_headings.js"></script>
<script src="assets/js/prism-core.js"></script>
<script src="assets/js/prism-autoloader.js"></script>
<script src="assets/js/prism_autoloader_path_override.js"></script>
<script src="assets/js/prism-keep-markup.js"></script>
<script src="assets/js/trie.js"></script>
<link rel="icon" type="image/png" href="assets/images/favicon.png">
<link rel="shortcut icon" href="assets/images/favicon.png">
</head>
<body class="no-script
">
<script>
$('body').removeClass('no-script');
</script>
<nav class="navbar navbar-fixed-top navbar-default" id="topnav">
<div class="container-fluid">
<div class="navbar-right">
<a id="toc-toggle">
<span class="glyphicon glyphicon-menu-right"></span>
<span class="glyphicon glyphicon-menu-left"></span>
</a>
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar-wrapper" aria-expanded="false">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<span title="light mode switch" class="glyphicon glyphicon-sunglasses pull-right" id="lightmode-icon"></span>
<form class="navbar-form pull-right" id="navbar-search-form">
<div class="form-group has-feedback">
<input type="text" class="form-control input-sm" name="search" id="sidenav-lookup-field" placeholder="search" disabled>
<span class="glyphicon glyphicon-search form-control-feedback" id="search-mgn-glass"></span>
</div>
</form>
</div>
<div class="navbar-header">
<a id="sidenav-toggle">
<span class="glyphicon glyphicon-menu-right"></span>
<span class="glyphicon glyphicon-menu-left"></span>
</a>
<a id="home-link" href="index.html" class="hotdoc-navbar-brand">
<img src="assets/images/meson_logo.png" alt="Home">
</a>
</div>
<div class="navbar-collapse collapse" id="navbar-wrapper">
<ul class="nav navbar-nav" id="menu">
<li class="dropdown">
<a class="dropdown-toggle" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
Modules <span class="caret"></span>
</a>
<ul class="dropdown-menu" id="modules-menu">
<li>
<a href="CMake-module.html">CMake</a>
</li>
<li>
<a href="Cuda-module.html">CUDA</a>
</li>
<li>
<a href="Dlang-module.html">Dlang</a>
</li>
<li>
<a href="External-Project-module.html">External Project</a>
</li>
<li>
<a href="Fs-module.html">Filesystem</a>
</li>
<li>
<a href="Gnome-module.html">GNOME</a>
</li>
<li>
<a href="Hotdoc-module.html">Hotdoc</a>
</li>
<li>
<a href="i18n-module.html">i18n</a>
</li>
<li>
<a href="Icestorm-module.html">Icestorm</a>
</li>
<li>
<a href="Java-module.html">Java</a>
</li>
<li>
<a href="Keyval-module.html">Keyval</a>
</li>
<li>
<a href="Pkgconfig-module.html">Pkgconfig</a>
</li>
<li>
<a href="Python-3-module.html">Python 3</a>
</li>
<li>
<a href="Python-module.html">Python</a>
</li>
<li>
<a href="Qt4-module.html">Qt4</a>
</li>
<li>
<a href="Qt5-module.html">Qt5</a>
</li>
<li>
<a href="Qt6-module.html">Qt6</a>
</li>
<li>
<a href="Rust-module.html">Rust</a>
</li>
<li>
<a href="Simd-module.html">Simd</a>
</li>
<li>
<a href="SourceSet-module.html">SourceSet</a>
</li>
<li>
<a href="Wayland-module.html">Wayland</a>
</li>
<li>
<a href="Windows-module.html">Windows</a>
</li>
</ul>
</li>
<li class="dropdown">
<a class="dropdown-toggle" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
Quick References <span class="caret"></span>
</a>
<ul class="dropdown-menu" id="quick-refs-menu">
<li>
<a href="Reference-manual.html">Functions</a>
</li>
<li>
<a href="Build-options.html">Options</a>
</li>
<li>
<a href="Configuration.html">Configuration</a>
</li>
<li>
<a href="Dependencies.html">Dependencies</a>
</li>
<li>
<a href="Unit-tests.html">Tests</a>
</li>
<li>
<a href="Syntax.html">Syntax</a>
</li>
</ul>
</li>
</ul>
<div class="hidden-xs hidden-sm navbar-text navbar-center">
<p><b>The Meson Build System</b></p>
</div>
</div>
</div>
</nav>
<main>
<div data-extension="core" data-hotdoc-in-toplevel="True" data-hotdoc-project="Meson-documentation" data-hotdoc-ref="Compiler-properties.html" class="page_container" id="page-wrapper">
<script src="assets/js/utils.js"></script>
<div class="panel panel-collapse oc-collapsed" id="sidenav" data-hotdoc-role="navigation">
<script src="assets/js/full-width.js"></script>
<div id="sitenav-wrapper">
<iframe src="hotdoc-sitemap.html" id="sitenav-frame"></iframe>
</div>
</div>
<div id="body">
<div id="main">
<div id="page-description" data-hotdoc-role="main">
<h1 id="compiler-properties">Compiler properties</h1>
<p>Not all compilers and platforms are alike. Therefore Meson provides
the tools to detect properties of the system during configure time. To
get most of this information, you first need to extract the <em><a href="Reference-manual_returned_compiler.html">compiler
object</a></em> from the main
<em>meson</em> variable.</p>
<pre><code class="language-meson">compiler = <a href="Reference-manual_builtin_meson.html#mesonget_compiler"><ins>meson.get_compiler</ins></a>('c')
</code></pre>
<p>Here we extract the C compiler. We could also have given the argument
<code>cpp</code> to get the C++ compiler, <code>objc</code> to get the objective C compiler
and so on. The call is valid for all languages specified in the
<em>project</em> declaration. Trying to obtain some other compiler will lead
to an unrecoverable error.</p>
<h2 id="system-information">System information</h2>
<p>This is a bit complex and more thoroughly explained on the page on
<a href="Cross-compilation.html">cross compilation</a>. But if you just want to
know the operating system your code will run on, issue this command:</p>
<pre><code class="language-meson">host_machine.system()
</code></pre>
<h2 id="compiler-id">Compiler id</h2>
<p>The compiler object method <a href="Reference-manual_returned_compiler.html#compilerget_id"><ins><code>compiler.get_id()</code></ins></a> returns a
lower case string describing the "family" of the compiler. Since 0.53.0
<a href="Reference-manual_returned_compiler.html#compilerget_linker_id"><ins><code>compiler.get_linker_id()</code></ins></a> returns a lower case string with the linker name. Since
compilers can often choose from multiple linkers depending on operating
system, <code>get_linker_id</code> can be useful for handling or mitigating effects
of particular linkers.</p>
<p>The compiler object also has a method <a href="Reference-manual_returned_compiler.html#compilerget_argument_syntax"><ins><code>compiler.get_argument_syntax()</code></ins></a> which
returns a lower case string of <code>gcc</code>, <code>msvc</code>, or another undefined string
value; identifying whether the compiler arguments use the same syntax as
either <code>gcc</code> or <code>msvc</code>, or that its arguments are not like either. This should
only be used to select the syntax of the arguments, such as those to test
with <a href="Reference-manual_returned_compiler.html#compilerhas_argument"><ins><code>compiler.has_argument()</code></ins></a>.</p>
<p>See <a href="Reference-tables.html#compiler-ids">reference tables</a> for a list of
supported compiler ids and their argument type.</p>
<h2 id="does-code-compile">Does code compile?</h2>
<p>Sometimes the only way to test the system is to try to compile some
sample code and see if it works. For example, this can test that a
"C++17" compiler actually supports a particular C++17 feature,
without resorting to maintaining a feature list vs. compiler vendor,
compiler version and operating system.
Testing that a code snippet runs is a two-phase operation. First
we define some code using the multiline string operator:</p>
<pre><code class="language-meson">code = '''#include<stdio.h>
void func() { printf("Compile me.\n"); }
'''
</code></pre>
<p>Then we can run the test.</p>
<pre><code class="language-meson">result = <a href="Reference-manual_returned_compiler.html#compilercompiles"><ins>compiler.compiles</ins></a>(code, name : 'basic check')
</code></pre>
<p>The variable <em>result</em> will now contain either <code>true</code> or <code>false</code>
depending on whether the compilation succeeded or not. The keyword
argument <code>name</code> is optional. If it is specified, Meson will write the
result of the check to its log.</p>
<h2 id="does-code-compile-and-link">Does code compile and link?</h2>
<p>Sometimes it is necessary to check whether a certain code fragment not
only compiles, but also links successfully, e.g. to check if a symbol
is actually present in a library. This can be done using the
<a href="Reference-manual_returned_compiler.html#compilerlinks"><ins><code>compiler.links()</code></ins></a> method like this:</p>
<pre><code class="language-meson">code = '''#include<stdio.h>
void func() { printf("Compile me.\n"); }
'''
</code></pre>
<p>Then we can run the test.</p>
<pre><code class="language-meson">result = <a href="Reference-manual_returned_compiler.html#compilerlinks"><ins>compiler.links</ins></a>(code, args : '-lfoo', name : 'link check')
</code></pre>
<p>The variable <em>result</em> will now contain either <code>true</code> or <code>false</code>
depending on whether the compilation and linking succeeded or not. The
keyword argument <code>name</code> is optional. If it is specified, Meson will
write the result of the check to its log.</p>
<h2 id="compile-and-run-test-application">Compile and run test application</h2>
<p>Here is how you would compile and run a small test application.
Testing if a code snippets <strong>runs</strong> versus merely that it links
is particularly important for some dependencies such as MPI.</p>
<pre><code class="language-meson">code = '''#include<stdio.h>
int main(int argc, char **argv) {
printf("%s\n", "stdout");
fprintf(stderr, "%s\n", "stderr");
return 0;
}
'''
result = <a href="Reference-manual_returned_compiler.html#compilerrun"><ins>compiler.run</ins></a>(code, name : 'basic check')
</code></pre>
<p>The <code>result</code> variable encapsulates the state of the test, which can be
extracted with the following methods. The <code>name</code> keyword argument
works the same as with <code>compiles</code>.</p>
<table>
<thead>
<tr>
<th> Method</th>
<th> Return value</th>
</tr>
</thead>
<tbody>
<tr>
<td> compiled</td>
<td> <code>True</code> if compilation succeeded. If <code>false</code> then all other methods return undefined values.</td>
</tr>
<tr>
<td> returncode</td>
<td> The return code of the application as an integer</td>
</tr>
<tr>
<td> stdout</td>
<td> Program's standard out as text.</td>
</tr>
<tr>
<td> stderr</td>
<td> Program's standard error as text.</td>
</tr>
</tbody>
</table>
<p>Here is an example usage:</p>
<pre><code class="language-meson">if result.stdout().strip() == 'some_value'
# do something
endif
</code></pre>
<h2 id="does-a-header-exist">Does a header exist?</h2>
<p>Header files provided by different platforms vary quite a lot. Meson
has functionality to detect whether a given header file is available
on the system. The test is done by trying to compile a simple test
program that includes the specified header. The following snippet
describes how this feature can be used.</p>
<pre><code class="language-meson">if <a href="Reference-manual_returned_compiler.html#compilerhas_header"><ins>compiler.has_header</ins></a>('sys/fstat.h')
# header exists, do something
endif
</code></pre>
<h2 id="expression-size">Expression size</h2>
<p>Often you need to determine the size of a particular element (such as
<code>int</code>, <code>wchar_t</code> or <code>char*</code>). Using the <code>compiler</code> variable mentioned
above, the check can be done like this.</p>
<pre><code class="language-meson">wcharsize = <a href="Reference-manual_returned_compiler.html#compilersizeof"><ins>compiler.sizeof</ins></a>('wchar_t', prefix : '#include<wchar.h>')
</code></pre>
<p>This will put the size of <code>wchar_t</code> as reported by sizeof into
variable <code>wcharsize</code>. The keyword argument <code>prefix</code> is optional. If
specified its contents is put at the top of the source file. This
argument is typically used for setting <code>#include</code> directives in
configuration files.</p>
<p>In older versions (<= 0.30) Meson would error out if the size could
not be determined. Since version 0.31 it returns -1 if the size could
not be determined.</p>
<h2 id="does-a-function-exist">Does a function exist?</h2>
<p>Just having a header doesn't say anything about its contents.
Sometimes you need to explicitly check if some function exists. This
is how we would check whether the function <code>open_memstream</code> exists in
header <code>stdio.h</code></p>
<pre><code class="language-meson">if <a href="Reference-manual_returned_compiler.html#compilerhas_function"><ins>compiler.has_function</ins></a>('open_memstream', prefix : '#include <stdio.h>')
# function exists, do whatever is required.
endif
</code></pre>
<p>Note that, on macOS programs can be compiled targeting older macOS
versions than the one that the program is compiled on. It can't be
assumed that the OS version that is compiled on matches the OS version
that the binary will run on.</p>
<p>Therefore when detecting function availability with <a href="Reference-manual_returned_compiler.html#compilerhas_function"><ins><code>compiler.has_function()</code></ins></a>, it
is important to specify the correct header in the prefix argument.</p>
<p>In the example above, the function <code>open_memstream</code> is detected, which
was introduced in macOS 10.13. When the user builds on macOS 10.13,
but targeting macOS 10.11 (<code>-mmacosx-version-min=10.11</code>), this will
correctly report the function as missing. Without the header however,
it would lack the necessary availability information and incorrectly
report the function as available.</p>
<h2 id="does-a-structure-contain-a-member">Does a structure contain a member?</h2>
<p>Some platforms have different standard structures. Here's how one
would check if a struct called <code>mystruct</code> from header <code>myheader.h</code>
contains a member called <code>some_member</code>.</p>
<pre><code class="language-meson">if <a href="Reference-manual_returned_compiler.html#compilerhas_member"><ins>compiler.has_member</ins></a>('struct mystruct', 'some_member', prefix : '#include<myheader.h>')
# member exists, do whatever is required
endif
</code></pre>
<h2 id="type-alignment">Type alignment</h2>
<p>Most platforms can't access some data types at any address. For
example it is common that a <code>char</code> can be at any address but a 32 bit
integer only at locations which are divisible by four. Determining the
alignment of data types is simple.</p>
<pre><code class="language-meson">int_alignment = <a href="Reference-manual_returned_compiler.html#compileralignment"><ins>compiler.alignment</ins></a>('int') # Will most likely contain the value 4.
</code></pre>
<h2 id="has-argument">Has argument</h2>
<p>This method tests if the compiler supports a given command line
argument. This is implemented by compiling a small file with the given
argument.</p>
<pre><code class="language-meson">has_special_flags = <a href="Reference-manual_returned_compiler.html#compilerhas_argument"><ins>compiler.has_argument</ins></a>('-Wspecialthing')
</code></pre>
<p><em>Note</em>: some compilers silently swallow command line arguments they do
not understand. Thus this test cannot be made 100% reliable.</p>
</div>
</div>
<div id="search_results">
<p>The results of the search are</p>
</div>
<div id="footer">
<hr>
<div class="license-description">
Website licensing information are available on the <a href="legal.html">Legal</a> page.
</div>
</div>
</div>
<div id="toc-column">
<div class="edit-button">
<a href="https://github.com/mesonbuild/meson/edit/master/docs/markdown/Compiler-properties.md" data-hotdoc-role="edit-button">Edit on GitHub</a>
</div>
<div id="toc-wrapper">
<nav id="toc"></nav>
</div>
</div>
</div>
</main>
<script src="assets/js/navbar_offset_scroller.js"></script>
</body>
</html>