summaryrefslogtreecommitdiff
path: root/docs/markdown/Builtin-options.md
AgeCommit message (Collapse)Author
2025-11-28docs: Fix typoKO Myung-Hun
2025-11-23Add documentation for import std.Jussi Pakkanen
2025-11-14Add `os2_emxomf' option to generate OMF files on OS/2KO Myung-Hun
1. Generate OMF objs with `-Zomf' compiler flags 2. Generate OMF libs with `.lib' suffix using `emxomfar' as a librarian
2025-10-23rust: Add rust_nightly feature optionXavier Claessens
This is used for project to require a nightly Rust compiler, and also for Meson to enable nightly feature if available.
2025-10-14doc: fix version for build_config optionCharles Brunet
was wrongly tagged in 59c3dd1
2025-10-01Add documentation for naming scheme.Jussi Pakkanen
2025-09-15docs: fix pre-1.8 order for per-subproject optionsPaolo Bonzini
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2025-09-15options: put back in place 1.7 ordering of opt=value vs subp:opt=valuePaolo Bonzini
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2025-08-28python: add a python.build_config option (PEP 739)Filipe Laíns
Signed-off-by: Filipe Laíns <lains@riseup.net> Signed-off-by: Michał Górny <mgorny@quansight.com>
2025-07-18rust: add rust_dynamic_std optionPaolo Bonzini
As an initial implementation, simply adding "-C prefer-dynamic" works for binary crates (as well as dylib and proc-macro that already used it). In the future this could be extended to other crate types. For more information see the comment in the changed file, as well as https://github.com/mesonbuild/meson/issues/8828 and https://github.com/mesonbuild/meson/issues/14215. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2025-07-07docs: document order in which options are appliedPaolo Bonzini
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2025-05-19docs: Note that debug=false does not define NDEBUGPaul Caprioli
2025-04-07Fix documentation typosEmil Berg
2025-03-24linkers: darwin: do not use -bundle for shared_modulesPaolo Bonzini
Both dynamic libraries and bundles these days can be dynamically loaded using the dl APIs (e.g. dlopen, dlclose). It is not possible to include bundles on a linker command line as if they were shared libraries, but that's pretty much the only difference. However, bundles fail the Apple verification for iOS: 2025-02-10 13:54:09.095 ERROR: Validation failed (409) The binary is invalid. The executable 'Runner.app/Frameworks/numpy._core._operand_flag_tests.framework/numpy._core._operand_flag_tests' has type 'BUNDLE' that is not valid. Only 'EXECUTE' is permitted. 2025-02-10 13:54:09.096 ERROR: Validation failed (409) Missing load commands. The executable at 'Runner.app/Frameworks/numpy._core._operand_flag_tests.framework' does not have the necessary load commands. Try rebuilding the app with the latest Xcode version. If you are using third party development tools, contact the provider. So switch to -dynamiclib for shared modules as well. Fixes: #14240
2025-03-09compilers: convert `b_sanitize` to a free-form array optionPatrick Steinhardt
In the preceding commit we have started to perform compiler checks for the value of `b_sanitize`, which allows us to detect sanitizers that aren't supported by the compiler toolchain. But we haven't yet loosened the option itself to accept arbitrary values, so until now it's still only possible to pass sanitizer combinations known by Meson, which is quite restrictive. Lift that restriction by adapting the `b_sanitize` option to become a free-form array. Like this, users can pass whatever combination of comma-separated sanitizers to Meson, which will then figure out whether that combination is supported via the compiler checks. This lifts a couple of restrictions and makes the supporting infrastructure way more future proof. A couple of notes regarding backwards compatibility: - All previous values of `b_sanitize` will remain valid as the syntax for free-form array values and valid combo choices is the same. We also treat 'none' specially so that we know to convert it into an empty array. - Even though the option has been converted into a free-form array, callers of `get_option('b_sanitize')` continue to get a string as value. We may eventually want to introduce a kwarg to alter this behaviour, but for now it is expected to be good enough for most use cases. Fixes #8283 Fixes #7761 Fixes #5154 Fixes #1582 Co-authored-by: Dylan Baker <dylan@pnwbakers.com> Signed-off-by: Patrick Steinhardt <ps@pks.im>
2025-01-28docs: clarify behavior of default_both_libraries optionDaiki Ueno
Signed-off-by: Daiki Ueno <dueno@redhat.com>
2025-01-27adding c_std=c2y option for clangajs
Signed-off-by: ajs <sam4lordjesus@outlook.com>
2025-01-08rust: change warning_level=0 to "--cap-lints allow"Paolo Bonzini
This is a better and more backwards-compatible way to disable all warnings, compared to "-A warnings". The Rust RFC (https://rust-lang.github.io/rfcs/1193-cap-lints.html) explains the rationale: > We would very much like to be able to modify lints, however. For example > rust-lang/rust#26473 updated the missing_docs lint to also look for missing > documentation on const items. This ended up breaking some crates in the > ecosystem due to their usage of #![deny(missing_docs)]. While at it, document that Rust deviates from the other languages in its interpretation of warning_level=0. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2024-09-11Fix typosspaette
2024-09-06auto select static or shared when linking both_libraries togetherCharles Brunet
2024-09-06add default_both_libraries core optionCharles Brunet
2024-06-10Add note about meson-python and installation pathEmil Melnikov
New people that want to use Meson for building Python extensions most probably will read Python module docs first. Direct them to meson-python and suggest to set `python.install_env=auto`.
2024-05-15docs: fix description of cpp_eh=noneEli Schwartz
We changed the behavior in #6116 but did not change the docs as well. Fixes #8233
2024-05-09In Builtin-options documentation, clarify warning_level=0.sammyj85
warning_level=0 is not 'none' but 'compiler default'.
2024-01-15compilers: add c23 and gnu23 c_stdsSimon Ser
Closes: https://github.com/mesonbuild/meson/issues/12702
2023-08-30Merge pull request #10332 from xclaesse/std-optJussi Pakkanen
c_std, cpp_std: Change to a list of desired versions in preference order
2023-08-14Python: Add 'limited_api' kwarg to extension_moduleAndrew McNulty
This commit adds a new keyword arg to extension_module() that enables a user to target the Python Limited API, declaring the version of the limited API that they wish to target. Two new unittests have been added to test this functionality.
2023-08-07c_std, cpp_std: Change to a list of desired versions in preference orderXavier Claessens
Projects that prefer GNU C but can fallback to ISO C can now set for example `default_options: 'c_std=gnu11,c11'` and it will use gnu11 when available, fallback to c11 otherwise. It is an error only if none of the values are supported by the current compiler. This allows to deprecate gnuXX values from MSVC compiler, that means that `default_options: 'c_std=gnu11'` will now print warning with MSVC but still fallback to 'c11' value. No warning is printed if at least one of the values is valid, i.e. `default_options: 'c_std=gnu11,c11'`. In the future that deprecation warning will become an hard error because `c_std=gnu11` should mean GNU is required, for projects that cannot be built with MSVC for example.
2023-06-28Experimental 'genvslite' WIP. (#11049)GertyP
* Capture all compile args from the first round of ninja backend generation for all languages used in building the targets so that these args, defines, and include paths can be applied to the .vcxproj's intellisense fields for all buildtypes/configurations. Solution generation is now set up for mutiple build configurations (buildtypes) when using '--genvslite'. All generated vcxprojs invoke the same high-level meson compile to build all targets; there's no selective target building (could add this later). Related to this, we skip pointlessly generating vcxprojs for targets that aren't buildable (BuildTarget-derived), which aren't of interest to the user anyway. When using --genvslite, no longer inject '<ProjectReference ...>' dependencies on which a generated .vcxproj depends because that imposes a forced visual studio build dependency, which we don't want, since we're essentially bypassing VS's build in favour of running 'meson compile ...'. When populating the vcxproj's shared intellisense defines, include paths, and compiler options fields, we choose the most frequent src file language, since this means more project src files can simply reference the project shared fields and fewer files of non-primary language types need to populate their full set of intellisense fields. This makes for smaller .vcxproj files. Paths for generated source/header/etc files, left alone, would be added to solution projects relative to the '..._vs' build directory, where they're never generated; they're generated under the respective '..._[debug/opt/release]' ninja build directories that correspond to the solution build configuration. Although VS doesn't allow conditional src/header listings in vcxprojs (at least not in a simple way that I'm aware of), we can ensure these generated sources get adjusted to at least reference locations under one of the concrete build directories (I've chosen '..._debug') under which they will be generated. Testing with --genvslite has revealed that, in some cases, the presence of 'c:\windows\system32;c:\windows' on the 'Path' environment variable (via the make-style project's ExecutablePath element) is critical to getting the 'meson compile ...' build to succeed. Not sure whether this is some 'find and guess' implicit defaults behaviour within meson or within the MSVC compiler that some projects may rely on. Feels weird but not sure of a better solution than forcibly adding these to the Path environment variable (the Executable Path property of the project). Added a new windows-only test to windowstests.py ('test_genvslite') to exercise the --genvslite option along with checking that the 'msbuild' command invokes the 'meson compile ...' of the build-type-appropriate-suffixed temporary build dir and checks expected program output. Check and report error if user specifies a non-ninja backend with a 'genvslite' setup, since that conflicts with the stated behaviour of genvslite. Also added this test case to 'WindowsTests.test_genvslite' I had problems tracking down some problematic environment variable behaviour, which appears to need a work-around. See further notes on VSINSTALLDIR, in windowstests.py, test_genvslite. 'meson setup --help' clearly states that positional arguments are ... [builddir] [sourcedir]. However, BasePlatformTests.init(...) was passing these in the order [sourcedir] [builddir]. This was producing failures, saying, "ERROR: Neither directory contains a build file meson.build." but when using the correct ordering, setup now succeeds. Changed regen, run_tests, and run_install utility projects to be simpler makefile projects instead, with commands to invoke the appropriate '...meson.py --internal regencheck ...' (or install/test) on the '[builddir]_[buildtype]' as appropriate for the curent VS configuration. Also, since the 'regen.vcxproj' utility didn't work correctly with '--genvslite' setup build dirs, and getting it to fully work would require more non-trivial intrusion into new parts of meson (i.e. '--internal regencheck', '--internal regenerate', and perhaps also 'setup --reconfigure'), for now, the REGEN project is replaced with a simpler, lighter-weight RECONFIGURE utility proj, which is unlinked from any solution build dependencies and which simply runs 'meson setup --reconfigure [builddir]_[buildtype] [srcdir]' on each of the ninja-backend build dirs for each buildtype. Yes, although this will enable the building/compiling to be correctly configured, it can leave the solution/vcxprojs stale and out-of-date, it's simple for the user to 'meson setup --genvslite ...' to fully regenerate an updated, correct solution again. However, I've noted this down as a 'fixme' to consider implementing the full regen behaviour for the genvslite case. * Review feedback changes - - Avoid use of 'captured_compile_args_per_buildtype_and_target' as an 'out' param. - Factored a little msetup.py, 'run(...)' macro/looping setup steps, for genvslite, out into a 'run_genvslite_setup' func. * Review feedback: Fixed missing spaces between multi-line strings. * 'backend_name' assignment gets immediately overwritten in 'genvslite' case so moved it into else/non-genvslite block. * Had to bump up 'test cases/unit/113 genvslites/...' up to 114; it collided with a newly added test dir again. * Changed validation of 'capture' and 'captured_compile_args_...' to use MesonBugException instead of MesonException. * Changed some function param and closing brace indentation.
2023-06-02docs: List vc++20 for cpp_stdNathan Kidd
vc++20 support was added in 012ec7d5b3379b035f1dd1369d74cafd26ff6ab0
2023-05-02python module: add an automatic byte-compilation stepEli Schwartz
For all source `*.py` files installed via either py.install_sources() or an `install_dir: py.get_install_dir()`, produce `*.pyc` files at install time. Controllable via a module option.
2023-03-29Make --vsenv a readonly builtin optionXavier Claessens
We need to remember its value when reconfiguring, but the Build object is not reused, only coredata is. This also makes CLI more consistent by allowing `-Dvsenv=true` syntax. Fixes: #11309
2023-03-20backends: add a new "none" backendEli Schwartz
It can only be used for projects that don't have any rules at all, i.e. they are purely using Meson to: - configure files - run (script?) tests - install files that exist by the end of the setup stage This can be useful e.g. for Meson itself, a pure python project.
2023-02-28doc: Be more specific about warning_level optionXavier Claessens
Fixes: #11469
2022-12-27add builtin option to install licensesEli Schwartz
Unless `meson.install_dependency_manifest()` is explicitly used, this will cause a default implied one to be installed.
2022-11-27Add warning_level=everythingDavid Robillard
Adds a new maximum warning level that is roughly equivalent to "all warnings". This adds a way to use `/Wall` with MSVC (without the previous broken warning), `-Weverything` with clang, and almost all general warnings in GCC with strictness roughly equivalent to clang's `-Weverything`. The GCC case must be implemented by meson since GCC doesn't provide a similar option. To avoid maintenance headaches for meson, this warning level is defined objectively: all warnings are included except those that require specific values or are specific to particular language revisions. This warning level is mainly intended for new code, and it is expected (nearly guaranteed) that projects will need to add some suppressions to build cleanly with it. More commonly, it's just a handy way to occasionally take a look at what warnings are present with some compiler, in case anything interesting shows up you might want to enable in general. Since the warnings enabled at this level are inherently unstable with respect to compiler versions, it is intended for use by developers and not to be set as the default.
2022-11-15escape asterisk used for footnotetastytea
unescaped it's turned into a list item
2022-11-11docs: improve ESL text, fix some English errorsGuilherme Janczak
Fixes: - Incorrect, redundant, or overabundant usage of "just" - Missing punctuation - Missing "the" - Parenthesized text far from what it describes There are some subjective changes, I hope those aren't controversial.
2022-10-13Add b_thinlto_cache for automatically configuring incremental ThinLTOTatsuyuki Ishi
2022-10-09compilers: Add optimization=plain optionJan Tojnar
https://github.com/mesonbuild/meson/pull/9287 changed the `optimization=0` to pass `-O0` to the compiler. This change is reasonable by itself but unfortunately, it breaks `buildtype=plain`, which promises that “no extra build flags are used”. `buildtype=plain` is important for distros like NixOS, which manage compiler flags for optimization and hardening themselves. Let’s introduce a new optimization level that does nothing and set it as the default for `buildtype=plain`.
2022-06-27docs: encourage using the "setup" subcommand where appropriateEli Schwartz
2022-06-27docs: fix confusing repetitionEli Schwartz
The end of the paragraph indicates that the options which support --foo will be listed in the help text. The beginning of the paragraph seems to suggest the same thing, except it doesn't distinguish between -Dfoo and --foo style options. The first mention is redundant and feels like the wrong part of the paragraph to mention it anyway.
2022-06-27docs: linkify some function referencesEli Schwartz
2022-06-06compilers: Add support for stand-alone leak sanitizerMarco Trevisan (Treviño)
Leak sanitizer can be enabled without the whole AddressSanitizer, this can be done by passing -fsanitize=leak as documented at [1]. Meson doesn't support this, so add support for it. [1] https://clang.llvm.org/docs/LeakSanitizer.html
2022-05-03add prefer_static built-in optionDudemanguy
By default, meson will try to look for shared libraries first before static ones. In the meson.build itself, one can use the static keyword to control if a static library will be tried first but there's no simple way for an end user performing a build to switch back and forth at will. Let's cover this usecase by adding an option that allows a user to specify if they want dependency lookups to try static or shared libraries first. The writer of the meson.build can manually specify the static keyword where appropriate which will override the value of this option.
2022-04-27improve help for -DdebugPaolo Bonzini
"Debug" is not a very helpful help message. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2022-04-19docs: Add documentation on pkgconfig.relocatableFredrik Salomonsson
- Documentation for the pkgconfig.relocatable module option in Builtin-options. Gives an explanation on what it does, usefulness and what error that can occur when using it. - Add pkgconfig.relocatable release snippet. Similar to the documentation in Builtin-options. Just a bit more brief. - Add Pkgconfig to DataTests.test_builtin_options_documented in the docs unit tests.
2022-03-22interpreter: Make compiler options per-subprojectXavier Claessens
2022-02-22python module: add option to specify a python environment to install toEli Schwartz
The default behavior of installing relative to prefix may be unexpected, and is definitely wrong in many cases. Give users control in order to specify that yes, they actually want to install to a venv. This is particularly useful for projects that use meson as a build system for a python module, where *all* files shall be installed into the python site-packages.
2022-02-09meson: Allow directory options outside of prefixJan Tojnar
This bring us in line with Autotools and CMake and it is useful for platforms like Nix, which install projects into multiple independent prefixes. As a consequence, `get_option` might return absolute paths for some directory options, if a directory outside of prefix is passed. This is technically a backwards incompatible change but its effect should be minimal, thanks to widespread use of `join_paths`/`/` operator and pkg-config generator module. It should only cause an issue when a path were constructed by concatenating the value of directory path option. Also remove a comment about commonpath since we do not use that since <https://github.com/mesonbuild/meson/commit/00f5dadd5b7d71c30bd7393d165a87f554eb92e5>. Fixes: https://github.com/mesonbuild/meson/issues/2561