From c47c7105cc8ad2a9a2b6587de05156ebcbc59484 Mon Sep 17 00:00:00 2001 From: Nirbheek Chauhan Date: Tue, 3 Jul 2018 01:51:24 +0530 Subject: [PATCH] 0.47 release notes: Fix syntax, rephrase confusing sections [skip ci] --- docs/markdown/Release-notes-for-0.47.0.md | 118 ++++++++++++---------- 1 file changed, 62 insertions(+), 56 deletions(-) diff --git a/docs/markdown/Release-notes-for-0.47.0.md b/docs/markdown/Release-notes-for-0.47.0.md index 0ca119ec7..fb36e961f 100644 --- a/docs/markdown/Release-notes-for-0.47.0.md +++ b/docs/markdown/Release-notes-for-0.47.0.md @@ -1,6 +1,6 @@ --- title: Release 0.47 -short-description: Release notes for 0.47 (preliminary) +short-description: Release notes for 0.47 ... # New features @@ -12,7 +12,7 @@ the point of invocation. All previously invoked build targets and commands are build/executed. All following ones are ignored. If the current script was invoked via `subdir()` the parent script continues normally. -## Concatenate string literals returned from get_define +## Concatenate string literals returned from `get_define()` After obtaining the value of a preprocessor symbol consecutive string literals are merged into a single string literal. @@ -25,13 +25,13 @@ version 6 - ARMCLANG. The required ARMCLANG compiler options for building a shareable library are not included in the current Meson implementation for ARMCLANG support, so it can not build shareable libraries. This current Meson implementation for ARMCLANG support can -not build assembly files with arm syntax(we need to use armasm instead -of ARMCLANG for the .s files with this syntax) and only supports gnu +not build assembly files with arm syntax (we need to use armasm instead +of ARMCLANG for the `.s` files with this syntax) and only supports GNU syntax. -The default extension of the executable output is .axf. +The default extension of the executable output is `.axf`. The environment path should be set properly for the ARM compiler executables. -The '--target', '-mcpu' options with the appropriate values should be mentioned +The `--target`, `-mcpu` options with the appropriate values should be mentioned in the cross file as shown in the snippet below. ``` @@ -45,7 +45,7 @@ Note: - The current changes are tested on Windows only. - PIC support is not enabled by default for ARM, if users want to use it, they need to add the required arguments - explicitly from cross-file(c_args/c++_args) or some other way. + explicitly from cross-file(`c_args`/`cpp_args`) or some other way. ## New base build option for LLVM (Apple) bitcode support @@ -63,7 +63,7 @@ Since this requires support in the linker, it is currently only enabled when using Apple ld. In the future it can be extended to clang on other platforms too. -## New compiler check: check_header() +## New compiler check: `check_header()` The existing compiler check `has_header()` only checks if the header exists, either with the `__has_include` C++11 builtin, or by running the pre-processor. @@ -76,31 +76,31 @@ run a full compile. Note that `has_header()` is much faster than `check_header()`, so it should be used whenever possible. -## New action 'copy' for configure_file() +## New action `copy:` for `configure_file()` -In addition to `configuration:` and `command:`, +In addition to the existing actions `configuration:` and `command:`, [`configure_file()`](#Reference-manual.md#configure_file) now accepts a keyword -argument `copy:` which specifies a new action: copying the file specified with +argument `copy:` which specifies a new action to copy the file specified with the `input:` keyword argument to a file in the build directory with the name specified with the `output:` keyword argument. These three keyword arguments are, as before, mutually exclusive. You can only do one action at a time. -## New encoding keyword for configure_file +## New keyword argument `encoding:` for `configure_file()` Add a new keyword to [`configure_file()`](#Reference-manual.md#configure_file) -that allows the developer to specify the input and output file encoding. +that allows the developer to specify the input and output file encoding. The +default value is the same as before: UTF-8. -If the file encoding of the input is not UTF-8 meson can crash (see #1542). -A crash as with UTF-16 is the best case and the worst meson will silently -corrupt the output file for example with ISO-2022-JP. For additional details -see pull request #3135. +In the past, Meson would not handle non-UTF-8/ASCII files correctly, and in the +worst case would try to coerce it to UTF-8 and mangle the data. UTF-8 is the +standard encoding now, but sometimes it is necessary to process files that use +a different encoding. -The new keyword defaults to UTF-8 and the documentation strongly suggest to -convert the file to UTF-8 when possible. +For additional details see [#3135](https://github.com/mesonbuild/meson/pull/3135). -## New keyword argument `output_format` for configure_file() +## New keyword argument `output_format:` for `configure_file()` When called without an input file, `configure_file` generates a C header file by default. A keyword argument was added to allow @@ -115,12 +115,12 @@ configure_file('config.asm', output_format: 'nasm') ``` -## Substitutions in `custom_target(depends:)` +## Substitutions in `custom_target(depfile:)` The `depfile` keyword argument to `custom_target` now accepts the `@BASENAME@` and `@PLAINNAME@` substitutions. -## Deprecate `build_always` +## Deprecated `build_always:` for custom targets Setting `build_always` to `true` for a custom target not only marks the target to be always considered out of date, but also adds it to the set of default @@ -133,7 +133,7 @@ be achieved by combining `build_always_stale` with `build_by_default`. The documentation has been updated accordingly. -## New built-in object dictionary +## New built-in object type: dictionary Meson dictionaries use a syntax similar to python's dictionaries, but have a narrower scope: they are immutable, keys can only @@ -143,23 +143,23 @@ keys causes a fatal error. Example usage: ```meson -dict = {'foo': 42, 'bar': 'baz'} +d = {'foo': 42, 'bar': 'baz'} -foo = dict.get('foo') -foobar = dict.get('foobar', 'fallback-value') +foo = d.get('foo') +foobar = d.get('foobar', 'fallback-value') -foreach key, value : dict +foreach key, value : d Do something with key and value endforeach ``` -## Array options treat -Dopt= and -Dopt=[] as equivalent +## Array options treat `-Dopt=` and `-Dopt=[]` as equivalent Prior to this change passing -Dopt= to an array opt would be interpreted as -[''] (an array with an empty string), now -Dopt= is the same as -Dopt=[], an +`['']` (an array with an empty string), now `-Dopt=` is the same as `-Dopt=[]`, an empty list. -## Feature detection based on meson_version in project() +## Feature detection based on `meson_version:` in `project()` Meson will now print a `WARNING:` message during configuration if you use a function or a keyword argument that was added in a meson version that's newer @@ -192,18 +192,19 @@ WARNING: Project specifies a minimum meson_version '>=0.43' which conflicts with * 0.44.0: {'configuration_data.get_unquoted()'} ``` -## New feature option type +## New type of build option for features -A new type of option can be defined in `meson_options.txt` for the traditional -`enabled / disabled / auto` tristate. The value of this option can be passed to -the `required` keyword argument of functions `dependency()`, `find_library()`, -`find_program()` and `add_languages()`. +A new type of [option called `feature`](Build-options.md#features) can be +defined in `meson_options.txt` for the traditional `enabled / disabled / auto` +tristate. The value of this option can be passed to the `required` keyword +argument of functions `dependency()`, `find_library()`, `find_program()` and +`add_languages()`. A new global option `auto_features` has been added to override the value of all `auto` features. It is intended to be used by packagers to have full control on which feature must be enabled or disabled. -## New options to gnome.gdbus_codegen +## New options to `gnome.gdbus_codegen()` You can now pass additional arguments to gdbus-codegen using the `extra_args` keyword. This is the same for the other gnome function calls. @@ -213,12 +214,14 @@ can be modified by setting the autocleanup keyword. For example: - sources += gnome.gdbus_codegen('com.mesonbuild.Test', - 'com.mesonbuild.Test.xml', - autocleanup : 'none', - extra_args : ['--pragma-once']) +```meson +sources += gnome.gdbus_codegen('com.mesonbuild.Test', + 'com.mesonbuild.Test.xml', + autocleanup : 'none', + extra_args : ['--pragma-once']) +``` -## Made install a top level Meson command +## Made 'install' a top level Meson command You can now run `meson install` in your build directory and it will do the install. It has several command line options you can toggle the @@ -228,34 +231,38 @@ is similar to how `meson test` already works. For example, to install only the files that have changed, you can do: ```console -meson install --only-changed +$ meson install --only-changed ``` -## install_mode argument extended to all installable targets +## `install_mode:` keyword argument extended to all installable targets -It is now possible to pass an install_mode argument to all installable targets, -such as executable(), libraries, headers, man pages and custom/generated +It is now possible to pass an `install_mode` argument to all installable targets, +such as `executable()`, libraries, headers, man pages and custom/generated targets. -The install_mode argument can be used to specify the file mode in symbolic +The `install_mode` argument can be used to specify the file mode in symbolic format and optionally the owner/uid and group/gid for the installed files. -## New built-in option install_umask with a default value 022 +## New built-in option `install_umask` with a default value 022 This umask is used to define the default permissions of files and directories created in the install tree. Files will preserve their executable mode, but the -exact permissions will obey the install_umask. +exact permissions will obey the `install_umask`. -The install_umask can be overridden in the meson command-line: +The `install_umask` can be overridden in the meson command-line: - $ meson --install-umask=027 builddir/ +```console +$ meson --install-umask=027 builddir/ +``` -A project can also override the default in the project() call: +A project can also override the default in the `project()` call: - project('myproject', 'c', - default_options : ['install_umask=027']) +```meson +project('myproject', 'c', + default_options : ['install_umask=027']) +``` -To disable the install_umask, set it to 'preserve', in which case permissions +To disable the `install_umask`, set it to `preserve`, in which case permissions are copied from the files in their origin. ## Octal and binary string literals @@ -267,8 +274,7 @@ int_493 = 0o755 int_1365 = 0b10101010101 ``` - -## New keyword arguments: 'check' and 'capture' for run_command() +## New keyword arguments: 'check' and 'capture' for `run_command()` If `check:` is `true`, then the configuration will fail if the command returns a non-zero exit status. The default value is `false` for compatibility reasons.