Debian Codegraph @

subprojects/meson-docs/docs/markdown/Build-options.md

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