Debian Codegraph @

subprojects/meson-docs/docs/markdown/Release-notes-for-0.58.0.md

raw
1 ---
2 title: Release 0.58.0
3 short-description: Release notes for 0.58.0
4 ...
5
6 # New features
7
8 ## New `meson.global_build_root()` and `meson.global_source_root()` methods
9
10 Returns the root source and build directory of the main project.
11
12 Those are direct replacement for `meson.build_root()` and `meson.source_root()`
13 that have been deprecated since 0.56.0. In some rare occasions they could not be
14 replaced by `meson.project_source_root()` or `meson.current_source_dir()`, in
15 which case the new methods can now be used instead. Old methods are still
16 deprecated because their names are not explicit enough and created many issues
17 when a project is being used as a subproject.
18
19 ## Developer environment
20
21 New method `meson.add_devenv()` adds an [`environment()`](#environment) object
22 to the list of environments that will be applied when using `meson devenv`
23 command line. This is useful for developers who wish to use the project without
24 installing it, it is often needed to set for example the path to plugins
25 directory, etc. Alternatively, a list or dictionary can be passed as first
26 argument.
27
28 ``` meson
29 devenv = environment()
30 devenv.set('PLUGINS_PATH', meson.current_build_dir())
31 ...
32 meson.add_devenv(devenv)
33 ```
34
35 New command line has been added: `meson devenv -C builddir [<command>]`.
36 It runs a command, or open interactive shell if no command is provided, with
37 environment setup to run project from the build directory, without installation.
38
39 These variables are set in environment in addition to those set using `meson.add_devenv()`:
40 - `MESON_DEVENV` is defined to `'1'`.
41 - `MESON_PROJECT_NAME` is defined to the main project's name.
42 - `PKG_CONFIG_PATH` includes the directory where Meson generates `-uninstalled.pc`
43 files.
44 - `PATH` includes every directory where there is an executable that would be
45 installed into `bindir`. On windows it also includes every directory where there
46 is a DLL needed to run those executables.
47 - `LD_LIBRARY_PATH` includes every directory where there is a shared library that
48 would be installed into `libdir`. This allows to run system application using
49 custom build of some libraries. For example running system GEdit when building
50 GTK from git. On OSX the environment variable is `DYLD_LIBRARY_PATH` and
51 `PATH` on Windows.
52 - `GI_TYPELIB_PATH` includes every directory where a GObject Introspection
53 typelib is built. This is automatically set when using `gnome.generate_gir()`.
54
55 ## `-pipe` no longer used by default
56
57 Meson used to add the `-pipe` command line argument to all compilers
58 that supported it, but no longer does. If you need this, then you can
59 add it manually. However note that you should not do this unless you
60 have actually measured that it provides performance improvements. In
61 our tests we could not find a case where adding `-pipe` made
62 compilation faster and using `-pipe` [can cause sporadic build
63 failures in certain
64 cases](https://github.com/mesonbuild/meson/issues/8508).
65
66 ## `meson.add_dist_script()` allowed in subprojects
67
68 `meson.add_dist_script()` can now be invoked from a subproject, it was a hard
69 error in earlier versions. Subproject dist scripts will only be executed
70 when running `meson dist --include-subprojects`. `MESON_PROJECT_SOURCE_ROOT`,
71 `MESON_PROJECT_BUILD_ROOT` and `MESON_PROJECT_DIST_ROOT` environment variables
72 are set when dist scripts are run. They are identical to `MESON_SOURCE_ROOT`,
73 `MESON_BUILD_ROOT` and `MESON_DIST_ROOT` for main project scripts, but for
74 subproject scripts they have the path to the root of the subproject appended,
75 usually `subprojects/<subproject-name>`.
76
77 Note that existing dist scripts likely need to be modified to use those new
78 environment variables instead of `MESON_DIST_ROOT` to work properly when used
79 from a subproject.
80
81 ## Do not add custom target dir to header path if `implicit_include_directories` is `false`
82
83 If you do the following:
84
85 ```meson
86 # in some subdirectory
87 gen_h = custom_target(...)
88 # in some other directory
89 executable('foo', 'foo.c', gen_h)
90 ```
91
92 then the output directory of the custom target is automatically added
93 to the header search path. This is convenient, but sometimes it can
94 lead to problems. Starting with this version, the directory will no
95 longer be put in the search path if the target has
96 `implicit_include_directories: false`. In these cases you need to set
97 up the path manually with `include_directories`.
98
99 ## Multiple append() and prepend() in `environment()` object
100
101 `append()` and `prepend()` methods can now be called multiple times
102 on the same `varname`. Earlier Meson versions would warn and only the last
103 operation was taking effect.
104
105 ```meson
106 env = environment()
107
108 # MY_PATH will be '0:1:2:3'
109 env.set('MY_PATH', '1')
110 env.append('MY_PATH', '2')
111 env.append('MY_PATH', '3')
112 env.prepend('MY_PATH', '0')
113 ```
114
115
116 ## `dep.get_variable(varname)`
117
118 `dep.get_variable()` now has `varname` as first positional argument.
119 It is used as default value for `cmake`, `pkgconfig`, `configtool` and `internal`
120 keyword arguments. It is useful in the common case where `pkgconfig` and `internal`
121 use the same variable name, in which case it's easier to write `dep.get_variable('foo')`
122 instead of `dep.get_variable(pkgconfig: 'foo', internal: 'foo')`.
123
124
125 ## clang-format include and ignore lists
126
127 When clang-format is installed and a `.clang-format` file is found at the main
128 project's root source directory, Meson automatically adds a `clang-format` target
129 that reformat all C and C++ files.
130
131 It is now possible to restrict files to be reformatted with optional
132 `.clang-format-include` and `.clang-format-ignore` files.
133
134 The file `.clang-format-include` contains a list of patterns matching the files
135 that will be reformatted. The `**` pattern matches this directory and all
136 subdirectories recursively. Empty lines and lines starting with `#` are ignored.
137 If `.clang-format-include` is not found, the pattern defaults to `**/*` which
138 means all files recursively in the source directory but has the disadvantage to
139 walk the whole source tree which could be slow in the case it contains lots of
140 files.
141
142 Example of `.clang-format-include` file:
143 ```
144 # All files in src/ and its subdirectories
145 src/**/*
146
147 # All files in include/ but not its subdirectories
148 include/*
149 ```
150
151 The file `.clang-format-ignore` contains a list of patterns matching the files
152 that will be excluded. Files matching the include list (see above) that match
153 one of the ignore pattern will not be reformatted. Unlike include patterns, ignore
154 patterns does not support `**` and a single `*` match any characters including
155 path separators. Empty lines and lines starting with `#` are ignored.
156
157 The build directory and file without a well known C or C++ suffix are always
158 ignored.
159
160 Example of `.clang-format-ignore` file:
161 ```
162 # Skip C++ files in src/ directory
163 src/*.cpp
164 ```
165
166 A new target `clang-format-check` has been added. It returns an error code if
167 any file needs to be reformatted. This is intended to be used by CI.
168
169 ## Introducing format strings to the Meson language
170
171 In addition to the conventional `'A string @0@ to be formatted @1@'.format(n, m)`
172 method of formatting strings in the Meson language, there's now the additional
173 `f'A string @n@ to be formatted @m@'` notation that provides a non-positional
174 and clearer alternative. Meson's format strings are currently restricted to
175 identity-expressions, meaning `f'format @'m' + 'e'@'` will not parse.
176
177 ## Skip subprojects installation
178
179 It is now possible to skip installation of some or all subprojects. This is
180 useful when subprojects are internal dependencies static linked into the main
181 project.
182
183 By default all subprojects are still installed.
184 - `meson install -C builddir --skip-subprojects` installs only the main project.
185 - `meson install -C builddir --skip-subprojects foo,bar` installs the main project
186 and all subprojects except for subprojects `foo` and `bar` if they are used.
187
188 ## String `.replace()`
189
190 String objects now have a method called replace for replacing all instances of a
191 substring in a string with another.
192
193 ```meson
194 s = 'aaabbb'
195 s = s.replace('aaa', 'bbb')
196 # 's' is now 'bbbbbb'
197 ```
198
199 ## `meson.get_cross_property()` has been deprecated
200
201 It's a pure subset of `meson.get_external_property`, and works strangely in
202 host == build configurations, since it would be more accurately described as
203 `get_host_property`.
204
205 ## New `range()` function
206
207 ``` meson
208 rangeobject range(stop)
209 rangeobject range(start, stop[, step])
210 ```
211
212 Return an opaque object that can be only be used in `foreach` statements.
213 - `start` must be integer greater or equal to 0. Defaults to 0.
214 - `stop` must be integer greater or equal to `start`.
215 - `step` must be integer greater or equal to 1. Defaults to 1.
216
217 It cause the `foreach` loop to be called with the value from `start` included
218 to `stop` excluded with an increment of `step` after each loop.
219
220 ```meson
221 # Loop 15 times with i from 0 to 14 included.
222 foreach i : range(15)
223 ...
224 endforeach
225 ```
226
227 The range object can also be assigned to a variable and indexed.
228 ```meson
229 r = range(5, 10, 2)
230 assert(r[2] == 9)
231 ```
232
233
234 ## Xcode improvements
235
236 The Xcode backend has been much improved and should now we usable
237 enough for day to day development.
238
239 ## Use fallback from wrap file when force fallback
240
241 Optional dependency like below will now fallback to the subproject
242 defined in the wrap file in the case `wrap_mode` is set to `forcefallback`
243 or `force_fallback_for` contains the subproject.
244
245 ```meson
246 # required is false because we could fallback to cc.find_library(), but in the
247 # forcefallback case this now configure the subproject.
248 dep = dependency('foo-1.0', required: false)
249 if not dep.found()
250 dep = cc.find_library('foo', has_headers: 'foo.h')
251 endif
252 ```
253
254 ```ini
255 [wrap-file]
256 ...
257 [provide]
258 dependency_names = foo-1.0
259 ```
260
261 ## `error()` with multiple arguments
262
263 Just like `warning()` and `message()`, `error()` can now take more than one
264 argument that will be separated by space.
265
266 ## Specify man page locale during installation
267
268 Locale directories can now be passed to `install_man`:
269
270 ```meson
271 # instead of
272 # install_data('foo.fr.1', install_dir: join_paths(get_option('mandir'), 'fr', 'man1'), rename: 'foo.1')`
273 install_man('foo.fr.1', locale: 'fr')
274 ```
275
276 ## Passing `custom_target()` output to `pkg.generate()`
277
278 It is now allowed to pass libraries generated by a `custom_target()` to
279 pkg-config file generator. The output filename must have a known library extension
280 such as `.a`, `.so`, etc.
281
282 ## JNI System Dependency
283
284 When building projects such as those interacting with the JNI, you need access
285 to a few header files located in a Java installation. This system dependency
286 will add the correct include paths to your target. It assumes that either
287 `JAVA_HOME` will be set to a valid Java installation, or the default `javac` on
288 your system is a located in the `bin` directory of a Java installation. Note:
289 symlinks are resolved.
290
291 ```meson
292 jni_dep = dependency('jni', version : '>=1.8')
293 ```
294
295 Currently this system dependency only works on `linux`, `win32`, and `darwin`.
296 This can easily be extended given the correct information about your compiler
297 and platform in an issue.
298
299 ## `meson subprojects update --reset` now re-extract tarballs
300
301 When using `--reset` option, the source tree of `[wrap-file]` subprojects is now
302 deleted and re-extracted from cached tarballs, or re-downloaded. This is because
303 Meson has no way to know if the source tree or the wrap file has been modified,
304 and `--reset` should guarantee that latest code is being used on next reconfigure.
305
306 Use `--reset` with caution if you do local changes on non-git subprojects.
307
308 ## Allow using generator with CustomTarget or Index of CustomTarget.
309
310 Calling `generator.process()` with either a CustomTarget or Index of CustomTarget
311 as files is now permitted.
312
313 ## Qt Dependency uses a Factory
314
315 This separates the Pkg-config and QMake based discovery methods into two
316 distinct classes in the backend. This allows using
317 `dependency.get_variable()` and `dependency.get_pkg_config_variable()`, as
318 well as being a cleaner implementation.
319
320 ## Purge subprojects folder
321
322 It is now possible to purge a subprojects folder of artifacts created
323 from wrap-based subprojects including anything in `packagecache`. This is useful
324 when you want to return to a completely clean source tree or busting caches with
325 stale patch directories or caches. By default the command will only print out
326 what it is removing. You need to pass `--confirm` to the command for actual
327 artifacts to be purged.
328
329 By default all wrap-based subprojects will be purged.
330
331 - `meson subprojects purge` prints non-cache wrap artifacts which will be
332 purged.
333 - `meson subprojects purge --confirm` purges non-cache wrap artifacts.
334 - `meson subprojects purge --confirm --include-cache` also removes the cache
335 artifacts.
336 - `meson subprojects purge --confirm subproj1 subproj2` removes non-cache wrap
337 artifacts associated with the listed subprojects.
338
339 ## Check if native or cross-file properties exist
340
341 It is now possible to check whether a native property or a cross-file property
342 exists with `meson.has_external_property('foo')`. This is useful if the
343 property in question is a boolean and one wants to distinguish between
344 "set" and "not provided" which can't be done the usual way by passing a
345 fallback parameter to `meson.get_external_property()` in this particular case.
346
347 ## `summary()` accepts features
348
349 Build feature options can be passed to `summary()` as the value to be printed.
350
351 ## Address sanitizer support for Visual Studio
352
353 The `b_sanitize` option for enabling Address sanitizer now works with
354 the Visual Studio compilers. This requires [a sufficiently new version
355 of Visual
356 Studio](https://devblogs.microsoft.com/cppblog/address-sanitizer-for-msvc-now-generally-available/).