| 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 |