Debian Codegraph @

subprojects/meson-docs/docs/markdown/Compiler-properties.md

raw
1 # Compiler properties
2
3 Not all compilers and platforms are alike. Therefore Meson provides
4 the tools to detect properties of the system during configure time. To
5 get most of this information, you first need to extract the *[compiler
6 object](Reference-manual_returned_compiler.md)* from the main
7 *meson* variable.
8
9 ```meson
10 compiler = [[#meson.get_compiler]]('c')
11 ```
12
13 Here we extract the C compiler. We could also have given the argument
14 `cpp` to get the C++ compiler, `objc` to get the objective C compiler
15 and so on. The call is valid for all languages specified in the
16 *project* declaration. Trying to obtain some other compiler will lead
17 to an unrecoverable error.
18
19 ## System information
20
21 This is a bit complex and more thoroughly explained on the page on
22 [cross compilation](Cross-compilation.md). But if you just want to
23 know the operating system your code will run on, issue this command:
24
25 ```meson
26 host_machine.system()
27 ```
28
29 ## Compiler id
30
31 The compiler object method [[compiler.get_id]] returns a
32 lower case string describing the "family" of the compiler. Since 0.53.0
33 [[compiler.get_linker_id]] returns a lower case string with the linker name. Since
34 compilers can often choose from multiple linkers depending on operating
35 system, `get_linker_id` can be useful for handling or mitigating effects
36 of particular linkers.
37
38 The compiler object also has a method [[compiler.get_argument_syntax]] which
39 returns a lower case string of `gcc`, `msvc`, or another undefined string
40 value; identifying whether the compiler arguments use the same syntax as
41 either `gcc` or `msvc`, or that its arguments are not like either. This should
42 only be used to select the syntax of the arguments, such as those to test
43 with [[compiler.has_argument]].
44
45 See [reference tables](Reference-tables.md#compiler-ids) for a list of
46 supported compiler ids and their argument type.
47
48 ## Does code compile?
49
50 Sometimes the only way to test the system is to try to compile some
51 sample code and see if it works. For example, this can test that a
52 "C++17" compiler actually supports a particular C++17 feature,
53 without resorting to maintaining a feature list vs. compiler vendor,
54 compiler version and operating system.
55 Testing that a code snippet runs is a two-phase operation. First
56 we define some code using the multiline string operator:
57
58 ```meson
59 code = '''#include<stdio.h>
60 void func() { printf("Compile me.\n"); }
61 '''
62 ```
63
64 Then we can run the test.
65
66 ```meson
67 result = [[#compiler.compiles]](code, name : 'basic check')
68 ```
69
70 The variable *result* will now contain either `true` or `false`
71 depending on whether the compilation succeeded or not. The keyword
72 argument `name` is optional. If it is specified, Meson will write the
73 result of the check to its log.
74
75 ## Does code compile and link?
76
77 Sometimes it is necessary to check whether a certain code fragment not
78 only compiles, but also links successfully, e.g. to check if a symbol
79 is actually present in a library. This can be done using the
80 [[compiler.links]] method like this:
81
82 ```meson
83 code = '''#include<stdio.h>
84 void func() { printf("Compile me.\n"); }
85 '''
86 ```
87
88 Then we can run the test.
89
90 ```meson
91 result = [[#compiler.links]](code, args : '-lfoo', name : 'link check')
92 ```
93
94 The variable *result* will now contain either `true` or `false`
95 depending on whether the compilation and linking succeeded or not. The
96 keyword argument `name` is optional. If it is specified, Meson will
97 write the result of the check to its log.
98
99 ## Compile and run test application
100
101 Here is how you would compile and run a small test application.
102 Testing if a code snippets **runs** versus merely that it links
103 is particularly important for some dependencies such as MPI.
104
105 ```meson
106 code = '''#include<stdio.h>
107 int main(int argc, char **argv) {
108 printf("%s\n", "stdout");
109 fprintf(stderr, "%s\n", "stderr");
110 return 0;
111 }
112 '''
113 result = [[#compiler.run]](code, name : 'basic check')
114 ```
115
116 The `result` variable encapsulates the state of the test, which can be
117 extracted with the following methods. The `name` keyword argument
118 works the same as with `compiles`.
119
120 | Method | Return value |
121 | ------ | ------------ |
122 | compiled | `True` if compilation succeeded. If `false` then all other methods return undefined values. |
123 | returncode | The return code of the application as an integer |
124 | stdout | Program's standard out as text. |
125 | stderr | Program's standard error as text. |
126
127 Here is an example usage:
128
129 ```meson
130 if result.stdout().strip() == 'some_value'
131 # do something
132 endif
133 ```
134
135 ## Does a header exist?
136
137 Header files provided by different platforms vary quite a lot. Meson
138 has functionality to detect whether a given header file is available
139 on the system. The test is done by trying to compile a simple test
140 program that includes the specified header. The following snippet
141 describes how this feature can be used.
142
143 ```meson
144 if [[#compiler.has_header]]('sys/fstat.h')
145 # header exists, do something
146 endif
147 ```
148
149 ## Expression size
150
151 Often you need to determine the size of a particular element (such as
152 `int`, `wchar_t` or `char*`). Using the `compiler` variable mentioned
153 above, the check can be done like this.
154
155 ```meson
156 wcharsize = [[#compiler.sizeof]]('wchar_t', prefix : '#include<wchar.h>')
157 ```
158
159 This will put the size of `wchar_t` as reported by sizeof into
160 variable `wcharsize`. The keyword argument `prefix` is optional. If
161 specified its contents is put at the top of the source file. This
162 argument is typically used for setting `#include` directives in
163 configuration files.
164
165 In older versions (<= 0.30) Meson would error out if the size could
166 not be determined. Since version 0.31 it returns -1 if the size could
167 not be determined.
168
169 ## Does a function exist?
170
171 Just having a header doesn't say anything about its contents.
172 Sometimes you need to explicitly check if some function exists. This
173 is how we would check whether the function `open_memstream` exists in
174 header `stdio.h`
175
176 ```meson
177 if [[#compiler.has_function]]('open_memstream', prefix : '#include <stdio.h>')
178 # function exists, do whatever is required.
179 endif
180 ```
181
182 Note that, on macOS programs can be compiled targeting older macOS
183 versions than the one that the program is compiled on. It can't be
184 assumed that the OS version that is compiled on matches the OS version
185 that the binary will run on.
186
187 Therefore when detecting function availability with [[compiler.has_function]], it
188 is important to specify the correct header in the prefix argument.
189
190 In the example above, the function `open_memstream` is detected, which
191 was introduced in macOS 10.13. When the user builds on macOS 10.13,
192 but targeting macOS 10.11 (`-mmacosx-version-min=10.11`), this will
193 correctly report the function as missing. Without the header however,
194 it would lack the necessary availability information and incorrectly
195 report the function as available.
196
197 ## Does a structure contain a member?
198
199 Some platforms have different standard structures. Here's how one
200 would check if a struct called `mystruct` from header `myheader.h`
201 contains a member called `some_member`.
202
203 ```meson
204 if [[#compiler.has_member]]('struct mystruct', 'some_member', prefix : '#include<myheader.h>')
205 # member exists, do whatever is required
206 endif
207 ```
208
209 ## Type alignment
210
211 Most platforms can't access some data types at any address. For
212 example it is common that a `char` can be at any address but a 32 bit
213 integer only at locations which are divisible by four. Determining the
214 alignment of data types is simple.
215
216 ```meson
217 int_alignment = [[#compiler.alignment]]('int') # Will most likely contain the value 4.
218 ```
219
220 ## Has argument
221
222 This method tests if the compiler supports a given command line
223 argument. This is implemented by compiling a small file with the given
224 argument.
225
226 ```meson
227 has_special_flags = [[#compiler.has_argument]]('-Wspecialthing')
228 ```
229
230 *Note*: some compilers silently swallow command line arguments they do
231 not understand. Thus this test cannot be made 100% reliable.