Release 0.58.0.

Author: jpakkane

Diff for: docs/markdown/Release-notes-for-0.58.0.md

@@ -0,0 +1,357 @@
+---
+title: Release 0.58.0
+short-description: Release notes for 0.58.0
+...
+
+# New features
+
+## New `meson.global_build_root()` and `meson.global_source_root()` methods
+
+Returns the root source and build directory of the main project.
+
+Those are direct replacement for `meson.build_root()` and `meson.source_root()`
+that have been deprecated since 0.56.0. In some rare occasions they could not be
+replaced by `meson.project_source_root()` or `meson.current_source_dir()`, in
+which case the new methods can now be used instead. Old methods are still
+deprecated because their names are not explicit enough and created many issues
+when a project is being used as a subproject.
+
+## Developer environment
+
+New method `meson.add_devenv()` adds an [`environment()`](#environment) object
+to the list of environments that will be applied when using `meson devenv`
+command line. This is useful for developpers who wish to use the project without
+installing it, it is often needed to set for example the path to plugins
+directory, etc. Alternatively, a list or dictionary can be passed as first
+argument.
+
+``` meson
+devenv = environment()
+devenv.set('PLUGINS_PATH', meson.current_build_dir())
+...
+meson.add_devenv(devenv)
+```
+
+New command line has been added: `meson devenv -C builddir [<command>]`.
+It runs a command, or open interactive shell if no command is provided, with
+environment setup to run project from the build directory, without installation.
+
+These variables are set in environment in addition to those set using `meson.add_devenv()`:
+- `MESON_DEVENV` is defined to `'1'`.
+- `MESON_PROJECT_NAME` is defined to the main project's name.
+- `PKG_CONFIG_PATH` includes the directory where Meson generates `-uninstalled.pc`
+  files.
+- `PATH` includes every directory where there is an executable that would be
+  installed into `bindir`. On windows it also includes every directory where there
+  is a DLL needed to run those executables.
+- `LD_LIBRARY_PATH` includes every directory where there is a shared library that
+  would be installed into `libdir`. This allows to run system application using
+  custom build of some libraries. For example running system GEdit when building
+  GTK from git. On OSX the environment variable is `DYLD_LIBRARY_PATH` and
+  `PATH` on Windows.
+- `GI_TYPELIB_PATH` includes every directory where a GObject Introspection
+  typelib is built. This is automatically set when using `gnome.generate_gir()`.
+
+## `-pipe` no longer used by default
+
+Meson used to add the `-pipe` command line argument to all compilers
+that supported it, but no longer does. If you need this, then you can
+add it manually. However note that you should not do this unless you
+have actually measured that it provides performance improvements. In
+our tests we could not find a case where adding `-pipe` made
+compilation faster and using `-pipe` [can cause sporadic build
+failures in certain
+cases](https://github.com/mesonbuild/meson/issues/8508).
+
+## `meson.add_dist_script()` allowd in subprojects
+
+`meson.add_dist_script()` can now be invoked from a subproject, it was a hard
+error in earlier versions. Subproject dist scripts will only be executed
+when running `meson dist --include-subprojects`. `MESON_PROJECT_SOURCE_ROOT`,
+`MESON_PROJECT_BUILD_ROOT` and `MESON_PROJECT_DIST_ROOT` environment variables
+are set when dist scripts are run. They are identical to `MESON_SOURCE_ROOT`,
+`MESON_BUILD_ROOT` and `MESON_DIST_ROOT` for main project scripts, but for
+subproject scripts they have the path to the root of the subproject appended,
+usually `subprojects/<subproject-name>`.
+
+Note that existing dist scripts likely need to be modified to use those new
+environment variables instead of `MESON_DIST_ROOT` to work properly when used
+from a subproject.
+
+## Do not add custom target dir to header path if `implicit_include_directories` is `false`
+
+If you do the following:
+
+```meson
+# in some subdirectory
+gen_h = custom_target(...)
+# in some other directory
+executable('foo', 'foo.c', gen_h)
+```
+
+then the output directory of the custom target is automatically added
+to the header search path. This is convenient, but sometimes it can
+lead to problems. Starting with this version, the directory will no
+longer be put in the search path if the target has
+`implicit_include_directories: false`. In these cases you need to set
+up the path manually with `include_directories`.
+
+## Multiple append() and prepend() in `environment()` object
+
+`append()` and `prepend()` methods can now be called multiple times
+on the same `varname`. Earlier Meson versions would warn and only the last
+opperation was taking effect.
+
+```meson
+env = environment()
+
+# MY_PATH will be '0:1:2:3'
+env.set('MY_PATH', '1')
+env.append('MY_PATH', '2')
+env.append('MY_PATH', '3')
+env.prepend('MY_PATH', '0')
+```
+
+
+## `dep.get_variable(varname)`
+
+`dep.get_variable()` now has `varname` as first positional argument.
+It is used as default value for `cmake`, `pkgconfig`, `configtool` and `internal`
+keyword arguments. It is useful in the common case where `pkgconfig` and `internal`
+use the same variable name, in which case it's easier to write `dep.get_variable('foo')`
+instead of `dep.get_variable(pkgconfig: 'foo', internal: 'foo')`.
+
+
+## clang-format include and ignore lists
+
+When clang-format is installed and a `.clang-format` file is found at the main
+project's root source directory, Meson automatically adds a `clang-format` target
+that reformat all C and C++ files.
+
+It is now possible to restrict files to be reformatted with optional
+`.clang-format-include` and `.clang-format-ignore` files.
+
+The file `.clang-format-include` contains a list of patterns matching the files
+that will be reformatted. The `**` pattern matches this directory and all
+subdirectories recursively. Empty lines and lines starting with `#` are ignored.
+If `.clang-format-include` is not found, the pattern defaults to `**/*` which
+means all files recursively in the source directory but has the disadvantage to
+walk the whole source tree which could be slow in the case it contains lots of
+files.
+
+Example of `.clang-format-include` file:
+```
+# All files in src/ and its subdirectories
+src/**/*
+
+# All files in include/ but not its subdirectories
+include/*
+```
+
+The file `.clang-format-ignore` contains a list of patterns matching the files
+that will be excluded. Files matching the include list (see above) that match
+one of the ignore pattern will not be reformatted. Unlike include patters, ignore
+patterns does not support `**` and a single `*` match any characters including
+path separators. Empty lines and lines starting with `#` are ignored.
+
+The build directory and file without a well known C or C++ suffix are always
+ignored.
+
+Example of `.clang-format-ignore` file:
+```
+# Skip C++ files in src/ directory
+src/*.cpp
+```
+
+A new target `clang-format-check` has been added. It returns an error code if
+any file needs to be reformatted. This is intended to be used by CI.
+
+## Introducing format strings to the Meson language
+
+In addition to the conventional `'A string @0@ to be formatted @1@'.format(n, m)`
+method of formatting strings in the Meson language, there's now the additional
+`f'A string @n@ to be formatted @m@'` notation that provides a non-positional
+and clearer alternative. Meson's format strings are currently restricted to
+identity-expressions, meaning `f'format @'m' + 'e'@'` will not parse.
+
+## Skip subprojects installation
+
+It is now possible to skip installation of some or all subprojects. This is
+useful when subprojects are internal dependencies static linked into the main
+project.
+
+By default all subprojects are still installed.
+- `meson install -C builddir --skip-subprojects` installs only the main project.
+- `meson install -C builddir --skip-subprojects foo,bar` installs the main project
+  and all subprojects except for subprojects `foo` and `bar` if they are used.
+
+## String `.replace()`
+
+String objects now have a method called replace for replacing all instances of a
+substring in a string with another.
+
+```meson
+s = 'aaabbb'
+s = s.replace('aaa', 'bbb')
+# 's' is now 'bbbbbb'
+```
+
+## `meson.get_cross_property()` has been deprecated
+
+It's a pure subset of `meson.get_external_property`, and works strangely in
+host == build configurations, since it would be more accurately described as
+`get_host_property`.
+
+## New `range()` function
+
+``` meson
+    rangeobject range(stop)
+    rangeobject range(start, stop[, step])
+```
+
+Return an opaque object that can be only be used in `foreach` statements.
+- `start` must be integer greater or equal to 0. Defaults to 0.
+- `stop` must be integer greater or equal to `start`.
+- `step` must be integer greater or equal to 1. Defaults to 1.
+
+It cause the `foreach` loop to be called with the value from `start` included
+to `stop` excluded with an increment of `step` after each loop.
+
+```meson
+# Loop 15 times with i from 0 to 14 included.
+foreach i : range(15)
+   ...
+endforeach
+```
+
+The range object can also be assigned to a variable and indexed.
+```meson
+r = range(5, 10, 2)
+assert(r[2] == 9)
+```
+
+
+## Xcode improvements
+
+The Xcode backend has been much improved and should now we usable
+enough for day to day development.
+
+## Use fallback from wrap file when force fallback
+
+Optional dependency like below will now fallback to the subproject
+defined in the wrap file in the case `wrap_mode` is set to `forcefallback`
+or `force_fallback_for` contains the subproject.
+
+```meson
+# required is false because we could fallback to cc.find_library(), but in the
+# forcefallback case this now configure the subproject.
+dep = dependency('foo-1.0', required: false)
+if not dep.found()
+  dep = cc.find_library('foo', has_headers: 'foo.h')
+endif
+```
+
+```ini
+[wrap-file]
+...
+[provide]
+dependency_names = foo-1.0
+```
+
+## `error()` with multiple arguments
+
+Just like `warning()` and `message()`, `error()` can now take more than one
+argument that will be separated by space.
+
+## Specify man page locale during installation
+
+Locale directories can now be passed to `install_man`:
+    
+```meson
+# instead of
+# install_data('foo.fr.1', install_dir: join_paths(get_option('mandir'), 'fr', 'man1'), rename: 'foo.1')`
+install_man('foo.fr.1', locale: 'fr')
+```
+
+## Passing `custom_target()` output to `pkg.generate()`
+
+It is now allowed to pass libraries generated by a `custom_target()` to
+pkg-config file generator. The output filename must have a known library extension
+such as `.a`, `.so`, etc.
+
+## JDK System Dependency
+
+When building projects such as those interacting with the JNI, you need access
+to a few header files located in a Java installation. This system dependency
+will add the correct include paths to your target. It assumes that either
+`JAVA_HOME` will be set to a valid Java installation, or the default `javac` on
+your system is a located in the `bin` directory of a Java installation. Note:
+symlinks are resolved.
+
+```meson
+jdk = dependency('jdk', version : '>=1.8')
+```
+
+Currently this system dependency only works on `linux`, `win32`, and `darwin`.
+This can easily be extended given the correct information about your compiler
+and platform in an issue.
+
+## `meson subprojects update --reset` now re-extract tarballs
+
+When using `--reset` option, the source tree of `[wrap-file]` subprojects is now
+deleted and re-extracted from cached tarballs, or re-downloaded. This is because
+Meson has no way to know if the source tree or the wrap file has been modified,
+and `--reset` should guarantee that latest code is being used on next reconfigure.
+
+Use `--reset` with caution if you do local changes on non-git subprojects.
+
+## Allow using generator with CustomTaget or Index of CustomTarget.
+
+Calling `generator.process()` with either a CustomTaget or Index of CustomTarget
+as files is now permitted.
+
+## Qt Dependency uses a Factory
+
+This separates the Pkg-config and QMake based discovery methods into two
+distinct classes in the backend. This allows using
+`dependency.get_variable()` and `dependency.get_pkg_config_variable()`, as
+well as being a cleaner implementation.
+
+## Purge subprojects folder
+
+It is now possible to purge a subprojects folder of artifacts created
+from wrap-based subprojects including anything in `packagecache`. This is useful
+when you want to return to a completely clean source tree or busting caches with
+stale patch directories or caches. By default the command will only print out
+what it is removing. You need to pass `--confirm` to the command for actual
+artifacts to be purged.
+
+By default all wrap-based subprojects will be purged.
+
+- `meson subprojects purge` prints non-cache wrap artifacts which will be
+purged.
+- `meson subprojects purge --confirm` purges non-cache wrap artifacts.
+- `meson subprojects purge --confirm --include-cache` also removes the cache
+artifacts.
+- `meson subprojects purge --confirm subproj1 subproj2` removes non-cache wrap
+artifacts associated with the listed subprojects.
+
+## Check if native or cross-file properties exist
+
+It is now possible to check whether a native property or a cross-file property
+exists with `meson.has_external_property('foo')`. This is useful if the
+property in question is a boolean and one wants to distinguish between
+"set" and "not provided" which can't be done the usual way by passing a
+fallback parameter to `meson.get_external_property()` in this particular case.
+
+## `summary()` accepts features
+
+Build feature options can be passed to `summary()` as the value to be printed.
+
+## Address sanitizer support for Visual Studio
+
+The `b_sanitize` option for enabling Address sanitizer now works with
+the Visual Studio compilers. This requires [a sufficiently new version
+of Visual
+Studio](https://devblogs.microsoft.com/cppblog/address-sanitizer-for-msvc-now-generally-available/).
+