| 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/). |