Debian Codegraph @

subprojects/meson-docs/docs/yaml/objects/compiler.yaml

raw
1 name: compiler
2 long_name: Compiler object
3 description: |
4 This object is returned by [[meson.get_compiler]].
5 It represents a compiler for a given language and allows you to query its properties.
6
7 notes:
8 - |
9 These compiler checks do not use compiler arguments added
10 with `add_*_arguments()`, via `-Dlang_args` on the command-line, or
11 through `CFLAGS`/`LDFLAGS`, etc in the environment. Hence, you can
12 trust that the tests will be fully self-contained, and won't fail
13 because of custom flags added by other parts of the build file or by
14 users.
15
16 - |
17 Note that if you have a single prefix with all your dependencies, you
18 might find it easier to append to the environment variables
19 `C_INCLUDE_PATH` with GCC/Clang and `INCLUDE` with MSVC to expand the
20 default include path, and `LIBRARY_PATH` with GCC/Clang and `LIB` with
21 MSVC to expand the default library search path.
22
23 However, with GCC, these variables will be ignored when
24 cross-compiling. In that case you need to use a specs file. See:
25 http://www.mingw.org/wiki/SpecsFileHOWTO
26
27 methods:
28
29 # Helper methods to pre-define common posargs
30 - name: _code
31 returns: void
32 description: You have found a bug if you can see this!
33 posargs:
34 code:
35 type: str | file
36 description: |
37 The source code to check.
38
39 If a string is passed, the code is used directly. If a [[@file]] object
40 is passed, its content is used for the compiler check.
41
42 # Helper methods to pre-define common kwargs
43 - name: _args
44 returns: void
45 description: You have found a bug if you can see this!
46 kwargs:
47 args:
48 type: list[str]
49 description: |
50 Used to pass a list of compiler arguments.
51 Defining include paths for headers not in the default include path
52 via `-Isome/path/to/header` is generally supported, however, usually not
53 recommended.
54
55 This is because include directories can also be specified via the
56 `include_directories` or the `dependency` kwarg (if present).
57 The same is also true for passing libraries to link with `-lfoo`.
58
59 - name: _include_directories
60 returns: void
61 description: You have found a bug if you can see this!
62 kwargs:
63 include_directories:
64 type: inc | list[inc]
65 since: 0.38.0
66 description: Extra directories for header searches.
67
68 - name: _dependencies
69 returns: void
70 description: You have found a bug if you can see this!
71 kwargs:
72 dependencies:
73 type: dep | list[dep]
74 description: Additionally dependencies required for compiling and / or linking.
75
76 - name: _prefix
77 returns: void
78 description: You have found a bug if you can see this!
79 kwargs:
80 prefix:
81 type: str | list[str]
82 description: |
83 Used to add `#include`s and other things that are required
84 for the symbol to be declared. Since 1.0.0 an array is accepted
85 too. When an array is passed, the items are concatenated together
86 separated by a newline.
87 System definitions should be passed via compiler args
88 (eg: `_GNU_SOURCE` is often required for some symbols to be exposed
89 on Linux, and it should be passed via `args` keyword argument).
90
91 - name: _no_builtin_args
92 returns: void
93 description: You have found a bug if you can see this!
94 kwargs:
95 no_builtin_args:
96 type: bool
97 default: false
98 description: When set to `true`, the compiler arguments controlled by built-in configuration options are not added.
99
100 - name: _name
101 returns: void
102 description: You have found a bug if you can see this!
103 kwargs:
104 name:
105 type: str
106 description: |
107 The name to use for printing a message about the compiler check.
108 If this keyword argument is not passed, no message will be printed about the check.
109
110 # Even more convenient
111 - name: _common
112 returns: void
113 description: You have found a bug if you can see this!
114 kwargs_inherit:
115 - compiler._args
116 - compiler._include_directories
117 - compiler._dependencies
118 - compiler._no_builtin_args
119 - compiler._prefix
120
121 - name: _compiles
122 returns: void
123 description: You have found a bug if you can see this!
124 kwargs:
125 required:
126 type: bool | feature
127 default: false
128 since: 1.5.0
129 description:
130 When set to `true`, Meson will halt if the check fails.
131
132 When set to a [`feature`](Build-options.md#features) option, the feature
133 will control if it is searched and whether to fail if not found.
134 kwargs_inherit:
135 - compiler._args
136 - compiler._include_directories
137 - compiler._dependencies
138 - compiler._no_builtin_args
139 - compiler._name
140 - compiler._werror
141
142 - name: _header
143 returns: void
144 description: You have found a bug if you can see this!
145 kwargs_inherit: compiler._common
146 kwargs:
147 required:
148 type: bool | feature
149 default: false
150 since: 0.50.0
151 description:
152 When set to `true`, Meson will halt if the header check fails.
153
154 When set to a [`feature`](Build-options.md#features) option, the feature
155 will control if it is searched and whether to fail if not found.
156
157 - name: _required
158 returns: void
159 description: You have found a bug if you can see this!
160 kwargs:
161 required:
162 type: bool | feature
163 default: false
164 since: 1.3.0
165 description:
166 When set to `true`, Meson will halt if the check fails.
167
168 When set to a [`feature`](Build-options.md#features) option, the feature
169 will control if it is searched and whether to fail if not found.
170
171 - name: _werror
172 returns: void
173 description: You have found a bug if you can see this!
174 kwargs:
175 werror:
176 type: bool
177 default: false
178 description: When set to `true`, compiler warnings are treated as error.
179 since: 1.3.0
180
181 # Star of the actual functions
182 - name: version
183 returns: str
184 description: Returns the compiler's version number as a string.
185
186 - name: cmd_array
187 returns: list[str]
188 description: Returns an array containing the command(s) for the compiler.
189
190
191 - name: alignment
192 returns: int
193 description: |
194 Returns the alignment of the specified type. For C-like languages,
195 For C-like languages, the header `stddef.h` and `stdio.h` are included
196 implicitly for native compilation, only `stddef.h` is included when
197 cross-compiling.
198
199 posargs:
200 typename:
201 type: str
202 description: The name of the type to check.
203
204 kwargs_inherit:
205 - compiler._args
206 - compiler._prefix
207 - compiler._dependencies
208 # TODO: why not also allow passing `include_directories`?
209
210 - name: run
211 returns: runresult
212 description: Attempts to compile and execute the given code fragment.
213 posargs_inherit: compiler._code
214 kwargs_inherit: compiler._compiles
215
216 - name: get_id
217 returns: str
218 description: |
219 Returns a string identifying the compiler.
220 For example, `gcc`, `msvc`, [and more](Reference-tables.md#compiler-ids).
221
222 - name: get_linker_id
223 returns: str
224 since: 0.53.0
225 description: |
226 Returns a string identifying the linker.
227 For example, `ld.bfd`, `link`, [and more](Reference-tables.md#linker-ids).
228
229 - name: symbols_have_underscore_prefix
230 returns: bool
231 since: 0.37.0
232 description: Returns `true` if the C symbol mangling is one underscore (`_`) prefixed to the symbol.
233
234 - name: has_member
235 returns: bool
236 description: Returns true if the type has the specified member.
237 kwargs_inherit:
238 - compiler._common
239 - compiler._required
240 posargs:
241 typename:
242 type: str
243 description: The type to check.
244 membername:
245 type: str
246 description: The member to check.
247
248 - name: has_members
249 returns: bool
250 description: Returns `true` if the type has *all* the specified members.
251 kwargs_inherit:
252 - compiler._common
253 - compiler._required
254 posargs:
255 typename:
256 type: str
257 description: The type to check.
258 varargs:
259 name: member
260 type: str
261 min_varargs: 1
262 description: The members to check
263
264 - name: has_function
265 returns: bool
266 description: |
267 Returns true if the given function is provided
268 by the standard library or a library passed in with the `args` keyword.
269
270 kwargs_inherit:
271 - compiler._common
272 - compiler._required
273 posargs:
274 funcname:
275 type: str
276 description: The function to check.
277
278 - name: has_type
279 returns: bool
280 description: Returns `true` if the specified token is a type.
281 kwargs_inherit:
282 - compiler._common
283 - compiler._required
284 posargs:
285 typename:
286 type: str
287 description: The type to check.
288
289 - name: compute_int
290 returns: int
291 since: 0.40.0
292 kwargs_inherit: compiler._common
293 description: |
294 Computes the value of the given expression
295 (as an example `1 + 2`). When cross compiling this is evaluated with
296 an iterative algorithm, you can specify keyword arguments `low`
297 (defaults to -1024), `high` (defaults to 1024) and `guess` to
298 specify max and min values for the search and the value to try
299 first.
300 For C-like languages, the header `stddef.h` and `stdio.h` are included
301 implicitly for native compilation, only `stddef.h` is included when
302 cross-compiling.
303
304 posargs:
305 expr:
306 type: str
307 description: The expression to compute.
308
309 kwargs:
310 low:
311 type: int
312 default: -1024
313 description: The min value.
314 high:
315 type: int
316 default: 1024
317 description: The max value.
318 guess:
319 type: int
320 description: The value to try first.
321
322 - name: sizeof
323 returns: int
324 description: |
325 returns the size of the given type (e.g. `'int'`) or -1 if the type is unknown.
326 For C-like languages, the header `stddef.h` and `stdio.h` are included
327 implicitly for native compilation, only `stddef.h` is included when
328 cross-compiling.
329 kwargs_inherit: compiler._common
330 posargs:
331 typename:
332 type: str
333 description: The type to compute.
334
335 - name: get_define
336 returns: str
337 since: 0.40.0
338 description: |
339 Returns the given preprocessor symbol's value
340 as a string or empty string if it is not defined.
341
342 *(since 0.47.0)* This method will concatenate string literals as
343 the compiler would. E.g. `"a" "b"` will become `"ab"`.
344
345 kwargs_inherit: compiler._common
346 posargs:
347 definename:
348 type: str
349 description: The define to check.
350
351 - name: has_define
352 returns: bool
353 since: 1.3.0
354 description: |
355 Returns true if the given preprocessor symbol is *defined*.
356 kwargs_inherit: compiler._common
357 posargs:
358 definename:
359 type: str
360 description: The define to check.
361
362 - name: compiles
363 returns: bool
364 description: Returns true if the code compiles.
365 posargs_inherit: compiler._code
366 kwargs_inherit: compiler._compiles
367
368 - name: links
369 returns: bool
370 description: |
371 Returns true if the code compiles and links.
372
373 *Since 0.60.0*, if the `file` object's
374 suffix does not match the compiler object's language, the compiler
375 corresponding to the suffix is used to compile the source, while the
376 target of the `links` method is used to link the resulting object file.
377 posargs_inherit: compiler._code
378 kwargs_inherit: compiler._compiles
379
380 - name: check_header
381 returns: bool
382 since: 0.47.0
383 description: |
384 Returns true if the specified header is *usable*
385 with the specified prefix, dependencies, and arguments.
386
387 kwargs_inherit: compiler._header
388 posargs:
389 header_name:
390 type: str
391 description: The header to check.
392
393 - name: has_header
394 returns: bool
395 description: |
396 Returns true if the specified header is *exists*
397 with the specified prefix, dependencies, and arguments.
398
399 This method is faster than [[compiler.check_header]] since it only does a
400 pre-processor check.
401
402 kwargs_inherit: compiler._header
403 posargs_inherit: compiler.check_header
404
405 - name: has_header_symbol
406 returns: bool
407 description: |
408 Detects whether a particular symbol is declared in the specified header.
409
410 Symbols here include function, variable, `#define`, type definition, etc.
411
412 kwargs_inherit: compiler._header
413 posargs:
414 header:
415 type: str
416 description: The header to check.
417 symbol:
418 type: str
419 description: The symbol to check.
420
421 - name: find_library
422 returns: dep
423 description: Tries to find the library specified in the positional argument.
424
425 posargs:
426 libname:
427 type: str
428 description: The library to find.
429 kwargs:
430 required:
431 type: bool | feature
432 default: true
433 description: |
434 If set `true`, Meson will abort with an error if the library could not
435 be found. Otherwise, Meson will continue and the found method of the
436 returned object will return `false`.
437
438 When set to a [`feature`](Build-options.md#features) option, the feature
439 will control if it is searched and whether to fail if not found.
440
441 *(since 0.47.0)* The value of a `feature` option can also be passed here.
442
443 has_headers:
444 type: list[str]
445 since: 0.50.0
446 description: |
447 List of headers that must be found as well.
448 This check is equivalent to checking each header with a
449 [[compiler.has_header]] call.
450
451 When used, kwargs that [[compiler.has_header]] would accept can be
452 passed here prefixed with `header_`, and will have the same effect on
453 the header check.
454
455 header_required:
456 type: bool | feature
457 since: 0.50.0
458 description: |
459 When used in conjunction with the has_headers keyword, set the
460 requirement of the headers.
461
462 static:
463 type: bool
464 default: false
465 since: 0.51.0
466 description: |
467 If `true`, the search is limited to static libraries only.
468 Setting this value to `false` (the default) will search for both shared
469 *and* static libraries.
470
471 disabler:
472 type: bool
473 default: false
474 since: 0.49.0
475 description: If `true`, this method will return a [[@disabler]] on a failed check.
476
477 dirs:
478 type: list[str]
479 description: |
480 Additional directories to search in.
481
482 By default the library is searched for in the system library directory
483 (e.g. /usr/lib). Specifying more directories here, causes Meson to search
484 in those directories as well as the system directories.
485 # does not work, since all _common kwargs need to be prefixed `header_` here
486 # kwargs_inherit: compiler._common
487 header_args:
488 type: list[str]
489 since: 0.51.0
490 description: |
491 When the `has_headers` kwarg is also used, this argument is passed to
492 [[compiler.has_header]] as `args`.
493 header_include_directories:
494 type: inc | list[inc]
495 since: 0.51.0
496 description: |
497 When the `has_headers` kwarg is also used, this argument is passed to
498 [[compiler.has_header]] as `include_directories`.
499 header_dependencies:
500 type: dep | list[dep]
501 since: 0.51.0
502 description: |
503 When the `has_headers` kwarg is also used, this argument is passed to
504 [[compiler.has_header]] as `dependencies`.
505 header_no_builtin_args:
506 type: bool
507 default: false
508 since: 0.51.0
509 description: |
510 When the `has_headers` kwarg is also used, this argument is passed to
511 [[compiler.has_header]] as `no_builtin_args`.
512 header_prefix:
513 type: str
514 since: 0.51.0
515 description: |
516 When the `has_headers` kwarg is also used, this argument is passed to
517 [[compiler.has_header]] as `prefix`.
518
519 # Compiler arguments
520 - name: has_argument
521 returns: bool
522 description: |
523 Returns `true` if the compiler accepts the specified command line argument,
524 that is, can compile code without erroring out or printing a warning about
525 an unknown flag.
526
527 posargs:
528 argument:
529 type: str
530 description: The argument to check.
531 kwargs_inherit:
532 - compiler._required
533
534 - name: has_multi_arguments
535 since: 0.37.0
536 returns: bool
537 description: |
538 the same as [[compiler.has_argument]] but takes multiple arguments
539 and uses them all in a single compiler invocation.
540
541 varargs:
542 name: arg
543 type: str
544 description: The arguments to check.
545 kwargs_inherit:
546 - compiler._required
547
548 - name: get_supported_arguments
549 returns: list[str]
550 since: 0.43.0
551 varargs_inherit: compiler.has_multi_arguments
552 description: |
553 Returns an array containing only the arguments supported by the compiler,
554 as if [[compiler.has_argument]] were called on them individually.
555
556 kwargs:
557 checked:
558 type: str
559 since: 0.59.0
560 default: "'off'"
561 description: |
562 Supported values:
563 - `'off'`: Quietly ignore unsupported arguments
564 - `'warn'`: Print a warning for unsupported arguments
565 - `'require'`: Abort if at least one argument is not supported
566
567 - name: first_supported_argument
568 returns: list[str]
569 since: 0.43.0
570 varargs_inherit: compiler.has_multi_arguments
571 description: |
572 Given a list of strings, returns a single-element list containing the first
573 argument that passes the [[compiler.has_argument]] test or an empty array if
574 none pass.
575
576
577 # Linker arguments
578 - name: has_link_argument
579 since: 0.46.0
580 returns: bool
581 description: |
582 Returns `true` if the linker accepts the specified command line argument,
583 that is, can
584 compile and link code without erroring out or printing a warning
585 about an unknown flag. Link arguments will be passed to the
586 compiler, so should usually have the `-Wl,` prefix. On VisualStudio
587 a `/link` argument will be prepended.
588
589 posargs:
590 argument:
591 type: str
592 description: The argument to check.
593 kwargs_inherit:
594 - compiler._required
595
596 - name: has_multi_link_arguments
597 since: 0.46.0
598 returns: bool
599 description: |
600 the same as [[compiler.has_link_argument]] but takes multiple arguments
601 and uses them all in a single compiler invocation.
602
603 varargs:
604 name: arg
605 type: str
606 description: The link arguments to check.
607 kwargs_inherit:
608 - compiler._required
609
610 - name: get_supported_link_arguments
611 returns: list[str]
612 since: 0.46.0
613 varargs_inherit: compiler.has_multi_link_arguments
614 description: |
615 Returns an array containing only the arguments supported by the compiler,
616 as if [[compiler.has_link_argument]] were called on them individually.
617
618 # TODO: why is this not present here?
619 # kwargs:
620 # checked:
621 # type: str
622 # since: 0.59.0
623 # default: "'off'"
624 # description: |
625 # Supported values:
626 # - `'off'`: Quietly ignore unsupported arguments
627 # - `'warn'`: Print a warning for unsupported arguments
628 # - `'require'`: Abort if at least one argument is not supported
629
630 - name: first_supported_link_argument
631 returns: list[str]
632 since: 0.46.0
633 varargs_inherit: compiler.has_multi_link_arguments
634 description: |
635 Given a list of strings, returns the first argument that passes the
636 [[compiler.has_link_argument]] test or an empty array if none pass.
637
638 - name: has_function_attribute
639 returns: bool
640 since: 0.48.0
641 description: |
642 Returns `true` if the compiler supports the GNU style (`__attribute__(...)`) `name`.
643 This is preferable to manual compile checks as it may be optimized for compilers that
644 do not support such attributes.
645 [This table](Reference-tables.md#gcc-__attribute__) lists all of the supported attributes.
646
647 posargs:
648 name:
649 type: str
650 description: The attribute name to check.
651 kwargs_inherit:
652 - compiler._required
653
654 - name: get_supported_function_attributes
655 varargs:
656 name: name
657 type: str
658 min_varargs: 1
659 description: The attribute names to check.
660 returns: list[str]
661 since: 0.48.0
662 description: |
663 Returns an array containing any names that are supported GCC style attributes.
664 Equivalent to [[compiler.has_function_attribute]] was called on each of
665 them individually.
666
667 # TODO: Again why doesn't this function have the checked kwarg?
668
669 - name: get_argument_syntax
670 returns: str
671 since: 0.49.0
672 description: |
673 returns a string identifying the type of arguments the compiler takes.
674 Can be one of `gcc`, `msvc`, or an undefined
675 string value. This method is useful for identifying compilers that are not
676 gcc or msvc, but use the same argument syntax as one of those two compilers
677 such as clang or icc, especially when they use different syntax on different
678 operating systems.
679
680 - name: preprocess
681 returns: list[custom_idx]
682 since: 0.64.0
683 description: |
684 Preprocess a list of source files but do not compile them. The preprocessor
685 will receive the same arguments (include directories, defines, etc) as with
686 normal compilation. That includes for example args added with
687 `add_project_arguments()`, or on the command line with `-Dc_args=-DFOO`.
688 varargs:
689 name: source
690 type: str | file | custom_tgt | custom_idx | generated_list
691 description: |
692 Input source to preprocess. The following types are supported:
693
694 - Strings relative to the current source directory
695 - [[@file]] objects defined in any preceding build file
696 - The return value of configure-time generators such as [[configure_file]]
697 - The return value of build-time generators such as
698 [[custom_target]] or [[generator.process]]
699 kwargs_inherit:
700 - compiler._include_directories
701 kwargs:
702 output:
703 type: str
704 description: |
705 Template for name of preprocessed files: `@PLAINNAME@` is replaced by
706 the source filename and `@BASENAME@` is replaced by the source filename
707 without its extension.
708 compile_args:
709 type: list[str]
710 description: |
711 Extra flags to pass to the preprocessor
712 dependencies:
713 type: dep | list[dep]
714 description: Additionally dependencies required.
715 since: 1.1.0
716 depends:
717 type: list[build_tgt | custom_tgt]
718 description: |
719 Specifies that this target depends on the specified
720 target(s). These targets should be built before starting
721 to preprocess an input.
722 since: 1.4.0