| 1 |
--- |
| 2 |
short-description: Build options to configure project properties |
| 3 |
... |
| 4 |
|
| 5 |
# Build options |
| 6 |
|
| 7 |
Most non-trivial builds require user-settable options. As an example a |
| 8 |
program may have two different data backends that are selectable at |
| 9 |
build time. Meson provides for this by having an option definition |
| 10 |
file. Its name is `meson.options` and it is placed at the root of |
| 11 |
your source tree. For versions of meson before 1.1, this file was called |
| 12 |
`meson_options.txt`. |
| 13 |
|
| 14 |
Here is a simple option file. |
| 15 |
|
| 16 |
```meson |
| 17 |
option('someoption', type : 'string', value : 'optval', description : 'An option') |
| 18 |
option('other_one', type : 'boolean', value : false) |
| 19 |
option('combo_opt', type : 'combo', choices : ['one', 'two', 'three'], value : 'three') |
| 20 |
option('integer_opt', type : 'integer', min : 0, max : 5, value : 3) # Since 0.45.0 |
| 21 |
option('free_array_opt', type : 'array', value : ['one', 'two']) # Since 0.44.0 |
| 22 |
option('array_opt', type : 'array', choices : ['one', 'two', 'three'], value : ['one', 'two']) |
| 23 |
option('some_feature', type : 'feature', value : 'enabled') # Since 0.47.0 |
| 24 |
option('long_desc', type : 'string', value : 'optval', |
| 25 |
description : 'An option with a very long description' + |
| 26 |
'that does something in a specific context') # Since 0.55.0 |
| 27 |
``` |
| 28 |
|
| 29 |
For built-in options, see [Built-in options][builtin_opts]. |
| 30 |
|
| 31 |
## Build option types |
| 32 |
|
| 33 |
All types allow a `description` value to be set describing the option, |
| 34 |
if no description is set then the name of the option will be used instead. |
| 35 |
|
| 36 |
### Strings |
| 37 |
|
| 38 |
The string type is a free form string. If the default value is not set |
| 39 |
then an empty string will be used as the default. |
| 40 |
|
| 41 |
### Booleans |
| 42 |
|
| 43 |
Booleans may have values of either `true` or `false`. If no default |
| 44 |
value is supplied then `true` will be used as the default. |
| 45 |
|
| 46 |
### Combos |
| 47 |
|
| 48 |
A combo allows any one of the values in the `choices` parameter to be |
| 49 |
selected. If no default value is set then the first value will be the |
| 50 |
default. |
| 51 |
|
| 52 |
### Integers |
| 53 |
|
| 54 |
An integer option contains a single integer with optional upper and |
| 55 |
lower values that are specified with the `min` and `max` keyword |
| 56 |
arguments. |
| 57 |
|
| 58 |
This type is available since Meson version 0.45.0. |
| 59 |
|
| 60 |
### Arrays |
| 61 |
|
| 62 |
Arrays represent an array of strings. By default the array can contain |
| 63 |
arbitrary strings. To limit the possible values that can be used set the |
| 64 |
`choices` parameter. Meson will then only allow the value array to |
| 65 |
contain strings that are in the given list. The array may be |
| 66 |
empty. The `value` parameter specifies the default value of the option |
| 67 |
and if it is unset then the values of `choices` will be used as the |
| 68 |
default. |
| 69 |
|
| 70 |
As of 0.47.0 -Dopt= and -Dopt=[] both pass an empty list, before this |
| 71 |
-Dopt= would pass a list with an empty string. |
| 72 |
|
| 73 |
This type is available since version 0.44.0 |
| 74 |
|
| 75 |
### Features |
| 76 |
|
| 77 |
A `feature` option has three states: `enabled`, `disabled` or `auto`. |
| 78 |
It is intended to be passed as a value for the `required` keyword |
| 79 |
argument of most functions. Currently supported in |
| 80 |
[[add_languages]], |
| 81 |
[[compiler.find_library]], |
| 82 |
[[compiler.has_header]], |
| 83 |
[[dependency]], |
| 84 |
[[find_program]], |
| 85 |
[[import]] and |
| 86 |
[[subproject]] |
| 87 |
functions. |
| 88 |
|
| 89 |
- `enabled` is the same as passing `required : true`. |
| 90 |
- `auto` is the same as passing `required : false`. |
| 91 |
- `disabled` do not look for the dependency and always return 'not-found'. |
| 92 |
|
| 93 |
When getting the value of this type of option using [[get_option]], a |
| 94 |
special [[@feature]] object is returned instead |
| 95 |
of the string representation of the option's value. This object can be |
| 96 |
passed to `required`: |
| 97 |
|
| 98 |
```meson |
| 99 |
d = dependency('foo', required : get_option('myfeature')) |
| 100 |
if d.found() |
| 101 |
app = executable('myapp', 'main.c', dependencies : [d]) |
| 102 |
endif |
| 103 |
``` |
| 104 |
|
| 105 |
To check the value of the feature, the object has three methods |
| 106 |
returning a boolean and taking no argument: |
| 107 |
|
| 108 |
- `.enabled()` |
| 109 |
- `.disabled()` |
| 110 |
- `.auto()` |
| 111 |
|
| 112 |
This is useful for custom code depending on the feature: |
| 113 |
|
| 114 |
```meson |
| 115 |
if get_option('myfeature').enabled() |
| 116 |
# ... |
| 117 |
endif |
| 118 |
``` |
| 119 |
|
| 120 |
If the value of a `feature` option is set to `auto`, that value is |
| 121 |
overridden by the global `auto_features` option (which defaults to |
| 122 |
`auto`). This is intended to be used by packagers who want to have |
| 123 |
full control on which dependencies are required and which are |
| 124 |
disabled, and not rely on build-deps being installed (at the right |
| 125 |
version) to get a feature enabled. They could set |
| 126 |
`auto_features=enabled` to enable all features and disable explicitly |
| 127 |
only the few they don't want, if any. |
| 128 |
|
| 129 |
This type is available since version 0.47.0 |
| 130 |
|
| 131 |
## Deprecated options |
| 132 |
|
| 133 |
Since *0.60.0* |
| 134 |
|
| 135 |
Project options can be marked as deprecated and Meson will warn when user sets a |
| 136 |
value to it. It is also possible to deprecate only some of the choices, and map |
| 137 |
deprecated values to a new value. |
| 138 |
|
| 139 |
```meson |
| 140 |
# Option fully deprecated, it warns when any value is set. |
| 141 |
option('o1', type: 'boolean', deprecated: true) |
| 142 |
|
| 143 |
# One of the choices is deprecated, it warns only when 'a' is in the list of values. |
| 144 |
option('o2', type: 'array', choices: ['a', 'b'], deprecated: ['a']) |
| 145 |
|
| 146 |
# One of the choices is deprecated, it warns only when 'a' is in the list of values |
| 147 |
# and replace it by 'c'. |
| 148 |
option('o3', type: 'array', choices: ['a', 'b', 'c'], deprecated: {'a': 'c'}) |
| 149 |
|
| 150 |
# A boolean option has been replaced by a feature, old true/false values are remapped. |
| 151 |
option('o4', type: 'feature', deprecated: {'true': 'enabled', 'false': 'disabled'}) |
| 152 |
|
| 153 |
# A feature option has been replaced by a boolean, enabled/disabled/auto values are remapped. |
| 154 |
option('o5', type: 'boolean', deprecated: {'enabled': 'true', 'disabled': 'false', 'auto': 'false'}) |
| 155 |
``` |
| 156 |
|
| 157 |
Since *0.63.0* the `deprecated` keyword argument can take the name of a new option |
| 158 |
that replaces this option. In that case, setting a value on the deprecated option |
| 159 |
will set the value on both the old and new names, assuming they accept the same |
| 160 |
values. |
| 161 |
|
| 162 |
```meson |
| 163 |
# A boolean option has been replaced by a feature with another name, old true/false values |
| 164 |
# are accepted by the new option for backward compatibility. |
| 165 |
option('o6', type: 'boolean', value: 'true', deprecated: 'o7') |
| 166 |
option('o7', type: 'feature', value: 'enabled', deprecated: {'true': 'enabled', 'false': 'disabled'}) |
| 167 |
|
| 168 |
# A project option is replaced by a module option |
| 169 |
option('o8', type: 'string', value: '', deprecated: 'python.platlibdir') |
| 170 |
``` |
| 171 |
|
| 172 |
## Using build options |
| 173 |
|
| 174 |
```meson |
| 175 |
optval = get_option('opt_name') |
| 176 |
``` |
| 177 |
|
| 178 |
This function also allows you to query the value of Meson's built-in |
| 179 |
project options. For example, to get the installation prefix you would |
| 180 |
issue the following command: |
| 181 |
|
| 182 |
```meson |
| 183 |
prefix = get_option('prefix') |
| 184 |
``` |
| 185 |
|
| 186 |
It should be noted that you cannot set option values in your Meson |
| 187 |
scripts. They have to be set externally with the `meson configure` |
| 188 |
command line tool. Running `meson configure` without arguments in a |
| 189 |
build dir shows you all options you can set. |
| 190 |
|
| 191 |
To change their values use the `-D` |
| 192 |
option: |
| 193 |
|
| 194 |
```console |
| 195 |
$ meson configure -Doption=newvalue |
| 196 |
``` |
| 197 |
|
| 198 |
Setting the value of arrays is a bit special. If you only pass a |
| 199 |
single string, then it is considered to have all values separated by |
| 200 |
commas. Thus invoking the following command: |
| 201 |
|
| 202 |
```console |
| 203 |
$ meson configure -Darray_opt=foo,bar |
| 204 |
``` |
| 205 |
|
| 206 |
would set the value to an array of two elements, `foo` and `bar`. |
| 207 |
|
| 208 |
If you need to have commas in your string values, then you need to |
| 209 |
pass the value with proper shell quoting like this: |
| 210 |
|
| 211 |
```console |
| 212 |
$ meson configure "-Doption=['a,b', 'c,d']" |
| 213 |
``` |
| 214 |
|
| 215 |
The inner values must always be single quotes and the outer ones |
| 216 |
double quotes. |
| 217 |
|
| 218 |
To change values in subprojects prepend the name of the subproject and |
| 219 |
a colon: |
| 220 |
|
| 221 |
```console |
| 222 |
$ meson configure -Dsubproject:option=newvalue |
| 223 |
``` |
| 224 |
|
| 225 |
**NOTE:** If you cannot call `meson configure` you likely have a old |
| 226 |
version of Meson. In that case you can call `mesonconf` instead, but |
| 227 |
that is deprecated in newer versions |
| 228 |
|
| 229 |
## Yielding to superproject option |
| 230 |
|
| 231 |
Suppose you have a master project and a subproject. In some cases it |
| 232 |
might be useful to have an option that has the same value in both of |
| 233 |
them. This can be achieved with the `yield` keyword. Suppose you have |
| 234 |
an option definition like this: |
| 235 |
|
| 236 |
```meson |
| 237 |
option('some_option', type : 'string', value : 'value', yield : true) |
| 238 |
``` |
| 239 |
|
| 240 |
If you build this project on its own, this option behaves like |
| 241 |
usual. However if you build this project as a subproject of another |
| 242 |
project which also has an option called `some_option`, then calling |
| 243 |
`get_option` returns the value of the superproject. If the value of |
| 244 |
`yield` is `false`, `get_option` returns the value of the subproject's |
| 245 |
option. |
| 246 |
|
| 247 |
|
| 248 |
## Built-in build options |
| 249 |
|
| 250 |
There are a number of [built-in options][builtin_opts]. To get the |
| 251 |
current list execute `meson configure` in the build directory. |
| 252 |
|
| 253 |
[builtin_opts]: https://mesonbuild.com/Builtin-options.html |
| 254 |
|
| 255 |
### Visual Studio |
| 256 |
|
| 257 |
#### Startup project |
| 258 |
|
| 259 |
The `backend_startup_project` option can be set to define the default |
| 260 |
project that will be executed with the "Start debugging F5" action in |
| 261 |
visual studio. It should be the same name as an executable target |
| 262 |
name. |
| 263 |
|
| 264 |
```meson |
| 265 |
project('my_project', 'c', default_options: ['backend_startup_project=my_exe']) |
| 266 |
executable('my_exe', ...) |
| 267 |
``` |
| 268 |
|
| 269 |
### Ninja |
| 270 |
|
| 271 |
#### Max links |
| 272 |
|
| 273 |
The `backend_max_links` can be set to limit the number of processes |
| 274 |
that ninja will use to link. |