diff options
100 files changed, 3563 insertions, 2649 deletions
diff --git a/docs/markdown/Adding-arguments.md b/docs/markdown/Adding-arguments.md index 8dd8488..adbc23e 100644 --- a/docs/markdown/Adding-arguments.md +++ b/docs/markdown/Adding-arguments.md @@ -62,7 +62,8 @@ executable('prog', 'prog.cc', cpp_args : '-DCPPTHING') Here we create a C++ executable with an extra argument that is used during compilation but not for linking. -You can find the parameter name for other languages in the [reference tables](Reference-tables.md). +You can find the parameter name for other languages in the [reference +tables](Reference-tables.md). Specifying extra linker arguments is done in the same way: diff --git a/docs/markdown/Build-options.md b/docs/markdown/Build-options.md index 429b9b2..4a0b178 100644 --- a/docs/markdown/Build-options.md +++ b/docs/markdown/Build-options.md @@ -66,16 +66,16 @@ empty. The `value` parameter specifies the default value of the option and if it is unset then the values of `choices` will be used as the default. -As of 0.47.0 -Dopt= and -Dopt=[] both pass an empty list, before this -Dopt= -would pass a list with an empty string. +As of 0.47.0 -Dopt= and -Dopt=[] both pass an empty list, before this +-Dopt= would pass a list with an empty string. This type is available since version 0.44.0 ### Features -A `feature` option has three states: `enabled`, `disabled` or `auto`. It is intended -to be passed as value for the `required` keyword argument of most functions. -Currently supported in +A `feature` option has three states: `enabled`, `disabled` or `auto`. +It is intended to be passed as value for the `required` keyword +argument of most functions. Currently supported in [`dependency()`](Reference-manual.md#dependency), [`find_library()`](Reference-manual.md#compiler-object), [`find_program()`](Reference-manual.md#find_program) and @@ -85,10 +85,11 @@ Currently supported in - `auto` is the same as passing `required : false`. - `disabled` do not look for the dependency and always return 'not-found'. -When getting the value of this type of option using `get_option()`, a special -[feature option object](Reference-manual.md#feature-option-object) -is returned instead of the string representation of the option's value. -This object can be passed to `required`: +When getting the value of this type of option using `get_option()`, a +special [feature option +object](Reference-manual.md#feature-option-object) is returned instead +of the string representation of the option's value. This object can be +passed to `required`: ```meson d = dependency('foo', required : get_option('myfeature')) @@ -112,13 +113,14 @@ if get_option('myfeature').enabled() endif ``` -If the value of a `feature` option is set to `auto`, that value is overridden by -the global `auto_features` option (which defaults to `auto`). This is intended -to be used by packagers who want to have full control on which dependencies are -required and which are disabled, and not rely on build-deps being installed -(at the right version) to get a feature enabled. They could set -`auto_features=enabled` to enable all features and disable explicitly only the -few they don't want, if any. +If the value of a `feature` option is set to `auto`, that value is +overridden by the global `auto_features` option (which defaults to +`auto`). This is intended to be used by packagers who want to have +full control on which dependencies are required and which are +disabled, and not rely on build-deps being installed (at the right +version) to get a feature enabled. They could set +`auto_features=enabled` to enable all features and disable explicitly +only the few they don't want, if any. This type is available since version 0.47.0 @@ -200,8 +202,8 @@ option. ## Built-in build options -There are a number of [built-in options][builtin_opts]. To get the current list execute `meson -configure` in the build directory. +There are a number of [built-in options][builtin_opts]. To get the +current list execute `meson configure` in the build directory. [builtin_opts]: https://mesonbuild.com/Builtin-options.html @@ -209,9 +211,10 @@ configure` in the build directory. #### Startup project -The backend\_startup\_project option can be set to define the default project -that will be executed with the "Start debugging F5" action in visual studio. -It should be the same name as an executable target name. +The `backend_startup_project` option can be set to define the default +project that will be executed with the "Start debugging F5" action in +visual studio. It should be the same name as an executable target +name. ```meson project('my_project', 'c', default_options: ['backend_startup_project=my_exe']) @@ -222,5 +225,5 @@ executable('my_exe', ...) #### Max links -The backend\_max\_links can be set to limit the number of processes that ninja -will use to link. +The `backend_max_links` can be set to limit the number of processes +that ninja will use to link. diff --git a/docs/markdown/Builtin-options.md b/docs/markdown/Builtin-options.md index 23995dc..189204f 100644 --- a/docs/markdown/Builtin-options.md +++ b/docs/markdown/Builtin-options.md @@ -11,19 +11,24 @@ universal options, base options, compiler options. ## Universal options A list of these options can be found by running `meson --help`. All -these can be set by passing `-Doption=value` to `meson` (aka `meson setup`), or -by setting them inside `default_options` of `project()` in your `meson.build`. -Some options can also be set by `--option=value`, or `--option value`--- a list -is shown by running `meson setup --help`. +these can be set by passing `-Doption=value` to `meson` (aka `meson +setup`), or by setting them inside `default_options` of `project()` in +your `meson.build`. Some options can also be set by `--option=value`, +or `--option value`--- a list is shown by running `meson setup +--help`. -For legacy reasons `--warnlevel` is the cli argument for the `warning_level` option. +For legacy reasons `--warnlevel` is the cli argument for the +`warning_level` option. -They can also be edited after setup using `meson configure -Doption=value`. +They can also be edited after setup using `meson configure +-Doption=value`. Installation options are all relative to the prefix, except: -* When the prefix is `/usr`: `sysconfdir` defaults to `/etc`, `localstatedir` defaults to `/var`, and `sharedstatedir` defaults to `/var/lib` -* When the prefix is `/usr/local`: `localstatedir` defaults to `/var/local`, and `sharedstatedir` defaults to `/var/local/lib` +* When the prefix is `/usr`: `sysconfdir` defaults to `/etc`, +* `localstatedir` defaults to `/var`, and `sharedstatedir` defaults to +* `/var/lib` When the prefix is `/usr/local`: `localstatedir` defaults +* to `/var/local`, and `sharedstatedir` defaults to `/var/local/lib` ### Directories @@ -44,21 +49,22 @@ Installation options are all relative to the prefix, except: | sysconfdir | etc | Sysconf data directory | -`prefix` defaults to `C:/` on Windows, and `/usr/local` otherwise. You should always -override this value. +`prefix` defaults to `C:/` on Windows, and `/usr/local` otherwise. You +should always override this value. -`libdir` is automatically detected based on your platform, it should be -correct when doing "native" (build machine == host machine) compilation. For -cross compiles meson will try to guess the correct libdir, but it may not be -accurate, especially on Linux where different distributions have different -defaults. Using a [cross file](Cross-compilation.md#defining-the-environment), -particularly the paths section may be necessary. +`libdir` is automatically detected based on your platform, it should +be correct when doing "native" (build machine == host machine) +compilation. For cross compiles meson will try to guess the correct +libdir, but it may not be accurate, especially on Linux where +different distributions have different defaults. Using a [cross +file](Cross-compilation.md#defining-the-environment), particularly the +paths section may be necessary. ### Core options -Options that are labeled "per machine" in the table are set per machine. See -the [specifying options per machine](#specifying-options-per-machine) section -for details. +Options that are labeled "per machine" in the table are set per +machine. See the [specifying options per +machine](#specifying-options-per-machine) section for details. | Option | Default value | Description | Is per machine | Is per subproject | | ------ | ------------- | ----------- | -------------- | ----------------- | @@ -82,13 +88,13 @@ for details. | wrap_mode {default, nofallback,<br>nodownload, forcefallback, nopromote} | default | Wrap mode to use | no | no | | force_fallback_for | [] | Force fallback for those dependencies | no | no | -<a name="build-type-options"></a> -For setting optimization levels and toggling debug, you can either set the -`buildtype` option, or you can set the `optimization` and `debug` options which -give finer control over the same. Whichever you decide to use, the other will -be deduced from it. For example, `-Dbuildtype=debugoptimized` is the same as -`-Ddebug=true -Doptimization=2` and vice-versa. This table documents the -two-way mapping: +<a name="build-type-options"></a> For setting optimization levels and +toggling debug, you can either set the `buildtype` option, or you can +set the `optimization` and `debug` options which give finer control +over the same. Whichever you decide to use, the other will be deduced +from it. For example, `-Dbuildtype=debugoptimized` is the same as +`-Ddebug=true -Doptimization=2` and vice-versa. This table documents +the two-way mapping: | buildtype | debug | optimization | | --------- | ----- | ------------ | @@ -102,15 +108,16 @@ All other combinations of `debug` and `optimization` set `buildtype` to `'custom ## Base options -These are set in the same way as universal options, either by `-Doption=value`, -or by setting them inside `default_options` of `project()` in your `meson.build`. -However, they cannot be shown in the -output of `meson --help` because they depend on both the current platform and -the compiler that will be selected. The only way to see them is to setup -a builddir and then run `meson configure` on it with no options. +These are set in the same way as universal options, either by +`-Doption=value`, or by setting them inside `default_options` of +`project()` in your `meson.build`. However, they cannot be shown in +the output of `meson --help` because they depend on both the current +platform and the compiler that will be selected. The only way to see +them is to setup a builddir and then run `meson configure` on it with +no options. -The following options are available. Note that they may not be available on all -platforms or with all compilers: +The following options are available. Note that they may not be +available on all platforms or with all compilers: | Option | Default value | Possible values | Description | | ----------- | ------------- | --------------- | ----------- | @@ -131,10 +138,11 @@ platforms or with all compilers: The value of `b_sanitize` can be one of: `none`, `address`, `thread`, `undefined`, `memory`, `address,undefined`. -<a name="b_vscrt-from_buildtype"></a> -The default value of `b_vscrt` is `from_buildtype`. The following table is used -internally to pick the CRT compiler arguments for `from_buildtype` or -`static_from_buildtype` *(since 0.56)* based on the value of the `buildtype` option: +<a name="b_vscrt-from_buildtype"></a> The default value of `b_vscrt` +is `from_buildtype`. The following table is used internally to pick +the CRT compiler arguments for `from_buildtype` or +`static_from_buildtype` *(since 0.56)* based on the value of the +`buildtype` option: | buildtype | from_buildtype | static_from_buildtype | | -------- | -------------- | --------------------- | @@ -147,21 +155,22 @@ internally to pick the CRT compiler arguments for `from_buildtype` or ### Notes about Apple Bitcode support `b_bitcode` will pass `-fembed-bitcode` while compiling and will pass -`-Wl,-bitcode_bundle` while linking. These options are incompatible with -`b_asneeded`, so that option will be silently disabled. +`-Wl,-bitcode_bundle` while linking. These options are incompatible +with `b_asneeded`, so that option will be silently disabled. -[Shared modules](Reference-manual.md#shared_module) will not have bitcode -embedded because `-Wl,-bitcode_bundle` is incompatible with both `-bundle` and -`-Wl,-undefined,dynamic_lookup` which are necessary for shared modules to work. +[Shared modules](Reference-manual.md#shared_module) will not have +bitcode embedded because `-Wl,-bitcode_bundle` is incompatible with +both `-bundle` and `-Wl,-undefined,dynamic_lookup` which are necessary +for shared modules to work. ## Compiler options Same caveats as base options above. -The following options are available. They can be set by passing `-Doption=value` -to `meson`. Note that both the options themselves and -the possible values they can take will depend on the target platform or -compiler being used: +The following options are available. They can be set by passing +`-Doption=value` to `meson`. Note that both the options themselves and +the possible values they can take will depend on the target platform +or compiler being used: | Option | Default value | Possible values | Description | | ------ | ------------- | --------------- | ----------- | @@ -180,56 +189,60 @@ compiler being used: | cpp_winlibs | see below | free-form comma-separated list | Standard Windows libs to link against | | fortran_std | none | [none, legacy, f95, f2003, f2008, f2018] | Fortran language standard to use | -The default values of `c_winlibs` and `cpp_winlibs` are in compiler-specific -argument forms, but the libraries are: kernel32, user32, gdi32, winspool, -shell32, ole32, oleaut32, uuid, comdlg32, advapi32. +The default values of `c_winlibs` and `cpp_winlibs` are in +compiler-specific argument forms, but the libraries are: kernel32, +user32, gdi32, winspool, shell32, ole32, oleaut32, uuid, comdlg32, +advapi32. -All these `<lang>_*` options are specified per machine. See below in the -[specifying options per machine](#specifying-options-per-machine) section on -how to do this in cross builds. +All these `<lang>_*` options are specified per machine. See below in +the [specifying options per machine](#specifying-options-per-machine) +section on how to do this in cross builds. -When using MSVC, `cpp_eh=none` will result in no exception flags being passed, -while the `cpp_eh=[value]` will result in `/EH[value]`. -Since *0.51.0* `cpp_eh=default` will result in `/EHsc` on MSVC. When using -gcc-style compilers, nothing is passed (allowing exceptions to work), while -`cpp_eh=none` passes `-fno-exceptions`. +When using MSVC, `cpp_eh=none` will result in no exception flags being +passed, while the `cpp_eh=[value]` will result in `/EH[value]`. Since +*0.51.0* `cpp_eh=default` will result in `/EHsc` on MSVC. When using +gcc-style compilers, nothing is passed (allowing exceptions to work), +while `cpp_eh=none` passes `-fno-exceptions`. -Since *0.54.0* The `<lang>_thread_count` option can be used to control the -value passed to `-s PTHREAD_POOL_SIZE` when using emcc. No other c/c++ -compiler supports this option. +Since *0.54.0* The `<lang>_thread_count` option can be used to control +the value passed to `-s PTHREAD_POOL_SIZE` when using emcc. No other +c/c++ compiler supports this option. ## Specifying options per machine -Since *0.51.0*, some options are specified per machine rather than globally for -all machine configurations. Prefixing the option with `build.` just affects the -build machine configuration, while unprefixed just affects the host machine -configuration, respectively. For example: +Since *0.51.0*, some options are specified per machine rather than +globally for all machine configurations. Prefixing the option with +`build.` just affects the build machine configuration, while +unprefixed just affects the host machine configuration, respectively. +For example: - - `build.pkg_config_path` controls the paths pkg-config will search for just - `native: true` dependencies (build machine). + - `build.pkg_config_path` controls the paths pkg-config will search + for just `native: true` dependencies (build machine). - - `pkg_config_path` controls the paths pkg-config will search for just - `native: false` dependencies (host machine). + - `pkg_config_path` controls the paths pkg-config will search for + just `native: false` dependencies (host machine). -This is useful for cross builds. In the native builds, build = host, and the -unprefixed option alone will suffice. +This is useful for cross builds. In the native builds, build = host, +and the unprefixed option alone will suffice. -Prior to *0.51.0*, these options just effected native builds when specified on -the command line, as there was no `build.` prefix. Similarly named fields in -the `[properties]` section of the cross file would effect cross compilers, but -the code paths were fairly different allowing differences in behavior to crop -out. +Prior to *0.51.0*, these options just effected native builds when +specified on the command line, as there was no `build.` prefix. +Similarly named fields in the `[properties]` section of the cross file +would effect cross compilers, but the code paths were fairly different +allowing differences in behavior to crop out. ## Specifying options per subproject -Since *0.54.0* `default_library` and `werror` built-in options can be defined -per subproject. This is useful for example when building shared libraries in the -main project, but static link a subproject, or when the main project must build -with no warnings but some subprojects cannot. +Since *0.54.0* `default_library` and `werror` built-in options can be +defined per subproject. This is useful for example when building +shared libraries in the main project, but static link a subproject, or +when the main project must build with no warnings but some subprojects +cannot. -Most of the time this would be used either by the parent project by setting -subproject's default_options (e.g. `subproject('foo', default_options: 'default_library=static')`), -or by the user using the command line `-Dfoo:default_library=static`. +Most of the time this would be used either by the parent project by +setting subproject's default_options (e.g. `subproject('foo', +default_options: 'default_library=static')`), or by the user using the +command line `-Dfoo:default_library=static`. The value is overridden in this order: - Value from parent project diff --git a/docs/markdown/CMake-module.md b/docs/markdown/CMake-module.md index f811ab4..7e981c6 100644 --- a/docs/markdown/CMake-module.md +++ b/docs/markdown/CMake-module.md @@ -48,13 +48,13 @@ The `subproject` method is almost identical to the normal meson `subproject` function. The only difference is that a CMake project instead of a meson project is configured. -The returned `sub_proj` supports the same options as a "normal" subproject. -Meson automatically detects CMake build targets, which can be accessed with -the methods listed [below](#subproject-object). +The returned `sub_proj` supports the same options as a "normal" +subproject. Meson automatically detects CMake build targets, which can +be accessed with the methods listed [below](#subproject-object). It is usually enough to just use the dependency object returned by the -`dependency()` method in the build targets. This is almost identical to -using `declare_dependency()` object from a normal meson subproject. +`dependency()` method in the build targets. This is almost identical +to using `declare_dependency()` object from a normal meson subproject. It is also possible to use executables defined in the CMake project as code generators with the `target()` method: @@ -111,22 +111,24 @@ sub_pro = cmake.subproject('someLibProject', options: opt_var) # Further changes to opt_var have no effect ``` -See [the CMake options object](#cmake-options-object) for a complete reference -of all supported functions. +See [the CMake options object](#cmake-options-object) for a complete +reference of all supported functions. The CMake configuration options object is very similar to the -[configuration data object](Reference-manual.md#configuration-data-object) object -returned by [`configuration_data`](Reference-manual.md#configuration_data). It +[configuration data +object](Reference-manual.md#configuration-data-object) object returned +by [`configuration_data`](Reference-manual.md#configuration_data). It is generated by the `subproject_options` function -All configuration options have to be set *before* the subproject is configured -and must be passed to the `subproject` method via the `options` key. Altering -the configuration object won't have any effect on previous `cmake.subproject` -calls. +All configuration options have to be set *before* the subproject is +configured and must be passed to the `subproject` method via the +`options` key. Altering the configuration object won't have any effect +on previous `cmake.subproject` calls. -In earlier meson versions CMake command-line parameters could be set with the -`cmake_options` kwarg. However, this feature is deprecated since 0.55.0 and only -kept for compatibility. It will not work together with the `options` kwarg. +In earlier meson versions CMake command-line parameters could be set +with the `cmake_options` kwarg. However, this feature is deprecated +since 0.55.0 and only kept for compatibility. It will not work +together with the `options` kwarg. ### `subproject` object @@ -151,9 +153,9 @@ and supports the following methods: ### `cmake options` object -This object is returned by the `subproject_options()` function and consumed by -the `options` kwarg of the `subproject` function. The following methods are -supported: +This object is returned by the `subproject_options()` function and +consumed by the `options` kwarg of the `subproject` function. The +following methods are supported: - `add_cmake_defines({'opt1': val1, ...})` add additional CMake commandline defines - `set_override_option(opt, val)` set specific [build options](Build-options.md) @@ -165,39 +167,42 @@ supported: - `append_link_args(arg1, ...)` append linger args to the targets - `clear()` reset all data in the `cmake options` object -The methods `set_override_option`, `set_install`, `append_compile_args` and -`append_link_args` support the optional `target` kwarg. If specified, the set -options affect the specific target. The effect of the option is global for the -subproject otherwise. +The methods `set_override_option`, `set_install`, +`append_compile_args` and `append_link_args` support the optional +`target` kwarg. If specified, the set options affect the specific +target. The effect of the option is global for the subproject +otherwise. -If, for instance, `opt_var.set_install(false)` is called, no target will be -installed regardless of what is set by CMake. However, it is still possible to -install specific targets (here `foo`) by setting the `target` kwarg: -`opt_var.set_install(true, target: 'foo')` +If, for instance, `opt_var.set_install(false)` is called, no target +will be installed regardless of what is set by CMake. However, it is +still possible to install specific targets (here `foo`) by setting the +`target` kwarg: `opt_var.set_install(true, target: 'foo')` -Options that are not set won't affect the generated subproject. So, if for -instance, `set_install` was not called then the values extracted from CMake will -be used. +Options that are not set won't affect the generated subproject. So, if +for instance, `set_install` was not called then the values extracted +from CMake will be used. ### Cross compilation *New in 0.56.0* -Meson will try to automatically guess most of the required CMake toolchain -variables from existing entries in the cross and native files. These variables -will be stored in an automatically generate CMake toolchain file in the build -directory. The remaining variables that can't be guessed can be added by the -user in the `[cmake]` cross/native file section (*new in 0.56.0*). +Meson will try to automatically guess most of the required CMake +toolchain variables from existing entries in the cross and native +files. These variables will be stored in an automatically generate +CMake toolchain file in the build directory. The remaining variables +that can't be guessed can be added by the user in the `[cmake]` +cross/native file section (*new in 0.56.0*). Adding a manual CMake toolchain file is also supported with the -`cmake_toolchain_file` setting in the `[properties]` section. Directly setting -a CMake toolchain file with `-DCMAKE_TOOLCHAIN_FILE=/path/to/some/Toolchain.cmake` -in the `meson.build` is **not** supported since the automatically generated -toolchain file is also used by Meson to inject arbitrary code into CMake to -enable the CMake subproject support. +`cmake_toolchain_file` setting in the `[properties]` section. Directly +setting a CMake toolchain file with +`-DCMAKE_TOOLCHAIN_FILE=/path/to/some/Toolchain.cmake` in the +`meson.build` is **not** supported since the automatically generated +toolchain file is also used by Meson to inject arbitrary code into +CMake to enable the CMake subproject support. -The closest configuration to only using a manual CMake toolchain file would be -to set these options in the machine file: +The closest configuration to only using a manual CMake toolchain file +would be to set these options in the machine file: ```ini [properties] @@ -210,17 +215,19 @@ cmake_defaults = false # No entries in this section ``` -This will result in a toolchain file with just the bare minimum to enable the -CMake subproject support and `include()` the `cmake_toolchain_file` as the -last instruction. +This will result in a toolchain file with just the bare minimum to +enable the CMake subproject support and `include()` the +`cmake_toolchain_file` as the last instruction. -For more information see the [cross and native file specification](Machine-files.md). +For more information see the [cross and native file +specification](Machine-files.md). ## CMake configuration files ### cmake.write_basic_package_version_file() -This function is the equivalent of the corresponding [CMake function](https://cmake.org/cmake/help/v3.11/module/CMakePackageConfigHelpers.html#generating-a-package-version-file), +This function is the equivalent of the corresponding [CMake +function](https://cmake.org/cmake/help/v3.11/module/CMakePackageConfigHelpers.html#generating-a-package-version-file), it generates a `name` package version file. * `name`: the name of the package. @@ -242,10 +249,13 @@ cmake.write_basic_package_version_file(name: 'myProject', version: '1.0.0') ### cmake.configure_package_config_file() -This function is the equivalent of the corresponding [CMake function](https://cmake.org/cmake/help/v3.11/module/CMakePackageConfigHelpers.html#generating-a-package-configuration-file), -it generates a `name` package configuration file from the `input` template file. Just like the cmake function -in this file the `@PACKAGE_INIT@` statement will be replaced by the appropriate piece of cmake code. -The equivalent `PATH_VARS` argument is given through the `configuration` parameter. +This function is the equivalent of the corresponding [CMake +function](https://cmake.org/cmake/help/v3.11/module/CMakePackageConfigHelpers.html#generating-a-package-configuration-file), +it generates a `name` package configuration file from the `input` +template file. Just like the cmake function in this file the +`@PACKAGE_INIT@` statement will be replaced by the appropriate piece +of cmake code. The equivalent `PATH_VARS` argument is given through +the `configuration` parameter. * `name`: the name of the package. * `input`: the template file where that will be treated for variable substitutions contained in `configuration`. diff --git a/docs/markdown/Commands.md b/docs/markdown/Commands.md index 984b293..96f1142 100644 --- a/docs/markdown/Commands.md +++ b/docs/markdown/Commands.md @@ -1,18 +1,21 @@ # Command-line commands -There are two different ways of invoking Meson. First, you can run it directly -from the source tree with the command `/path/to/source/meson.py`. Meson may -also be installed in which case the command is simply `meson`. In this manual -we only use the latter format for simplicity. +There are two different ways of invoking Meson. First, you can run it +directly from the source tree with the command +`/path/to/source/meson.py`. Meson may also be installed in which case +the command is simply `meson`. In this manual we only use the latter +format for simplicity. Meson is invoked using the following syntax: `meson [COMMAND] [COMMAND_OPTIONS]` -This section describes all available commands and some of their Optional arguments. -The most common workflow is to run [`setup`](#setup), followed by [`compile`](#compile), and then [`install`](#install). +This section describes all available commands and some of their +Optional arguments. The most common workflow is to run +[`setup`](#setup), followed by [`compile`](#compile), and then +[`install`](#install). -For the full list of all available options for a specific command use the following syntax: -`meson COMMAND --help` +For the full list of all available options for a specific command use +the following syntax: `meson COMMAND --help` ### configure @@ -24,7 +27,8 @@ Changes options of a configured meson project. Most arguments are the same as in [`setup`](#setup). -Note: reconfiguring project will not reset options to their default values (even if they were changed in `meson.build`). +Note: reconfiguring project will not reset options to their default +values (even if they were changed in `meson.build`). #### Examples: @@ -59,7 +63,8 @@ Builds a default or a specified target of a configured meson project. - `PATH`: path to the target relative to the root `meson.build` file. Note: relative path for a target specified in the root `meson.build` is `./`. - `TYPE`: type of the target. Can be one of the following: 'executable', 'static_library', 'shared_library', 'shared_module', 'custom', 'run', 'jar'. -`PATH` and/or `TYPE` can be omitted if the resulting `TARGET` can be used to uniquely identify the target in `meson.build`. +`PATH` and/or `TYPE` can be omitted if the resulting `TARGET` can be +used to uniquely identify the target in `meson.build`. #### Backend specific arguments @@ -67,7 +72,8 @@ Builds a default or a specified target of a configured meson project. `BACKEND-args` use the following syntax: -If you only pass a single string, then it is considered to have all values separated by commas. Thus invoking the following command: +If you only pass a single string, then it is considered to have all +values separated by commas. Thus invoking the following command: ``` $ meson compile --ninja-args=-n,-d,explain @@ -75,7 +81,8 @@ $ meson compile --ninja-args=-n,-d,explain would add `-n`, `-d` and `explain` arguments to ninja invocation. -If you need to have commas or spaces in your string values, then you need to pass the value with proper shell quoting like this: +If you need to have commas or spaces in your string values, then you +need to pass the value with proper shell quoting like this: ``` $ meson compile "--ninja-args=['a,b', 'c d']" @@ -89,16 +96,20 @@ meson compile -C builddir ``` Execute a dry run on ninja backend with additional debug info: + ``` meson compile --ninja-args=-n,-d,explain ``` -Build three targets: two targets that have the same `foo` name, but different type, and a `bar` target: +Build three targets: two targets that have the same `foo` name, but +different type, and a `bar` target: + ``` meson compile foo:shared_library foo:static_library bar ``` Produce a coverage html report (if available): + ``` meson compile coverage-html ``` @@ -150,6 +161,7 @@ Displays information about a configured meson project. #### Examples: Display basic information about a configured project in `builddir`: + ``` meson introspect builddir --projectinfo ``` @@ -200,7 +212,8 @@ This is the default meson command (invoked if there was no COMMAND supplied). {{ setup_arguments.inc }} -See [meson introduction page](Running-Meson.md#configuring-the-build-directory) for more info. +See [meson introduction +page](Running-Meson.md#configuring-the-build-directory) for more info. #### Examples: diff --git a/docs/markdown/Compiler-properties.md b/docs/markdown/Compiler-properties.md index 5d29dd1..d3382b3 100644 --- a/docs/markdown/Compiler-properties.md +++ b/docs/markdown/Compiler-properties.md @@ -41,8 +41,8 @@ either `gcc` or `msvc`, or that its arguments are not like either. This should only be used to select the syntax of the arguments, such as those to test with `has_argument`. -See [reference tables](Reference-tables.md#compiler-ids) for a list of supported compiler -ids and their argument type. +See [reference tables](Reference-tables.md#compiler-ids) for a list of +supported compiler ids and their argument type. ## Does code compile? @@ -167,10 +167,10 @@ not be determined. ## Does a function exist? -Just having a header doesn't say anything about its -contents. Sometimes you need to explicitly check if some function -exists. This is how we would check whether the function `open_memstream` -exists in header `stdio.h` +Just having a header doesn't say anything about its contents. +Sometimes you need to explicitly check if some function exists. This +is how we would check whether the function `open_memstream` exists in +header `stdio.h` ```meson if compiler.has_function('open_memstream', prefix : '#include <stdio.h>') @@ -180,18 +180,18 @@ endif Note that, on macOS programs can be compiled targeting older macOS versions than the one that the program is compiled on. It can't be -assumed that the OS version that is compiled on matches the OS -version that the binary will run on. +assumed that the OS version that is compiled on matches the OS version +that the binary will run on. Therefore when detecting function availability with `has_function`, it is important to specify the correct header in the prefix argument. In the example above, the function `open_memstream` is detected, which -was introduced in macOS 10.13. When the user builds on macOS 10.13, but -targeting macOS 10.11 (`-mmacosx-version-min=10.11`), this will correctly -report the function as missing. Without the header however, it would lack -the necessary availability information and incorrectly report the function -as available. +was introduced in macOS 10.13. When the user builds on macOS 10.13, +but targeting macOS 10.11 (`-mmacosx-version-min=10.11`), this will +correctly report the function as missing. Without the header however, +it would lack the necessary availability information and incorrectly +report the function as available. ## Does a structure contain a member? diff --git a/docs/markdown/Conference-presentations.md b/docs/markdown/Conference-presentations.md index abfc52f..b800129 100644 --- a/docs/markdown/Conference-presentations.md +++ b/docs/markdown/Conference-presentations.md @@ -1,17 +1,31 @@ # Conference presentations on Meson -- FOSDEM 2014, [Introducing the Meson build system](https://video.fosdem.org/2014/H2215_Ferrer/Sunday/Introducing_the_Meson_build_system.webm) (jpakkane) +- FOSDEM 2014, [Introducing the Meson build + system](https://video.fosdem.org/2014/H2215_Ferrer/Sunday/Introducing_the_Meson_build_system.webm) + (jpakkane) -- LCA 2015, [Making build systems not suck](https://www.youtube.com/watch?v=KPi0AuVpxLI) (jpakkane) +- LCA 2015, [Making build systems not + suck](https://www.youtube.com/watch?v=KPi0AuVpxLI) (jpakkane) -- GUADEC 2015, [Improving the way Gnome apps are built](https://www.youtube.com/watch?v=wTf0NjjNwTU) (jpakkane) +- GUADEC 2015, [Improving the way Gnome apps are + built](https://www.youtube.com/watch?v=wTf0NjjNwTU) (jpakkane) -- GStreamer conference 2015, [Done in 6.0 seconds](https://gstconf.ubicast.tv/videos/done-in-60-seconds-a-new-build-system-for-gstreamer) (jpakkane) +- GStreamer conference 2015, [Done in 6.0 + seconds](https://gstconf.ubicast.tv/videos/done-in-60-seconds-a-new-build-system-for-gstreamer) + (jpakkane) -- LCA 2016, [Builds, dependencies and deployment in the modern multiplatform world](https://www.youtube.com/watch?v=CTJtKtQ8R5k) (jpakkane) +- LCA 2016, [Builds, dependencies and deployment in the modern + multiplatform world](https://www.youtube.com/watch?v=CTJtKtQ8R5k) + (jpakkane) -- GUADEC 2016, [Making your GNOME app compile 2.4x faster](https://media.ccc.de/v/44-making_your_gnome_app_compile_24x_faster) (nirbheek) +- GUADEC 2016, [Making your GNOME app compile 2.4x + faster](https://media.ccc.de/v/44-making_your_gnome_app_compile_24x_faster) + (nirbheek) -- Libre Application Summit 2016, [New world, new tools](https://youtu.be/0-gx1qU2pPo) (jpakkane) +- Libre Application Summit 2016, [New world, new + tools](https://youtu.be/0-gx1qU2pPo) (jpakkane) -- GStreamer conference 2016, [GStreamer Development on Windows and faster builds everywhere with Meson](https://gstconf.ubicast.tv/videos/gstreamer-development-on-windows-ans-faster-builds-everywhere-with-meson/) (tpm) +- GStreamer conference 2016, [GStreamer Development on Windows and + faster builds everywhere with + Meson](https://gstconf.ubicast.tv/videos/gstreamer-development-on-windows-ans-faster-builds-everywhere-with-meson/) + (tpm) diff --git a/docs/markdown/Configuration.md b/docs/markdown/Configuration.md index cd1af14..a2fc639 100644 --- a/docs/markdown/Configuration.md +++ b/docs/markdown/Configuration.md @@ -115,19 +115,20 @@ Will produce: ## Dealing with file encodings -The default meson file encoding to configure files is utf-8. If you need to -configure a file that is not utf-8 encoded the encoding keyword will allow -you to specify which file encoding to use. It is however strongly advised to -convert your non utf-8 file to utf-8 whenever possible. Supported file -encodings are those of python3, see [standard-encodings](https://docs.python.org/3/library/codecs.html#standard-encodings). +The default meson file encoding to configure files is utf-8. If you +need to configure a file that is not utf-8 encoded the encoding +keyword will allow you to specify which file encoding to use. It is +however strongly advised to convert your non utf-8 file to utf-8 +whenever possible. Supported file encodings are those of python3, see +[standard-encodings](https://docs.python.org/3/library/codecs.html#standard-encodings). ## Using dictionaries -Since *0.49.0* `configuration_data()` takes an optional dictionary as first -argument. If provided, each key/value pair is added into the +Since *0.49.0* `configuration_data()` takes an optional dictionary as +first argument. If provided, each key/value pair is added into the `configuration_data` as if `set()` method was called for each of them. -`configure_file()`'s `configuration` kwarg also accepts a dictionary instead of -a configuration_data object. +`configure_file()`'s `configuration` kwarg also accepts a dictionary +instead of a configuration_data object. Example: ```meson diff --git a/docs/markdown/Configuring-a-build-directory.md b/docs/markdown/Configuring-a-build-directory.md index 199d1d7..0b6053c 100644 --- a/docs/markdown/Configuring-a-build-directory.md +++ b/docs/markdown/Configuring-a-build-directory.md @@ -11,9 +11,9 @@ options provided in your `meson_options.txt` file and so on. The main tool for this is the `meson configure` command. -You invoke `meson configure` by giving it the location of your build dir. If -omitted, the current working directory is used instead. Here's a -sample output for a simple project. +You invoke `meson configure` by giving it the location of your build +dir. If omitted, the current working directory is used instead. Here's +a sample output for a simple project. Core properties @@ -109,11 +109,12 @@ you would issue the following command. meson configure -Dprefix=/tmp/testroot -Then you would run your build command (usually `meson compile`), which would -cause Meson to detect that the build setup has changed and do all the -work required to bring your build tree up to date. +Then you would run your build command (usually `meson compile`), which +would cause Meson to detect that the build setup has changed and do +all the work required to bring your build tree up to date. Since 0.50.0, it is also possible to get a list of all build options -by invoking [`meson configure`](Commands.md#configure) with the project source directory or -the path to the root `meson.build`. In this case, meson will print the -default values of all options similar to the example output from above. +by invoking [`meson configure`](Commands.md#configure) with the +project source directory or the path to the root `meson.build`. In +this case, meson will print the default values of all options similar +to the example output from above. diff --git a/docs/markdown/Contact-information.md b/docs/markdown/Contact-information.md index 87a76a5..e908a3f 100644 --- a/docs/markdown/Contact-information.md +++ b/docs/markdown/Contact-information.md @@ -8,7 +8,7 @@ If you find bugs, please file them in the [issue tracker](https://github.com/jpakkane/meson/issues). The maintainer of Meson is Jussi Pakkanen. You should usually not -contact him privately but rather use the channels listed -above. However if such a need arises, he can be reached at gmail where -his username is `jpakkane` (that is not a typo, the last letter is -indeed *e*). +contact him privately but rather use the channels listed above. +However if such a need arises, he can be reached at gmail where his +username is `jpakkane` (that is not a typo, the last letter is indeed +*e*). diff --git a/docs/markdown/Continuous-Integration.md b/docs/markdown/Continuous-Integration.md index 9a2391c..d2b64f2 100644 --- a/docs/markdown/Continuous-Integration.md +++ b/docs/markdown/Continuous-Integration.md @@ -42,8 +42,8 @@ script: ## CircleCi for Linux (with Docker) -[CircleCi](https://circleci.com/) can work for spinning all of the Linux images you wish. -Here's a sample `yml` file for use with that. +[CircleCi](https://circleci.com/) can work for spinning all of the +Linux images you wish. Here's a sample `yml` file for use with that. ```yaml version: 2.1 @@ -99,11 +99,14 @@ workflows: ## AppVeyor for Windows -For CI on Windows, [AppVeyor](https://www.appveyor.com/) has a wide selection of -[default configurations](https://www.appveyor.com/docs/windows-images-software/). -AppVeyor also has [MacOS](https://www.appveyor.com/docs/macos-images-software/) and -[Linux](https://www.appveyor.com/docs/linux-images-software/) CI images. -This is a sample `appveyor.yml` file for Windows with Visual Studio 2015 and 2017. +For CI on Windows, [AppVeyor](https://www.appveyor.com/) has a wide +selection of [default +configurations](https://www.appveyor.com/docs/windows-images-software/). +AppVeyor also has +[MacOS](https://www.appveyor.com/docs/macos-images-software/) and +[Linux](https://www.appveyor.com/docs/linux-images-software/) CI +images. This is a sample `appveyor.yml` file for Windows with Visual +Studio 2015 and 2017. ```yaml image: Visual Studio 2017 @@ -154,7 +157,10 @@ For Qt 5, add the following line near the `PYTHON_ROOT` assignment: And afterwards add `%QT_ROOT%\bin` to the `PATH` variable. -You might have to adjust your build matrix as there are, for example, no msvc2017 32-bit builds. Visit the [Build Environment](https://www.appveyor.com/docs/build-environment/) page in the AppVeyor docs for more details. +You might have to adjust your build matrix as there are, for example, +no msvc2017 32-bit builds. Visit the [Build +Environment](https://www.appveyor.com/docs/build-environment/) page in +the AppVeyor docs for more details. ### Boost @@ -193,10 +199,13 @@ script: ## GitHub Actions -GitHub Actions are distinct from Azure Pipelines in their workflow syntax. -It can be easier to setup specific CI tasks in Actions than Pipelines, depending on the particular task. -This is an example file: .github/workflows/ci_meson.yml supposing the project is C-based, using GCC on Linux, Mac and Windows. -The optional `on:` parameters only run this CI when the C code is changed--corresponding ci_python.yml might run only on "**.py" file changes. +GitHub Actions are distinct from Azure Pipelines in their workflow +syntax. It can be easier to setup specific CI tasks in Actions than +Pipelines, depending on the particular task. This is an example file: +.github/workflows/ci_meson.yml supposing the project is C-based, using +GCC on Linux, Mac and Windows. The optional `on:` parameters only run +this CI when the C code is changed--corresponding ci_python.yml might +run only on "**.py" file changes. ```yml name: ci_meson diff --git a/docs/markdown/Contributing.md b/docs/markdown/Contributing.md index 3e5bcca..fe5bd0d 100644 --- a/docs/markdown/Contributing.md +++ b/docs/markdown/Contributing.md @@ -36,7 +36,8 @@ Every new feature requires some extra steps, namely: - Must include a project test under `test cases/`, or if that's not possible or if the test requires a special environment, it must go into `run_unittests.py`. -- Must be registered with the [FeatureChecks framework](Release-notes-for-0.47.0.md#feature-detection-based-on-meson_version-in-project) +- Must be registered with the [FeatureChecks + framework](Release-notes-for-0.47.0.md#feature-detection-based-on-meson_version-in-project) that will warn the user if they try to use a new feature while targeting an older meson version. - Needs a release note snippet inside `docs/markdown/snippets/` with @@ -155,21 +156,23 @@ should be implemented as a Python script. The goal of test projects is also to provide sample projects that end users can use as a base for their own projects. -All project tests follow the same pattern: they are configured, compiled, tests -are run and finally install is run. Passing means that configuring, building and -tests succeed and that installed files match those expected. +All project tests follow the same pattern: they are configured, +compiled, tests are run and finally install is run. Passing means that +configuring, building and tests succeed and that installed files match +those expected. -Any tests that require more thorough analysis, such as checking that certain -compiler arguments can be found in the command line or that the generated -pkg-config files actually work should be done with a unit test. +Any tests that require more thorough analysis, such as checking that +certain compiler arguments can be found in the command line or that +the generated pkg-config files actually work should be done with a +unit test. Additionally: * `crossfile.ini` and `nativefile.ini` are passed to the configure step with `--cross-file` and `--native-file` options, respectively. -* `mlog.cmd_ci_include()` can be called from anywhere inside meson to capture the -contents of an additional file into the CI log on failure. +* `mlog.cmd_ci_include()` can be called from anywhere inside meson to +capture the contents of an additional file into the CI log on failure. Projects needed by unit tests are in the `test cases/unit` subdirectory. They are not run as part of `./run_project_tests.py`. @@ -261,9 +264,15 @@ Except for the `file` and `expr` types, all paths should be provided *without* a | `version` | `shared_lib`, `pdb` | Sets the version to look for appropriately per-platform | | `language` | `pdb` | Determines which compiler/linker determines the existence of this file | -The `shared_lib` and `pdb` types takes an optional additional parameter, `version`, this is us a string in `X.Y.Z` format that will be applied to the library. Each version to be tested must have a single version. The harness will apply this correctly per platform: +The `shared_lib` and `pdb` types takes an optional additional +parameter, `version`, this is us a string in `X.Y.Z` format that will +be applied to the library. Each version to be tested must have a +single version. The harness will apply this correctly per platform: -`pdb` takes an optional `language` argument. This determines which compiler/linker should generate the pdb file. Because it's possible to mix compilers that do and don't generate pdb files (dmd's optlink doesn't). Currently this is only needed when mixing D and C code. +`pdb` takes an optional `language` argument. This determines which +compiler/linker should generate the pdb file. Because it's possible to +mix compilers that do and don't generate pdb files (dmd's optlink +doesn't). Currently this is only needed when mixing D and C code. ```json { @@ -273,10 +282,14 @@ The `shared_lib` and `pdb` types takes an optional additional parameter, `versio } ``` -This will be applied appropriately per platform. On windows this expects `lib.dll` and `lib-1.dll`. on MacOS it expects `liblib.dylib` and `liblib.1.dylib`. On other Unices it expects `liblib.so`, `liblib.so.1`, and `liblib.so.1.2.3`. +This will be applied appropriately per platform. On windows this +expects `lib.dll` and `lib-1.dll`. on MacOS it expects `liblib.dylib` +and `liblib.1.dylib`. On other Unices it expects `liblib.so`, +`liblib.so.1`, and `liblib.so.1.2.3`. -If the `platform` key is present, the installed file entry is only considered if -the platform matches. The following values for `platform` are currently supported: +If the `platform` key is present, the installed file entry is only +considered if the platform matches. The following values for +`platform` are currently supported: | platform | Description | | ---------- | -------------------------------------------------------------------- | @@ -287,22 +300,25 @@ the platform matches. The following values for `platform` are currently supporte #### matrix -The `matrix` section can be used to define a test matrix to run project tests -with different meson options. +The `matrix` section can be used to define a test matrix to run +project tests with different meson options. -In the `options` dict, all possible options and their values are specified. Each -key in the `options` dict is a meson option. It stores a list of all potential -values in a dict format, which allows to skip specific values based on the current -environment. +In the `options` dict, all possible options and their values are +specified. Each key in the `options` dict is a meson option. It stores +a list of all potential values in a dict format, which allows to skip +specific values based on the current environment. -Each value must contain the `val` key for the value of the option. `null` can be -used for adding matrix entries without the current option. +Each value must contain the `val` key for the value of the option. +`null` can be used for adding matrix entries without the current +option. -Additionally, the `skip_on_env` key can be used to specify a list of environment -variables. If at least one environment variable in `skip_on_env` is present, all -matrix entries containing this value are skipped. +Additionally, the `skip_on_env` key can be used to specify a list of +environment variables. If at least one environment variable in +`skip_on_env` is present, all matrix entries containing this value are +skipped. -Similarly, the `compilers` key can be used to define a mapping of compilers to languages that are required for this value. +Similarly, the `compilers` key can be used to define a mapping of +compilers to languages that are required for this value. ```json { @@ -314,10 +330,11 @@ Similarly, the `compilers` key can be used to define a mapping of compilers to l } ``` -Specific option combinations can be excluded with the `exclude` section. It should -be noted that `exclude` does not require exact matches. Instead, any matrix entry -containing all option value combinations in `exclude` will be excluded. Thus -an empty dict (`{}`) to will match **all** elements in the test matrix. +Specific option combinations can be excluded with the `exclude` +section. It should be noted that `exclude` does not require exact +matches. Instead, any matrix entry containing all option value +combinations in `exclude` will be excluded. Thus an empty dict (`{}`) +to will match **all** elements in the test matrix. The above example will produce the following matrix entries: - `opt1=abc` @@ -334,26 +351,29 @@ Currently supported values are: #### tools -This section specifies a dict of tool requirements in a simple key-value format. -If a tool is specified, it has to be present in the environment, and the version -requirement must be fulfilled. Otherwise, the entire test is skipped (including -every element in the test matrix). +This section specifies a dict of tool requirements in a simple +key-value format. If a tool is specified, it has to be present in the +environment, and the version requirement must be fulfilled. Otherwise, +the entire test is skipped (including every element in the test +matrix). #### stdout -The `stdout` key contains a list of dicts, describing the expected stdout. +The `stdout` key contains a list of dicts, describing the expected +stdout. Each dict contains the following keys: - `line` - `match` (optional) -Each item in the list is matched, in order, against the remaining actual stdout -lines, after any previous matches. If the actual stdout is exhausted before -every item in the list is matched, the expected output has not been seen, and -the test has failed. +Each item in the list is matched, in order, against the remaining +actual stdout lines, after any previous matches. If the actual stdout +is exhausted before every item in the list is matched, the expected +output has not been seen, and the test has failed. -The `match` element of the dict determines how the `line` element is matched: +The `match` element of the dict determines how the `line` element is +matched: | Type | Description | | -------- | ----------------------- | @@ -362,8 +382,9 @@ The `match` element of the dict determines how the `line` element is matched: ### Skipping integration tests -Meson uses several continuous integration testing systems that have slightly -different interfaces for indicating a commit should be skipped. +Meson uses several continuous integration testing systems that have +slightly different interfaces for indicating a commit should be +skipped. Continuous integration systems currently used: - [Azure Pipelines](https://docs.microsoft.com/en-us/azure/devops/pipelines/scripts/git-commands?view=vsts&tabs=yaml#how-do-i-avoid-triggering-a-ci-build-when-the-script-pushes) @@ -373,7 +394,8 @@ Continuous integration systems currently used: To promote consistent naming policy, use: -- `[skip ci]` in the commit title if you want to disable all integration tests +- `[skip ci]` in the commit title if you want to disable all + integration tests ## Documentation @@ -480,7 +502,8 @@ This piece of code would never converge. Every Meson run would change the value of the option and thus the output you get out of this build definition would be random. -Meson does not permit this by forbidding these sorts of covert channels. +Meson does not permit this by forbidding these sorts of covert +channels. There is one exception to this rule. Users can call into external commands with `run_command`. If the output of that command does not diff --git a/docs/markdown/Creating-Linux-binaries.md b/docs/markdown/Creating-Linux-binaries.md index c3b4b64..f5aa6a4 100644 --- a/docs/markdown/Creating-Linux-binaries.md +++ b/docs/markdown/Creating-Linux-binaries.md @@ -70,13 +70,12 @@ way. You want to embed and statically link every dependency you can (especially C++ dependencies). Meson's [Wrap package manager](Wrap-dependency-system-manual.md) might be of use here. This -is equivalent to what you would do on Windows, OSX, Android -etc. Sometimes static linking is not possible. In these cases you need -to copy the .so files inside your package. Let's use SDL2 as an -example. First we download and install it as usual giving it our -custom install prefix (that is, `./configure ---prefix=${HOME}/devroot`). This makes Meson's dependency detector -pick it up automatically. +is equivalent to what you would do on Windows, OSX, Android etc. +Sometimes static linking is not possible. In these cases you need to +copy the .so files inside your package. Let's use SDL2 as an example. +First we download and install it as usual giving it our custom install +prefix (that is, `./configure --prefix=${HOME}/devroot`). This makes +Meson's dependency detector pick it up automatically. ## Building and installing diff --git a/docs/markdown/Creating-releases.md b/docs/markdown/Creating-releases.md index 55242a6..1e039ea 100644 --- a/docs/markdown/Creating-releases.md +++ b/docs/markdown/Creating-releases.md @@ -24,10 +24,10 @@ ninja dist ``` This creates a file called `projectname-version.tar.xz` in the build -tree subdirectory `meson-dist`. This archive contains the full contents -of the latest commit in revision control including all the submodules -(recursively). All revision control metadata is removed. Meson then -takes this archive and tests that it works by doing a full +tree subdirectory `meson-dist`. This archive contains the full +contents of the latest commit in revision control including all the +submodules (recursively). All revision control metadata is removed. +Meson then takes this archive and tests that it works by doing a full `compile` + `test` + `install` cycle. If all these pass, Meson will then create a `SHA-256` checksum file next to the archive. @@ -36,17 +36,19 @@ then create a `SHA-256` checksum file next to the archive. Meson behaviour is different from Autotools. The Autotools "dist" target packages up the current source tree. Meson packages the latest -revision control commit. The reason for this is that it prevents developers -from doing accidental releases where the distributed archive does not match -any commit in revision control (especially the one tagged for the release). +revision control commit. The reason for this is that it prevents +developers from doing accidental releases where the distributed +archive does not match any commit in revision control (especially the +one tagged for the release). ## Include subprojects in your release -The `meson dist` command has `--include-subprojects` command line option. -When enabled, the source tree of all subprojects used by the current build -will also be included in the final tarball. This is useful to distribute -self contained tarball that can be built offline (i.e. `--wrap-mode=nodownload`). +The `meson dist` command has `--include-subprojects` command line +option. When enabled, the source tree of all subprojects used by the +current build will also be included in the final tarball. This is +useful to distribute self contained tarball that can be built offline +(i.e. `--wrap-mode=nodownload`). ## Skip build and test with `--no-tests` diff --git a/docs/markdown/Cross-compilation.md b/docs/markdown/Cross-compilation.md index 21ca9f5..b25504a 100644 --- a/docs/markdown/Cross-compilation.md +++ b/docs/markdown/Cross-compilation.md @@ -36,54 +36,54 @@ Let's next look at the most common cross-compilation setup. Let's suppose you are on a 64 bit OSX machine and you are cross compiling a binary that will run on a 32 bit ARM Linux board. In this case your *build machine* is 64 bit OSX, your *host machine* is 32 bit ARM Linux -and your *target machine* is irrelevant (but defaults to the same value -as the *host machine*). This should be quite understandable as well. +and your *target machine* is irrelevant (but defaults to the same +value as the *host machine*). This should be quite understandable as +well. -The usual mistake in this case is to call the OSX system the *host* and -the ARM Linux board the *target*. That's because these were their actual -names when the cross-compiler itself was compiled! Let's assume the -cross-compiler was created on OSX too. When that happened the *build* -and *host machines* were the same OSX and different from the ARM Linux -*target machine*. +The usual mistake in this case is to call the OSX system the *host* +and the ARM Linux board the *target*. That's because these were their +actual names when the cross-compiler itself was compiled! Let's assume +the cross-compiler was created on OSX too. When that happened the +*build* and *host machines* were the same OSX and different from the +ARM Linux *target machine*. In a nutshell, the typical mistake assumes that the terms *build*, *host* and *target* refer to some fixed positions whereas they're actually relative to where the current compiler is running. Think of -*host* as a *child* of the current compiler and *target* as an optional -*grand-child*. Compilers don't change their terminology when they're -creating another compiler, that would at the very least make their user -interface much more complex. - -The most complicated case is when you cross-compile a cross -compiler. As an example you can, on a Linux machine, generate a cross -compiler that runs on Windows but produces binaries on MIPS Linux. In -this case *build machine* is x86 Linux, *host machine* is x86 Windows -and *target machine* is MIPS Linux. This setup is known as the -[Canadian -Cross](https://en.wikipedia.org/wiki/Cross_compiler#Canadian_Cross). As -a side note, be careful when reading cross compilation articles on +*host* as a *child* of the current compiler and *target* as an +optional *grand-child*. Compilers don't change their terminology when +they're creating another compiler, that would at the very least make +their user interface much more complex. + +The most complicated case is when you cross-compile a cross compiler. +As an example you can, on a Linux machine, generate a cross compiler +that runs on Windows but produces binaries on MIPS Linux. In this case +*build machine* is x86 Linux, *host machine* is x86 Windows and +*target machine* is MIPS Linux. This setup is known as the [Canadian +Cross](https://en.wikipedia.org/wiki/Cross_compiler#Canadian_Cross). +As a side note, be careful when reading cross compilation articles on Wikipedia or the net in general. It is very common for them to get build, host and target mixed up, even in consecutive sentences, which can leave you puzzled until you figure it out. -Again note that when you cross-compile something, -the 3 systems (*build*, *host*, and *target*) used when -building the cross compiler don't align with the ones used when -building something with that newly-built cross compiler. To take our -Canadian Cross scenario from above (for full generality), since its -*host machine* is x86 Windows, the *build machine* of anything we -build with it is *x86 Windows*. And since its *target machine* is MIPS -Linux, the *host machine* of anything we build with it is *MIPS -Linux*. Only the *target machine* of whatever we build with it can be -freely chosen by us, say if we want to build another cross compiler -that runs on MIPS Linux and targets Aarch64 iOS. As this example -hopefully makes clear to you, the machine names are relative and -shifted over to the left by one position. +Again note that when you cross-compile something, the 3 systems +(*build*, *host*, and *target*) used when building the cross compiler +don't align with the ones used when building something with that +newly-built cross compiler. To take our Canadian Cross scenario from +above (for full generality), since its *host machine* is x86 Windows, +the *build machine* of anything we build with it is *x86 Windows*. And +since its *target machine* is MIPS Linux, the *host machine* of +anything we build with it is *MIPS Linux*. Only the *target machine* +of whatever we build with it can be freely chosen by us, say if we +want to build another cross compiler that runs on MIPS Linux and +targets Aarch64 iOS. As this example hopefully makes clear to you, the +machine names are relative and shifted over to the left by one +position. If you did not understand all of the details, don't worry. For most -people it takes a while to wrap their head around these -concepts. Don't panic, it might take a while to click, but you will -get the hang of it eventually. +people it takes a while to wrap their head around these concepts. +Don't panic, it might take a while to click, but you will get the hang +of it eventually. ## Defining the environment @@ -92,8 +92,9 @@ various properties of the cross build environment. The cross file consists of different sections. There are a number of options shared by cross and native files, -[here](Machine-files.md). It is assumed that you have read that section already, -as this documentation will only call out options specific to cross files. +[here](Machine-files.md). It is assumed that you have read that +section already, as this documentation will only call out options +specific to cross files. ### Binaries @@ -102,19 +103,20 @@ as this documentation will only call out options specific to cross files. exe_wrapper = 'wine' # A command used to run generated executables. ``` -The `exe_wrapper` option defines a *wrapper command* that can be used to run -executables for this host. In this case we can use Wine, which runs Windows -applications on Linux. Other choices include running the application with -qemu or a hardware simulator. If you have this kind of a wrapper, these lines -are all you need to write. Meson will automatically use the given wrapper -when it needs to run host binaries. This happens e.g. when running the -project's test suite. +The `exe_wrapper` option defines a *wrapper command* that can be used +to run executables for this host. In this case we can use Wine, which +runs Windows applications on Linux. Other choices include running the +application with qemu or a hardware simulator. If you have this kind +of a wrapper, these lines are all you need to write. Meson will +automatically use the given wrapper when it needs to run host +binaries. This happens e.g. when running the project's test suite. ### Properties In addition to the properties allowed in [all machine -files](Machine-files.md#properties), the cross file may contain specific -information about the cross compiler or the host machine. It looks like this: +files](Machine-files.md#properties), the cross file may contain +specific information about the cross compiler or the host machine. It +looks like this: ```ini [properties] @@ -133,23 +135,24 @@ pkg_config_libdir = '/some/path/lib/pkgconfig' ``` In most cases you don't need the size and alignment settings, Meson -will detect all these by compiling and running some sample -programs. If your build requires some piece of data that is not listed -here, Meson will stop and write an error message describing how to fix -the issue. If you need extra compiler arguments to be used during -cross compilation you can set them with `[langname]_args = -[args]`. Just remember to specify the args as an array and not as a -single string (i.e. not as `'-DCROSS=1 -DSOMETHING=3'`). - -*Since 0.52.0* The `sys_root` property may point to the root of the host -system path (the system that will run the compiled binaries). This is used -internally by Meson to set the PKG_CONFIG_SYSROOT_DIR environment variable -for pkg-config. If this is unset the host system is assumed to share a root -with the build system. - -*Since 0.54.0* The pkg_config_libdir property may point to a list of path used -internally by Meson to set the PKG_CONFIG_LIBDIR environment variable for pkg-config. -This prevents pkg-config from searching cross dependencies in system directories. +will detect all these by compiling and running some sample programs. +If your build requires some piece of data that is not listed here, +Meson will stop and write an error message describing how to fix the +issue. If you need extra compiler arguments to be used during cross +compilation you can set them with `[langname]_args = [args]`. Just +remember to specify the args as an array and not as a single string +(i.e. not as `'-DCROSS=1 -DSOMETHING=3'`). + +*Since 0.52.0* The `sys_root` property may point to the root of the +host system path (the system that will run the compiled binaries). +This is used internally by Meson to set the PKG_CONFIG_SYSROOT_DIR +environment variable for pkg-config. If this is unset the host system +is assumed to share a root with the build system. + +*Since 0.54.0* The pkg_config_libdir property may point to a list of +path used internally by Meson to set the PKG_CONFIG_LIBDIR environment +variable for pkg-config. This prevents pkg-config from searching cross +dependencies in system directories. One important thing to note, if you did not define an `exe_wrapper` in the previous section, is that Meson will make a best-effort guess at @@ -191,22 +194,23 @@ These values define the machines sufficiently for cross compilation purposes. The corresponding target definition would look the same but have `target_machine` in the header. These values are available in your Meson scripts. There are three predefined variables called, -surprisingly, `build_machine`, `host_machine` and -`target_machine`. Determining the operating system of your host -machine is simply a matter of calling `host_machine.system()`. - -There are two different values for the CPU. The first one is `cpu_family`. It -is a general type of the CPU. This should have a value from [the CPU Family -table](Reference-tables.md#cpu-families). *Note* that meson does not add -`el` to end cpu_family value for little endian systems. Big endian and little -endian mips are both just `mips`, with the `endian` field set approriately. - -The second value is `cpu` which is -a more specific subtype for the CPU. Typical values for a `x86` CPU family -might include `i386` or `i586` and for `arm` family `armv5` or `armv7hl`. -Note that CPU type strings are very system dependent. You might get a -different value if you check its value on the same machine but with different -operating systems. +surprisingly, `build_machine`, `host_machine` and `target_machine`. +Determining the operating system of your host machine is simply a +matter of calling `host_machine.system()`. + +There are two different values for the CPU. The first one is +`cpu_family`. It is a general type of the CPU. This should have a +value from [the CPU Family table](Reference-tables.md#cpu-families). +*Note* that meson does not add `el` to end cpu_family value for little +endian systems. Big endian and little endian mips are both just +`mips`, with the `endian` field set approriately. + +The second value is `cpu` which is a more specific subtype for the +CPU. Typical values for a `x86` CPU family might include `i386` or +`i586` and for `arm` family `armv5` or `armv7hl`. Note that CPU type +strings are very system dependent. You might get a different value if +you check its value on the same machine but with different operating +systems. If you do not define your host machine, it is assumed to be the build machine. Similarly if you do not specify target machine, it is assumed @@ -250,8 +254,8 @@ host_int_size = host_compiler.sizeof('int') Sometimes you need to build a tool which is used to generate source files. These are then compiled for the actual target. For this you -would want to build some targets with the system's native -compiler. This requires only one extra keyword argument. +would want to build some targets with the system's native compiler. +This requires only one extra keyword argument. ```meson native_exe = executable('mygen', 'mygen.c', native : true) @@ -292,11 +296,11 @@ c_stdlib = 'mylibc' ## Changing cross file settings Cross file settings are only read when the build directory is set up -the first time. Any changes to them after the fact will be -ignored. This is the same as regular compiles where you can't change -the compiler once a build tree has been set up. If you need to edit -your cross file, then you need to wipe your build tree and recreate it -from scratch. +the first time. Any changes to them after the fact will be ignored. +This is the same as regular compiles where you can't change the +compiler once a build tree has been set up. If you need to edit your +cross file, then you need to wipe your build tree and recreate it from +scratch. ## Custom data @@ -317,25 +321,27 @@ myvar = meson.get_cross_property('somekey') ## Cross file locations -As of version 0.44.0 meson supports loading cross files from system locations -(except on Windows). This will be $XDG_DATA_DIRS/meson/cross, or if -XDG_DATA_DIRS is undefined, then /usr/local/share/meson/cross and -/usr/share/meson/cross will be tried in that order, for system wide cross -files. User local files can be put in $XDG_DATA_HOME/meson/cross, or -~/.local/share/meson/cross if that is undefined. +As of version 0.44.0 meson supports loading cross files from system +locations (except on Windows). This will be +$XDG_DATA_DIRS/meson/cross, or if XDG_DATA_DIRS is undefined, then +/usr/local/share/meson/cross and /usr/share/meson/cross will be tried +in that order, for system wide cross files. User local files can be +put in $XDG_DATA_HOME/meson/cross, or ~/.local/share/meson/cross if +that is undefined. The order of locations tried is as follows: - A file relative to the local dir - The user local location - The system wide locations in order -Distributions are encouraged to ship cross files either with -their cross compiler toolchain packages or as a standalone package, and put +Distributions are encouraged to ship cross files either with their +cross compiler toolchain packages or as a standalone package, and put them in one of the system paths referenced above. -These files can be loaded automatically without adding a path to the cross -file. For example, if a ~/.local/share/meson/cross contains a file called x86-linux, -then the following command would start a cross build using that cross files: +These files can be loaded automatically without adding a path to the +cross file. For example, if a ~/.local/share/meson/cross contains a +file called x86-linux, then the following command would start a cross +build using that cross files: ```sh meson builddir/ --cross-file x86-linux diff --git a/docs/markdown/Cuda-module.md b/docs/markdown/Cuda-module.md index 2f8cb02..24a607a 100644 --- a/docs/markdown/Cuda-module.md +++ b/docs/markdown/Cuda-module.md @@ -62,8 +62,9 @@ Multiple architectures and compute capabilities may be passed in using - Lists of strings - Space (` `), comma (`,`) or semicolon (`;`)-separated strings -The single-word architectural sets `'All'`, `'Common'` or `'Auto'` cannot be -mixed with architecture names or compute capabilities. Their interpretation is: +The single-word architectural sets `'All'`, `'Common'` or `'Auto'` +cannot be mixed with architecture names or compute capabilities. Their +interpretation is: | Name | Compute Capability | |-------------------|--------------------| @@ -162,8 +163,9 @@ This will print Message: Building for architectures sm30 sm35 sm50 compute50 -_Note:_ This function is intended to closely replicate CMake's FindCUDA module function -`CUDA_SELECT_NVCC_ARCH_FLAGS(out_variable, [list of CUDA compute architectures])` +_Note:_ This function is intended to closely replicate CMake's +FindCUDA module function `CUDA_SELECT_NVCC_ARCH_FLAGS(out_variable, +[list of CUDA compute architectures])` @@ -174,11 +176,11 @@ _Since: 0.50.0_ cuda.min_driver_version(cuda_version_string) ``` -Returns the minimum NVIDIA proprietary driver version required, on the host -system, by kernels compiled with a CUDA Toolkit with the given version string. - -The output of this function is generally intended for informative message -printing, but could be used for assertions or to conditionally enable -features known to exist within the minimum NVIDIA driver required. - +Returns the minimum NVIDIA proprietary driver version required, on the +host system, by kernels compiled with a CUDA Toolkit with the given +version string. +The output of this function is generally intended for informative +message printing, but could be used for assertions or to conditionally +enable features known to exist within the minimum NVIDIA driver +required. diff --git a/docs/markdown/Custom-build-targets.md b/docs/markdown/Custom-build-targets.md index 76bf939..b92bbc5 100644 --- a/docs/markdown/Custom-build-targets.md +++ b/docs/markdown/Custom-build-targets.md @@ -33,9 +33,9 @@ See [Generating Sources](Generating-sources.md) for more information on this top Meson only permits you to specify one command to run. This is by design as writing shell pipelines into build definition files leads to -code that is very hard to maintain. If your command requires -multiple steps you need to write a wrapper script that does all the -necessary work. +code that is very hard to maintain. If your command requires multiple +steps you need to write a wrapper script that does all the necessary +work. When doing this you need to be mindful of the following issues: diff --git a/docs/markdown/D.md b/docs/markdown/D.md index 39aebc8..4a00a3b 100644 --- a/docs/markdown/D.md +++ b/docs/markdown/D.md @@ -16,14 +16,20 @@ executable('myapp', 'app.d') ## [Conditional compilation](https://dlang.org/spec/version.html) -If you are using the [version()](https://dlang.org/spec/version.html#version-specification) feature for conditional compilation, -you can use it using the `d_module_versions` target property: +If you are using the +[version()](https://dlang.org/spec/version.html#version-specification) +feature for conditional compilation, you can use it using the +`d_module_versions` target property: + ```meson project('myapp', 'd') executable('myapp', 'app.d', d_module_versions: ['Demo', 'FeatureA']) ``` -For debugging, [debug()](https://dlang.org/spec/version.html#debug) conditions are compiled automatically in debug builds, and extra identifiers can be added with the `d_debug` argument: +For debugging, [debug()](https://dlang.org/spec/version.html#debug) +conditions are compiled automatically in debug builds, and extra +identifiers can be added with the `d_debug` argument: + ```meson project('myapp', 'd') executable('myapp', 'app.d', d_debug: [3, 'DebugFeatureA']) @@ -31,15 +37,15 @@ executable('myapp', 'app.d', d_debug: [3, 'DebugFeatureA']) ## Using embedded unittests -If you are using embedded [unittest functions](https://dlang.org/spec/unittest.html), your source code needs -to be compiled twice, once in regular -mode, and once with unittests active. This is done by setting the -`d_unittest` target property to `true`. -Meson will only ever pass the respective compiler's `-unittest` flag, -and never have the compiler generate an empty main function. -If you need that feature in a portable way, create an empty `main()` -function for unittests yourself, since the GNU D compiler -does not have this feature. +If you are using embedded [unittest +functions](https://dlang.org/spec/unittest.html), your source code +needs to be compiled twice, once in regular mode, and once with +unittests active. This is done by setting the `d_unittest` target +property to `true`. Meson will only ever pass the respective +compiler's `-unittest` flag, and never have the compiler generate an +empty main function. If you need that feature in a portable way, +create an empty `main()` function for unittests yourself, since the +GNU D compiler does not have this feature. This is an example for using D unittests with Meson: ```meson @@ -87,13 +93,13 @@ install_subdir('src/mylib/', install_dir: 'include/d/mylib/') ``` It is important to make the D sources install in a subdirectory in the - include path, in this case `/usr/include/d/mylib/mylib`. -All D compilers include the `/usr/include/d` directory by default, and - if your library would be installed into `/usr/include/d/mylib`, there -is a high chance that, when you compile your project again on a -machine where you installed it, the compiler will prefer the old -installed include over the new version in the source tree, leading to -very confusing errors. +include path, in this case `/usr/include/d/mylib/mylib`. All D +compilers include the `/usr/include/d` directory by default, and if +your library would be installed into `/usr/include/d/mylib`, there is +a high chance that, when you compile your project again on a machine +where you installed it, the compiler will prefer the old installed +include over the new version in the source tree, leading to very +confusing errors. This is an example of how to use the D library we just built and installed in an application: @@ -113,7 +119,9 @@ compilers will lead to problems. # Integrating with DUB DUB is a fully integrated build system for D, but it is also a way to -provide dependencies. Adding dependencies from the [D package registry](https://code.dlang.org/) -is pretty straight forward. You can find how to do this in -[Dependencies](Dependencies.md#some-notes-on-dub). You can also automatically -generate a `dub.json` file as explained in [Dlang](Dlang-module.md#generate_dub_file). +provide dependencies. Adding dependencies from the [D package +registry](https://code.dlang.org/) is pretty straight forward. You can +find how to do this in +[Dependencies](Dependencies.md#some-notes-on-dub). You can also +automatically generate a `dub.json` file as explained in +[Dlang](Dlang-module.md#generate_dub_file). diff --git a/docs/markdown/Dependencies.md b/docs/markdown/Dependencies.md index aa93712..d357ec1 100644 --- a/docs/markdown/Dependencies.md +++ b/docs/markdown/Dependencies.md @@ -69,10 +69,10 @@ page](#dependencies-with-custom-lookup-functionality). *Note* new in 0.51.0 *new in 0.54.0, the `internal` keyword* -When you need to get an arbitrary variables from a dependency that can be -found multiple ways and you don't want to constrain the type you can use -the generic `get_variable` method. This currently supports cmake, pkg-config, -and config-tool based variables. +When you need to get an arbitrary variables from a dependency that can +be found multiple ways and you don't want to constrain the type you +can use the generic `get_variable` method. This currently supports +cmake, pkg-config, and config-tool based variables. ```meson foo_dep = dependency('foo') @@ -80,14 +80,15 @@ var = foo_dep.get_variable(cmake : 'CMAKE_VAR', pkgconfig : 'pkg-config-var', co ``` It accepts the keywords 'cmake', 'pkgconfig', 'pkgconfig_define', -'configtool', 'internal', and 'default_value'. 'pkgconfig_define' works just -like the 'define_variable' argument to `get_pkgconfig_variable`. When this -method is invoked the keyword corresponding to the underlying type of the -dependency will be used to look for a variable. If that variable cannot be -found or if the caller does not provide an argument for the type of -dependency, one of the following will happen: If 'default_value' was provided -that value will be returned, if 'default_value' was not provided then an -error will be raised. +'configtool', 'internal', and 'default_value'. 'pkgconfig_define' +works just like the 'define_variable' argument to +`get_pkgconfig_variable`. When this method is invoked the keyword +corresponding to the underlying type of the dependency will be used to +look for a variable. If that variable cannot be found or if the caller +does not provide an argument for the type of dependency, one of the +following will happen: If 'default_value' was provided that value will +be returned, if 'default_value' was not provided then an error will be +raised. # Declaring your own @@ -130,8 +131,8 @@ What this declaration means is that first Meson tries to look up the dependency from the system (such as by using pkg-config). If it is not available, then it builds subproject named `foo` and from that extracts a variable `foo_dep`. That means that the return value of -this function is either an external or an internal dependency -object. Since they can be used interchangeably, the rest of the build +this function is either an external or an internal dependency object. +Since they can be used interchangeably, the rest of the build definitions do not need to care which one it is. Meson will take care of all the work behind the scenes to make this work. @@ -156,14 +157,14 @@ The dependency method order for `auto` is: Meson can use the CMake `find_package()` function to detect dependencies with the builtin `Find<NAME>.cmake` modules and exported -project configurations (usually in `/usr/lib/cmake`). Meson is able -to use both the old-style `<NAME>_LIBRARIES` variables as well as +project configurations (usually in `/usr/lib/cmake`). Meson is able to +use both the old-style `<NAME>_LIBRARIES` variables as well as imported targets. It is possible to manually specify a list of CMake targets that should be used with the `modules` property. However, this step is optional -since meson tries to automatically guess the correct target based on the -name of the dependency. +since meson tries to automatically guess the correct target based on +the name of the dependency. Depending on the dependency it may be necessary to explicitly specify a CMake target with the `modules` property if meson is unable to guess @@ -173,22 +174,25 @@ it automatically. cmake_dep = dependency('ZLIB', method : 'cmake', modules : ['ZLIB::ZLIB']) ``` -Support for adding additional `COMPONENTS` for the CMake `find_package` lookup -is provided with the `components` kwarg (*introduced in 0.54.0*). All specified -componets will be passed directly to `find_package(COMPONENTS)`. +Support for adding additional `COMPONENTS` for the CMake +`find_package` lookup is provided with the `components` kwarg +(*introduced in 0.54.0*). All specified componets will be passed +directly to `find_package(COMPONENTS)`. Support for packages which require a specified version for CMake -`find_package` to succeed is provided with the `cmake_package_version` kwarg -(*introduced in 0.57.0*). The specified `cmake_package_version` will be -passed directly as the second parameter to `find_package`. +`find_package` to succeed is provided with the `cmake_package_version` +kwarg (*introduced in 0.57.0*). The specified `cmake_package_version` +will be passed directly as the second parameter to `find_package`. -It is also possible to reuse existing `Find<name>.cmake` files with the -`cmake_module_path` property. Using this property is equivalent to setting the -`CMAKE_MODULE_PATH` variable in CMake. The path(s) given to `cmake_module_path` -should all be relative to the project source directory. Absolute paths -should only be used if the CMake files are not stored in the project itself. +It is also possible to reuse existing `Find<name>.cmake` files with +the `cmake_module_path` property. Using this property is equivalent to +setting the `CMAKE_MODULE_PATH` variable in CMake. The path(s) given +to `cmake_module_path` should all be relative to the project source +directory. Absolute paths should only be used if the CMake files are +not stored in the project itself. -Additional CMake parameters can be specified with the `cmake_args` property. +Additional CMake parameters can be specified with the `cmake_args` +property. ## Dub @@ -216,15 +220,16 @@ DC="dmd" meson builddir Some dependencies have specific detection logic. Generic dependency names are case-sensitive<sup>[1](#footnote1)</sup>, -but these dependency names are matched case-insensitively. The +but these dependency names are matched case-insensitively. The recommended style is to write them in all lower-case. -In some cases, more than one detection method exists, and the `method` keyword -may be used to select a detection method to use. The `auto` method uses any -checking mechanisms in whatever order meson thinks is best. +In some cases, more than one detection method exists, and the `method` +keyword may be used to select a detection method to use. The `auto` +method uses any checking mechanisms in whatever order meson thinks is +best. -e.g. libwmf and CUPS provide both pkg-config and config-tool support. You can -force one or another via the `method` keyword: +e.g. libwmf and CUPS provide both pkg-config and config-tool support. +You can force one or another via the `method` keyword: ```meson cups_dep = dependency('cups', method : 'pkg-config') @@ -247,8 +252,9 @@ libgcrypt_dep = dependency('libgcrypt', version: '>= 1.8') gpgme_dep = dependency('gpgme', version: '>= 1.0') ``` -*Since 0.55.0* Meson won't search $PATH any more for a config tool binary when -cross compiling if the config tool did not have an entry in the cross file. +*Since 0.55.0* Meson won't search $PATH any more for a config tool +binary when cross compiling if the config tool did not have an entry +in the cross file. ## AppleFrameworks @@ -293,12 +299,12 @@ You can call `dependency` multiple times with different modules and use those to link against your targets. If your boost headers or libraries are in non-standard locations you -can set the `BOOST_ROOT`, or the `BOOST_INCLUDEDIR` and `BOOST_LIBRARYDIR` -environment variables. *(added in 0.56.0)* You can also set these -parameters as `boost_root`, `boost_include`, and `boost_librarydir` in your -native or cross machine file. Note that machine file variables are -preferred to environment variables, and that specifying any of these -disables system-wide search for boost. +can set the `BOOST_ROOT`, or the `BOOST_INCLUDEDIR` and +`BOOST_LIBRARYDIR` environment variables. *(added in 0.56.0)* You can +also set these parameters as `boost_root`, `boost_include`, and +`boost_librarydir` in your native or cross machine file. Note that +machine file variables are preferred to environment variables, and +that specifying any of these disables system-wide search for boost. You can set the argument `threading` to `single` to use boost libraries that have been compiled for single-threaded use instead. @@ -367,12 +373,15 @@ language-specific, you must specify the requested language using the * `dependency('hdf5', language: 'cpp')` for the C++ HDF5 headers and libraries * `dependency('hdf5', language: 'fortran')` for the Fortran HDF5 headers and libraries -Meson uses pkg-config to find HDF5. The standard low-level HDF5 function and the `HL` high-level HDF5 functions are linked for each language. +Meson uses pkg-config to find HDF5. The standard low-level HDF5 +function and the `HL` high-level HDF5 functions are linked for each +language. `method` may be `auto`, `config-tool` or `pkg-config`. *New in 0.56.0* the `config-tool` method. -*New in 0.56.0* the dependencies now return proper dependency types and `get_variable` and similar methods should work as expected. +*New in 0.56.0* the dependencies now return proper dependency types + and `get_variable` and similar methods should work as expected. ## libwmf @@ -382,13 +391,13 @@ Meson uses pkg-config to find HDF5. The standard low-level HDF5 function and the ## LLVM -Meson has native support for LLVM going back to version LLVM version 3.5. -It supports a few additional features compared to other config-tool based -dependencies. +Meson has native support for LLVM going back to version LLVM version +3.5. It supports a few additional features compared to other +config-tool based dependencies. -As of 0.44.0 Meson supports the `static` keyword argument for -LLVM. Before this LLVM >= 3.9 would always dynamically link, while -older versions would statically link, due to a quirk in `llvm-config`. +As of 0.44.0 Meson supports the `static` keyword argument for LLVM. +Before this LLVM >= 3.9 would always dynamically link, while older +versions would statically link, due to a quirk in `llvm-config`. `method` may be `auto`, `config-tool`, or `cmake`. @@ -412,10 +421,13 @@ llvm_dep = dependency( ``` ### Using LLVM tools -When using LLVM as library but also needing its tools, it is often beneficial to use the same version. -This can partially be achieved with the `version` argument of `find_program()`. -However, distributions tend to package different LLVM versions in rather different ways. -Therefore, it is often better to use the llvm dependency directly to retrieve the tools: + +When using LLVM as library but also needing its tools, it is often +beneficial to use the same version. This can partially be achieved +with the `version` argument of `find_program()`. However, +distributions tend to package different LLVM versions in rather +different ways. Therefore, it is often better to use the llvm +dependency directly to retrieve the tools: ```meson llvm_dep = dependency('llvm', version : ['>= 8', '< 9']) @@ -495,9 +507,9 @@ Python3 is handled specially by meson: - On Windows the fallback is the current `python3` interpreter. - On OSX the fallback is a framework dependency from `/Library/Frameworks`. -Note that `python3` found by this dependency might differ from the one used in -`python3` module because modules uses the current interpreter, but dependency tries -`pkg-config` first. +Note that `python3` found by this dependency might differ from the one +used in `python3` module because modules uses the current interpreter, +but dependency tries `pkg-config` first. `method` may be `auto`, `extraframework`, `pkg-config` or `sysconfig` @@ -534,42 +546,46 @@ the list of sources for the target. The `modules` keyword of `dependency` works just like it does with Boost. It tells which subparts of Qt the program uses. -You can set the `main` keyword argument to `true` to use the `WinMain()` -function provided by qtmain static library (this argument does nothing on platforms -other than Windows). +You can set the `main` keyword argument to `true` to use the +`WinMain()` function provided by qtmain static library (this argument +does nothing on platforms other than Windows). -Setting the optional `private_headers` keyword to true adds the private header -include path of the given module(s) to the compiler flags. (since v0.47.0) +Setting the optional `private_headers` keyword to true adds the +private header include path of the given module(s) to the compiler +flags. (since v0.47.0) -**Note** using private headers in your project is a bad idea, do so at your own -risk. +**Note** using private headers in your project is a bad idea, do so at +your own risk. `method` may be `auto`, `pkg-config` or `qmake`. ## SDL2 -SDL2 can be located using `pkg-confg`, the `sdl2-config` config tool, or as an -OSX framework. +SDL2 can be located using `pkg-confg`, the `sdl2-config` config tool, +or as an OSX framework. -`method` may be `auto`, `config-tool`, `extraframework` or `pkg-config`. +`method` may be `auto`, `config-tool`, `extraframework` or +`pkg-config`. ## Threads -This dependency selects the appropriate compiler flags and/or libraries to use -for thread support. +This dependency selects the appropriate compiler flags and/or +libraries to use for thread support. See [threads](Threads.md). ## Valgrind -Meson will find valgrind using `pkg-config`, but only uses the compilation flags -and avoids trying to link with it's non-PIC static libs. +Meson will find valgrind using `pkg-config`, but only uses the +compilation flags and avoids trying to link with it's non-PIC static +libs. ## Vulkan *(added 0.42.0)* -Vulkan can be located using `pkg-config`, or the `VULKAN_SDK` environment variable. +Vulkan can be located using `pkg-config`, or the `VULKAN_SDK` +environment variable. `method` may be `auto`, `pkg-config` or `system`. @@ -601,20 +617,22 @@ $ wx-config --libs std stc *(added 0.51.0)* -Shaderc currently does not ship with any means of detection. Nevertheless, Meson -can try to detect it using `pkg-config`, but will default to looking for the -appropriate library manually. If the `static` keyword argument is `true`, -`shaderc_combined` is preferred. Otherwise, `shaderc_shared` is preferred. Note -that it is not possible to obtain the shaderc version using this method. +Shaderc currently does not ship with any means of detection. +Nevertheless, Meson can try to detect it using `pkg-config`, but will +default to looking for the appropriate library manually. If the +`static` keyword argument is `true`, `shaderc_combined` is preferred. +Otherwise, `shaderc_shared` is preferred. Note that it is not possible +to obtain the shaderc version using this method. `method` may be `auto`, `pkg-config` or `system`. ## Zlib -Zlib ships with pkg-config and cmake support, but on some operating systems -(windows, macOs, FreeBSD, dragonflybsd), it is provided as part of the base -operating system without pkg-config support. The new System finder can be used -on these OSes to link with the bundled version. +Zlib ships with pkg-config and cmake support, but on some operating +systems (windows, macOs, FreeBSD, dragonflybsd), it is provided as +part of the base operating system without pkg-config support. The new +System finder can be used on these OSes to link with the bundled +version. `method` may be `auto`, `pkg-config`, `cmake`, or `system`. @@ -624,9 +642,9 @@ on these OSes to link with the bundled version. *(Since 0.54.0)* -Curses (and ncurses) are a cross platform pain in the butt. Meson wraps up -these dependencies in the `curses` dependency. This covers both `ncurses` -(preferred) and other curses implementations. +Curses (and ncurses) are a cross platform pain in the butt. Meson +wraps up these dependencies in the `curses` dependency. This covers +both `ncurses` (preferred) and other curses implementations. `method` may be `auto`, `pkg-config`, `config-tool`, or `system`. diff --git a/docs/markdown/Design-rationale.md b/docs/markdown/Design-rationale.md index 7121192..462129e 100644 --- a/docs/markdown/Design-rationale.md +++ b/docs/markdown/Design-rationale.md @@ -2,7 +2,8 @@ title: Design rationale ... -This is the original design rationale for Meson. The syntax it describes does not match the released version +This is the original design rationale for Meson. The syntax it +describes does not match the released version == A software developer's most important tool is the editor. If you talk @@ -65,7 +66,8 @@ what would it take to build a "good" build system. What kind of syntax would suit this problem? What sort of problems would this application need to solve? What sort of solutions would be the most appropriate? -To get things started, here is a list of requirements any modern cross-platform build system needs to provide. +To get things started, here is a list of requirements any modern +cross-platform build system needs to provide. ### 1. Must be simple to use @@ -174,7 +176,8 @@ examples we would like to emphasize that this is not in any way the final code. It is proof of concept code that works in the system as it currently exists (February 2013), but may change at any time. -Let's start simple. Here is the code to compile a single executable binary. +Let's start simple. Here is the code to compile a single executable +binary. ```meson project('compile one', 'c') diff --git a/docs/markdown/Dlang-module.md b/docs/markdown/Dlang-module.md index 677359d..7221698 100644 --- a/docs/markdown/Dlang-module.md +++ b/docs/markdown/Dlang-module.md @@ -40,4 +40,5 @@ initial one. The module will only update the values specified in `generate_dub_file()`. Although not required, you will need to have a `description` and -`license` if you want to publish the package in the [D package registry](https://code.dlang.org/). +`license` if you want to publish the package in the [D package +registry](https://code.dlang.org/). diff --git a/docs/markdown/External-Project-module.md b/docs/markdown/External-Project-module.md index 54b248f..65bd92d 100644 --- a/docs/markdown/External-Project-module.md +++ b/docs/markdown/External-Project-module.md @@ -5,19 +5,21 @@ *This is an experimental module, API could change.* -This module allows building code that uses build systems other than Meson. This -module is intended to be used to build Autotools subprojects as fallback if the -dependency couldn't be found on the system (e.g. too old distro version). - -The project will be compiled out-of-tree inside Meson's build directory. The -project will also be installed inside Meson's build directory using make's +This module allows building code that uses build systems other than +Meson. This module is intended to be used to build Autotools +subprojects as fallback if the dependency couldn't be found on the +system (e.g. too old distro version). + +The project will be compiled out-of-tree inside Meson's build +directory. The project will also be installed inside Meson's build +directory using make's [`DESTDIR`](https://www.gnu.org/prep/standards/html_node/DESTDIR.html) -feature. During project installation step, that DESTDIR will be copied verbatim -into the desired location. +feature. During project installation step, that DESTDIR will be copied +verbatim into the desired location. -External subprojects can use libraries built by Meson (main project, or other -subprojects) using pkg-config, thanks to `*-uninstalled.pc` files generated by -[`pkg.generate()`](Pkgconfig-module.md). +External subprojects can use libraries built by Meson (main project, +or other subprojects) using pkg-config, thanks to `*-uninstalled.pc` +files generated by [`pkg.generate()`](Pkgconfig-module.md). External build system requirements: - Must support out-of-tree build. The configure script will be invoked with the @@ -49,13 +51,13 @@ Known limitations: ### `add_project()` -This function should be called at the root directory of a project using another -build system. Usually in a `meson.build` file placed in the top directory of a -subproject, but could be also in any subdir. +This function should be called at the root directory of a project +using another build system. Usually in a `meson.build` file placed in +the top directory of a subproject, but could be also in any subdir. -Its first positional argument is the name of the configure script to be -executed (e.g. `configure` or `autogen.sh`), that file must be in the current -directory and executable. +Its first positional argument is the name of the configure script to +be executed (e.g. `configure` or `autogen.sh`), that file must be in +the current directory and executable. Keyword arguments: - `configure_options`: An array of strings to be passed as arguments to the @@ -81,8 +83,8 @@ Returns an [`ExternalProject`](#ExternalProject_object) object #### `dependency(libname)` -Return a dependency object that can be used to build targets against a library -from the external project. +Return a dependency object that can be used to build targets against a +library from the external project. Keyword arguments: - `subdir` path relative to `includedir` to be added to the header search path. @@ -109,8 +111,9 @@ mylib_dep = p.dependency('mylib') ## Using wrap file -Most of the time the project will be built as a subproject, and fetched using -a `.wrap` file. In that case the simple `meson.build` file needed to build the -subproject can be provided by adding `patch_directory=mysubproject` line -in the wrap file, and place the build definition file at +Most of the time the project will be built as a subproject, and +fetched using a `.wrap` file. In that case the simple `meson.build` +file needed to build the subproject can be provided by adding +`patch_directory=mysubproject` line in the wrap file, and place the +build definition file at `subprojects/packagefiles/mysubproject/meson.build`. diff --git a/docs/markdown/External-commands.md b/docs/markdown/External-commands.md index 272182c..be9d171 100644 --- a/docs/markdown/External-commands.md +++ b/docs/markdown/External-commands.md @@ -33,14 +33,14 @@ run_command('command', 'arg1', 'arg2', env: env) The `run_command` function returns an object that can be queried for return value and text written to stdout and stderr. The `strip` method -call is used to strip trailing and leading whitespace from -strings. Usually output from command line programs ends in a newline, -which is unwanted in string variables. The first argument can be -either a string or an executable you have detected earlier with -`find_program`. +call is used to strip trailing and leading whitespace from strings. +Usually output from command line programs ends in a newline, which is +unwanted in string variables. The first argument can be either a +string or an executable you have detected earlier with `find_program`. Meson will autodetect scripts with a shebang line and run them with -the executable/interpreter specified in it both on Windows and on Unixes. +the executable/interpreter specified in it both on Windows and on +Unixes. Note that you can not pass your command line as a single string. That is, calling `run_command('do_something foo bar')` will not work. You diff --git a/docs/markdown/FAQ.md b/docs/markdown/FAQ.md index b0db361..bd2316f 100644 --- a/docs/markdown/FAQ.md +++ b/docs/markdown/FAQ.md @@ -61,10 +61,10 @@ Instead of specifying files explicitly, people seem to want to do this: executable('myprog', sources : '*.cpp') # This does NOT work! ``` -Meson does not support this syntax and the reason for this is -simple. This can not be made both reliable and fast. By reliable we -mean that if the user adds a new source file to the subdirectory, -Meson should detect that and make it part of the build automatically. +Meson does not support this syntax and the reason for this is simple. +This can not be made both reliable and fast. By reliable we mean that +if the user adds a new source file to the subdirectory, Meson should +detect that and make it part of the build automatically. One of the main requirements of Meson is that it must be fast. This means that a no-op build in a tree of 10 000 source files must take no @@ -396,12 +396,14 @@ advantages: so specifying `libfoo.a` instead of `foo.lib` does not change the workflow, and is an improvement since it's less ambiguous. -If, for some reason, you really need your project to output static libraries of -the form `foo.lib` when building with MSVC, you can set the +If, for some reason, you really need your project to output static +libraries of the form `foo.lib` when building with MSVC, you can set +the [`name_prefix:`](https://mesonbuild.com/Reference-manual.html#library) -kwarg to `''` and the [`name_suffix:`](https://mesonbuild.com/Reference-manual.html#library) -kwarg to `'lib'`. To get the default behaviour for each, you can either not -specify the kwarg, or pass `[]` (an empty array) to it. +kwarg to `''` and the +[`name_suffix:`](https://mesonbuild.com/Reference-manual.html#library) +kwarg to `'lib'`. To get the default behaviour for each, you can +either not specify the kwarg, or pass `[]` (an empty array) to it. ## Do I need to add my headers to the sources list like in Autotools? diff --git a/docs/markdown/Fs-module.md b/docs/markdown/Fs-module.md index 29273de..d4945e9 100644 --- a/docs/markdown/Fs-module.md +++ b/docs/markdown/Fs-module.md @@ -72,11 +72,12 @@ The `fs.size(filename)` method returns the size of the file in integer bytes. ### is_samepath -The `fs.is_samepath(path1, path2)` returns boolean `true` if both paths resolve to the same path. -For example, suppose path1 is a symlink and path2 is a relative path. -If path1 can be resolved to path2, then `true` is returned. -If path1 is not resolved to path2, `false` is returned. -If path1 or path2 do not exist, `false` is returned. +The `fs.is_samepath(path1, path2)` returns boolean `true` if both +paths resolve to the same path. For example, suppose path1 is a +symlink and path2 is a relative path. If `path1` can be resolved to +`path2`, then `true` is returned. If `path1` is not resolved to +`path2`, `false` is returned. If `path1` or `path2` do not exist, +`false` is returned. Examples: @@ -102,13 +103,15 @@ fs.is_samepath(p, s) # false ## Filename modification -The files need not actually exist yet for these path string manipulation methods. +The files need not actually exist yet for these path string +manipulation methods. ### expanduser *since 0.54.0* -A path string with a leading `~` is expanded to the user home directory +A path string with a leading `~` is expanded to the user home +directory Examples: @@ -122,8 +125,9 @@ fs.expanduser('~/foo') # <homedir>/foo *since 0.54.0* -`fs.as_posix(path)` assumes a Windows path, even if on a Unix-like system. -Thus, all `'\'` or `'\\'` are turned to '/', even if you meant to escape a character. +`fs.as_posix(path)` assumes a Windows path, even if on a Unix-like +system. Thus, all `'\'` or `'\\'` are turned to '/', even if you meant +to escape a character. Examples @@ -136,8 +140,8 @@ fs.as_posix('foo\\bar/baz') == 'foo/bar/baz' # true ### replace_suffix -The `replace_suffix` method is a *string manipulation* convenient for filename modifications. -It allows changing the filename suffix like: +The `replace_suffix` method is a *string manipulation* convenient for +filename modifications. It allows changing the filename suffix like: #### swap suffix @@ -188,7 +192,8 @@ fs.name('foo/bar/baz.dll.a') # baz.dll.a *since 0.54.0* -Returns the last component of the path, dropping the last part of the suffix +Returns the last component of the path, dropping the last part of the +suffix ```meson fs.stem('foo/bar/baz.dll') # baz diff --git a/docs/markdown/Generating-sources.md b/docs/markdown/Generating-sources.md index e22112f..44e36b7 100644 --- a/docs/markdown/Generating-sources.md +++ b/docs/markdown/Generating-sources.md @@ -48,8 +48,9 @@ Then you just put that in your program and you're done. ### Generating headers -Adding a generated header to a source list will ensure that the header is -generated and that the proper include paths are created for the target: +Adding a generated header to a source list will ensure that the header +is generated and that the proper include paths are created for the +target: ```meson prog_python = import('python').find_installation('python3') @@ -73,18 +74,19 @@ libfoo = static_library('foo', [foo_c, foo_h]) executable('myexe', ['main.c', foo_h], link_with : libfoo) ``` -Each target that depends on a generated header should add that header to it's sources, -as seen above with `libfoo` and `myexe`. This is because there is no way for -meson or the backend to know that `myexe` depends on `foo.h` just because -`libfoo` does, it could be a private header. +Each target that depends on a generated header should add that header +to it's sources, as seen above with `libfoo` and `myexe`. This is +because there is no way for meson or the backend to know that `myexe` +depends on `foo.h` just because `libfoo` does, it could be a private +header. ### Generating multiple files at a time -Sometimes it makes sense for a single generator to create two or more files at -a time, (perhaps a header and source file), meson has this case covered as -well. `custom_target`s can be indexed like a list to get each output file -separately. The order is the same as the order of the output argument to -`custom_target` +Sometimes it makes sense for a single generator to create two or more +files at a time, (perhaps a header and source file), meson has this +case covered as well. `custom_target`s can be indexed like a list to +get each output file separately. The order is the same as the order of +the output argument to `custom_target` ```meson prog_python = import('python').find_installation('python3') @@ -101,13 +103,14 @@ libfoo = static_library('foo', [foo_ch]) executable('myexe', ['main.c', foo_ch[1]], link_with : libfoo) ``` -In this case `libfoo` depends on both `foo.c` and `foo.h` but `myexe` only -depends on `foo.h`, the second output. +In this case `libfoo` depends on both `foo.c` and `foo.h` but `myexe` +only depends on `foo.h`, the second output. ### Using dependencies to manage generated resources -In some cases it might be easier to use `declare_dependency` to "bundle" the header -and library dependency, especially if there are many generated headers: +In some cases it might be easier to use `declare_dependency` to +"bundle" the header and library dependency, especially if there are +many generated headers: ```meson idep_foo = declare_dependency( @@ -117,7 +120,8 @@ idep_foo = declare_dependency( ``` See [dependencies](Dependencies.md#declaring-your-own), and -[reference](Reference-manual.md#declare_dependency) for more information. +[reference](Reference-manual.md#declare_dependency) for more +information. ## Using generator() diff --git a/docs/markdown/Gnome-module.md b/docs/markdown/Gnome-module.md index 3d06233..fd58d51 100644 --- a/docs/markdown/Gnome-module.md +++ b/docs/markdown/Gnome-module.md @@ -3,7 +3,7 @@ This module provides helper tools for build operations needed when building Gnome/GLib programs. -**Note**:Â the compilation commands here might not work properly when +**Note**: the compilation commands here might not work properly when you change the source files. This is a bug in the respective compilers which do not expose the required dependency information. This has been reported upstream in [this bug]. Until @@ -128,9 +128,9 @@ Returns an array of two elements which are: `[c_source, header_file]` ### gnome.mkenums() Generates enum files for GObject using the `glib-mkenums` tool. The -first argument is the base name of the output files, unless `c_template` -and `h_template` are specified. In this case, the output files will be -the base name of the values passed as templates. +first argument is the base name of the output files, unless +`c_template` and `h_template` are specified. In this case, the output +files will be the base name of the values passed as templates. This method is essentially a wrapper around the `glib-mkenums` tool's command line API. It is the most featureful method for enum creation. @@ -252,14 +252,14 @@ one XML file. bundle depending on previous options * `install_header`: (*Added 0.46.0*) if true, install the header file -Starting *0.46.0*, this function returns a list of at least two custom targets -(in order): one for the source code and one for the header. The list will -contain a third custom target for the generated docbook files if that keyword -argument is passed. +Starting *0.46.0*, this function returns a list of at least two custom +targets (in order): one for the source code and one for the header. +The list will contain a third custom target for the generated docbook +files if that keyword argument is passed. -Earlier versions return a single custom target representing all the outputs. -Generally, you should just add this list of targets to a top level target's -source list. +Earlier versions return a single custom target representing all the +outputs. Generally, you should just add this list of targets to a top +level target's source list. Example: @@ -344,11 +344,12 @@ of the module. Note that this has the downside of rebuilding the doc for each build, which is often very slow. It usually should be enabled only in CI. -This also creates a `$module-doc` target that can be run to build documentation. -Normally the documentation is only built on install. +This also creates a `$module-doc` target that can be run to build +documentation. Normally the documentation is only built on install. -*Since 0.52.0* Returns a target object that can be passed as dependency to other -targets using generated doc files (e.g. in `content_files` of another doc). +*Since 0.52.0* Returns a target object that can be passed as +dependency to other targets using generated doc files (e.g. in +`content_files` of another doc). ### gnome.gtkdoc_html_dir() diff --git a/docs/markdown/IDE-integration.md b/docs/markdown/IDE-integration.md index 5cd72ba..9b550ca 100644 --- a/docs/markdown/IDE-integration.md +++ b/docs/markdown/IDE-integration.md @@ -4,29 +4,31 @@ short-description: Meson's API to integrate Meson support into an IDE # IDE integration -Meson has exporters for Visual Studio and XCode, but writing a custom backend -for every IDE out there is not a scalable approach. To solve this problem, -Meson provides an API that makes it easy for any IDE or build tools to -integrate Meson builds and provide an experience comparable to a solution -native to the IDE. +Meson has exporters for Visual Studio and XCode, but writing a custom +backend for every IDE out there is not a scalable approach. To solve +this problem, Meson provides an API that makes it easy for any IDE or +build tools to integrate Meson builds and provide an experience +comparable to a solution native to the IDE. All the resources required for such a IDE integration can be found in the `meson-info` directory in the build directory. -The first thing to do when setting up a Meson project in an IDE is to select -the source and build directories. For this example we assume that the source -resides in an Eclipse-like directory called `workspace/project` and the build -tree is nested inside it as `workspace/project/build`. First, we initialize -Meson by running the following command in the source directory. +The first thing to do when setting up a Meson project in an IDE is to +select the source and build directories. For this example we assume +that the source resides in an Eclipse-like directory called +`workspace/project` and the build tree is nested inside it as +`workspace/project/build`. First, we initialize Meson by running the +following command in the source directory. meson builddir With this command meson will configure the project and also generate -introspection information that is stored in `intro-*.json` files in the -`meson-info` directory. The introspection dump will be automatically updated -when meson is (re)configured, or the build options change. Thus, an IDE can -watch for changes in this directory to know when something changed. Note that -`meson-info.json` guaranteed to be the last file written. +introspection information that is stored in `intro-*.json` files in +the `meson-info` directory. The introspection dump will be +automatically updated when meson is (re)configured, or the build +options change. Thus, an IDE can watch for changes in this directory +to know when something changed. Note that `meson-info.json` guaranteed +to be the last file written. The `meson-info` directory should contain the following files: @@ -41,13 +43,14 @@ The `meson-info` directory should contain the following files: | `intro-targets.json` | Full list of all build targets | | `intro-tests.json` | Lists all tests with instructions how to run them | -The content of the JSON files is further specified in the remainder of this document. +The content of the JSON files is further specified in the remainder of +this document. ## The `targets` section -The most important file for an IDE is probably `intro-targets.json`. Here each -target with its sources and compiler parameters is specified. The JSON format -for one target is defined as follows: +The most important file for an IDE is probably `intro-targets.json`. +Here each target with its sources and compiler parameters is +specified. The JSON format for one target is defined as follows: ```json { @@ -64,25 +67,27 @@ for one target is defined as follows: } ``` -If the key `installed` is set to `true`, the key `install_filename` will also -be present. It stores the installation location for each file in `filename`. -If one file in `filename` is not installed, its corresponding install location -is set to `null`. +If the key `installed` is set to `true`, the key `install_filename` +will also be present. It stores the installation location for each +file in `filename`. If one file in `filename` is not installed, its +corresponding install location is set to `null`. -The `subproject` key specifies the name of the subproject this target was -defined in, or `null` if the target was defined in the top level project. +The `subproject` key specifies the name of the subproject this target +was defined in, or `null` if the target was defined in the top level +project. -*(New in 0.56.0)* The `extra_files` key lists all files specified via the -`extra_files` kwarg of a build target. See [`executable()`](Reference-manual.md#executable). +*(New in 0.56.0)* The `extra_files` key lists all files specified via +the `extra_files` kwarg of a build target. See +[`executable()`](Reference-manual.md#executable). -A target usually generates only one file. However, it is possible for custom -targets to have multiple outputs. +A target usually generates only one file. However, it is possible for +custom targets to have multiple outputs. ### Target sources -The `intro-targets.json` file also stores a list of all source objects of the -target in the `target_sources`. With this information, an IDE can provide code -completion for all source files. +The `intro-targets.json` file also stores a list of all source objects +of the target in the `target_sources`. With this information, an IDE +can provide code completion for all source files. ```json { @@ -94,11 +99,11 @@ completion for all source files. } ``` -It should be noted that the compiler parameters stored in the `parameters` -differ from the actual parameters used to compile the file. This is because -the parameters are optimized for the usage in an IDE to provide autocompletion -support, etc. It is thus not recommended to use this introspection information -for actual compilation. +It should be noted that the compiler parameters stored in the +`parameters` differ from the actual parameters used to compile the +file. This is because the parameters are optimized for the usage in an +IDE to provide autocompletion support, etc. It is thus not recommended +to use this introspection information for actual compilation. ### Possible values for `type` @@ -116,12 +121,13 @@ The following table shows all valid types for a target. ### Using `--targets` without a build directory -It is also possible to get most targets without a build directory. This can be -done by running `meson introspect --targets /path/to/meson.build`. +It is also possible to get most targets without a build directory. +This can be done by running `meson introspect --targets +/path/to/meson.build`. -The generated output is similar to running the introspection with a build -directory or reading the `intro-targets.json`. However, there are some key -differences: +The generated output is similar to running the introspection with a +build directory or reading the `intro-targets.json`. However, there +are some key differences: - The paths in `filename` now are _relative_ to the future build directory - The `install_filename` key is completely missing @@ -130,17 +136,18 @@ differences: - Empty lists for `compiler` and `parameters` and `generated_sources` - The `sources` list _should_ contain all sources of the target -There is no guarantee that the sources list in `target_sources` is correct. -There might be differences, due to internal limitations. It is also not -guaranteed that all targets will be listed in the output. It might even be -possible that targets are listed, which won't exist when meson is run normally. -This can happen if a target is defined inside an if statement. -Use this feature with care. +There is no guarantee that the sources list in `target_sources` is +correct. There might be differences, due to internal limitations. It +is also not guaranteed that all targets will be listed in the output. +It might even be possible that targets are listed, which won't exist +when meson is run normally. This can happen if a target is defined +inside an if statement. Use this feature with care. ## Build Options -The list of all build options (build type, warning level, etc.) is stored in -the `intro-buildoptions.json` file. Here is the JSON format for each option. +The list of all build options (build type, warning level, etc.) is +stored in the `intro-buildoptions.json` file. Here is the JSON format +for each option. ```json { @@ -161,8 +168,8 @@ The supported types are: - integer - array -For the type `combo` the key `choices` is also present. Here all valid values -for the option are stored. +For the type `combo` the key `choices` is also present. Here all valid +values for the option are stored. The possible values for `section` are: @@ -174,8 +181,8 @@ The possible values for `section` are: - user - test -The `machine` key specifies the machine configuration for the option. Possible -values are: +The `machine` key specifies the machine configuration for the option. +Possible values are: - any - host @@ -184,26 +191,28 @@ values are: To set the options, use the `meson configure` command. Since Meson 0.50.0 it is also possible to get the default buildoptions -without a build directory by providing the root `meson.build` instead of a -build directory to `meson introspect --buildoptions`. +without a build directory by providing the root `meson.build` instead +of a build directory to `meson introspect --buildoptions`. -Running `--buildoptions` without a build directory produces the same output as -running it with a freshly configured build directory. +Running `--buildoptions` without a build directory produces the same +output as running it with a freshly configured build directory. -However, this behavior is not guaranteed if subprojects are present. Due to -internal limitations all subprojects are processed even if they are never used -in a real meson run. Because of this options for the subprojects can differ. +However, this behavior is not guaranteed if subprojects are present. +Due to internal limitations all subprojects are processed even if they +are never used in a real meson run. Because of this options for the +subprojects can differ. ## The dependencies section The list of all _found_ dependencies can be acquired from -`intro-dependencies.json`. Here, the name, version, compiler and linker -arguments for a dependency are listed. +`intro-dependencies.json`. Here, the name, version, compiler and +linker arguments for a dependency are listed. ### Scanning for dependecie with `--scan-dependencies` -It is also possible to get most dependencies used without a build directory. -This can be done by running `meson introspect --scan-dependencies /path/to/meson.build`. +It is also possible to get most dependencies used without a build +directory. This can be done by running `meson introspect +--scan-dependencies /path/to/meson.build`. The output format is as follows: @@ -219,28 +228,30 @@ The output format is as follows: ] ``` -The `required` keyword specifies whether the dependency is marked as required -in the `meson.build` (all dependencies are required by default). The -`conditional` key indicates whether the `dependency()` function was called -inside a conditional block. In a real meson run these dependencies might not be -used, thus they _may_ not be required, even if the `required` key is set. The -`has_fallback` key just indicates whether a fallback was directly set in the -`dependency()` function. The `version` key always contains a list of version -requirements from the `meson.build` and **not** the actual version of the -dependency on disc. The version list is empty if no version was specified -in the `meson.build`. +The `required` keyword specifies whether the dependency is marked as +required in the `meson.build` (all dependencies are required by +default). The `conditional` key indicates whether the `dependency()` +function was called inside a conditional block. In a real meson run +these dependencies might not be used, thus they _may_ not be required, +even if the `required` key is set. The `has_fallback` key just +indicates whether a fallback was directly set in the `dependency()` +function. The `version` key always contains a list of version +requirements from the `meson.build` and **not** the actual version of +the dependency on disc. The version list is empty if no version was +specified in the `meson.build`. ## Tests -Compilation and unit tests are done as usual by running the `meson compile` and -`meson test` commands. A JSON formatted result log can be found in -`workspace/project/builddir/meson-logs/testlog.json`. +Compilation and unit tests are done as usual by running the `meson +compile` and `meson test` commands. A JSON formatted result log can be +found in `workspace/project/builddir/meson-logs/testlog.json`. -When these tests fail, the user probably wants to run the failing test in a -debugger. To make this as integrated as possible, extract the tests from the -`intro-tests.json` and `intro-benchmarks.json` files. This provides you with -all the information needed to run the test: what command to execute, command -line arguments, environment variable settings and how to process the output. +When these tests fail, the user probably wants to run the failing test +in a debugger. To make this as integrated as possible, extract the +tests from the `intro-tests.json` and `intro-benchmarks.json` files. +This provides you with all the information needed to run the test: +what command to execute, command line arguments, environment variable +settings and how to process the output. ```json { @@ -260,14 +271,15 @@ line arguments, environment variable settings and how to process the output. ``` The `depends` entry *(since 0.56.0)* contains target ids; they can be -looked up in the targets introspection data. The executable -pointed to by `cmd` is also included in the entry, as are any -arguments to the test that are build products. +looked up in the targets introspection data. The executable pointed to +by `cmd` is also included in the entry, as are any arguments to the +test that are build products. ## Build system files -It is also possible to get Meson build files used in your current project. This -can be done by running `meson introspect --buildsystem-files /path/to/builddir`. +It is also possible to get Meson build files used in your current +project. This can be done by running `meson introspect +--buildsystem-files /path/to/builddir`. The output format is as follows: @@ -281,15 +293,18 @@ The output format is as follows: # Programmatic interface -Meson also provides the `meson introspect` for project introspection via the -command line. Use `meson introspect -h` to see all available options. +Meson also provides the `meson introspect` for project introspection +via the command line. Use `meson introspect -h` to see all available +options. -This API can also work without a build directory for the `--projectinfo` command. +This API can also work without a build directory for the +`--projectinfo` command. # AST of a `meson.build` -Since meson *0.55.0* it is possible to dump the AST of a `meson.build` as a JSON -object. The interface for this is `meson introspect --ast /path/to/meson.build`. +Since meson *0.55.0* it is possible to dump the AST of a `meson.build` +as a JSON object. The interface for this is `meson introspect --ast +/path/to/meson.build`. Each node of the AST has at least the following entries: @@ -332,9 +347,10 @@ Possible values for `node` with additional keys: | `UMinusNode` | `right`: node | | `TernaryNode` | `condition`: node; `true`: node; `false`: node | -We do not guarantee the stability of this format since it is heavily linked to -the internal Meson AST. However, breaking changes (removal of a node type or the -removal of a key) are unlikely and will be announced in the release notes. +We do not guarantee the stability of this format since it is heavily +linked to the internal Meson AST. However, breaking changes (removal +of a node type or the removal of a key) are unlikely and will be +announced in the release notes. # Existing integrations diff --git a/docs/markdown/Icestorm-module.md b/docs/markdown/Icestorm-module.md index bc2ad61..10b64ef 100644 --- a/docs/markdown/Icestorm-module.md +++ b/docs/markdown/Icestorm-module.md @@ -2,14 +2,14 @@ This module is available since version 0.45.0. -**Note**:Â this module is unstable. It is only provided as a technology -preview. Its API may change in arbitrary ways between releases or it +**Note**: this module is unstable. It is only provided as a technology +preview. Its API may change in arbitrary ways between releases or it might be removed from Meson altogether. ## Usage -This module provides an experimental method to create FPGA bitstreams using -the [IceStorm](http://www.clifford.at/icestorm/) suite of tools. +This module provides an experimental method to create FPGA bitstreams +using the [IceStorm](http://www.clifford.at/icestorm/) suite of tools. The module exposes only one method called `project` and it is used like this: diff --git a/docs/markdown/Include-directories.md b/docs/markdown/Include-directories.md index c1d4ac1..6dfed5e 100644 --- a/docs/markdown/Include-directories.md +++ b/docs/markdown/Include-directories.md @@ -4,18 +4,27 @@ short-description: Instructions on handling include directories # Include directories -Most `C`/`C++` projects have headers in different directories than sources. Thus you need to specify include directories. Let's assume that we are at some subdirectory and wish to add its `include` subdirectory to some target's search path. To create a include directory object we do this: +Most `C`/`C++` projects have headers in different directories than +sources. Thus you need to specify include directories. Let's assume +that we are at some subdirectory and wish to add its `include` +subdirectory to some target's search path. To create a include +directory object we do this: ```meson incdir = include_directories('include') ``` -The `incdir` variable now holds a reference to the `include` subdir. Now we pass that as an argument to a build target: +The `incdir` variable now holds a reference to the `include` subdir. +Now we pass that as an argument to a build target: ```meson executable('someprog', 'someprog.c', include_directories : incdir) ``` -Note that these two commands can be given in any subdirectories and it will still work. Meson will keep track of the locations and generate proper compiler flags to make it all work. +Note that these two commands can be given in any subdirectories and it +will still work. Meson will keep track of the locations and generate +proper compiler flags to make it all work. -Another thing to note is that `include_directories` adds both the source directory and corresponding build directory to include path, so you don't have to care. +Another thing to note is that `include_directories` adds both the +source directory and corresponding build directory to include path, so +you don't have to care. diff --git a/docs/markdown/IndepthTutorial.md b/docs/markdown/IndepthTutorial.md index d2e2662..edbbe55 100644 --- a/docs/markdown/IndepthTutorial.md +++ b/docs/markdown/IndepthTutorial.md @@ -1,8 +1,16 @@ # An in-depth tutorial -In this tutorial we set up a project with multiple targets, unit tests and dependencies between targets. Our main product is a shared library called *foo* that is written in `C++11`. We are going to ignore the contents of the source files, as they are not really important from a build definition point of view. The library makes use of the `GLib` library so we need to detect and link it properly. We also make the resulting library installable. - -The source tree contains three subdirectories `src`, `include` and `test` that contain, respectively, the source code, headers and unit tests of our project. +In this tutorial we set up a project with multiple targets, unit tests +and dependencies between targets. Our main product is a shared library +called *foo* that is written in `C++11`. We are going to ignore the +contents of the source files, as they are not really important from a +build definition point of view. The library makes use of the `GLib` +library so we need to detect and link it properly. We also make the +resulting library installable. + +The source tree contains three subdirectories `src`, `include` and +`test` that contain, respectively, the source code, headers and unit +tests of our project. To start things up, here is the top level `meson.build` file. @@ -27,23 +35,47 @@ pkg_mod.generate(libraries : foolib, description : 'A Library to barnicate your foos.') ``` -The definition always starts with a call to the `project` function. In it you must specify the project's name and programming languages to use, in this case only `C++`. We also specify two additional arguments, the project's version and the license it is under. Our project is version `1.0.0` and is specified to be under the MIT license. - -Then we find GLib, which is an *external dependency*. The `dependency` function tells Meson to find the library (by default using `pkg-config`). If the library is not found, Meson will raise an error and stop processing the build definition. - -Then we add a global compiler argument `-DSOME_TOKEN=value`. This flag is used for *all* C++ source file compilations. It is not possible to unset it for some targets. The reason for this is that it is hard to keep track of what compiler flags are in use if global settings change per target. - -Since `include` directory contains the header files, we need a way to tell compilations to add that directory to the compiler command line. This is done with the `include_directories` command that takes a directory and returns an object representing this directory. It is stored in variable `inc` which makes it accessible later on. - -After this are three `subdir` commands. These instruct Meson to go to the specified subdirectory, open the `meson.build` file that's in there and execute it. The last few lines are a stanza to generate a `pkg-config` file. We'll skip that for now and come back to it at the end of this document. - -The first subdirectory we go into is `include`. In it we have a a header file for the library that we want to install. This requires one line. +The definition always starts with a call to the `project` function. In +it you must specify the project's name and programming languages to +use, in this case only `C++`. We also specify two additional +arguments, the project's version and the license it is under. Our +project is version `1.0.0` and is specified to be under the MIT +license. + +Then we find GLib, which is an *external dependency*. The `dependency` +function tells Meson to find the library (by default using +`pkg-config`). If the library is not found, Meson will raise an error +and stop processing the build definition. + +Then we add a global compiler argument `-DSOME_TOKEN=value`. This flag +is used for *all* C++ source file compilations. It is not possible to +unset it for some targets. The reason for this is that it is hard to +keep track of what compiler flags are in use if global settings change +per target. + +Since `include` directory contains the header files, we need a way to +tell compilations to add that directory to the compiler command line. +This is done with the `include_directories` command that takes a +directory and returns an object representing this directory. It is +stored in variable `inc` which makes it accessible later on. + +After this are three `subdir` commands. These instruct Meson to go to +the specified subdirectory, open the `meson.build` file that's in +there and execute it. The last few lines are a stanza to generate a +`pkg-config` file. We'll skip that for now and come back to it at the +end of this document. + +The first subdirectory we go into is `include`. In it we have a a +header file for the library that we want to install. This requires one +line. ```meson install_headers('foolib.h') ``` -This installs the given header file to the system's header directory. This is by default `/[install prefix]/include`, but it can be changed with a command line argument. +This installs the given header file to the system's header directory. +This is by default `/[install prefix]/include`, but it can be changed +with a command line argument. The Meson definition of `src` subdir is simple. @@ -56,11 +88,22 @@ foolib = shared_library('foo', install : true) ``` -Here we just tell Meson to build the library with the given sources. We also tell it to use the include directories we stored to variable `inc` earlier. Since this library uses GLib, we tell Meson to add all necessary compiler and linker flags with the `dependencies` keyword argument. Its value is `glib_dep` which we set at the top level `meson.build` file. The `install` argument tells Meson to install the result. As with the headers, the shared library is installed to the system's default location (usually `/[install prefix]/lib`) but is again overridable. +Here we just tell Meson to build the library with the given sources. +We also tell it to use the include directories we stored to variable +`inc` earlier. Since this library uses GLib, we tell Meson to add all +necessary compiler and linker flags with the `dependencies` keyword +argument. Its value is `glib_dep` which we set at the top level +`meson.build` file. The `install` argument tells Meson to install the +result. As with the headers, the shared library is installed to the +system's default location (usually `/[install prefix]/lib`) but is +again overridable. -The resulting library is stored in variable `foolib` just like the include directory was stored in the previous file. +The resulting library is stored in variable `foolib` just like the +include directory was stored in the previous file. -Once Meson has processed the `src` subdir it returns to the main Meson file and executes the next line that moves it into the `test` subdir. Its contents look like this. +Once Meson has processed the `src` subdir it returns to the main Meson +file and executes the next line that moves it into the `test` subdir. +Its contents look like this. ```meson testexe = executable('testexe', 'footest.cpp', @@ -69,13 +112,30 @@ testexe = executable('testexe', 'footest.cpp', test('foolib test', testexe) ``` -First we build a test executable that has the same include directory as the main library and which also links against the freshly built shared library. Note that you don't need to specify `glib_dep` here just to be able to use the built library `foolib`. If the executable used GLib functionality itself, then we would of course need to add it as a keyword argument here. - -Finally we define a test with the name `foolib test`. It consists of running the binary we just built. If the executable exits with a zero return value, the test is considered passed. Nonzero return values mark the test as failed. - -At this point we can return to the pkg-config generator line. All shared libraries should provide a pkg-config file, which explains how that library is used. Meson provides this simple generator that should be sufficient for most simple projects. All you need to do is list a few basic pieces of information and Meson takes care of generating an appropriate file. More advanced users might want to create their own pkg-config files using Meson's [configuration file generator system](Configuration.md). - -With these four files we are done. To configure, build and run the test suite, we just need to execute the following commands (starting at source tree root directory). +First we build a test executable that has the same include directory +as the main library and which also links against the freshly built +shared library. Note that you don't need to specify `glib_dep` here +just to be able to use the built library `foolib`. If the executable +used GLib functionality itself, then we would of course need to add it +as a keyword argument here. + +Finally we define a test with the name `foolib test`. It consists of +running the binary we just built. If the executable exits with a zero +return value, the test is considered passed. Nonzero return values +mark the test as failed. + +At this point we can return to the pkg-config generator line. All +shared libraries should provide a pkg-config file, which explains how +that library is used. Meson provides this simple generator that should +be sufficient for most simple projects. All you need to do is list a +few basic pieces of information and Meson takes care of generating an +appropriate file. More advanced users might want to create their own +pkg-config files using Meson's [configuration file generator +system](Configuration.md). + +With these four files we are done. To configure, build and run the +test suite, we just need to execute the following commands (starting +at source tree root directory). ```console $ meson builddir && cd builddir diff --git a/docs/markdown/Installing.md b/docs/markdown/Installing.md index 9dc2ad4..93f6d19 100644 --- a/docs/markdown/Installing.md +++ b/docs/markdown/Installing.md @@ -4,7 +4,8 @@ short-description: Installing targets # Installing -Invoked via the [following command](Commands.md#install) *(available since 0.47.0)*: +Invoked via the [following command](Commands.md#install) *(available +since 0.47.0)*: ```sh meson install @@ -114,8 +115,8 @@ $ DESTDIR=/path/to/staging/area meson install ## Custom install behaviour -Installation behaviour can be further customized using -additional arguments. +Installation behaviour can be further customized using additional +arguments. For example, if you wish to install the current setup without rebuilding the code (which the default install target always does) and diff --git a/docs/markdown/Java.md b/docs/markdown/Java.md index 9b89304..f0dd403 100644 --- a/docs/markdown/Java.md +++ b/docs/markdown/Java.md @@ -5,7 +5,8 @@ short-description: Compiling Java programs # Compiling Java applications -Meson has experimental support for compiling Java programs. The basic syntax consists of only one function and would be used like this: +Meson has experimental support for compiling Java programs. The basic +syntax consists of only one function and would be used like this: ```meson project('javaprog', 'java') diff --git a/docs/markdown/Keyval-module.md b/docs/markdown/Keyval-module.md index afc48fa..3735888 100644 --- a/docs/markdown/Keyval-module.md +++ b/docs/markdown/Keyval-module.md @@ -8,13 +8,14 @@ authors: # keyval module -This module parses files consisting of a series of `key=value` lines. One use -of this module is to load kconfig configurations in meson projects. +This module parses files consisting of a series of `key=value` lines. +One use of this module is to load kconfig configurations in meson +projects. -**Note**:Â this does not provide kconfig frontend tooling to generate a +**Note**: this does not provide kconfig frontend tooling to generate a configuration. You still need something such as kconfig frontends (see -link below) to parse your Kconfig files, and then (after you've -chosen the configuration options), output a ".config" file. +link below) to parse your Kconfig files, and then (after you've chosen +the configuration options), output a ".config" file. [kconfig-frontends]: http://ymorin.is-a-geek.org/projects/kconfig-frontends @@ -35,19 +36,21 @@ with the name `keyval`. You can, of course, replace the name This function loads a file consisting of a series of `key=value` lines and returns a dictionary object. -`keyval.load()` makes no attempt at parsing the values in the file. -In particular boolean and integer values will be represented as strings, -and strings will keep any quoting that is present in the input file. It -can be useful to create a [`configuration_data()`](#configuration_data) -object from the dictionary and use methods such as `get_unquoted()`. +`keyval.load()` makes no attempt at parsing the values in the file. In +particular boolean and integer values will be represented as strings, +and strings will keep any quoting that is present in the input file. +It can be useful to create a +[`configuration_data()`](#configuration_data) object from the +dictionary and use methods such as `get_unquoted()`. Kconfig frontends usually have ".config" as the default name for the -configuration file. However, placing the configuration file in the source -directory limits the user to one configuration per source directory. -In order to allow separate configurations for each build directory, as is -the Meson standard, `meson.build` should not hardcode ".config" as the -argument to `kconfig.load()`, and should instead make the argument to -`kconfig.load()` a [project build option](Build-options.md). +configuration file. However, placing the configuration file in the +source directory limits the user to one configuration per source +directory. In order to allow separate configurations for each build +directory, as is the Meson standard, `meson.build` should not hardcode +".config" as the argument to `kconfig.load()`, and should instead make +the argument to `kconfig.load()` a [project build +option](Build-options.md). * The first (and only) argument is the path to the configuration file to load (usually ".config"). diff --git a/docs/markdown/Localisation.md b/docs/markdown/Localisation.md index ed63e13..8a09feb 100644 --- a/docs/markdown/Localisation.md +++ b/docs/markdown/Localisation.md @@ -4,9 +4,12 @@ short-description: Localization with GNU Gettext # Localisation -Localising your application with GNU gettext takes a little effort but is quite straightforward. We'll create a `po` subdirectory at your project root directory for all the localisation info. +Localising your application with GNU gettext takes a little effort but +is quite straightforward. We'll create a `po` subdirectory at your +project root directory for all the localisation info. ## Generating .pot and .po files + In your main meson.build file include the `po` subdirectory in the build process. subdir('po') @@ -17,12 +20,17 @@ In this `po` subdirectory we need: - `meson.build`: Localization specific meson file ### LINGUAS + File with space separated list of languages. A sample LINGUAS might look like this. aa ab ae af ### POTFILES -File that lists all the source files that gettext should scan in order to find strings to translate. The syntax of the file is one line per source file and the line must contain the relative path from source root. A sample POTFILES might look like this. + +File that lists all the source files that gettext should scan in order +to find strings to translate. The syntax of the file is one line per +source file and the line must contain the relative path from source +root. A sample POTFILES might look like this. src/file1.c src/file2.c @@ -30,7 +38,11 @@ File that lists all the source files that gettext should scan in order to find s include/mything/somefile.h ### meson.build -Localization specific meson file. It imports and uses the `i18n` module. If not defined before it needs to define the `GETTEXT_PACKAGE` global. + +Localization specific meson file. It imports and uses the `i18n` +module. If not defined before it needs to define the `GETTEXT_PACKAGE` +global. + ```meson i18n = import('i18n') # define GETTEXT_PACKAGE @@ -39,13 +51,25 @@ i18n.gettext(meson.project_name(), args: '--directory=' + meson.source_root() ) ``` -The first command imports the `i18n` module that provides gettext features. The fourth line does the actual invocation. The first argument is the gettext package name. This causes two things to happen. The first is that Meson will generate binary mo files and put them to their proper locations when doing an install. The second is that it creates a build rule to regenerate the main pot file. If you are using the Ninja backend, this is how you would invoke the rebuild. + +The first command imports the `i18n` module that provides gettext +features. The fourth line does the actual invocation. The first +argument is the gettext package name. This causes two things to +happen. The first is that Meson will generate binary mo files and put +them to their proper locations when doing an install. The second is +that it creates a build rule to regenerate the main pot file. If you +are using the Ninja backend, this is how you would invoke the rebuild. ### generate .pot file -Then we need to generate the main pot file. The potfile can have any name but is usually the name of the gettext package. Let's say the project is called *intltest*. In this case the corresponding pot file would be called `intltest.pot`. +Then we need to generate the main pot file. The potfile can have any +name but is usually the name of the gettext package. Let's say the +project is called *intltest*. In this case the corresponding pot file +would be called `intltest.pot`. -Run the following command from your build folder to generate the pot file. It is recommended to inspect it manually afterwards and fill in e.g. proper copyright and contact information. +Run the following command from your build folder to generate the pot +file. It is recommended to inspect it manually afterwards and fill in +e.g. proper copyright and contact information. ```console $ meson compile intltest-pot @@ -53,7 +77,9 @@ $ meson compile intltest-pot ### generate .po files -For each language listed in the array above we need a corresponding `.po` file. Those can be generated by running the following command from your build folder. +For each language listed in the array above we need a corresponding +`.po` file. Those can be generated by running the following command +from your build folder. ```console $ meson compile intltest-update-po diff --git a/docs/markdown/Machine-files.md b/docs/markdown/Machine-files.md index e553720..fd99937 100644 --- a/docs/markdown/Machine-files.md +++ b/docs/markdown/Machine-files.md @@ -1,12 +1,13 @@ # Cross and Native File reference -Cross and native files are nearly identical, but not completely. This is the -documentation on the common values used by both, for the specific values of -one or the other see the [cross compilation](Cross-compilation.md) and [native +Cross and native files are nearly identical, but not completely. This +is the documentation on the common values used by both, for the +specific values of one or the other see the [cross +compilation](Cross-compilation.md) and [native environments](Native-environments.md). -*Changed in 0.56.0* Keys within sections are now case sensitive. This is -*required to make project options work correctly. +*Changed in 0.56.0* Keys within sections are now case sensitive. This +*is required to make project options work correctly. ## Data Types @@ -54,10 +55,10 @@ The following sections are allowed: *Since 0.56.0* -String and list concatenation is supported using the `+` operator, joining paths -is supported using the `/` operator. -Entries defined in the `[constants]` section can be used in any other section -(they are always parsed first), entries in any other section can be used only +String and list concatenation is supported using the `+` operator, +joining paths is supported using the `/` operator. Entries defined in +the `[constants]` section can be used in any other section (they are +always parsed first), entries in any other section can be used only within that same section and only after it has been defined. ```ini @@ -73,8 +74,10 @@ cpp_args = c_args + ['-DSOMETHING_ELSE'] c = toolchain / 'gcc' ``` -This can be useful with cross file composition as well. A generic cross file -could be composed with a platform specific file where constants are defined: +This can be useful with cross file composition as well. A generic +cross file could be composed with a platform specific file where +constants are defined: + ```ini # aarch64.ini [constants] @@ -91,10 +94,12 @@ pkgconfig = arch + '-pkg-config' ... ``` -This can be used as `meson setup --cross-file aarch64.ini --cross-file cross.ini builddir`. +This can be used as `meson setup --cross-file aarch64.ini --cross-file +cross.ini builddir`. + +Note that file composition happens before the parsing of values. The +example below results in `b` being `'HelloWorld'`: -Note that file composition happens before the parsing of values. The example -below results in `b` being `'HelloWorld'`: ```ini # file1.ini: [constants] @@ -108,8 +113,9 @@ b = a + 'World' a = 'Hello' ``` -The example below results in an error when file1.ini is included before file2.ini -because `b` would be defined before `a`: +The example below results in an error when file1.ini is included +before file2.ini because `b` would be defined before `a`: + ```ini # file1.ini: [constants] @@ -130,15 +136,16 @@ internally by meson, or by the `find_program` function. These values must be either strings or an array of strings Compilers and linkers are defined here using `<lang>` and `<lang>_ld`. -`<lang>_ld` is special because it is compiler specific. For compilers like -gcc and clang which are used to invoke the linker this is a value to pass to -their "choose the linker" argument (-fuse-ld= in this case). For compilers -like MSVC and Clang-Cl, this is the path to a linker for meson to invoke, -such as `link.exe` or `lld-link.exe`. Support for `ld` is *new in 0.53.0* +`<lang>_ld` is special because it is compiler specific. For compilers +like gcc and clang which are used to invoke the linker this is a value +to pass to their "choose the linker" argument (-fuse-ld= in this +case). For compilers like MSVC and Clang-Cl, this is the path to a +linker for meson to invoke, such as `link.exe` or `lld-link.exe`. +Support for `ld` is *new in 0.53.0* -*changed in 0.53.1* the `ld` variable was replaced by `<lang>_ld`, because it -*regressed a large number of projects. in 0.53.0 the `ld` variable was used -instead. +*changed in 0.53.1* the `ld` variable was replaced by `<lang>_ld`, +*because it regressed a large number of projects. in 0.53.0 the `ld` +*variable was used instead. Native example: @@ -161,7 +168,9 @@ strip = '/usr/i586-mingw32msvc/bin/strip' pkgconfig = '/usr/bin/i586-mingw32msvc-pkg-config' ``` -An incomplete list of internally used programs that can be overridden here is: +An incomplete list of internally used programs that can be overridden +here is: + - cmake - cups-config - gnustep-config @@ -178,8 +187,9 @@ An incomplete list of internally used programs that can be overridden here is: *Deprecated in 0.56.0* use the built-in section instead. -As of 0.50.0 paths and directories such as libdir can be defined in the native -and cross files in a paths section. These should be strings. +As of 0.50.0 paths and directories such as libdir can be defined in +the native and cross files in a paths section. These should be +strings. ```ini [paths] @@ -187,10 +197,10 @@ libdir = 'mylibdir' prefix = '/my prefix' ``` -These values will only be loaded when not cross compiling. Any arguments on the -command line will override any options in the native file. For example, passing -`--libdir=otherlibdir` would result in a prefix of `/my prefix` and a libdir of -`otherlibdir`. +These values will only be loaded when not cross compiling. Any +arguments on the command line will override any options in the native +file. For example, passing `--libdir=otherlibdir` would result in a +prefix of `/my prefix` and a libdir of `otherlibdir`. ### Properties @@ -200,9 +210,9 @@ In addition to special data that may be specified in cross files, this section may contain random key value pairs accessed using the `meson.get_external_property()`, or `meson.get_cross_property()`. -*Changed in 0.56.0* putting `<lang>_args` and `<lang>_link_args` in the -properties section has been deprecated, and should be put in the built-in -options section. +*Changed in 0.56.0* putting `<lang>_args` and `<lang>_link_args` in +the properties section has been deprecated, and should be put in the +built-in options section. #### Supported properties @@ -231,9 +241,10 @@ section. *New in 0.56.0* -All variables set in the `[cmake]` section will be added to the generate CMake -toolchain file used for both CMake dependencies and CMake subprojects. The type -of each entry must be either a string or a list of strings. +All variables set in the `[cmake]` section will be added to the +generate CMake toolchain file used for both CMake dependencies and +CMake subprojects. The type of each entry must be either a string or a +list of strings. **Note:** All occurrences of `\` in the value of all keys will be replaced with a `/` since CMake has a lot of issues with correctly escaping `\` when @@ -251,8 +262,8 @@ CMAKE_CXX_COMPILER = 'C:\\user\\bin\\g++' CMAKE_SOME_VARIABLE = ['some', 'value with spaces'] ``` -For instance, the `[cmake]` section from above will generate the following -code in the CMake toolchain file: +For instance, the `[cmake]` section from above will generate the +following code in the CMake toolchain file: ```cmake set(CMAKE_C_COMPILER "/usr/bin/gcc") @@ -264,14 +275,16 @@ set(CMAKE_SOME_VARIABLE "some" "value with spaces") *New in 0.56.0* -Path options are not allowed, those must be set in the `[paths]` section. +Path options are not allowed, those must be set in the `[paths]` +section. -Being able to set project specific options in a cross or native file can be -done using the `[project options]` section of the specific file (if doing a -cross build the options from the native file will be ignored) +Being able to set project specific options in a cross or native file +can be done using the `[project options]` section of the specific file +(if doing a cross build the options from the native file will be +ignored) -For setting options in subprojects use the `[<subproject>:project options]` -section instead. +For setting options in subprojects use the `[<subproject>:project +options]` section instead. ```ini [project options] @@ -290,8 +303,9 @@ Meson built-in options can be set the same way: c_std = 'c99' ``` -You can set some meson built-in options on a per-subproject basis, such as -`default_library` and `werror`. The order of precedence is: +You can set some meson built-in options on a per-subproject basis, +such as `default_library` and `werror`. The order of precedence is: + 1) Command line 2) Machine file 3) Build system definitions @@ -302,9 +316,9 @@ default_library = 'static' werror = false ``` -Options set on a per-subproject basis will inherit the -option from the parent if the parent has a setting but the subproject -doesn't, even when there is a default set meson language. +Options set on a per-subproject basis will inherit the option from the +parent if the parent has a setting but the subproject doesn't, even +when there is a default set meson language. ```ini [built-in options] @@ -313,9 +327,10 @@ default_library = 'static' will make subprojects use default_library as static. -Some options can be set on a per-machine basis (in other words, the value of -the build machine can be different than the host machine in a cross compile). -In these cases the values from both a cross file and a native file are used. +Some options can be set on a per-machine basis (in other words, the +value of the build machine can be different than the host machine in a +cross compile). In these cases the values from both a cross file and a +native file are used. An incomplete list of options is: - pkg_config_path @@ -323,21 +338,21 @@ An incomplete list of options is: ## Loading multiple machine files -Native files allow layering (cross files can be layered since meson 0.52.0). -More than one file can be loaded, with values from a previous file being -overridden by the next. The intention of this is not overriding, but to allow -composing files. This composition is done by passing the command line -argument multiple times: +Native files allow layering (cross files can be layered since meson +0.52.0). More than one file can be loaded, with values from a previous +file being overridden by the next. The intention of this is not +overriding, but to allow composing files. This composition is done by +passing the command line argument multiple times: ```console meson setup builddir/ --cross-file first.ini --cross-file second.ini --cross-file thrid.ini ``` -In this case `first.ini` will be loaded, then `second.ini`, with values from -`second.ini` replacing `first.ini`, and so on. +In this case `first.ini` will be loaded, then `second.ini`, with +values from `second.ini` replacing `first.ini`, and so on. -For example, if there is a project using C and C++, python 3.4-3.7, and LLVM -5-7, and it needs to build with clang 5, 6, and 7, and gcc 5.x, 6.x, and 7.x; -expressing all of these configurations in monolithic configurations would -result in 81 different native files. By layering them, it can be expressed by -just 12 native files. +For example, if there is a project using C and C++, python 3.4-3.7, +and LLVM 5-7, and it needs to build with clang 5, 6, and 7, and gcc +5.x, 6.x, and 7.x; expressing all of these configurations in +monolithic configurations would result in 81 different native files. +By layering them, it can be expressed by just 12 native files. diff --git a/docs/markdown/Meson-sample.md b/docs/markdown/Meson-sample.md index f98e022..f504cd9 100644 --- a/docs/markdown/Meson-sample.md +++ b/docs/markdown/Meson-sample.md @@ -11,11 +11,18 @@ project('simple', 'c') executable('myexe', 'source.c') ``` -All Meson build definitions begin with the `project` command. It specifies the name of the project and what programming languages it uses. Here the project is called *simple* and it uses only the C programming language. All strings are single-quoted. +All Meson build definitions begin with the `project` command. It +specifies the name of the project and what programming languages it +uses. Here the project is called *simple* and it uses only the C +programming language. All strings are single-quoted. -On the next line we define a *build target*, in this case an executable called *myexe*. It consists of one source file. This is all the code that a user needs to write to compile an executable with Meson. +On the next line we define a *build target*, in this case an +executable called *myexe*. It consists of one source file. This is all +the code that a user needs to write to compile an executable with +Meson. -Variables are fully supported. The above code snippet could also have been declared like this. +Variables are fully supported. The above code snippet could also have +been declared like this. ```meson project('simple', 'c') @@ -23,7 +30,8 @@ src = 'source.c' executable('myexe', src) ``` -Most executables consist of more than one source file. The easiest way to deal with this is to put them in an array. +Most executables consist of more than one source file. The easiest way +to deal with this is to put them in an array. ```meson project('simple', 'c') @@ -31,7 +39,9 @@ src = ['source1.c', 'source2.c', 'source3.c'] executable('myexe', src) ``` -Meson also supports the notion of *keyword arguments*. Indeed most arguments to functions can only be passed using them. The above snippet could be rewritten like this. +Meson also supports the notion of *keyword arguments*. Indeed most +arguments to functions can only be passed using them. The above +snippet could be rewritten like this. ```meson project('simple', 'c') @@ -39,9 +49,12 @@ src = ['source1.c', 'source2.c', 'source3.c'] executable('myexe', sources : src) ``` -These two formats are equivalent and choosing one over the other is mostly a question of personal preference. +These two formats are equivalent and choosing one over the other is +mostly a question of personal preference. -The `executable` command actually returns an *executable object*, which represents the given build target. It can be passed on to other functions, like this. +The `executable` command actually returns an *executable object*, +which represents the given build target. It can be passed on to other +functions, like this. ```meson project('simple', 'c') @@ -50,9 +63,18 @@ exe = executable('myexe', src) test('simple test', exe) ``` -Here we create a unit test called *simple test*, and which uses the built executable. When the tests are run with the `meson test` command, the built executable is run. If it returns zero, the test passes. A non-zero return value indicates an error, which Meson will then report to the user. +Here we create a unit test called *simple test*, and which uses the +built executable. When the tests are run with the `meson test` +command, the built executable is run. If it returns zero, the test +passes. A non-zero return value indicates an error, which Meson will +then report to the user. A note to Visual Studio users ----- -There's a slight terminology difference between Meson and Visual Studio. A Meson *project* is the equivalent to a Visual Studio *solution*. That is, the topmost thing that encompasses all things to be built. A Visual Studio *project* on the other hand is the equivalent of a Meson top level build target, such as an executable or a shared library. +There's a slight terminology difference between Meson and Visual +Studio. A Meson *project* is the equivalent to a Visual Studio +*solution*. That is, the topmost thing that encompasses all things to +be built. A Visual Studio *project* on the other hand is the +equivalent of a Meson top level build target, such as an executable or +a shared library. diff --git a/docs/markdown/MesonCI.md b/docs/markdown/MesonCI.md index 00fd1ff..b365656 100644 --- a/docs/markdown/MesonCI.md +++ b/docs/markdown/MesonCI.md @@ -1,46 +1,43 @@ # Meson CI setup -This document is aimed for Meson contributors and documents -the CI setup used for testing Meson itself. The Meson -project uses multiple CI platforms for covering a wide -range of target systems. +This document is aimed for Meson contributors and documents the CI +setup used for testing Meson itself. The Meson project uses multiple +CI platforms for covering a wide range of target systems. ## GitHub actions The configuration files for GitHub actions are located in -`.github/workflows`. Here, all [images](#docker-images) -are tested with the full `run_tests.py` run. Additionally, -some other, smaller, tests are run. +`.github/workflows`. Here, all [images](#docker-images) are tested +with the full `run_tests.py` run. Additionally, some other, smaller, +tests are run. ## Docker images -The Linux docker images are automatically built and -uploaded by GitHub actions. An image rebuild is triggerd -when any of the image definition files are changed (in -`ci/ciimage`) in the master branch. Additionally, the -images are also updated weekly. +The Linux docker images are automatically built and uploaded by GitHub +actions. An image rebuild is triggerd when any of the image definition +files are changed (in `ci/ciimage`) in the master branch. +Additionally, the images are also updated weekly. -Each docker image has one corresponding dirctory in -`ci/ciimage` with an `image.json` and an `install.sh`. +Each docker image has one corresponding dirctory in `ci/ciimage` with +an `image.json` and an `install.sh`. ### Image generation There are no manual Dockerfiles. Instead the Dockerfile is -automatically generated by the `build.py` script. This is -done to ensure that all images have the same layout and can -all be built and tested automatically. +automatically generated by the `build.py` script. This is done to +ensure that all images have the same layout and can all be built and +tested automatically. -The Dockerfile is generated from the `image.json` file and -basically only adds a few common files and runs the -`install.sh` script which should contain all distribution -specific setup steps. The `common.sh` can be sourced via -`source /ci/common.sh` to access some shared functionalety. +The Dockerfile is generated from the `image.json` file and basically +only adds a few common files and runs the `install.sh` script which +should contain all distribution specific setup steps. The `common.sh` +can be sourced via `source /ci/common.sh` to access some shared +functionalety. -To generate the image run `build.py -t build <image>`. A -generated image can be tested with `build.py -t test <image>`. +To generate the image run `build.py -t build <image>`. A generated +image can be tested with `build.py -t test <image>`. ### Common image setup -Each docker image has a `/ci` directory with an -`env_vars.sh` script. This script has to be sourced before -running the meson test suite. +Each docker image has a `/ci` directory with an `env_vars.sh` script. +This script has to be sourced before running the meson test suite. diff --git a/docs/markdown/Mixing-build-systems.md b/docs/markdown/Mixing-build-systems.md index 98ca0ed..6830064 100644 --- a/docs/markdown/Mixing-build-systems.md +++ b/docs/markdown/Mixing-build-systems.md @@ -2,21 +2,21 @@ Meson has been designed with the principle that all dependencies are either provided by "the platform" via a mechanism such as Pkg-Config -or that they are built as Meson subprojects under the main -project. There are several projects that would like to mix build -systems, that is, build dependencies in the same build directory as -the other build system by having one build system call the other. The -build directories do not necessarily need to be inside each other, but -that is the common case. - -This page lists the Meson project's stance on mixing build -systems. The tl/dr version is that while we do provide some -functionality for this use case, it only works for simple -cases. Anything more complex can not be made reliable and trying to do -that would burden Meson developers with an effectively infinite -maintenance burden. Thus these use cases are not guaranteed to work, -and even if a project using them works today there are no guarantees -that it will work in any future version. +or that they are built as Meson subprojects under the main project. +There are several projects that would like to mix build systems, that +is, build dependencies in the same build directory as the other build +system by having one build system call the other. The build +directories do not necessarily need to be inside each other, but that +is the common case. + +This page lists the Meson project's stance on mixing build systems. +The tl/dr version is that while we do provide some functionality for +this use case, it only works for simple cases. Anything more complex +can not be made reliable and trying to do that would burden Meson +developers with an effectively infinite maintenance burden. Thus these +use cases are not guaranteed to work, and even if a project using them +works today there are no guarantees that it will work in any future +version. ## The definition of "build system mixing" diff --git a/docs/markdown/Modules.md b/docs/markdown/Modules.md index c354169..a966682 100644 --- a/docs/markdown/Modules.md +++ b/docs/markdown/Modules.md @@ -4,13 +4,16 @@ short-description: Meson modules for common build operations # Modules -In addition to core language features, Meson also provides a module system aimed at providing helper methods for common build operations. Using modules is simple, first you import them: +In addition to core language features, Meson also provides a module +system aimed at providing helper methods for common build operations. +Using modules is simple, first you import them: ```meson mymod = import('somemodule') ``` -After this you can use the returned object to use the functionality provided: +After this you can use the returned object to use the functionality +provided: ```meson mymod.do_something('text argument') diff --git a/docs/markdown/Native-environments.md b/docs/markdown/Native-environments.md index 8dcce2a..d793132 100644 --- a/docs/markdown/Native-environments.md +++ b/docs/markdown/Native-environments.md @@ -6,15 +6,16 @@ short-description: Setting up native compilation New in 0.49.0 -Meson has [cross files for describing cross compilation environments](Cross-compilation.md), -for describing native environments it has equivalent "native files". +Meson has [cross files for describing cross compilation +environments](Cross-compilation.md), for describing native +environments it has equivalent "native files". -Natives describe the *build machine*, and can be used to override properties of -non-cross builds, as well as properties that are marked as "native" in a cross -build. +Natives describe the *build machine*, and can be used to override +properties of non-cross builds, as well as properties that are marked +as "native" in a cross build. -There are a couple of reasons you might want to use a native file to keep a -persistent environment: +There are a couple of reasons you might want to use a native file to +keep a persistent environment: * To build with a non-default native tool chain (such as clang instead of gcc) * To use a non-default version of another binary, such as yacc, or llvm-config @@ -44,6 +45,6 @@ The order of locations tried is as follows: - The user local location - The system wide locations in order -These files are not intended to be shipped by distributions, unless they are -specifically for distribution packaging, they are mainly intended for -developers. +These files are not intended to be shipped by distributions, unless +they are specifically for distribution packaging, they are mainly +intended for developers. diff --git a/docs/markdown/Performance-comparison.md b/docs/markdown/Performance-comparison.md index 3f15e82..2f47d11 100644 --- a/docs/markdown/Performance-comparison.md +++ b/docs/markdown/Performance-comparison.md @@ -1,6 +1,7 @@ # Performance comparison -This page lists experiments comparing build performance between Meson and other build systems. +This page lists experiments comparing build performance between Meson +and other build systems. - [Simple comparison](Simple-comparison.md) - [ARM performance test](ARM-performance-test.md) diff --git a/docs/markdown/Pkg-config-files.md b/docs/markdown/Pkg-config-files.md index 3aa8897..1fbef0b 100644 --- a/docs/markdown/Pkg-config-files.md +++ b/docs/markdown/Pkg-config-files.md @@ -1,6 +1,13 @@ # Pkg config files -[Pkg-config](https://en.wikipedia.org/wiki/Pkg-config) is a way for shared libraries to declare the compiler flags needed to use them. There are two different ways of generating Pkg-config files in Meson. The first way is to build them manually with the `configure_file` command. The second way is to use Meson's built in Pkg-config file generator. The difference between the two is that the latter is very simple and meant for basic use cases. The former should be used when you need to provide a more customized solution. +[Pkg-config](https://en.wikipedia.org/wiki/Pkg-config) is a way for +shared libraries to declare the compiler flags needed to use them. +There are two different ways of generating Pkg-config files in Meson. +The first way is to build them manually with the `configure_file` +command. The second way is to use Meson's built in Pkg-config file +generator. The difference between the two is that the latter is very +simple and meant for basic use cases. The former should be used when +you need to provide a more customized solution. In this document we describe the simple generator approach. It is used in the following way. @@ -16,6 +23,8 @@ pkg.generate(libraries : libs, description : 'A simple demo library.') ``` -This causes a file called `simple.pc` to be created and placed into the install directory during the install phase. +This causes a file called `simple.pc` to be created and placed into +the install directory during the install phase. -More information on the pkg-config module and the parameters can be found on the [pkgconfig-module](Pkgconfig-module.md) page. +More information on the pkg-config module and the parameters can be +found on the [pkgconfig-module](Pkgconfig-module.md) page. diff --git a/docs/markdown/Pkgconfig-module.md b/docs/markdown/Pkgconfig-module.md index 53c23fa..1f9ecb0 100644 --- a/docs/markdown/Pkgconfig-module.md +++ b/docs/markdown/Pkgconfig-module.md @@ -62,27 +62,29 @@ keyword arguments. pkg-config files in projects which also have architecture-dependent outputs. - `conflicts` (*since 0.36.0, incorrectly issued a warning prior to 0.54.0*) list of strings to be put in the `Conflicts` field. -Since 0.46 a `StaticLibrary` or `SharedLibrary` object can optionally be passed -as first positional argument. If one is provided a default value will be -provided for all required fields of the pc file: +Since 0.46 a `StaticLibrary` or `SharedLibrary` object can optionally +be passed as first positional argument. If one is provided a default +value will be provided for all required fields of the pc file: - `install_dir` is set to `pkgconfig` folder in the same location than the provided library. - `description` is set to the project's name followed by the library's name. - `name` is set to the library's name. -Since 0.54.0 uninstalled pkg-config files are generated as well. They are -located in `<build dir>/meson-uninstalled/`. It is sometimes -useful to build projects against libraries built by meson without having to -install them into a prefix. In order to do so, just set +Since 0.54.0 uninstalled pkg-config files are generated as well. They +are located in `<build dir>/meson-uninstalled/`. It is sometimes +useful to build projects against libraries built by meson without +having to install them into a prefix. In order to do so, just set `PKG_CONFIG_PATH=<builddir>/meson-uninstalled` before building your -application. That will cause pkg-config to prefer those `-uninstalled.pc` files -and find libraries and headers from the meson builddir. This is an experimental -feature provided on a best-effort basis, it might not work in all use-cases. +application. That will cause pkg-config to prefer those +`-uninstalled.pc` files and find libraries and headers from the meson +builddir. This is an experimental feature provided on a best-effort +basis, it might not work in all use-cases. ### Implicit dependencies -The exact rules followed to find dependencies that are implicitly added into the -pkg-config file have evolved over time. Here are the rules as of Meson *0.49.0*, -previous versions might have slightly different behaviour. +The exact rules followed to find dependencies that are implicitly +added into the pkg-config file have evolved over time. Here are the +rules as of Meson *0.49.0*, previous versions might have slightly +different behaviour. - Not found libraries or dependencies are ignored. - Libraries and dependencies are private by default (i.e. added into diff --git a/docs/markdown/Playground.md b/docs/markdown/Playground.md index 5699f22..9061978 100644 --- a/docs/markdown/Playground.md +++ b/docs/markdown/Playground.md @@ -1,10 +1,14 @@ # playground -This page is *not* part of official documentation. It exists merely for testing new stuff for the wiki. +This page is *not* part of official documentation. It exists merely +for testing new stuff for the wiki. ## Ref manual reformat -The current format is not very readable. We should have something more like what [glib](https://developer.gnome.org/glib/stable/glib-Hash-Tables.html) or [Python](https://docs.python.org/3/library/os.html) do. +The current format is not very readable. We should have something more +like what +[glib](https://developer.gnome.org/glib/stable/glib-Hash-Tables.html) +or [Python](https://docs.python.org/3/library/os.html) do. Here's a first proposal. diff --git a/docs/markdown/Porting-from-autotools.md b/docs/markdown/Porting-from-autotools.md index 2170ffa..05af79a 100644 --- a/docs/markdown/Porting-from-autotools.md +++ b/docs/markdown/Porting-from-autotools.md @@ -1,12 +1,18 @@ # Porting from Autotools -This page uses [AppStream-glib](https://github.com/hughsie/appstream-glib/) as an example project. AppStream-Glib contains some libraries, GObject Introspection data, tests, man pages, i18n, bash-completion with optional flags to build/not build support for some things. +This page uses +[AppStream-glib](https://github.com/hughsie/appstream-glib/) as an +example project. AppStream-Glib contains some libraries, GObject +Introspection data, tests, man pages, i18n, bash-completion with +optional flags to build/not build support for some things. -Meson comes with a helper script `ac_converter` that you can use to convert the basic autoconf checks for your project. +Meson comes with a helper script `ac_converter` that you can use to +convert the basic autoconf checks for your project. ## Configure.ac -First let's look at `configure.ac` and write the same in `meson.build`. +First let's look at `configure.ac` and write the same in +`meson.build`. ```autoconf AC_PREREQ(2.63) @@ -54,7 +60,8 @@ AC_SUBST(AS_MICRO_VERSION) AC_SUBST(AS_VERSION) ``` -You don't need to do the same in Meson, because it does not have two different types of files (Makefile, configure). +You don't need to do the same in Meson, because it does not have two +different types of files (Makefile, configure). ### Auto headers @@ -74,9 +81,12 @@ configure_file(output : 'config.h', configuration : conf) ``` -Meson doesn't support autoheaders, you need to manually specify what do you want to see in header file, write `configuration_data()` object and use `configure_file()`. +Meson doesn't support autoheaders, you need to manually specify what +do you want to see in header file, write `configuration_data()` object +and use `configure_file()`. -You can also substitute variables of type `@SOME_VAR@` with configure data. The details are on the [configuration page](Configuration.md). +You can also substitute variables of type `@SOME_VAR@` with configure +data. The details are on the [configuration page](Configuration.md). ### Finding programs @@ -148,7 +158,8 @@ option('enable-dep11', type : 'boolean', value : true, description : 'enable DEP ## Makefile.am -Next step is `Makefile.am`. In meson you don't need to have other file, you still use `meson.build`. +Next step is `Makefile.am`. In meson you don't need to have other +file, you still use `meson.build`. ### Sub directories @@ -193,7 +204,10 @@ EXTRA_DIST = \ config.h ``` -In Meson you don't need have `*CLEANFILES`, because in meson you are building in temporary directory (usually called `build`), you manually removing it. You also not need to use `EXTRA_DIST`, because you will make tarballs via `git archive` or something like this. +In Meson you don't need have `*CLEANFILES`, because in meson you are +building in temporary directory (usually called `build`), you manually +removing it. You also not need to use `EXTRA_DIST`, because you will +make tarballs via `git archive` or something like this. ### glib-compile-resources diff --git a/docs/markdown/Precompiled-headers.md b/docs/markdown/Precompiled-headers.md index 05b50bc..8b7f58e 100644 --- a/docs/markdown/Precompiled-headers.md +++ b/docs/markdown/Precompiled-headers.md @@ -40,9 +40,9 @@ Toggling the usage of precompiled headers If you wish to compile your project without precompiled headers, you can change the value of the pch option by passing `-Db_pch=false` -argument to Meson at configure time or later with `meson configure`. You can -also toggle the use of pch in a configured build directory with the -GUI tool. You don't have to do any changes to the source +argument to Meson at configure time or later with `meson configure`. +You can also toggle the use of pch in a configured build directory +with the GUI tool. You don't have to do any changes to the source code. Typically this is done to test whether your project compiles cleanly without pch (that is, checking that its #includes are in order) and working around compiler bugs. @@ -51,11 +51,11 @@ Using precompiled headers with GCC and derivatives -- Once you have a file to precompile, you can enable the use of pch for -a given target with a *pch* keyword argument. As an example, let's assume -you want to build a small C binary with precompiled headers. -Let's say the source files of the binary use the system headers `stdio.h` -and `string.h`. Then you create a header file `pch/myexe_pch.h` with this -content: +a given target with a *pch* keyword argument. As an example, let's +assume you want to build a small C binary with precompiled headers. +Let's say the source files of the binary use the system headers +`stdio.h` and `string.h`. Then you create a header file +`pch/myexe_pch.h` with this content: ```c #include <stdio.h> diff --git a/docs/markdown/Python-3-module.md b/docs/markdown/Python-3-module.md index f32cdc9..b89ea3e 100644 --- a/docs/markdown/Python-3-module.md +++ b/docs/markdown/Python-3-module.md @@ -3,18 +3,21 @@ This module provides support for dealing with Python 3. It has the following methods. -This module is deprecated and replaced by the [python](Python-module.md) module. +This module is deprecated and replaced by the +[python](Python-module.md) module. ## find_python This is a cross platform way of finding the Python 3 executable, which may have a different name on different operating systems. Returns an -[external program](Reference-manual.md#external-program-object) object. +[external program](Reference-manual.md#external-program-object) +object. *Added 0.38.0* -Deprecated, replaced by [`find_installation`](Python-module.md#find_installation) -function from `python` module. +Deprecated, replaced by +[`find_installation`](Python-module.md#find_installation) function +from `python` module. ## extension_module @@ -29,8 +32,9 @@ need to add `dependencies : dependency('python3')`, see *Added 0.38.0* -Deprecated, replaced by [`extension_module`](Python-module.md#extension_module) -method from `python` module. +Deprecated, replaced by +[`extension_module`](Python-module.md#extension_module) method from +`python` module. ## language_version @@ -38,8 +42,9 @@ Returns a string with the Python language version such as `3.5`. *Added 0.40.0* -Deprecated, replaced by [`language_version`](Python-module.md#language_version) -method from `python` module. +Deprecated, replaced by +[`language_version`](Python-module.md#language_version) method from +`python` module. ## sysconfig_path diff --git a/docs/markdown/Python-module.md b/docs/markdown/Python-module.md index d99b36a..4aff4c9 100644 --- a/docs/markdown/Python-module.md +++ b/docs/markdown/Python-module.md @@ -34,10 +34,10 @@ If provided, it can be: - A path, eg `/usr/local/bin/python3.4m` -- One of `python2` or `python3`: in either case, the module will try some - alternative names: `py -2` or `py -3` on Windows, and `python` everywhere. - In the latter case, it will check whether the version provided by the - sysconfig module matches the required major version +- One of `python2` or `python3`: in either case, the module will try + some alternative names: `py -2` or `py -3` on Windows, and `python` + everywhere. In the latter case, it will check whether the version + provided by the sysconfig module matches the required major version Keyword arguments are the following: @@ -83,8 +83,9 @@ shared_module py_installation.extension_module(module_name, list_of_sources, ... Create a `shared_module` target that is named according to the naming conventions of the target platform. -All positional and keyword arguments are the same as for [shared_module], -excluding `name_suffix` and `name_prefix`, and with the addition of the following: +All positional and keyword arguments are the same as for +[shared_module], excluding `name_suffix` and `name_prefix`, and with +the addition of the following: - `subdir`: By default, meson will install the extension module in the relevant top-level location for the python installation, eg @@ -92,8 +93,9 @@ excluding `name_suffix` and `name_prefix`, and with the addition of the followin it will be appended to that location. This keyword argument is mutually exclusive with `install_dir` -`extension_module` does not add any dependencies to the library so user may -need to add `dependencies : py_installation.dependency()`, see [][`dependency()`]. +`extension_module` does not add any dependencies to the library so +user may need to add `dependencies : py_installation.dependency()`, +see [][`dependency()`]. **Returns**: a [buildtarget object] @@ -103,12 +105,13 @@ need to add `dependencies : py_installation.dependency()`, see [][`dependency()` python_dependency py_installation.dependency(...) ``` -This method accepts no positional arguments, and the same keyword arguments as -the standard [dependency] function. It also supports the following keyword -argument: +This method accepts no positional arguments, and the same keyword +arguments as the standard [dependency] function. It also supports the +following keyword argument: -- `embed`: *(since 0.53.0)* If true, meson will try to find a python dependency - that can be used for embedding python into an application. +- `embed`: *(since 0.53.0)* If true, meson will try to find a python + dependency that can be used for embedding python into an + application. **Returns**: a [python dependency][`python_dependency` object] @@ -120,14 +123,14 @@ void py_installation.install_sources(list_of_files, ...) Install actual python sources (`.py`). -All positional and keyword arguments are the same as for [install_data], -with the addition of the following: +All positional and keyword arguments are the same as for +[install_data], with the addition of the following: -- `pure`: On some platforms, architecture independent files are expected - to be placed in a separate directory. However, if the python sources - should be installed alongside an extension module built with this - module, this keyword argument can be used to override that behaviour. - Defaults to `true` +- `pure`: On some platforms, architecture independent files are + expected to be placed in a separate directory. However, if the + python sources should be installed alongside an extension module + built with this module, this keyword argument can be used to + override that behaviour. Defaults to `true` - `subdir`: See documentation for the argument of the same name to [][`extension_module()`] @@ -140,8 +143,8 @@ string py_installation.get_install_dir(...) Retrieve the directory [][`install_sources()`] will install to. -It can be useful in cases where `install_sources` cannot be used directly, -for example when using [configure_file]. +It can be useful in cases where `install_sources` cannot be used +directly, for example when using [configure_file]. This function accepts no arguments, its keyword arguments are the same as [][`install_sources()`]. @@ -223,14 +226,15 @@ a non-existing variable will cause a fatal error. bool py_installation.has_variable(variable_name) ``` -**Returns**: true if a variable named `variable_name` can be retrieved with -[][`get_variable()`], false otherwise. +**Returns**: true if a variable named `variable_name` can be retrieved +with [][`get_variable()`], false otherwise. ## `python_dependency` object -This [dependency object] subclass will try various methods to obtain the -compiler and linker arguments, starting with pkg-config then potentially -using information obtained from python's `sysconfig` module. +This [dependency object] subclass will try various methods to obtain +the compiler and linker arguments, starting with pkg-config then +potentially using information obtained from python's `sysconfig` +module. It exposes the same methods as its parent class. diff --git a/docs/markdown/Qt5-module.md b/docs/markdown/Qt5-module.md index 6826460..32c34ea 100644 --- a/docs/markdown/Qt5-module.md +++ b/docs/markdown/Qt5-module.md @@ -25,14 +25,15 @@ This method generates the necessary targets to build translation files with lrel - `qresource` rcc source file to extract ts_files from; cannot be used with ts_files kwarg. Available since v0.56.0. - `rcc_extra_arguments`, any additional arguments to `rcc` (optional), when used with `qresource. Available since v0.56.0. -Returns either: a list of custom targets for the compiled translations, or, if -using a `qresource` file, a single custom target containing the processed -source file, which should be passed to a main build target. +Returns either: a list of custom targets for the compiled +translations, or, if using a `qresource` file, a single custom target +containing the processed source file, which should be passed to a main +build target. ## has_tools -This method returns `true` if all tools used by this module are found, `false` -otherwise. +This method returns `true` if all tools used by this module are found, +`false` otherwise. It should be used to compile optional Qt code: ```meson @@ -56,10 +57,11 @@ This method takes the following keyword arguments: See [Qt dependencies](Dependencies.md#qt4-qt5) The 'modules' argument is used to include Qt modules in the project. -See the Qt documentation for the [list of modules](http://doc.qt.io/qt-5/qtmodules.html). +See the Qt documentation for the [list of +modules](http://doc.qt.io/qt-5/qtmodules.html). -The 'private_headers' argument allows usage of Qt's modules private headers. -(since v0.47.0) +The 'private_headers' argument allows usage of Qt's modules private +headers. (since v0.47.0) ## Example A simple example would look like this: @@ -78,9 +80,10 @@ executable('myprog', 'main.cpp', 'myclass.cpp', moc_files, dependencies : qt5_dep) ``` -Sometimes, translations are embedded inside the binary using qresource files. -In this case the ts files do not need to be explicitly listed, but will be -inferred from the built qm files listed in the qresource file. For example: +Sometimes, translations are embedded inside the binary using qresource +files. In this case the ts files do not need to be explicitly listed, +but will be inferred from the built qm files listed in the qresource +file. For example: ```meson qt5 = import('qt5') diff --git a/docs/markdown/Quick-guide.md b/docs/markdown/Quick-guide.md index 74636e5..1363a69 100644 --- a/docs/markdown/Quick-guide.md +++ b/docs/markdown/Quick-guide.md @@ -9,8 +9,9 @@ Meson has been designed to be as simple to use as possible. This page outlines the initial steps needed for installation, troubleshooting, and standard use. -For more advanced configuration please refer to the command line help `meson --help` -or the Meson documentation located at the [Mesonbuild](https://mesonbuild.com) website. +For more advanced configuration please refer to the command line help +`meson --help` or the Meson documentation located at the +[Mesonbuild](https://mesonbuild.com) website. Table of Contents: * [Requirements](#requirements) @@ -57,7 +58,8 @@ Install as root: $ pip3 install meson ``` -*If you are unsure whether to install as root or a local user, install as a local user.* +*If you are unsure whether to install as root or a local user, install + as a local user.* Installation from source @@ -76,12 +78,20 @@ Common Issues: $ meson builddir $ bash: /usr/bin/meson: No such file or directory ``` -Description: The default installation prefix for the python pip module installation is not included in your shell environment PATH. The default prefix for python pip installation modules is located under ``/usr/local``. + +Description: The default installation prefix for the python pip module +installation is not included in your shell environment PATH. The +default prefix for python pip installation modules is located under +``/usr/local``. **Resolution: -This issue can be resolved by altering the default shell environment PATH to include ``/usr/local/bin``. ** +This issue can be resolved by altering the default shell environment +PATH to include ``/usr/local/bin``. ** -*Note: There are other ways of fixing this issue such as using symlinks or copying the binaries to a default path and these methods are not recommended or supported as they may break package management interoperability.* +*Note: There are other ways of fixing this issue such as using + symlinks or copying the binaries to a default path and these methods + are not recommended or supported as they may break package management + interoperability.* Compiling a Meson project @@ -99,19 +109,19 @@ $ meson test The only thing to note is that you need to create a separate build directory. Meson will not allow you to build source code inside your -source tree. All build artifacts are stored in the build -directory. This allows you to have multiple build trees with different +source tree. All build artifacts are stored in the build directory. +This allows you to have multiple build trees with different configurations at the same time. This way generated files are not added into revision control by accident. -To recompile after code changes, just type `meson compile`. The build command -is always the same. You can do arbitrary changes to source code and -build system files and Meson will detect those and will do the right -thing. If you want to build optimized binaries, just use the argument -`--buildtype=debugoptimized` when running Meson. It is recommended -that you keep one build directory for unoptimized builds and one for -optimized ones. To compile any given configuration, just go into the -corresponding build directory and run `meson compile`. +To recompile after code changes, just type `meson compile`. The build +command is always the same. You can do arbitrary changes to source +code and build system files and Meson will detect those and will do +the right thing. If you want to build optimized binaries, just use the +argument `--buildtype=debugoptimized` when running Meson. It is +recommended that you keep one build directory for unoptimized builds +and one for optimized ones. To compile any given configuration, just +go into the corresponding build directory and run `meson compile`. Meson will automatically add compiler flags to enable debug information and compiler warnings (i.e. `-g` and `-Wall`). This means diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index 3a844da..72199df 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -54,9 +54,9 @@ Like `add_global_arguments` but the arguments are passed to the linker. bool add_languages(*langs*) ``` -Add programming languages used by the project. Equivalent to having them in the -`project` declaration. This function is usually used to add languages that are -only used under some conditions, like this: +Add programming languages used by the project. Equivalent to having +them in the `project` declaration. This function is usually used to +add languages that are only used under some conditions, like this: ```meson project('foobar', 'c') @@ -141,11 +141,12 @@ runtarget alias_target(target_name, dep1, ...) *(since 0.52.0)* -This function creates a new top-level target. Like all top-level targets, this -integrates with the selected backend. For instance, with you can -run it as `meson compile target_name`. This is a dummy target that does not execute any -command, but ensures that all dependencies are built. Dependencies can be any -build target (e.g. return value of [executable()](#executable), custom_target(), etc) +This function creates a new top-level target. Like all top-level +targets, this integrates with the selected backend. For instance, with +you can run it as `meson compile target_name`. This is a dummy target +that does not execute any command, but ensures that all dependencies +are built. Dependencies can be any build target (e.g. return value of +[executable()](#executable), custom_target(), etc) ### assert() @@ -165,13 +166,14 @@ statement instead. ``` Creates a benchmark item that will be run when the benchmark target is -run. The behavior of this function is identical to [`test()`](#test) except for: +run. The behavior of this function is identical to [`test()`](#test) +except for: * benchmark() has no `is_parallel` keyword because benchmarks are not run in parallel * benchmark() does not automatically add the `MALLOC_PERTURB_` environment variable -*Note:* Prior to 0.52.0 benchmark would warn that `depends` and `priority` -were unsupported, this is incorrect. +*Note:* Prior to 0.52.0 benchmark would warn that `depends` and +`priority` were unsupported, this is incorrect. ### both_libraries() @@ -181,9 +183,9 @@ were unsupported, this is incorrect. *(since 0.46.0)* -Builds both a static and shared library with the given -sources. Positional and keyword arguments are otherwise the same as -for [`library`](#library). Source files will be compiled only once and +Builds both a static and shared library with the given sources. +Positional and keyword arguments are otherwise the same as for +[`library`](#library). Source files will be compiled only once and object files will be reused to build both shared and static libraries, unless `b_staticpic` user option or `pic` argument are set to false in which case sources will be compiled twice. @@ -253,8 +255,8 @@ When a [`configuration_data()`](#configuration_data) object is passed to the `configuration:` keyword argument, it takes a template file as the `input:` (optional) and produces the `output:` (required) by substituting values from the configuration data as detailed in [the -configuration file documentation](Configuration.md). *(since 0.49.0)* A -dictionary can be passed instead of a +configuration file documentation](Configuration.md). *(since 0.49.0)* +A dictionary can be passed instead of a [`configuration_data()`](#configuration_data) object. When a list of strings is passed to the `command:` keyword argument, @@ -398,14 +400,15 @@ the following special string substitutions: - `@BASENAME@`: the input filename, with extension removed - `@PRIVATE_DIR@` *(since 0.50.1)*: path to a directory where the custom target must store all its intermediate files. -*(since 0.47.0)* The `depfile` keyword argument also accepts the `@BASENAME@` and `@PLAINNAME@` substitutions. +*(since 0.47.0)* The `depfile` keyword argument also accepts the + `@BASENAME@` and `@PLAINNAME@` substitutions. The returned object also has methods that are documented in the [object methods section](#custom-target-object) below. -**Note:** Assuming that `command:` is executed by a POSIX `sh` shell is not -portable, notably to Windows. Instead, consider using a `native: true` -[executable()](#executable), or a python script. +**Note:** Assuming that `command:` is executed by a POSIX `sh` shell +is not portable, notably to Windows. Instead, consider using a +`native: true` [executable()](#executable), or a python script. ### declare_dependency() @@ -540,11 +543,11 @@ add CMake `COMPONENTS` for the `find_package` lookup) - `disabler` *(since 0.49.0)*: if `true` and the dependency couldn't be found, returns a [disabler object](#disabler-object) instead of a not-found dependency. -If dependency_name is `''`, the dependency is always not found. So +If dependency_name is `''`, the dependency is always not found. So with `required: false`, this always returns a dependency object for which the `found()` method returns `false`, and which can be passed like any other dependency to the `dependencies:` keyword argument of a -`build_target`. This can be used to implement a dependency which is +`build_target`. This can be used to implement a dependency which is sometimes not required e.g. in some branches of a conditional, or with a `fallback:` kwarg, can be used to declare an optional dependency that only looks in the specified subproject, and only if that's @@ -606,12 +609,12 @@ libraries (`.so`, `.dll`, etc) will be linked. With the Ninja backend, Meson will create a build-time [order-only dependency](https://ninja-build.org/manual.html#ref_dependencies) on -all generated input files, including unknown files. This is needed -to bootstrap the generation of the real dependencies in the -[depfile](https://ninja-build.org/manual.html#ref_headers) -generated by your compiler to determine when to rebuild sources. -Ninja relies on this dependency file for all input files, generated -and non-generated. The behavior is similar for other backends. +all generated input files, including unknown files. This is needed to +bootstrap the generation of the real dependencies in the +[depfile](https://ninja-build.org/manual.html#ref_headers) generated +by your compiler to determine when to rebuild sources. Ninja relies on +this dependency file for all input files, generated and non-generated. +The behavior is similar for other backends. Executable supports the following keyword arguments. Note that just like the positional arguments above, these keyword arguments can also @@ -796,9 +799,9 @@ Keyword arguments are the following: Meson will also autodetect scripts with a shebang line and run them with the executable/interpreter specified in it both on Windows (because the command invocator will reject the command otherwise) and -Unixes (if the script file does not have the executable bit -set). Hence, you *must not* manually add the interpreter while using -this script as part of a list of commands. +Unixes (if the script file does not have the executable bit set). +Hence, you *must not* manually add the interpreter while using this +script as part of a list of commands. If you need to check for a program in a non-standard location, you can just pass an absolute path to `find_program`, e.g. @@ -926,7 +929,8 @@ The only exceptions are: `sysconfdir`, `localstatedir`, and configuration as-is, which may be absolute, or relative to `prefix`. [`install_dir` arguments](Installing.md) handles that as expected, but if you need the absolute path to one of these e.g. to use in a define -etc., you should use `get_option('prefix') / get_option('localstatedir')` +etc., you should use `get_option('prefix') / +get_option('localstatedir')` For options of type `feature` a [feature option object](#feature-option-object) @@ -1108,8 +1112,7 @@ Accepts the following keywords: Installs the specified man files from the source tree into system's man directory during the install step. This directory can be -overridden by specifying it with the `install_dir` keyword -argument. +overridden by specifying it with the `install_dir` keyword argument. Accepts the following keywords: @@ -1117,14 +1120,20 @@ Accepts the following keywords: format and optionally the owner/uid and group/gid for the installed files. An example value could be `['rwxr-sr-x', 'root', 'root']`. -*(since 0.49.0)* [manpages are no longer compressed implicitly][install_man_49]. +*(since 0.49.0)* [manpages are no longer compressed + implicitly][install_man_49]. -[install_man_49]: https://mesonbuild.com/Release-notes-for-0-49-0.html#manpages-are-no-longer-compressed-implicitly +[install_man_49]: +https://mesonbuild.com/Release-notes-for-0-49-0.html#manpages-are-no-longer-compressed-implicitly ### install_subdir() ``` meson - void install_subdir(subdir_name, install_dir : ..., exclude_files : ..., exclude_directories : ..., strip_directory : ...) + void install_subdir(subdir_name, + install_dir : ..., + exclude_files : ..., + exclude_directories : ..., + strip_directory : ...) ``` Installs the entire given subdirectory and its contents from the @@ -1286,8 +1295,8 @@ them for the default behaviour for each platform. This function prints its argument to stdout. -*(since 0.54.0)* Can take more than one argument that will be separated by -space. +*(since 0.54.0)* Can take more than one argument that will be +separated by space. ### warning() @@ -1315,19 +1324,21 @@ This function is used to summarize build configuration at the end of the build process. This function provides a way for projects (and subprojects) to report this information in a clear way. -The content is a series of key/value pairs grouped into sections. If the section -keyword argument is omitted, those key/value pairs are implicitly grouped into a section -with no title. key/value pairs can optionally be grouped into a dictionary, -but keep in mind that dictionaries does not guarantee ordering. `key` must be string, +The content is a series of key/value pairs grouped into sections. If +the section keyword argument is omitted, those key/value pairs are +implicitly grouped into a section with no title. key/value pairs can +optionally be grouped into a dictionary, but keep in mind that +dictionaries does not guarantee ordering. `key` must be string, `value` can be: - an integer, boolean or string - *since 0.57.0* an external program or a dependency - a list of those. -`summary()` can be called multiple times as long as the same section/key -pair doesn't appear twice. All sections will be collected and printed at -the end of the configuration in the same order as they have been called. +`summary()` can be called multiple times as long as the same +section/key pair doesn't appear twice. All sections will be collected +and printed at the end of the configuration in the same order as they +have been called. Keyword arguments: - `section`: title to group a set of key/value pairs. @@ -1388,10 +1399,10 @@ It may be followed by the list of programming languages that the project uses. *(since 0.40.0)* The list of languages is optional. -These languages may be used both for `native: false` (the default) (host -machine) targets and for `native: true` (build machine) targets. *(since -0.56.0)* The build machine compilers for the specified languages are not -required. +These languages may be used both for `native: false` (the default) +(host machine) targets and for `native: true` (build machine) targets. +*(since 0.56.0)* The build machine compilers for the specified +languages are not required. Supported values for languages are `c`, `cpp` (for `C++`), `cuda`, `d`, `objc`, `objcpp`, `fortran`, `java`, `cs` (for `C#`), `vala` and `rust`. @@ -1442,8 +1453,8 @@ Project supports the following keyword arguments. runresult run_command(command, list_of_args, ...) ``` -Runs the command specified in positional arguments. `command` can be -a string, or the output of [`find_program()`](#find_program), +Runs the command specified in positional arguments. `command` can be a +string, or the output of [`find_program()`](#find_program), [`files()`](#files) or [`configure_file()`](#configure_file), or [a compiler object](#compiler-object). @@ -1474,10 +1485,10 @@ runtarget run_target(target_name, ...) This function creates a new top-level target that runs a specified command with the specified arguments. Like all top-level targets, this -integrates with the selected backend. For instance, you can -run it as `meson compile target_name`. Note that a run target produces no -output as far as Meson is concerned. It is only meant for tasks such -as running a code formatter or flashing an external device's firmware +integrates with the selected backend. For instance, you can run it as +`meson compile target_name`. Note that a run target produces no output +as far as Meson is concerned. It is only meant for tasks such as +running a code formatter or flashing an external device's firmware with a built file. The command is run from an *unspecified* directory, and Meson will set @@ -1618,15 +1629,15 @@ This function has one keyword argument. subdir_done() ``` -Stops further interpretation of the meson script file from the point of -the invocation. All steps executed up to this point are valid and will -be executed by meson. This means that all targets defined before the call -of `subdir_done` will be build. +Stops further interpretation of the meson script file from the point +of the invocation. All steps executed up to this point are valid and +will be executed by meson. This means that all targets defined before +the call of `subdir_done` will be build. -If the current script was called by `subdir` the execution returns to the -calling directory and continues as if the script had reached the end. -If the current script is the top level script meson configures the project -as defined up to this point. +If the current script was called by `subdir` the execution returns to +the calling directory and continues as if the script had reached the +end. If the current script is the top level script meson configures +the project as defined up to this point. Example: ```meson @@ -1684,30 +1695,31 @@ argument to [`dependency()`](#dependency). Defines a test to run with the test harness. Takes two positional arguments, the first is the name of the test and the second is the -executable to run. The executable can be an [executable build target +executable to run. The executable can be an [executable build target object](#build-target-object) returned by [`executable()`](#executable) or an [external program object](#external-program-object) returned by [`find_program()`](#find_program). -*(since 0.55.0)* When cross compiling, if an exe_wrapper is needed and defined -the environment variable `MESON_EXE_WRAPPER` will be set to the string value -of that wrapper (implementation detail: using `mesonlib.join_args`). Test -scripts may use this to run cross built binaries. If your test needs -`MESON_EXE_WRAPPER` in cross build situations it is your responsibility to -return code 77 to tell the harness to report "skip". +*(since 0.55.0)* When cross compiling, if an exe_wrapper is needed and +defined the environment variable `MESON_EXE_WRAPPER` will be set to +the string value of that wrapper (implementation detail: using +`mesonlib.join_args`). Test scripts may use this to run cross built +binaries. If your test needs `MESON_EXE_WRAPPER` in cross build +situations it is your responsibility to return code 77 to tell the +harness to report "skip". By default, environment variable [`MALLOC_PERTURB_`](http://man7.org/linux/man-pages/man3/mallopt.3.html) is automatically set by `meson test` to a random value between 1..255. This can help find memory leaks on configurations using glibc, -including with non-GCC compilers. However, this can have a performance impact, -and may fail a test due to external libraries whose internals are out of the -user's control. To check if this feature is causing an expected runtime crash, -disable the feature by temporarily setting environment variable -`MALLOC_PERTURB_=0`. While it's preferable to only temporarily disable this -check, if a project requires permanent disabling of this check -in meson.build do like: +including with non-GCC compilers. However, this can have a performance +impact, and may fail a test due to external libraries whose internals +are out of the user's control. To check if this feature is causing an +expected runtime crash, disable the feature by temporarily setting +environment variable `MALLOC_PERTURB_=0`. While it's preferable to +only temporarily disable this check, if a project requires permanent +disabling of this check in meson.build do like: ```meson nomalloc = environment({'MALLOC_PERTURB_': '0'}) @@ -1798,10 +1810,10 @@ result to `output`. This method returns a used to signal dependencies if other targets use the file outputted by this. -For example, if you generate a header with this and want to use that in -a build target, you must add the return value to the sources of that -build target. Without that, Meson will not know the order in which to -build the targets. +For example, if you generate a header with this and want to use that +in a build target, you must add the return value to the sources of +that build target. Without that, Meson will not know the order in +which to build the targets. If you desire more specific behavior than what this command provides, you should use `custom_target`. @@ -2369,11 +2381,12 @@ The following keyword arguments can be used: `sizeof`, `has_type`, `has_function`, `has_member`, `has_members`, `check_header`, `has_header`, `has_header_symbol`, `get_define` -**Note:** These compiler checks do not use compiler arguments added with -`add_*_arguments()`, via `-Dlang_args` on the command-line, or through -`CFLAGS`/`LDFLAGS`, etc in the environment. Hence, you can trust that -the tests will be fully self-contained, and won't fail because of custom -flags added by other parts of the build file or by users. +**Note:** These compiler checks do not use compiler arguments added +with `add_*_arguments()`, via `-Dlang_args` on the command-line, or +through `CFLAGS`/`LDFLAGS`, etc in the environment. Hence, you can +trust that the tests will be fully self-contained, and won't fail +because of custom flags added by other parts of the build file or by +users. Note that if you have a single prefix with all your dependencies, you might find it easier to append to the environment variables @@ -2387,10 +2400,10 @@ cross-compiling. In that case you need to use a specs file. See: ### `build target` object -A build target is either an [executable](#executable), -[shared library](#shared_library), [static library](#static_library), -[both shared and static library](#both_libraries) or -[shared module](#shared_module). +A build target is either an [executable](#executable), [shared +library](#shared_library), [static library](#static_library), [both +shared and static library](#both_libraries) or [shared +module](#shared_module). - `extract_all_objects()`: is same as `extract_objects` but returns all object files generated by this target. *(since 0.46.0)* keyword argument diff --git a/docs/markdown/Reference-tables.md b/docs/markdown/Reference-tables.md index 3fadbde..9f6b704 100644 --- a/docs/markdown/Reference-tables.md +++ b/docs/markdown/Reference-tables.md @@ -159,20 +159,21 @@ These are the parameter names for passing language specific arguments to your bu | Rust | rust_args | rust_link_args | | Vala | vala_args | vala_link_args | -All these `<lang>_*` options are specified per machine. See in [specifying -options per machine](Builtin-options.md#Specifying-options-per-machine) for on -how to do this in cross builds. +All these `<lang>_*` options are specified per machine. See in +[specifying options per +machine](Builtin-options.md#Specifying-options-per-machine) for on how +to do this in cross builds. ## Compiler and linker flag environment variables These environment variables will be used to modify the compiler and linker flags. -It is recommended that you **do not use these**. They are provided purely to -for backwards compatibility with other build systems. There are many caveats to -their use, especially when rebuilding the project. It is **highly** recommended -that you use [the command line arguments](#language-arguments-parameter-names) -instead. +It is recommended that you **do not use these**. They are provided +purely to for backwards compatibility with other build systems. There +are many caveats to their use, especially when rebuilding the project. +It is **highly** recommended that you use [the command line +arguments](#language-arguments-parameter-names) instead. | Name | Comment | | ----- | ------- | @@ -185,8 +186,8 @@ instead. | RUSTFLAGS | Flags for the Rust compiler | | LDFLAGS | The linker flags, used for all languages | -N.B. these settings are specified per machine, and so the environment varibles -actually come in pairs. See the [environment variables per +N.B. these settings are specified per machine, and so the environment +varibles actually come in pairs. See the [environment variables per machine](#Environment-variables-per-machine) section for details. ## Function Attributes @@ -282,8 +283,8 @@ These are the values that can be passed to `dependency` function's ## Compiler and Linker selection variables -N.B. these settings are specified per machine, and so the environment varibles -actually come in pairs. See the [environment variables per +N.B. these settings are specified per machine, and so the environment +varibles actually come in pairs. See the [environment variables per machine](#Environment-variables-per-machine) section for details. | Language | Compiler | Linker | Note | @@ -298,16 +299,17 @@ machine](#Environment-variables-per-machine) section for details. | Vala | VALAC | | Use CC_LD. Vala transpiles to C | | C# | CSC | CSC | The linker is the compiler | -*The old environment variales are still supported, but are deprecated and will -be removed in a future version of meson.* +*The old environment variales are still supported, but are deprecated +and will be removed in a future version of meson.* ## Environment variables per machine -Since *0.54.0*, Following Autotool and other legacy build systems, environment -variables that affect machine-specific settings come in pairs: for every bare -environment variable `FOO`, there is a suffixed `FOO_FOR_BUILD`, where `FOO` -just affects the host machine configuration, while `FOO_FOR_BUILD` just affects -the build machine configuration. For example: +Since *0.54.0*, Following Autotool and other legacy build systems, +environment variables that affect machine-specific settings come in +pairs: for every bare environment variable `FOO`, there is a suffixed +`FOO_FOR_BUILD`, where `FOO` just affects the host machine +configuration, while `FOO_FOR_BUILD` just affects the build machine +configuration. For example: - `PKG_CONFIG_PATH_FOR_BUILD` controls the paths pkg-config will search for just `native: true` dependencies (build machine). @@ -315,12 +317,13 @@ the build machine configuration. For example: - `PKG_CONFIG_PATH` controls the paths pkg-config will search for just `native: false` dependencies (host machine). -This mirrors the `build.` prefix used for (built-in) meson options, which has -the same meaning. +This mirrors the `build.` prefix used for (built-in) meson options, +which has the same meaning. -This is useful for cross builds. In the native builds, build = host, and the -unsuffixed environment variables alone will suffice. +This is useful for cross builds. In the native builds, build = host, +and the unsuffixed environment variables alone will suffice. -Prior to *0.54.0*, there was no `_FOR_BUILD`-suffixed variables, and most -environment variables only effected native machine configurations, though this -wasn't consistent (e.g. `PKG_CONFIG_PATH` still affected cross builds). +Prior to *0.54.0*, there was no `_FOR_BUILD`-suffixed variables, and +most environment variables only effected native machine +configurations, though this wasn't consistent (e.g. `PKG_CONFIG_PATH` +still affected cross builds). diff --git a/docs/markdown/Release-notes-for-0.37.0.md b/docs/markdown/Release-notes-for-0.37.0.md index 7e8aa54..930c1d1 100644 --- a/docs/markdown/Release-notes-for-0.37.0.md +++ b/docs/markdown/Release-notes-for-0.37.0.md @@ -7,7 +7,8 @@ short-description: Release notes for 0.37 ## Mesontest -Mesontest is a new testing tool that allows you to run your tests in many different ways. As an example you can run tests multiple times: +Mesontest is a new testing tool that allows you to run your tests in +many different ways. As an example you can run tests multiple times: mesontest --repeat=1000 a_test @@ -15,13 +16,17 @@ or with an arbitrary wrapper executable: mesontest --wrap='valgrind --tool=helgrind' a_test -or under `gdb`, 1000 times in a row. This is handy for tests that fail spuriously, as when the crash happens you are given the full GDB command line: +or under `gdb`, 1000 times in a row. This is handy for tests that fail +spuriously, as when the crash happens you are given the full GDB +command line: mesontest --repeat=1000 --gdb a_test ## Mesonrewriter -Mesonrewriter is an experimental tool to manipulate your build definitions programmatically. It is not installed by default yet but those interested can run it from the source repository. +Mesonrewriter is an experimental tool to manipulate your build +definitions programmatically. It is not installed by default yet but +those interested can run it from the source repository. As an example, here is how you would add a source file to a build target: @@ -29,7 +34,9 @@ As an example, here is how you would add a source file to a build target: ## Shared modules -The new `shared_module` function allows the creation of shared modules, that is, extension modules such as plugins that are meant to be used solely with `dlopen` rather than linking them to targets. +The new `shared_module` function allows the creation of shared +modules, that is, extension modules such as plugins that are meant to +be used solely with `dlopen` rather than linking them to targets. ## Gnome module @@ -56,21 +63,32 @@ The new `shared_module` function allows the creation of shared modules, that is, ## LLVM IR compilation -Meson has long had support for compiling assembler (GAS) files. In this release we add support for compiling LLVM IR files in a similar way when building with the Clang compiler. Just add it to the list of files when creating a `library` or `executable` target like any other source file. No special handling is required: +Meson has long had support for compiling assembler (GAS) files. In +this release we add support for compiling LLVM IR files in a similar +way when building with the Clang compiler. Just add it to the list of +files when creating a `library` or `executable` target like any other +source file. No special handling is required: ```meson executable('some-exe', 'main.c', 'asm-file.S', 'ir-file.ll') ``` -As always, you can also mix LLVM IR files with C++, C, and Assembly (GAS) sources. +As always, you can also mix LLVM IR files with C++, C, and Assembly +(GAS) sources. ## ViM indent and syntax files -We now include filetype, indent, and syntax files for ViM [with the source tree](https://github.com/mesonbuild/meson/tree/master/data/syntax-highlighting/vim). Please file issues (or pull requests!) for enhancements or if you face any problems using them. +We now include filetype, indent, and syntax files for ViM [with the +source +tree](https://github.com/mesonbuild/meson/tree/master/data/syntax-highlighting/vim). +Please file issues (or pull requests!) for enhancements or if you face +any problems using them. ## Push URLs in .wrap files -[.wrap files](Using-the-WrapDB.md) for subprojects can now include a separate push URL to allow developers to push changes directly from a subproject git checkout. +[.wrap files](Using-the-WrapDB.md) for subprojects can now include a +separate push URL to allow developers to push changes directly from a +subproject git checkout. ## pkg-config dependencies @@ -87,7 +105,8 @@ dependency('foolite', version : ['>=3.12.1', '!=3.13.99']) ## Overriding more binaries with environment variables -You can now specify the binary to be used for the following tools by setting the corresponding environment variable +You can now specify the binary to be used for the following tools by +setting the corresponding environment variable | Name | Environment variable | | ---- | -------------------- | @@ -97,11 +116,18 @@ You can now specify the binary to be used for the following tools by setting the ## Support for `localstatedir` -Similar to other options such as `bindir` and `datadir`, you can now specify the `localstatedir` for a project by passing `--localstatedir=dir` to `meson` or `-Dlocalstatedir=dir` to `mesonconf` after configuration. You can also access it from inside the `meson.build` file with `get_option('localstatedir')`. +Similar to other options such as `bindir` and `datadir`, you can now +specify the `localstatedir` for a project by passing +`--localstatedir=dir` to `meson` or `-Dlocalstatedir=dir` to +`mesonconf` after configuration. You can also access it from inside +the `meson.build` file with `get_option('localstatedir')`. ## New compiler function `symbols_have_underscore_prefix` -Checks if the compiler prefixes an underscore to C global symbols with the default calling convention. This is useful when linking to compiled assembly code, or other code that does not have its C symbol mangling handled transparently by the compiler. +Checks if the compiler prefixes an underscore to C global symbols with +the default calling convention. This is useful when linking to +compiled assembly code, or other code that does not have its C symbol +mangling handled transparently by the compiler. ```meson cc = meson.get_compiler('c') @@ -111,18 +137,37 @@ if cc.symbols_have_underscore_prefix() endif ``` -C symbol mangling is platform and architecture dependent, and a helper function is needed to detect it. For example, Windows 32-bit prefixes underscore, but 64-bit does not. Linux does not prefix an underscore but OS X does. +C symbol mangling is platform and architecture dependent, and a helper +function is needed to detect it. For example, Windows 32-bit prefixes +underscore, but 64-bit does not. Linux does not prefix an underscore +but OS X does. ## Vala -GLib Resources compiled with [`gnome.compile_resources`](Gnome-module.md#compile_resources) that are added to the sources of a Vala build target will now cause the appropriate `--gresources` flag to be passed to the Vala compiler so you don't need to add that yourself to `vala_args:`. +GLib Resources compiled with +[`gnome.compile_resources`](Gnome-module.md#compile_resources) that +are added to the sources of a Vala build target will now cause the +appropriate `--gresources` flag to be passed to the Vala compiler so +you don't need to add that yourself to `vala_args:`. ## Improvements to install scripts -You can now pass arguments to install scripts added with [`meson.add_install_script()`](Reference-manual.md#meson-object). All arguments after the script name will be passed to the script. - -The `MESON_INSTALL_DESTDIR_PREFIX` environment variable is now set when install scripts are called. This contains the values of the `DESTDIR` environment variable and the `prefix` option passed to Meson joined together. This is useful because both those are usually absolute paths, and joining absolute paths in a cross-platform way is tricky. [`os.path.join` in Python](https://docs.python.org/3/library/os.path.html#os.path.join) will discard all previous path segments when it encounters an absolute path, and simply concatenating them will not work on Windows where absolute paths begin with the drive letter. +You can now pass arguments to install scripts added with +[`meson.add_install_script()`](Reference-manual.md#meson-object). All +arguments after the script name will be passed to the script. + +The `MESON_INSTALL_DESTDIR_PREFIX` environment variable is now set +when install scripts are called. This contains the values of the +`DESTDIR` environment variable and the `prefix` option passed to Meson +joined together. This is useful because both those are usually +absolute paths, and joining absolute paths in a cross-platform way is +tricky. [`os.path.join` in +Python](https://docs.python.org/3/library/os.path.html#os.path.join) +will discard all previous path segments when it encounters an absolute +path, and simply concatenating them will not work on Windows where +absolute paths begin with the drive letter. ## More install directories -Added new options `sbindir` and `infodir` that can be used for installation. +Added new options `sbindir` and `infodir` that can be used for +installation. diff --git a/docs/markdown/Release-notes-for-0.38.0.md b/docs/markdown/Release-notes-for-0.38.0.md index cbd8fff..152308d 100644 --- a/docs/markdown/Release-notes-for-0.38.0.md +++ b/docs/markdown/Release-notes-for-0.38.0.md @@ -5,11 +5,19 @@ short-description: Release notes for 0.38 ## Uninstall target -Meson allows you to uninstall an install step by invoking the uninstall target. This will remove all files installed as part of install. Note that this does not restore the original files. This also does not undo changes done by custom install scripts (because they can do arbitrary install operations). +Meson allows you to uninstall an install step by invoking the +uninstall target. This will remove all files installed as part of +install. Note that this does not restore the original files. This also +does not undo changes done by custom install scripts (because they can +do arbitrary install operations). ## Support for arbitrary test setups -Sometimes you need to run unit tests with special settings. For example under Valgrind. Usually this requires extra command line options for the tool. This is supported with the new *test setup* feature. For example to set up a test run with Valgrind, you'd write this in a `meson.build` file: +Sometimes you need to run unit tests with special settings. For +example under Valgrind. Usually this requires extra command line +options for the tool. This is supported with the new *test setup* +feature. For example to set up a test run with Valgrind, you'd write +this in a `meson.build` file: ```meson add_test_setup('valgrind', @@ -17,7 +25,9 @@ add_test_setup('valgrind', timeout_multiplier : 100) ``` -This tells Meson to run tests with Valgrind using the given options and multiplying the test timeout values by 100. To run this test setup simply issue the following command: +This tells Meson to run tests with Valgrind using the given options +and multiplying the test timeout values by 100. To run this test setup +simply issue the following command: ```console $ mesontest --setup=valgrind @@ -25,11 +35,13 @@ $ mesontest --setup=valgrind ## Intel C/C++ compiler support -As usual, just set `CC=icc CXX=icpc` and Meson will use it as the C/C++ compiler. Currently only Linux is supported. +As usual, just set `CC=icc CXX=icpc` and Meson will use it as the +C/C++ compiler. Currently only Linux is supported. ## Get values from configuration data objects -Now it is possible to query values stored in configuration data objects. +Now it is possible to query values stored in configuration data +objects. ```meson cdata.set('key', 'value') @@ -40,7 +52,8 @@ cdata.get('nokey') # halts with an error ## Python 3 module support -Building Python 3 extension modules has always been possible, but it is now even easier: +Building Python 3 extension modules has always been possible, but it +is now even easier: ```meson py3_mod = import('python3') @@ -51,34 +64,51 @@ pylib = py3_mod.extension_module('modname', ## Default options to subprojects -Projects can specify overriding values for subprojects' `default_options` when invoking a subproject: +Projects can specify overriding values for subprojects' +`default_options` when invoking a subproject: ```meson subproject('foo', default_options : ['optname=overridevalue']) dependency('some-dep', fallback : ['some_subproject', 'some_dep'], default_options : ['optname=overridevalue']) ``` -The effect is the same as if the default options were written in the subproject's `project` call. +The effect is the same as if the default options were written in the +subproject's `project` call. ## Set targets to be built (or not) by default -Build targets got a new keyword `build_by_default` which tells whether the target should be built by default when running e.g. `ninja`. Custom targets are not built by default but other targets are. Any target that is tagged as installed or to be built always is also built by default, regardless of the value of this keyword. +Build targets got a new keyword `build_by_default` which tells whether +the target should be built by default when running e.g. `ninja`. +Custom targets are not built by default but other targets are. Any +target that is tagged as installed or to be built always is also built +by default, regardless of the value of this keyword. ## Add option to mesonconf to wipe cached data. -Meson caches the results of dependency lookups. Sometimes these may get out of sync with the system state. Mesonconf now has a `--clearcache` option to clear these values so they will be re-searched from the system upon next compile. +Meson caches the results of dependency lookups. Sometimes these may +get out of sync with the system state. Mesonconf now has a +`--clearcache` option to clear these values so they will be +re-searched from the system upon next compile. ## Can specify file permissions and owner when installing data -The new `install_mode` keyword argument can be used to specify file permissions and uid/gid of files when doing the install. This allows you to, for example, install suid root scripts. +The new `install_mode` keyword argument can be used to specify file +permissions and uid/gid of files when doing the install. This allows +you to, for example, install suid root scripts. ## `has_header()` checks are now faster -When using compilers that implement the [`__has_include()` preprocessor macro](https://clang.llvm.org/docs/LanguageExtensions.html#include-file-checking-macros), the check is now ~40% faster. +When using compilers that implement the [`__has_include()` +preprocessor +macro](https://clang.llvm.org/docs/LanguageExtensions.html#include-file-checking-macros), +the check is now ~40% faster. ## Array indexing now supports fallback values -The second argument to the array [`.get()`](Reference-manual.md#array-object) function is now returned if the specified index could not be found +The second argument to the array +[`.get()`](Reference-manual.md#array-object) function is now returned +if the specified index could not be found + ```meson array = [10, 11, 12, 13] array.get(0) # this will return `10` @@ -88,4 +118,6 @@ array.get(4, 0) # this will return `0` ## Silent mode for Mesontest -The Meson test executor got a new argument `-q` (and `--quiet`) that suppresses all output of successful tests. This makes interactive usage nicer because only errors are printed. +The Meson test executor got a new argument `-q` (and `--quiet`) that +suppresses all output of successful tests. This makes interactive +usage nicer because only errors are printed. diff --git a/docs/markdown/Release-notes-for-0.39.0.md b/docs/markdown/Release-notes-for-0.39.0.md index 705bb80..73b49ae 100644 --- a/docs/markdown/Release-notes-for-0.39.0.md +++ b/docs/markdown/Release-notes-for-0.39.0.md @@ -3,12 +3,14 @@ title: Release 0.39 short-description: Release notes for 0.39 ... -The 0.39.0 release turned out to consist almost entirely of bug fixes and minor polishes. +The 0.39.0 release turned out to consist almost entirely of bug fixes +and minor polishes. # New features ## Extra arguments for tests -The Meson test executable allows specifying extra command line arguments to pass to test executables. +The Meson test executable allows specifying extra command line +arguments to pass to test executables. mesontest --test-args=--more-debug-info currenttest diff --git a/docs/markdown/Release-notes-for-0.40.0.md b/docs/markdown/Release-notes-for-0.40.0.md index a480788..9ba4839 100644 --- a/docs/markdown/Release-notes-for-0.40.0.md +++ b/docs/markdown/Release-notes-for-0.40.0.md @@ -7,11 +7,13 @@ short-description: Release notes for 0.40 ## Outputs of generators can be used in custom targets in the VS backend -This has been possible with the Ninja backend for a long time but now the Visual Studio backend works too. +This has been possible with the Ninja backend for a long time but now +the Visual Studio backend works too. ## `compute_int` method in the compiler objects -This method can be used to evaluate the value of an expression. As an example: +This method can be used to evaluate the value of an expression. As an +example: ```meson cc = meson.get_compiler('c') @@ -20,29 +22,44 @@ two = cc.compute_int('1 + 1') # A very slow way of adding two numbers. ## Visual Studio 2017 support -There is now a VS2017 backend (`--backend=vs2017`) as well as a generic VS backend (`--backend=vs`) that autodetects the currently active VS version. +There is now a VS2017 backend (`--backend=vs2017`) as well as a +generic VS backend (`--backend=vs`) that autodetects the currently +active VS version. ## Automatic initialization of subprojects that are git submodules -If you have a directory inside your subprojects directory (usually `subprojects/`) that is a git submodule, meson will automatically initialize it if your build files refer to it. This will be done without needing a wrap file since git contains all the information needed. +If you have a directory inside your subprojects directory (usually +`subprojects/`) that is a git submodule, meson will automatically +initialize it if your build files refer to it. This will be done +without needing a wrap file since git contains all the information +needed. ## No download mode for wraps -Added a new option `wrap-mode` that can be toggled to prevent Meson from downloading dependency projects. Attempting to do so will cause an error. This is useful for distro packagers and other cases where you must explicitly enforce that nothing is downloaded from the net during configuration or build. +Added a new option `wrap-mode` that can be toggled to prevent Meson +from downloading dependency projects. Attempting to do so will cause +an error. This is useful for distro packagers and other cases where +you must explicitly enforce that nothing is downloaded from the net +during configuration or build. ## Overriding options per target -Build targets got a new keyword argument `override_options` that can be used to override system options. As an example if you have a target that you know can't be built with `-Werror` enabled you can override the value of the option like this: +Build targets got a new keyword argument `override_options` that can +be used to override system options. As an example if you have a target +that you know can't be built with `-Werror` enabled you can override +the value of the option like this: ```meson executable('foo', 'foo.c', override_options : ['werror=false']) ``` -Note that this does not affect project options, only those options that come from Meson (language standards, unity builds etc). +Note that this does not affect project options, only those options +that come from Meson (language standards, unity builds etc). ## Compiler object get define -Compiler objects got a new method `get_define()` that returns the given preprocessor symbol as a string. +Compiler objects got a new method `get_define()` that returns the +given preprocessor symbol as a string. ```meson cc = meson.get_compiler('c') @@ -51,11 +68,14 @@ one = cc.get_define('__linux__') # returns '1' on Linux hosts ## Cygwin support -Meson now works under Cygwin and we have added it to our CI test matrix. +Meson now works under Cygwin and we have added it to our CI test +matrix. ## Multiple install directories -Custom targets can produce many output files. Previously it was only possible to install all of them in the same directory, but now you can install each output in its own directory like this: +Custom targets can produce many output files. Previously it was only +possible to install all of them in the same directory, but now you can +install each output in its own directory like this: ```meson custom_target('two_out', @@ -65,9 +85,13 @@ custom_target('two_out', install_dir : ['dir1', 'dir2']) ``` -For backwards compatibility and for conciseness, if you only specify one directory all outputs will be installed into it. +For backwards compatibility and for conciseness, if you only specify +one directory all outputs will be installed into it. -The same feature is also available for Vala build targets. For instance, to install a shared library built by valac, the generated header, and the generated VAPI (respectively) into the default locations, you can do: +The same feature is also available for Vala build targets. For +instance, to install a shared library built by valac, the generated +header, and the generated VAPI (respectively) into the default +locations, you can do: ```meson shared_library('valalib', 'mylib.vala', @@ -75,11 +99,18 @@ shared_library('valalib', 'mylib.vala', install_dir : [true, true, true]) ``` -To install any of the three in a custom directory, just pass it as a string instead of `true`. To not install it, pass `false`. You can also pass a single string (as before) and it will cause only the library to be installed, so this is a backwards-compatible change. +To install any of the three in a custom directory, just pass it as a +string instead of `true`. To not install it, pass `false`. You can +also pass a single string (as before) and it will cause only the +library to be installed, so this is a backwards-compatible change. ## Can specify method of obtaining dependencies -Some dependencies have many ways of being provided. As an example Qt can either be detected via `pkg-config` or `qmake`. Until now Meson has had a heuristic for selecting which method to choose but sometimes it does the wrong thing. This can now be overridden with the `method` keyword like this: +Some dependencies have many ways of being provided. As an example Qt +can either be detected via `pkg-config` or `qmake`. Until now Meson +has had a heuristic for selecting which method to choose but sometimes +it does the wrong thing. This can now be overridden with the `method` +keyword like this: ```meson qt5_dep = dependency('qt5', modules : 'core', method : 'qmake') @@ -87,20 +118,35 @@ qt5_dep = dependency('qt5', modules : 'core', method : 'qmake') ## Link whole contents of static libraries -The default behavior of static libraries is to discard all symbols that are not not directly referenced. This may lead to exported symbols being lost. Most compilers support "whole archive" linking that includes all symbols and code of a given static library. This is exposed with the `link_whole` keyword. +The default behavior of static libraries is to discard all symbols +that are not not directly referenced. This may lead to exported +symbols being lost. Most compilers support "whole archive" linking +that includes all symbols and code of a given static library. This is +exposed with the `link_whole` keyword. ```meson shared_library('foo', 'foo.c', link_whole : some_static_library) ``` -Note that Visual Studio compilers only support this functionality on VS 2015 and newer. +Note that Visual Studio compilers only support this functionality on +VS 2015 and newer. ## Unity builds only for subprojects -Up until now unity builds were either done for every target or none of them. Now unity builds can be specified to be enabled only for subprojects, which change seldom, and not for the master project, which changes a lot. This is enabled by setting the `unity` option to `subprojects`. +Up until now unity builds were either done for every target or none of +them. Now unity builds can be specified to be enabled only for +subprojects, which change seldom, and not for the master project, +which changes a lot. This is enabled by setting the `unity` option to +`subprojects`. ## Running `mesonintrospect` from scripts -Meson now sets the `MESONINTROSPECT` environment variable in addition to `MESON_SOURCE_ROOT` and other variables when running scripts. It is guaranteed to point to the correct `mesonintrospect` script, which is important when running meson uninstalled from git or when your `PATH`s may not be set up correctly. +Meson now sets the `MESONINTROSPECT` environment variable in addition +to `MESON_SOURCE_ROOT` and other variables when running scripts. It is +guaranteed to point to the correct `mesonintrospect` script, which is +important when running meson uninstalled from git or when your `PATH`s +may not be set up correctly. -Specifically, the following meson functions will set it: `meson.add_install_script()`, `meson.add_postconf_script()`, `run_command()`, `run_target()`. +Specifically, the following meson functions will set it: +`meson.add_install_script()`, `meson.add_postconf_script()`, +`run_command()`, `run_target()`. diff --git a/docs/markdown/Release-notes-for-0.41.0.md b/docs/markdown/Release-notes-for-0.41.0.md index 7861aad..8ce181a 100644 --- a/docs/markdown/Release-notes-for-0.41.0.md +++ b/docs/markdown/Release-notes-for-0.41.0.md @@ -11,15 +11,15 @@ Native support for linking against LLVM using the `dependency` function. ## vcs_tag keyword fallback is now optional -The `fallback` keyword in `vcs_tag()` is now optional. If not given, its value -defaults to the return value of `meson.project_version()`. +The `fallback` keyword in `vcs_tag()` is now optional. If not given, +its value defaults to the return value of `meson.project_version()`. ## Better quoting of special characters in ninja command invocations -The ninja backend now quotes special characters that may be interpreted by -ninja itself, providing better interoperability with custom commands. This -support may not be perfect; please report any issues found with special -characters to the issue tracker. +The ninja backend now quotes special characters that may be +interpreted by ninja itself, providing better interoperability with +custom commands. This support may not be perfect; please report any +issues found with special characters to the issue tracker. ## Pkgconfig support for custom variables diff --git a/docs/markdown/Release-notes-for-0.42.0.md b/docs/markdown/Release-notes-for-0.42.0.md index e89f1a1..585380b 100644 --- a/docs/markdown/Release-notes-for-0.42.0.md +++ b/docs/markdown/Release-notes-for-0.42.0.md @@ -7,19 +7,20 @@ short-description: Release notes for 0.42 ## Distribution tarballs from Mercurial repositories -Creating distribution tarballs can now be made out of projects based on -Mercurial. As before, this remains possible only with the Ninja backend. +Creating distribution tarballs can now be made out of projects based +on Mercurial. As before, this remains possible only with the Ninja +backend. ## Keyword argument verification -Meson will now check the keyword arguments used when calling any function -and print a warning if any of the keyword arguments is not known. In the -future this will become a hard error. +Meson will now check the keyword arguments used when calling any +function and print a warning if any of the keyword arguments is not +known. In the future this will become a hard error. ## Add support for Genie to Vala compiler -The Vala compiler has an alternative syntax, Genie, that uses the `.gs` -file extension. Meson now recognises and uses Genie files. +The Vala compiler has an alternative syntax, Genie, that uses the +`.gs` file extension. Meson now recognises and uses Genie files. ## Pkgconfig support for additional cflags @@ -47,8 +48,8 @@ uses_lto = get_option('b_lto') Rust targets now take an optional `rust_crate_type` keyword, allowing you to set the crate type of the resulting artifact. Valid crate types are `dylib` or `cdylib` for shared libraries, and `rlib` or -`staticlib` for static libraries. For more, see -Rust's [linkage reference][rust-linkage]. +`staticlib` for static libraries. For more, see Rust's [linkage +reference][rust-linkage]. [rust-linkage]: https://doc.rust-lang.org/reference/linkage.html diff --git a/docs/markdown/Release-notes-for-0.43.0.md b/docs/markdown/Release-notes-for-0.43.0.md index 0ca66ae..1ce774d 100644 --- a/docs/markdown/Release-notes-for-0.43.0.md +++ b/docs/markdown/Release-notes-for-0.43.0.md @@ -5,11 +5,12 @@ short-description: Release notes for 0.43 ## Portability improvements to Boost Dependency -The Boost dependency has been improved to better detect the various ways to -install boost on multiple platforms. At the same time the `modules` semantics -for the dependency has been changed. Previously it was allowed to specify -header directories as `modules` but it wasn't required. Now, modules are only -used to specify libraries that require linking. +The Boost dependency has been improved to better detect the various +ways to install boost on multiple platforms. At the same time the +`modules` semantics for the dependency has been changed. Previously it +was allowed to specify header directories as `modules` but it wasn't +required. Now, modules are only used to specify libraries that require +linking. This is a breaking change and the fix is to remove all modules that aren't found. @@ -21,10 +22,11 @@ Generators can now be configured to capture the standard output. See ## Can index CustomTarget objects -The `CustomTarget` object can now be indexed like an array. The resulting -object can be used as a source file for other Targets, this will create a -dependency on the original `CustomTarget`, but will only insert the generated -file corresponding to the index value of the `CustomTarget`'s `output` keyword. +The `CustomTarget` object can now be indexed like an array. The +resulting object can be used as a source file for other Targets, this +will create a dependency on the original `CustomTarget`, but will only +insert the generated file corresponding to the index value of the +`CustomTarget`'s `output` keyword. ```meson c = custom_target( @@ -65,8 +67,8 @@ native_objdump = find_program('objdump', native : true) ## Easier handling of supported compiler arguments -A common pattern for handling multiple desired compiler arguments, was to -test their presence and add them to an array one-by-one, e.g.: +A common pattern for handling multiple desired compiler arguments, was +to test their presence and add them to an array one-by-one, e.g.: ```meson warning_flags_maybe = [ @@ -83,8 +85,8 @@ endforeach cc.add_project_argument(warning_flags) ``` -A helper has been added for the foreach/has_argument pattern, so you can -now simply do: +A helper has been added for the foreach/has_argument pattern, so you +can now simply do: ```meson warning_flags = [ ... ] @@ -93,11 +95,11 @@ flags = cc.get_supported_arguments(warning_flags) ## Better support for shared libraries in non-system paths -Meson has support for prebuilt object files and static libraries. -This release adds feature parity to shared libraries that are either -in non-standard system paths or shipped as part of your project. On -systems that support rpath, Meson automatically adds rpath entries -to built targets using manually found external libraries. +Meson has support for prebuilt object files and static libraries. This +release adds feature parity to shared libraries that are either in +non-standard system paths or shipped as part of your project. On +systems that support rpath, Meson automatically adds rpath entries to +built targets using manually found external libraries. This means that e.g. supporting prebuilt libraries shipped with your source or provided by subprojects or wrap definitions by writing a @@ -117,7 +119,7 @@ Then you can use the dependency object in the same way as any other. ## wrap-svn The [Wrap dependency system](Wrap-dependency-system-manual.md) now -supports [Subversion](https://subversion.apache.org/) (svn). This +supports [Subversion](https://subversion.apache.org/) (svn). This support is rudimentary. The repository url has to point to a specific -(sub)directory containing the `meson.build` file (typically -`trunk/`). However, providing a `revision` is supported. +(sub)directory containing the `meson.build` file (typically `trunk/`). +However, providing a `revision` is supported. diff --git a/docs/markdown/Release-notes-for-0.44.0.md b/docs/markdown/Release-notes-for-0.44.0.md index d765940..4948893 100644 --- a/docs/markdown/Release-notes-for-0.44.0.md +++ b/docs/markdown/Release-notes-for-0.44.0.md @@ -7,8 +7,8 @@ short-description: Release notes for 0.44 ## Added warning function -This function prints its argument to the console prefixed by "WARNING:" in -yellow color. A simple example: +This function prints its argument to the console prefixed by +"WARNING:" in yellow color. A simple example: warning('foo is deprecated, please use bar instead') @@ -31,8 +31,8 @@ These options now default in a way consistent with If prefix is `/usr`, default sysconfdir to `/etc`, localstatedir to `/var` and sharedstatedir to `/var/lib`. -If prefix is `/usr/local` (the default), default localstatedir to `/var/local` -and sharedstatedir to `/var/local/lib`. +If prefix is `/usr/local` (the default), default localstatedir to +`/var/local` and sharedstatedir to `/var/local/lib`. ## An array type for user options @@ -57,12 +57,12 @@ meson _build -Darray_opt=two,three ## LLVM dependency supports both dynamic and static linking -The LLVM dependency has been improved to consistently use dynamic linking. -Previously recent version (>= 3.9) would link dynamically while older versions -would link statically. +The LLVM dependency has been improved to consistently use dynamic +linking. Previously recent version (>= 3.9) would link dynamically +while older versions would link statically. -Now LLVM also accepts the `static` keyword to enable statically linking to LLVM -modules instead of dynamically linking. +Now LLVM also accepts the `static` keyword to enable statically +linking to LLVM modules instead of dynamically linking. ## Added `if_found` to subdir @@ -124,8 +124,8 @@ statements. ## Config-Tool based dependencies gained a method to get arbitrary options -A number of dependencies (CUPS, LLVM, pcap, WxWidgets, GnuStep) use a config -tool instead of pkg-config. As of this version they now have a +A number of dependencies (CUPS, LLVM, pcap, WxWidgets, GnuStep) use a +config tool instead of pkg-config. As of this version they now have a `get_configtool_variable` method, which is analogous to the `get_pkgconfig_variable` for pkg config. @@ -136,9 +136,9 @@ llvm_inc_dir = dep_llvm.get_configtool_variable('includedir') ## Embedded Python in Windows MSI packages -Meson now ships an internal version of Python in the MSI installer packages. -This means that it can run Python scripts that are part of your build -transparently. That is, if you do the following: +Meson now ships an internal version of Python in the MSI installer +packages. This means that it can run Python scripts that are part of +your build transparently. That is, if you do the following: ```meson myprog = find_program('myscript.py') @@ -148,6 +148,7 @@ Then Meson will run the script with its internal Python version if necessary. ## Libwmf dependency now supports libwmf-config -Earlier, `dependency('libwmf')` could only detect the library with pkg-config -files. Now, if pkg-config files are not found, Meson will look for -`libwmf-config` and if it's found, will use that to find the library. +Earlier, `dependency('libwmf')` could only detect the library with +pkg-config files. Now, if pkg-config files are not found, Meson will +look for `libwmf-config` and if it's found, will use that to find the +library. diff --git a/docs/markdown/Release-notes-for-0.45.0.md b/docs/markdown/Release-notes-for-0.45.0.md index 2b67f9b..9dd56e3 100644 --- a/docs/markdown/Release-notes-for-0.45.0.md +++ b/docs/markdown/Release-notes-for-0.45.0.md @@ -96,9 +96,9 @@ int_255 = 0xFF The value `if-release` can be given for the `b_ndebug` project option. -This will make the `NDEBUG` pre-compiler macro to be defined for release -type builds as if the `b_ndebug` project option had had the value `true` -defined for it. +This will make the `NDEBUG` pre-compiler macro to be defined for +release type builds as if the `b_ndebug` project option had had the +value `true` defined for it. ## `install_data()` defaults to `{datadir}/{projectname}` @@ -128,9 +128,9 @@ returns a list of all licenses for the project. ## Rust cross-compilation Cross-compilation is now supported for Rust targets. Like other -cross-compilers, the Rust binary must be specified in your cross -file. It should specify a `--target` (as installed by `rustup target`) -and a custom linker pointing to your C cross-compiler. For example: +cross-compilers, the Rust binary must be specified in your cross file. +It should specify a `--target` (as installed by `rustup target`) and a +custom linker pointing to your C cross-compiler. For example: ```ini [binaries] @@ -151,8 +151,8 @@ private sysroot. ## Project templates -Meson ships with predefined project templates. To start a new project from -scratch, simply go to an empty directory and type: +Meson ships with predefined project templates. To start a new project +from scratch, simply go to an empty directory and type: meson init --name=myproject --type=executable --language=c @@ -175,11 +175,13 @@ defined in it. ## Can use custom targets as Windows resource files -The `compile_resources()` function of the `windows` module can now be used on custom targets as well as regular files. +The `compile_resources()` function of the `windows` module can now be +used on custom targets as well as regular files. ## Can promote dependencies with wrap command -The `promote` command makes it easy to copy nested dependencies to the top level. +The `promote` command makes it easy to copy nested dependencies to the +top level. meson wrap promote scommon diff --git a/docs/markdown/Release-notes-for-0.46.0.md b/docs/markdown/Release-notes-for-0.46.0.md index e3b45e9..fd63fd0 100644 --- a/docs/markdown/Release-notes-for-0.46.0.md +++ b/docs/markdown/Release-notes-for-0.46.0.md @@ -7,10 +7,11 @@ short-description: Release notes for 0.46 ## Allow early return from a script -Added the function `subdir_done()`. Its invocation exits the current script at -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. +Added the function `subdir_done()`. Its invocation exits the current +script at 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. ## Log output slightly changed @@ -20,12 +21,12 @@ adjust your code. ## ARM compiler for C and CPP -Cross-compilation is now supported for ARM targets using ARM compiler - ARMCC. -The current implementation does not support shareable libraries. -The default extension of the output is .axf. -The environment path should be set properly for the ARM compiler executables. -The '--cpu' option with the appropriate target type should be mentioned -in the cross file as shown in the snippet below. +Cross-compilation is now supported for ARM targets using ARM compiler +- ARMCC. The current implementation does not support shareable +libraries. The default extension of the output is .axf. The +environment path should be set properly for the ARM compiler +executables. The '--cpu' option with the appropriate target type +should be mentioned in the cross file as shown in the snippet below. ```ini [properties] @@ -36,20 +37,20 @@ cpp_args = ['--cpu=Cortex-M0plus'] ## Building both shared and static libraries -A new function `both_libraries()` has been added to build both shared and static -libraries at the same time. Source files will be compiled only once and object -files will be reused to build both shared and static libraries, unless -`b_staticpic` user option or `pic:` keyword argument are set to false in which -case sources will be compiled twice. +A new function `both_libraries()` has been added to build both shared +and static libraries at the same time. Source files will be compiled +only once and object files will be reused to build both shared and +static libraries, unless `b_staticpic` user option or `pic:` keyword +argument are set to false in which case sources will be compiled +twice. The returned `buildtarget` object always represents the shared library. ## Compiler object can now be passed to run_command() -This can be used to run the current compiler with the specified arguments -to obtain additional information from it. -One of the use cases is to get the location of development files for the -GCC plugins: +This can be used to run the current compiler with the specified +arguments to obtain additional information from it. One of the use +cases is to get the location of development files for the GCC plugins: ```meson cc = meson.get_compiler('c') @@ -64,25 +65,26 @@ transparently works for build targets which use that dependency. ## Old command names are now errors -The old executable names `mesonintrospect`, `mesonconf`, `mesonrewriter` -and `mesontest` have been deprecated for a long time. Starting from -this version they no longer do anything but instead always error -out. All functionality is available as subcommands in the main `meson` -binary. +The old executable names `mesonintrospect`, `mesonconf`, +`mesonrewriter` and `mesontest` have been deprecated for a long time. +Starting from this version they no longer do anything but instead +always error out. All functionality is available as subcommands in the +main `meson` binary. ## Meson and meson configure now accept the same arguments -Previously meson required that builtin arguments (like prefix) be passed as -`--prefix` to `meson` and `-Dprefix` to `meson configure`. `meson` now accepts -D -form like `meson configure` has. `meson configure` also accepts the `--prefix` -form, like `meson` has. +Previously meson required that builtin arguments (like prefix) be +passed as `--prefix` to `meson` and `-Dprefix` to `meson configure`. +`meson` now accepts -D form like `meson configure` has. `meson +configure` also accepts the `--prefix` form, like `meson` has. ## Recursively extract objects -The `recursive:` keyword argument has been added to `extract_all_objects()`. When set -to `true` it will also return objects passed to the `objects:` argument of this -target. By default only objects built for this target are returned to maintain -backward compatibility with previous versions. The default will eventually be +The `recursive:` keyword argument has been added to +`extract_all_objects()`. When set to `true` it will also return +objects passed to the `objects:` argument of this target. By default +only objects built for this target are returned to maintain backward +compatibility with previous versions. The default will eventually be changed to `true` in a future version. ```meson @@ -130,8 +132,9 @@ meson.override_find_program('mycodegen', prog_script) ## New functions: has_link_argument() and friends -A new set of methods has been added to [compiler objects](Reference-manual.md#compiler-object) -to test if the linker supports given arguments. +A new set of methods has been added to [compiler +objects](Reference-manual.md#compiler-object) to test if the linker +supports given arguments. - `has_link_argument()` - `has_multi_link_arguments()` @@ -150,9 +153,9 @@ directory called "help" in these cases. A feature to generate a meson.build file compiling given C/C++ source files into a single executable has been added to "meson init". By default, it will take all recognizable source files in the current -directory. You can also specify a list of dependencies with the -d +directory. You can also specify a list of dependencies with the -d flag and automatically invoke a build with the -b flag to check if the -code builds with those dependencies. +code builds with those dependencies. For example, @@ -182,8 +185,9 @@ install_data(['file1.txt', 'file2.txt'], ## Support for lcc compiler for e2k (Elbrus) architecture In this version, a support for lcc compiler for Elbrus processors -based on [e2k microarchitecture](https://en.wikipedia.org/wiki/Elbrus_2000) -has been added. +based on [e2k +microarchitecture](https://en.wikipedia.org/wiki/Elbrus_2000) has been +added. Examples of such CPUs: * [Elbrus-8S](https://en.wikipedia.org/wiki/Elbrus-8S); @@ -206,47 +210,52 @@ So every noted difference is properly handled now in meson. ## String escape character sequence update Single-quoted strings in meson have been taught the same set of escape -sequences as in Python. It is therefore now possible to use arbitrary bytes in -strings, like for example `NUL` (`\0`) and other ASCII control characters. See -the chapter about [*Strings* in *Syntax*](Syntax.md#strings) for more -details. +sequences as in Python. It is therefore now possible to use arbitrary +bytes in strings, like for example `NUL` (`\0`) and other ASCII +control characters. See the chapter about [*Strings* in +*Syntax*](Syntax.md#strings) for more details. -Potential backwards compatibility issue: Any valid escape sequence according to -the new rules will be interpreted as an escape sequence instead of the literal -characters. Previously only the following escape sequences were supported in -single-quote strings: `\'`, `\\` and `\n`. +Potential backwards compatibility issue: Any valid escape sequence +according to the new rules will be interpreted as an escape sequence +instead of the literal characters. Previously only the following +escape sequences were supported in single-quote strings: `\'`, `\\` +and `\n`. -Note that the behaviour of triple-quoted (multiline) strings has not changed. -They behave like raw strings and do not support any escape sequences. +Note that the behaviour of triple-quoted (multiline) strings has not +changed. They behave like raw strings and do not support any escape +sequences. ## New `forcefallback` wrap mode -A new wrap mode was added, `--wrap-mode=forcefallback`. When this is set, -dependencies for which a fallback was provided will always use it, even -if an external dependency exists and satisfies the version requirements. +A new wrap mode was added, `--wrap-mode=forcefallback`. When this is +set, dependencies for which a fallback was provided will always use +it, even if an external dependency exists and satisfies the version +requirements. ## Relaxing of target name requirements -In earlier versions of Meson you could only have one target of a given name for each type. -For example you could not have two executables named `foo`. This requirement is now -relaxed so that you can have multiple targets with the same name, as long as they are in -different subdirectories. +In earlier versions of Meson you could only have one target of a given +name for each type. For example you could not have two executables +named `foo`. This requirement is now relaxed so that you can have +multiple targets with the same name, as long as they are in different +subdirectories. -Note that projects that have multiple targets with the same name can not be built with -the `flat` layout or any backend that writes outputs in the same directory. +Note that projects that have multiple targets with the same name can +not be built with the `flat` layout or any backend that writes outputs +in the same directory. ## Addition of OpenMP dependency -An OpenMP dependency (`openmp`) has been added that encapsulates the various -flags used by compilers to enable OpenMP and checks for the existence of the -`omp.h` header. The `language` keyword may be passed to force the use of a -specific compiler for the checks. +An OpenMP dependency (`openmp`) has been added that encapsulates the +various flags used by compilers to enable OpenMP and checks for the +existence of the `omp.h` header. The `language` keyword may be passed +to force the use of a specific compiler for the checks. ## Added new partial_dependency method to dependencies and libraries -It is now possible to use only part of a dependency in a target. This allows, -for example, to only use headers with convenience libraries to avoid linking -to the same library multiple times. +It is now possible to use only part of a dependency in a target. This +allows, for example, to only use headers with convenience libraries to +avoid linking to the same library multiple times. ```meson dep = dependency('xcb') @@ -264,22 +273,25 @@ final = shared_library( ) ``` -A partial dependency will have the same name version as the full dependency it -is derived from, as well as any values requested. +A partial dependency will have the same name version as the full +dependency it is derived from, as well as any values requested. ## Improved generation of pkg-config files for static only libraries. -Previously pkg-config files generated by the pkgconfig modules for static libraries -with dependencies could only be used in a dependencies with `static: true`. +Previously pkg-config files generated by the pkgconfig modules for +static libraries with dependencies could only be used in a +dependencies with `static: true`. -Now the generated file contains the needed dependencies libraries directly within -`Requires` and `Libs` for build static libraries passed via the `libraries` keyword -argument. +Now the generated file contains the needed dependencies libraries +directly within `Requires` and `Libs` for build static libraries +passed via the `libraries` keyword argument. -Projects that install both a static and a shared version of a library should use -the result of [`both_libraries()`](Reference-manual.md#both_libraries) to the -pkg-config file generator or use [`configure_file()`](Reference-manual.md#configure_file) -for more complicated setups. +Projects that install both a static and a shared version of a library +should use the result of +[`both_libraries()`](Reference-manual.md#both_libraries) to the +pkg-config file generator or use +[`configure_file()`](Reference-manual.md#configure_file) for more +complicated setups. ## Improvements to pkgconfig module @@ -298,19 +310,20 @@ pkgconfig.generate(mylib) ## pkgconfig.generate() requires parameters non-string arguments -`pkgconfig.generate()` `requires:` and `requires_private:` keyword arguments -now accept pkgconfig-dependencies and libraries that pkgconfig-files were -generated for. +`pkgconfig.generate()` `requires:` and `requires_private:` keyword +arguments now accept pkgconfig-dependencies and libraries that +pkgconfig-files were generated for. ## Generic python module -Meson now has is a revamped and generic (python 2 and 3) version of the python3 -module. With [this new interface](Python-module.md), projects can now fully -specify the version of python they want to build against / install sources to, -and can do so against multiple major or minor versions in parallel. +Meson now has is a revamped and generic (python 2 and 3) version of +the python3 module. With [this new interface](Python-module.md), +projects can now fully specify the version of python they want to +build against / install sources to, and can do so against multiple +major or minor versions in parallel. ## test() now supports the `depends:` keyword argument -Build targets and custom targets can be listed in the `depends:` keyword argument -of test function. These targets will be built before test is run even if they have -`build_by_default : false`. +Build targets and custom targets can be listed in the `depends:` +keyword argument of test function. These targets will be built before +test is run even if they have `build_by_default : false`. diff --git a/docs/markdown/Release-notes-for-0.47.0.md b/docs/markdown/Release-notes-for-0.47.0.md index 9093035..df230dd 100644 --- a/docs/markdown/Release-notes-for-0.47.0.md +++ b/docs/markdown/Release-notes-for-0.47.0.md @@ -7,32 +7,34 @@ short-description: Release notes for 0.47 ## Allow early return from a script -Added the function `subdir_done()`. Its invocation exits the current script at -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. +Added the function `subdir_done()`. Its invocation exits the current +script at 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()` -After obtaining the value of a preprocessor symbol consecutive string literals -are merged into a single string literal. -For example a preprocessor symbol's value `"ab" "cd"` is returned as `"abcd"`. +After obtaining the value of a preprocessor symbol consecutive string +literals are merged into a single string literal. For example a +preprocessor symbol's value `"ab" "cd"` is returned as `"abcd"`. ## ARM compiler(version 6) for C and CPP Cross-compilation is now supported for ARM targets using ARM compiler -version 6 - ARMCLANG. The required ARMCLANG compiler options for +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 -syntax. +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 syntax. -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 -in the cross file as shown in the snippet below. +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 in the cross file as shown in the snippet +below. ```ini [properties] @@ -48,61 +50,63 @@ Note: ## New base build option for LLVM (Apple) bitcode support -When building with clang on macOS, you can now build your static and shared -binaries with embedded bitcode by enabling the `b_bitcode` [base -option](Builtin-options.md#base-options) by passing `-Db_bitcode=true` to -Meson. +When building with clang on macOS, you can now build your static and +shared binaries with embedded bitcode by enabling the `b_bitcode` +[base option](Builtin-options.md#base-options) by passing +`-Db_bitcode=true` to Meson. -This is better than passing the options manually in the environment since Meson -will automatically disable conflicting options such as `b_asneeded`, and will -disable bitcode support on targets that don't support it such as -`shared_module()`. +This is better than passing the options manually in the environment +since Meson will automatically disable conflicting options such as +`b_asneeded`, and will disable bitcode support on targets that don't +support it such as `shared_module()`. -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. +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()` -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. +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. -However, sometimes the header you are looking for is unusable on some platforms -or with some compilers in a way that is only detectable at compile-time. For -such cases, you should use `check_header()` which will include the header and -run a full compile. +However, sometimes the header you are looking for is unusable on some +platforms or with some compilers in a way that is only detectable at +compile-time. For such cases, you should use `check_header()` which +will include the header and run a full compile. -Note that `has_header()` is much faster than `check_header()`, so it should be -used whenever possible. +Note that `has_header()` is much faster than `check_header()`, so it +should be used whenever possible. ## New action `copy:` for `configure_file()` 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 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. +[`configure_file()`](Reference-manual.md#configure_file) now accepts a +keyword 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. +These three keyword arguments are, as before, mutually exclusive. You +can only do one action at a time. ## 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. The +Add a new keyword to +[`configure_file()`](Reference-manual.md#configure_file) that allows +the developer to specify the input and output file encoding. The default value is the same as before: UTF-8. -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. +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. For additional details see [#3135](https://github.com/mesonbuild/meson/pull/3135). ## 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 +When called without an input file, `configure_file` generates a C +header file by default. A keyword argument was added to allow specifying the output format, for example for use with nasm or yasm: ```meson @@ -121,23 +125,24 @@ and `@PLAINNAME@` substitutions. ## 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 -targets. This option is therefore deprecated and the new option -`build_always_stale` is introduced. +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 targets. This option is therefore deprecated and +the new option `build_always_stale` is introduced. -`build_always_stale` *only* marks the target to be always considered out of -date, but does not add it to the set of default targets. The old behaviour can -be achieved by combining `build_always_stale` with `build_by_default`. +`build_always_stale` *only* marks the target to be always considered +out of date, but does not add it to the set of default targets. The +old behaviour can be achieved by combining `build_always_stale` with +`build_by_default`. The documentation has been updated accordingly. ## 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 -be string literals, and initializing a dictionary with duplicate -keys causes a fatal error. +Meson dictionaries use a syntax similar to python's dictionaries, but +have a narrower scope: they are immutable, keys can only be string +literals, and initializing a dictionary with duplicate keys causes a +fatal error. Example usage: @@ -154,15 +159,16 @@ endforeach ## 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 -empty list. +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 empty list. ## 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 -than the version specified inside `project()`. For example: +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 than the version specified inside `project()`. For +example: ```meson project('featurenew', meson_version: '>=0.43') @@ -193,23 +199,24 @@ WARNING: Project specifies a minimum meson_version '>=0.43' which conflicts with ## New type of build option for features -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 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. +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()` -You can now pass additional arguments to gdbus-codegen using the `extra_args` -keyword. This is the same for the other gnome function calls. +You can now pass additional arguments to gdbus-codegen using the +`extra_args` keyword. This is the same for the other gnome function +calls. -Meson now automatically adds autocleanup support to the generated code. This -can be modified by setting the autocleanup keyword. +Meson now automatically adds autocleanup support to the generated +code. This can be modified by setting the autocleanup keyword. For example: @@ -235,18 +242,20 @@ $ meson install --only-changed ## `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 -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 targets. -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. +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 -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`. +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`. The `install_umask` can be overridden in the meson command-line: @@ -261,8 +270,8 @@ project('myproject', 'c', default_options : ['install_umask=027']) ``` -To disable the `install_umask`, set it to `preserve`, in which case permissions -are copied from the files in their origin. +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 @@ -275,27 +284,29 @@ int_1365 = 0b10101010101 ## 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. +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. -`run_command()` used to always capture the output and stored it for use in -build files. However, sometimes the stdout is in a binary format which is meant -to be discarded. For that case, you can now set the `capture:` keyword argument -to `false`. +`run_command()` used to always capture the output and stored it for +use in build files. However, sometimes the stdout is in a binary +format which is meant to be discarded. For that case, you can now set +the `capture:` keyword argument to `false`. ## Windows resource files dependencies The `compile_resources()` function of the `windows` module now takes the `depend_files:` and `depends:` keywords. -When using binutils's `windres`, dependencies on files `#include`'d by the -preprocessor are now automatically tracked. +When using binutils's `windres`, dependencies on files `#include`'d by +the preprocessor are now automatically tracked. ## Polkit support for privileged installation -When running `install`, if installation fails with a permission error and -`pkexec` is available, Meson will attempt to use it to spawn a permission -dialog for privileged installation and retry the installation. +When running `install`, if installation fails with a permission error +and `pkexec` is available, Meson will attempt to use it to spawn a +permission dialog for privileged installation and retry the +installation. -If `pkexec` is not available, the old behaviour is retained and you will need -to explicitly run the install step with `sudo`. +If `pkexec` is not available, the old behaviour is retained and you +will need to explicitly run the install step with `sudo`. diff --git a/docs/markdown/Release-notes-for-0.48.0.md b/docs/markdown/Release-notes-for-0.48.0.md index eaeeefe..4b68b6d 100644 --- a/docs/markdown/Release-notes-for-0.48.0.md +++ b/docs/markdown/Release-notes-for-0.48.0.md @@ -12,8 +12,8 @@ use, such as *debug* and *minsize*. There is also a *plain* type that adds nothing by default but instead makes it the user's responsibility to add everything by hand. This works but is a bit tedious. -In this release we have added new new options to manually toggle -e.g. optimization levels and debug info so those can be changed +In this release we have added new new options to manually toggle e.g. +optimization levels and debug info so those can be changed independently of other options. For example by default the debug buildtype has no optmization enabled at all. If you wish to use GCC's `-Og` instead, you could set it with the following command: @@ -29,9 +29,11 @@ manually changed with the new base option `b_vscrt`. ## Meson warns if two calls to `configure_file()` write to the same file -If two calls to [`configure_file()`](Reference-manual.md#configure_file) -write to the same file Meson will print a `WARNING:` message during -configuration. For example: +If two calls to +[`configure_file()`](Reference-manual.md#configure_file) write to the +same file Meson will print a `WARNING:` message during configuration. +For example: + ```meson project('configure_file', 'cpp') @@ -82,18 +84,18 @@ not receive any feedback about what the program is doing. ## `dependency(version:)` now applies to all dependency types -Previously, version constraints were only enforced for dependencies found using -the pkg-config dependency provider. These constraints now apply to dependencies -found using any dependency provider. +Previously, version constraints were only enforced for dependencies +found using the pkg-config dependency provider. These constraints now +apply to dependencies found using any dependency provider. -Some combinations of dependency, host and method do not currently support -discovery of the version. In these cases, the dependency will not be found if a -version constraint is applied, otherwise the `version()` method for the -dependency object will return `'unknown'`. +Some combinations of dependency, host and method do not currently +support discovery of the version. In these cases, the dependency will +not be found if a version constraint is applied, otherwise the +`version()` method for the dependency object will return `'unknown'`. -(If discovering the version in one of these combinations is important to you, -and a method exists to determine the version in that case, please file an issue -with as much information as possible.) +(If discovering the version in one of these combinations is important +to you, and a method exists to determine the version in that case, +please file an issue with as much information as possible.) ## python3 module is deprecated @@ -139,17 +141,17 @@ meson.add_dist_script('dist_cleanup.py') ## Fatal warnings -A new command line option has been added: `--fatal-meson-warnings`. When enabled, any -warning message printed by Meson will be fatal and raise an exception. It is -intended to be used by developers and CIs to easily catch deprecation warnings, -or any other potential issues. +A new command line option has been added: `--fatal-meson-warnings`. +When enabled, any warning message printed by Meson will be fatal and +raise an exception. It is intended to be used by developers and CIs to +easily catch deprecation warnings, or any other potential issues. ## Helper methods added for checking GNU style attributes: `__attribute__(...)` -A set of new helpers have been added to the C and C++ compiler objects for -checking GNU style function attributes. These are not just simpler to use, they -may be optimized to return fast on compilers that don't support these -attributes. Currently this is true for MSVC. +A set of new helpers have been added to the C and C++ compiler objects +for checking GNU style function attributes. These are not just simpler +to use, they may be optimized to return fast on compilers that don't +support these attributes. Currently this is true for MSVC. ```meson cc = meson.get_compiler('c') @@ -176,11 +178,12 @@ endforeach ## `gnome.generate_gir()` now optionally accepts multiple libraries -The GNOME module can now generate a single gir for multiple libraries, which -is something `g-ir-scanner` supported, but had not been exposed yet. +The GNOME module can now generate a single gir for multiple libraries, +which is something `g-ir-scanner` supported, but had not been exposed +yet. -gnome.generate_gir() will now accept multiple positional arguments, if none -of these arguments are an `Executable` instance. +gnome.generate_gir() will now accept multiple positional arguments, if +none of these arguments are an `Executable` instance. ## Hotdoc module @@ -242,12 +245,13 @@ add_project_arguments(..., native : true) add_project_arguments(..., native : false) ``` -Also remember that cross compilation is a property of each -target. There can be target that are compiled with the native compiler -and some which are compiled with the cross compiler. +Also remember that cross compilation is a property of each target. +There can be target that are compiled with the native compiler and +some which are compiled with the cross compiler. Unfortunately this change is backwards incompatible and may cause some -projects to fail building. However this should be very rare in practice. +projects to fail building. However this should be very rare in +practice. ## More flexible `override_find_program()`. @@ -264,25 +268,28 @@ Now, by default `shared_library()` sets `-compatibility_version` and `-current_version` of a macOS dylib using the `soversion`. This can be overridden by using the `darwin_versions:` kwarg to -[`shared_library()`](Reference-manual.md#shared_library). As usual, you can -also pass this kwarg to `library()` or `build_target()` and it will be used in -the appropriate circumstances. +[`shared_library()`](Reference-manual.md#shared_library). As usual, +you can also pass this kwarg to `library()` or `build_target()` and it +will be used in the appropriate circumstances. ## Version comparison -`dependency(version:)` and other version constraints now handle versions -containing non-numeric characters better, comparing versions using the rpmvercmp -algorithm (as using the `pkg-config` autoconf macro `PKG_CHECK_MODULES` does). +`dependency(version:)` and other version constraints now handle +versions containing non-numeric characters better, comparing versions +using the rpmvercmp algorithm (as using the `pkg-config` autoconf +macro `PKG_CHECK_MODULES` does). -This is a breaking change for exact comparison constraints which rely on the -previous comparison behaviour of extending the compared versions with `'0'` -elements, up to the same length of `'.'`-separated elements. +This is a breaking change for exact comparison constraints which rely +on the previous comparison behaviour of extending the compared +versions with `'0'` elements, up to the same length of `'.'`-separated +elements. -For example, a version of `'0.11.0'` would previously match a version constraint -of `'==0.11'`, but no longer does, being instead considered strictly greater. +For example, a version of `'0.11.0'` would previously match a version +constraint of `'==0.11'`, but no longer does, being instead considered +strictly greater. -Instead, use a version constraint which exactly compares with the precise -version required, e.g. `'==0.11.0'`. +Instead, use a version constraint which exactly compares with the +precise version required, e.g. `'==0.11.0'`. ## Keyword argument for GNU symbol visibility @@ -308,13 +315,15 @@ clone-recursive=true ## `subproject()` function now supports the `required:` kwarg -This allows you to declare an optional subproject. You can now call `found()` -on the return value of the `subproject()` call to see if the subproject is -available before calling `get_variable()` to fetch information from it. +This allows you to declare an optional subproject. You can now call +`found()` on the return value of the `subproject()` call to see if the +subproject is available before calling `get_variable()` to fetch +information from it. ## `dependency()` objects now support the `.name()` method -You can now fetch the name of the dependency that was searched like so: +You can now fetch the name of the dependency that was searched like +so: ```meson glib_dep = dependency('glib-2.0') diff --git a/docs/markdown/Release-notes-for-0.49.0.md b/docs/markdown/Release-notes-for-0.49.0.md index 327ed75..6b84af1 100644 --- a/docs/markdown/Release-notes-for-0.49.0.md +++ b/docs/markdown/Release-notes-for-0.49.0.md @@ -7,9 +7,10 @@ short-description: Release notes for 0.49 ## Libgcrypt dependency now supports libgcrypt-config -Earlier, `dependency('libgcrypt')` could only detect the library with pkg-config -files. Now, if pkg-config files are not found, Meson will look for -`libgcrypt-config` and if it's found, will use that to find the library. +Earlier, `dependency('libgcrypt')` could only detect the library with +pkg-config files. Now, if pkg-config files are not found, Meson will +look for `libgcrypt-config` and if it's found, will use that to find +the library. ## New `section` key for the buildoptions introspection @@ -32,7 +33,7 @@ Cross-compilation is now supported for Renesas RX targets with the CC-RX compiler. The environment path should be set properly for the CC-RX compiler -executables. The `-cpu` option with the appropriate value should be +executables. The `-cpu` option with the appropriate value should be mentioned in the cross-file as shown in the snippet below. ```ini @@ -41,21 +42,20 @@ c_args = ['-cpu=rx600'] cpp_args = ['-cpu=rx600'] ``` -The default extension of the executable output is `.abs`. Other -target specific arguments to the compiler and linker will need to be -added explicitly from the +The default extension of the executable output is `.abs`. Other target +specific arguments to the compiler and linker will need to be added +explicitly from the cross-file(`c_args`/`c_link_args`/`cpp_args`/`cpp_link_args`) or some -other way. Refer to the CC-RX User's manual for additional compiler +other way. Refer to the CC-RX User's manual for additional compiler and linker options. ## CMake `find_package` dependency backend -Meson can now use the CMake `find_package` ecosystem to -detect dependencies. Both the old-style `<NAME>_LIBRARIES` -variables as well as imported targets are supported. Meson -can automatically guess the correct CMake target in most -cases but it is also possible to manually specify a target -with the `modules` property. +Meson can now use the CMake `find_package` ecosystem to detect +dependencies. Both the old-style `<NAME>_LIBRARIES` variables as well +as imported targets are supported. Meson can automatically guess the +correct CMake target in most cases but it is also possible to manually +specify a target with the `modules` property. ```meson # Implicitly uses CMake as a fallback and guesses a target @@ -70,10 +70,10 @@ no `method` (or `auto`) was provided in the dependency options. ## New compiler method `get_argument_syntax` -The compiler object now has `get_argument_syntax` method, which returns a -string value of `gcc`, `msvc`, or an undefined value string value. This can be -used to determine if a compiler uses gcc syntax (`-Wfoo`), msvc syntax -(`/w1234`), or some other kind of arguments. +The compiler object now has `get_argument_syntax` method, which +returns a string value of `gcc`, `msvc`, or an undefined value string +value. This can be used to determine if a compiler uses gcc syntax +(`-Wfoo`), msvc syntax (`/w1234`), or some other kind of arguments. ```meson cc = meson.get_compiler('c') @@ -93,22 +93,28 @@ endif ## Return `Disabler()` instead of not-found object -Functions such as `dependency()`, `find_library()`, `find_program()`, and -`python.find_installation()` have a new keyword argument: `disabler`. When set -to `true` those functions return `Disabler()` objects instead of not-found -objects. +Functions such as `dependency()`, `find_library()`, `find_program()`, +and `python.find_installation()` have a new keyword argument: +`disabler`. When set to `true` those functions return `Disabler()` +objects instead of not-found objects. ## `introspect --projectinfo` can now be used without configured build directory -This allows IDE integration to get information about the project before the user has configured a build directory. +This allows IDE integration to get information about the project +before the user has configured a build directory. -Before you could use `meson.py introspect --projectinfo build-directory`. -Now you also can use `meson.py introspect --projectinfo project-dir/meson.build`. +Before you could use `meson.py introspect --projectinfo +build-directory`. Now you also can use `meson.py introspect +--projectinfo project-dir/meson.build`. -The output is similar to the output with a build directory but additionally also includes information from `introspect --buildsystem-files`. +The output is similar to the output with a build directory but +additionally also includes information from `introspect +--buildsystem-files`. + +For example `meson.py introspect --projectinfo test\ cases/common/47\ +subproject\ options/meson.build` This outputs (pretty printed for +readability): -For example `meson.py introspect --projectinfo test\ cases/common/47\ subproject\ options/meson.build` -This outputs (pretty printed for readability): ``` { "buildsystem_files": [ @@ -166,28 +172,28 @@ is a hard error. ## Manpages are no longer compressed implicitly -Earlier, the `install_man` command has automatically compressed installed -manpages into `.gz` format. This collided with manpage compression hooks -already used by various distributions. Now, manpages are installed uncompressed -and distributors are expected to handle compressing them according to their own -compression preferences. +Earlier, the `install_man` command has automatically compressed +installed manpages into `.gz` format. This collided with manpage +compression hooks already used by various distributions. Now, manpages +are installed uncompressed and distributors are expected to handle +compressing them according to their own compression preferences. ## Native config files -Native files (`--native-file`) are the counterpart to cross files (`--cross-file`), -and allow specifying information about the build machine, both when cross compiling -and when not. +Native files (`--native-file`) are the counterpart to cross files +(`--cross-file`), and allow specifying information about the build +machine, both when cross compiling and when not. -Currently the native files only allow specifying the names of binaries, similar -to the cross file, for example: +Currently the native files only allow specifying the names of +binaries, similar to the cross file, for example: ```ini [binaries] llvm-config = "/opt/llvm-custom/bin/llvm-config" ``` -Will override the llvm-config used for *native* binaries. Targets for the host -machine will continue to use the cross file. +Will override the llvm-config used for *native* binaries. Targets for +the host machine will continue to use the cross file. ## Foreach `break` and `continue` @@ -241,8 +247,8 @@ path elements: joined = 'foo' / 'bar' ``` -Before Meson 0.49, joining path elements was done with the legacy `join_paths` -function, but the `/` syntax above is now recommended. +Before Meson 0.49, joining path elements was done with the legacy +`join_paths` function, but the `/` syntax above is now recommended. ```meson joined = join_paths('foo', 'bar') @@ -252,29 +258,34 @@ This only works for strings. ## Position-independent executables -When `b_pie` option, or `executable()`'s `pie` keyword argument is set to -`true`, position-independent executables are built. All their objects are built -with `-fPIE` and the executable is linked with `-pie`. Any static library they -link must be built with `pic` set to `true` (see `b_staticpic` option). +When `b_pie` option, or `executable()`'s `pie` keyword argument is set +to `true`, position-independent executables are built. All their +objects are built with `-fPIE` and the executable is linked with +`-pie`. Any static library they link must be built with `pic` set to +`true` (see `b_staticpic` option). ## Deprecation warning in pkg-config generator -All libraries passed to the `libraries` keyword argument of the `generate()` -method used to be associated with that generated pkg-config file. That means -that any subsequent call to `generate()` where those libraries appear would add -the filebase of the `generate()` that first contained them into `Requires:` or -`Requires.private:` field instead of adding an `-l` to `Libs:` or `Libs.private:`. - -This behaviour is now deprecated. The library that should be associated with -the generated pkg-config file should be passed as first positional argument -instead of in the `libraries` keyword argument. The previous behaviour is -maintained but prints a deprecation warning and support for this will be removed -in a future Meson release. If you can not create the needed pkg-config file -without this warning, please file an issue with as much details as possible -about the situation. - -For example this sample will write `Requires: liba` into `libb.pc` but print a -deprecation warning: +All libraries passed to the `libraries` keyword argument of the +`generate()` method used to be associated with that generated +pkg-config file. That means that any subsequent call to `generate()` +where those libraries appear would add the filebase of the +`generate()` that first contained them into `Requires:` or +`Requires.private:` field instead of adding an `-l` to `Libs:` or +`Libs.private:`. + +This behaviour is now deprecated. The library that should be +associated with the generated pkg-config file should be passed as +first positional argument instead of in the `libraries` keyword +argument. The previous behaviour is maintained but prints a +deprecation warning and support for this will be removed in a future +Meson release. If you can not create the needed pkg-config file +without this warning, please file an issue with as much details as +possible about the situation. + +For example this sample will write `Requires: liba` into `libb.pc` but +print a deprecation warning: + ```meson liba = library(...) pkg.generate(libraries : liba) diff --git a/docs/markdown/Release-notes-for-0.50.0.md b/docs/markdown/Release-notes-for-0.50.0.md index a9363d8..480a612 100644 --- a/docs/markdown/Release-notes-for-0.50.0.md +++ b/docs/markdown/Release-notes-for-0.50.0.md @@ -7,19 +7,20 @@ short-description: Release notes for 0.50.0 ## Added `cmake_module_path` and `cmake_args` to dependency -The CMake dependency backend can now make use of existing `Find<name>.cmake` -files by setting the `CMAKE_MODULE_PATH` with the new `dependency()` property -`cmake_module_path`. The paths given to `cmake_module_path` should be relative -to the project source directory. +The CMake dependency backend can now make use of existing +`Find<name>.cmake` files by setting the `CMAKE_MODULE_PATH` with the +new `dependency()` property `cmake_module_path`. The paths given to +`cmake_module_path` should be relative to the project source +directory. -Furthermore the property `cmake_args` was added to give CMake additional -parameters. +Furthermore the property `cmake_args` was added to give CMake +additional parameters. ## Added PGI compiler support Nvidia / PGI C, C++ and Fortran [no-cost](https://www.pgroup.com/products/community.htm) compilers are -now supported. They have been tested on Linux so far. +now supported. They have been tested on Linux so far. @@ -65,8 +66,10 @@ not. ## Fix ninja console log from generators with multiple output nodes -This resolves [issue #4760](https://github.com/mesonbuild/meson/issues/4760) -where a generator with multiple output nodes printed an empty string to the console +This resolves [issue +#4760](https://github.com/mesonbuild/meson/issues/4760) where a +generator with multiple output nodes printed an empty string to the +console ## `introspect --buildoptions` can now be used without configured build directory @@ -100,11 +103,11 @@ executable(..., include_directories: foo_inc) ## Fortran submodule support -Initial support for Fortran `submodule` was added, where the submodule is in -the same or different file than the parent `module`. -The submodule hierarchy specified in the source Fortran code `submodule` -statements are used by Meson to resolve source file dependencies. -For example: +Initial support for Fortran `submodule` was added, where the submodule +is in the same or different file than the parent `module`. The +submodule hierarchy specified in the source Fortran code `submodule` +statements are used by Meson to resolve source file dependencies. For +example: ```fortran submodule (ancestor:parent) child @@ -113,13 +116,14 @@ submodule (ancestor:parent) child ## Add `subproject_dir` to `--projectinfo` introspection output -This allows applications interfacing with Meson (such as IDEs) to know about -an overridden subproject directory. +This allows applications interfacing with Meson (such as IDEs) to know +about an overridden subproject directory. ## Find library with its headers -The `find_library()` method can now also verify if the library's headers are -found in a single call, using the `has_header()` method internally. +The `find_library()` method can now also verify if the library's +headers are found in a single call, using the `has_header()` method +internally. ```meson # Aborts if the 'z' library is found but not its header file @@ -128,8 +132,9 @@ zlib = find_library('z', has_headers : 'zlib.h') zlib = find_library('z', has_headers : 'zlib.h', required : false) ``` -Any keyword argument with the `header_` prefix passed to `find_library()` will -be passed to the `has_header()` method with the prefix removed. +Any keyword argument with the `header_` prefix passed to +`find_library()` will be passed to the `has_header()` method with the +prefix removed. ```meson libfoo = find_library('foo', @@ -214,9 +219,9 @@ what to extract. Previously, file paths could only be passed as strings. ## Changed the JSON format of the introspection -All paths used in the meson introspection JSON format are now absolute. This -affects the `filename` key in the targets introspection and the output of -`--buildsystem-files`. +All paths used in the meson introspection JSON format are now +absolute. This affects the `filename` key in the targets introspection +and the output of `--buildsystem-files`. Furthermore, the `filename` and `install_filename` keys in the targets introspection are now lists of strings with identical length. @@ -262,21 +267,22 @@ The output format is as follows: ] ``` -The `required` keyword specifies whether the dependency is marked as required -in the `meson.build` (all dependencies are required by default). The -`conditional` key indicates whether the `dependency()` function was called -inside a conditional block. In a real meson run these dependencies might not be -used, thus they _may_ not be required, even if the `required` key is set. The -`has_fallback` key just indicates whether a fallback was directly set in the -`dependency()` function. +The `required` keyword specifies whether the dependency is marked as +required in the `meson.build` (all dependencies are required by +default). The `conditional` key indicates whether the `dependency()` +function was called inside a conditional block. In a real meson run +these dependencies might not be used, thus they _may_ not be required, +even if the `required` key is set. The `has_fallback` key just +indicates whether a fallback was directly set in the `dependency()` +function. ## `introspect --targets` can now be used without configured build directory -It is now possible to run `meson introspect --targets /path/to/meson.build` -without a configured build directory. +It is now possible to run `meson introspect --targets +/path/to/meson.build` without a configured build directory. -The generated output is similar to running the introspection with a build -directory. However, there are some key differences: +The generated output is similar to running the introspection with a +build directory. However, there are some key differences: - The paths in `filename` now are _relative_ to the future build directory - The `install_filename` key is completely missing @@ -285,26 +291,27 @@ directory. However, there are some key differences: - Empty lists for `compiler` and `parameters` and `generated_sources` - The `sources` list _should_ contain all sources of the target -There is no guarantee that the sources list in `target_sources` is correct. -There might be differences, due to internal limitations. It is also not -guaranteed that all targets will be listed in the output. It might even be -possible that targets are listed, which won't exist when meson is run normally. -This can happen if a target is defined inside an if statement. -Use this feature with care. +There is no guarantee that the sources list in `target_sources` is +correct. There might be differences, due to internal limitations. It +is also not guaranteed that all targets will be listed in the output. +It might even be possible that targets are listed, which won't exist +when meson is run normally. This can happen if a target is defined +inside an if statement. Use this feature with care. ## Added option to introspect multiple parameters at once Meson introspect can now print the results of multiple introspection -commands in a single call. The results are then printed as a single JSON -object. +commands in a single call. The results are then printed as a single +JSON object. The format for a single command was not changed to keep backward compatibility. -Furthermore the option `-a,--all`, `-i,--indent` and `-f,--force-object-output` -were added to print all introspection information in one go, format the -JSON output (the default is still compact JSON) and force use the new -output format, even if only one introspection command was given. +Furthermore the option `-a,--all`, `-i,--indent` and +`-f,--force-object-output` were added to print all introspection +information in one go, format the JSON output (the default is still +compact JSON) and force use the new output format, even if only one +introspection command was given. A complete introspection dump is also stored in the `meson-info` directory. This dump will be (re)generated each time meson updates the @@ -319,10 +326,10 @@ Additionlly the format of `meson introspect target` was changed: ## `meson configure` can now print the default options of an unconfigured project -With this release, it is also possible to get a list of all build options -by invoking `meson configure` with the project source directory or -the path to the root `meson.build`. In this case, meson will print the -default values of all options. +With this release, it is also possible to get a list of all build +options by invoking `meson configure` with the project source +directory or the path to the root `meson.build`. In this case, meson +will print the default values of all options. ## HDF5 @@ -330,13 +337,14 @@ HDF5 support is added via pkg-config. ## Added the `meson-info.json` introspection file -Meson now generates a `meson-info.json` file in the `meson-info` directory -to provide introspection information about the latest meson run. This file -is updated when the build configuration is changed and the build files are -(re)generated. +Meson now generates a `meson-info.json` file in the `meson-info` +directory to provide introspection information about the latest meson +run. This file is updated when the build configuration is changed and +the build files are (re)generated. ## New kwarg `install:` for `configure_file()` -Previously when using `configure_file()`, you could install the outputted file -by setting the `install_dir:` keyword argument. Now, there is an explicit kwarg -`install:` to enable/disable it. Omitting it will maintain the old behaviour. +Previously when using `configure_file()`, you could install the +outputted file by setting the `install_dir:` keyword argument. Now, +there is an explicit kwarg `install:` to enable/disable it. Omitting +it will maintain the old behaviour. diff --git a/docs/markdown/Release-notes-for-0.51.0.md b/docs/markdown/Release-notes-for-0.51.0.md index 8a73cbc..3b57ca0 100644 --- a/docs/markdown/Release-notes-for-0.51.0.md +++ b/docs/markdown/Release-notes-for-0.51.0.md @@ -8,38 +8,41 @@ short-description: Release notes for 0.51.0 ## (C) Preprocessor flag handling Meson previously stored `CPPFLAGS` and per-language compilation flags -separately. (That latter would come from `CFLAGS`, `CXXFLAGS`, etc., along with -`<lang>_args` options whether specified no the command-line interface (`-D..`), -`meson.build` (`default_options`), or cross file (`[properties]`).) This was -mostly unobservable, except for certain preprocessor-only checks like -`check_header` would only use the preprocessor flags, leading to confusion if -some `-isystem` was in `CFLAGS` but not `CPPFLAGS`. Now, they are lumped -together, and `CPPFLAGS`, for the languages which are deemed to care to about, -is just another source of compilation flags along with the others already +separately. (That latter would come from `CFLAGS`, `CXXFLAGS`, etc., +along with `<lang>_args` options whether specified no the command-line +interface (`-D..`), `meson.build` (`default_options`), or cross file +(`[properties]`).) This was mostly unobservable, except for certain +preprocessor-only checks like `check_header` would only use the +preprocessor flags, leading to confusion if some `-isystem` was in +`CFLAGS` but not `CPPFLAGS`. Now, they are lumped together, and +`CPPFLAGS`, for the languages which are deemed to care to about, is +just another source of compilation flags along with the others already listed. ## Sanity checking compilers with user flags -Sanity checks previously only used user-specified flags for cross compilers, but -now do in all cases. +Sanity checks previously only used user-specified flags for cross +compilers, but now do in all cases. -All compilers meson might decide to use for the build are "sanity checked" -before other tests are run. This usually involves building simple executable and -trying to run it. Previously user flags (compilation and/or linking flags) were -used for sanity checking cross compilers, but not native compilers. This is -because such flags might be essential for a cross binary to succeed, but usually -aren't for a native compiler. +All compilers meson might decide to use for the build are "sanity +checked" before other tests are run. This usually involves building +simple executable and trying to run it. Previously user flags +(compilation and/or linking flags) were used for sanity checking cross +compilers, but not native compilers. This is because such flags might +be essential for a cross binary to succeed, but usually aren't for a +native compiler. -In recent releases, there has been an effort to minimize the special-casing of -cross or native builds so as to make building more predictable in less-tested -cases. Since this the user flags are necessary for cross, but not harmful for -native, it makes more sense to use them in all sanity checks than use them in no -sanity checks, so this is what we now do. +In recent releases, there has been an effort to minimize the +special-casing of cross or native builds so as to make building more +predictable in less-tested cases. Since this the user flags are +necessary for cross, but not harmful for native, it makes more sense +to use them in all sanity checks than use them in no sanity checks, so +this is what we now do. ## New `sourceset` module A new module, `sourceset`, was added to help building many binaries -from the same source files. Source sets associate source files and +from the same source files. Source sets associate source files and dependencies to keys in a `configuration_data` object or a dictionary; they then take multiple `configuration_data` objects or dictionaries, and compute the set of source files and dependencies for each of those @@ -69,9 +72,10 @@ shared_module(...) ## New modules kwarg for python.find_installation -This mirrors the modules argument that some kinds of dependencies (such as -qt, llvm, and cmake based dependencies) take, allowing you to check that a -particular module is available when getting a python version. +This mirrors the modules argument that some kinds of dependencies +(such as qt, llvm, and cmake based dependencies) take, allowing you to +check that a particular module is available when getting a python +version. ```meson py = import('python').find_installation('python3', modules : ['numpy']) @@ -79,10 +83,10 @@ py = import('python').find_installation('python3', modules : ['numpy']) ## Support for the Intel Compiler on Windows (ICL) -Support has been added for ICL.EXE and ifort on windows. The support should be -on part with ICC support on Linux/MacOS. The ICL C/C++ compiler behaves like -Microsoft's CL.EXE rather than GCC/Clang like ICC does, and has a different id, -`intel-cl` to differentiate it. +Support has been added for ICL.EXE and ifort on windows. The support +should be on part with ICC support on Linux/MacOS. The ICL C/C++ +compiler behaves like Microsoft's CL.EXE rather than GCC/Clang like +ICC does, and has a different id, `intel-cl` to differentiate it. ```meson cc = meson.get_compiler('c') @@ -93,8 +97,8 @@ endif ## Added basic support for the Xtensa CPU toolchain -You can now use `xt-xcc`, `xt-xc++`, `xt-nm`, etc... on your cross compilation -file and meson won't complain about an unknown toolchain. +You can now use `xt-xcc`, `xt-xc++`, `xt-nm`, etc... on your cross +compilation file and meson won't complain about an unknown toolchain. ## Dependency objects now have a get_variable method @@ -118,11 +122,13 @@ endif ## CMake prefix path overrides When using pkg-config as a dependency resolver we can pass -`-Dpkg_config_path=$somepath` to extend or overwrite where pkg-config will -search for dependencies. Now cmake can do the same, as long as the dependency -uses a ${Name}Config.cmake file (not a Find{$Name}.cmake file), by passing -`-Dcmake_prefix_path=list,of,paths`. It is important that point this at the -prefix that the dependency is installed into, not the cmake path. +`-Dpkg_config_path=$somepath` to extend or overwrite where pkg-config +will search for dependencies. Now cmake can do the same, as long as +the dependency uses a ${Name}Config.cmake file (not a +Find{$Name}.cmake file), by passing +`-Dcmake_prefix_path=list,of,paths`. It is important that point this +at the prefix that the dependency is installed into, not the cmake +path. If you have installed something to `/tmp/dep`, which has a layout like: ``` @@ -162,7 +168,7 @@ executable(..., link_language : 'fortran') ``` A specific case this option fixes is where for example the main -program is Fortran that calls C and/or C++ code. The automatic +program is Fortran that calls C and/or C++ code. The automatic language detection of Meson prioritizes C/C++, and so an compile-time error results like `undefined reference to main`, because the linker is C or C++ instead of Fortran, which is fixed by this per-target @@ -176,11 +182,12 @@ kconfig output files from `meson.build`. ## Add new `meson subprojects foreach` command -`meson subprojects` has learned a new `foreach` command which accepts a command -with arguments and executes it in each subproject directory. +`meson subprojects` has learned a new `foreach` command which accepts +a command with arguments and executes it in each subproject directory. -For example this can be useful to check the status of subprojects (e.g. with -`git status` or `git diff`) before performing other actions on them. +For example this can be useful to check the status of subprojects +(e.g. with `git status` or `git diff`) before performing other actions +on them. ## Added c17 and c18 as c_std values for recent GCC and Clang Versions @@ -243,18 +250,19 @@ cg = generator(program_runner, ## Specifying options per mer machine Previously, no cross builds were controllable from the command line. -Machine-specific options like the pkg-config path and compiler options only -affected native targets, that is to say all targets in native builds, and -`native: true` targets in cross builds. Now, prefix the option with `build.` to -affect build machine targets, and leave it unprefixed to affect host machine -targets. +Machine-specific options like the pkg-config path and compiler options +only affected native targets, that is to say all targets in native +builds, and `native: true` targets in cross builds. Now, prefix the +option with `build.` to affect build machine targets, and leave it +unprefixed to affect host machine targets. -For those trying to ensure native and cross builds to the same platform produced -the same result, the old way was frustrating because very different invocations -were needed to affect the same targets, if it was possible at all. Now, the same -command line arguments affect the same targets everywhere --- Meson is closer to -ignoring whether the "overall" build is native or cross, and just caring about -whether individual targets are for the build or host machines. +For those trying to ensure native and cross builds to the same +platform produced the same result, the old way was frustrating because +very different invocations were needed to affect the same targets, if +it was possible at all. Now, the same command line arguments affect +the same targets everywhere --- Meson is closer to ignoring whether +the "overall" build is native or cross, and just caring about whether +individual targets are for the build or host machines. ## subproject.get_variable() now accepts a `fallback` argument @@ -269,26 +277,27 @@ var = subproject.get_variable('does-not-exist', 'fallback-value') ## Add keyword `static` to `find_library` -`find_library` has learned the `static` keyword. They keyword must be a boolean, -where `true` only searches for static libraries and `false` only searches for -dynamic/shared. Leaving the keyword unset will keep the old behavior of first -searching for dynamic and then falling back to static. +`find_library` has learned the `static` keyword. They keyword must be +a boolean, where `true` only searches for static libraries and `false` +only searches for dynamic/shared. Leaving the keyword unset will keep +the old behavior of first searching for dynamic and then falling back +to static. ## Fortran `include` statements recursively parsed While non-standard and generally not recommended, some legacy Fortran -programs use `include` directives to inject code inline. Since v0.51, +programs use `include` directives to inject code inline. Since v0.51, Meson can handle Fortran `include` directives recursively. DO NOT list `include` files as sources for a target, as in general -their syntax is not correct as a standalone target. In general +their syntax is not correct as a standalone target. In general `include` files are meant to be injected inline as if they were copy and pasted into the source file. `include` was never standard and was superceded by Fortran 90 `module`. The `include` file is only recognized by Meson if it has a Fortran -file suffix, such as `.f` `.F` `.f90` `.F90` or similar. This is to +file suffix, such as `.f` `.F` `.f90` `.F90` or similar. This is to avoid deeply nested scanning of large external legacy C libraries that only interface to Fortran by `include biglib.h` or similar. @@ -326,4 +335,3 @@ subprojects in question. ## Multiple cross files can be specified `--cross-file` can be passed multiple times, with the configuration files overlaying the same way as `--native-file`. - diff --git a/docs/markdown/Release-notes-for-0.52.0.md b/docs/markdown/Release-notes-for-0.52.0.md index b972f81..79f1cef 100644 --- a/docs/markdown/Release-notes-for-0.52.0.md +++ b/docs/markdown/Release-notes-for-0.52.0.md @@ -28,18 +28,19 @@ now give a dictionary. runtarget alias_target(target_name, dep1, ...) ``` -This function creates a new top-level target. Like all top-level targets, this -integrates with the selected backend. For instance, with Ninja you can -run it as `ninja target_name`. This is a dummy target that does not execute any -command, but ensures that all dependencies are built. Dependencies can be any -build target (e.g. return value of executable(), custom_target(), etc) +This function creates a new top-level target. Like all top-level +targets, this integrates with the selected backend. For instance, with +Ninja you can run it as `ninja target_name`. This is a dummy target +that does not execute any command, but ensures that all dependencies +are built. Dependencies can be any build target (e.g. return value of +executable(), custom_target(), etc) ## Enhancements to the pkg_config_path argument -Setting sys_root in the [properties] section of your cross file will now set -PKG_CONFIG_SYSROOT_DIR automatically for host system dependencies when -cross compiling. +Setting sys_root in the [properties] section of your cross file will +now set PKG_CONFIG_SYSROOT_DIR automatically for host system +dependencies when cross compiling. ## The meson test program now accepts an additional "--gdb-path" argument to specify the GDB binary @@ -53,13 +54,14 @@ $ meson test --gdb --gdb-path cgdb testname ## Better support for illumos and Solaris -illumos (and hopefully Solaris) support has been dramatically improved, and one -can reasonably expect projects to compile. +illumos (and hopefully Solaris) support has been dramatically +improved, and one can reasonably expect projects to compile. ## Splitting of Compiler.get_function_attribute('visibility') -On macOS there is no `protected` visibility, which results in the visbility -check always failing. 0.52.0 introduces two changes to improve this situation: +On macOS there is no `protected` visibility, which results in the +visbility check always failing. 0.52.0 introduces two changes to +improve this situation: 1. the "visibility" check no longer includes "protected" 2. a new set of "split" checks are introduced which check for a single @@ -86,9 +88,9 @@ Add `dependency('blocks')` to use the Clang blocks extension. ## Meson's builtin b_lundef is now supported on macOS -This has always been possible, but there are some additional restrictions on -macOS (mainly do to Apple only features). With the linker internal -re-architecture this has become possible +This has always been possible, but there are some additional +restrictions on macOS (mainly do to Apple only features). With the +linker internal re-architecture this has become possible ## Compiler and dynamic linker representation split @@ -119,7 +121,8 @@ python run_project_tests.py --only fortran python run_project_tests.py --only fortran python3 ``` -This assists Meson development by only running the tests for the portion of Meson being worked on during local development. +This assists Meson development by only running the tests for the +portion of Meson being worked on during local development. ## Experimental Webassembly support via Emscripten @@ -129,13 +132,14 @@ subject to change. ## Version check in `find_program()` -A new `version` keyword argument has been added to `find_program` to specify -the required version. See [`dependency()`](#dependency) for argument format. -The version of the program is determined by running `program_name --version` -command. If stdout is empty it fallbacks to stderr. If the output contains more -text than simply a version number, only the first occurrence of numbers separated -by dots is kept. If the output is more complicated than that, the version -checking will have to be done manually using [`run_command()`](#run_command). +A new `version` keyword argument has been added to `find_program` to +specify the required version. See [`dependency()`](#dependency) for +argument format. The version of the program is determined by running +`program_name --version` command. If stdout is empty it fallbacks to +stderr. If the output contains more text than simply a version number, +only the first occurrence of numbers separated by dots is kept. If the +output is more complicated than that, the version checking will have +to be done manually using [`run_command()`](#run_command). ## Added `vs_module_defs` to `shared_module()` @@ -144,9 +148,9 @@ Like `shared_library()`, `shared_module()` now accepts ## Improved support for static libraries -Static libraries had numerous shortcomings in the past, especially when using -uninstalled static libraries. This release brings many internal changes in the -way they are handled, including: +Static libraries had numerous shortcomings in the past, especially +when using uninstalled static libraries. This release brings many +internal changes in the way they are handled, including: - `link_whole:` of static libraries. In the example below, lib2 used to miss symbols from lib1 and was unusable. @@ -172,10 +176,10 @@ lib2 = both_libraries(sources, link_with : lib1, install : true) pkg.generate(lib2) ``` -Many projects have been using `extract_all_objects()` to work around those issues, -and hopefully those hacks could now be removed. Since this is a pretty large -change, please double check if your static libraries behave correctly, and -report any regression. +Many projects have been using `extract_all_objects()` to work around +those issues, and hopefully those hacks could now be removed. Since +this is a pretty large change, please double check if your static +libraries behave correctly, and report any regression. ## Enhancements to the kconfig module @@ -189,9 +193,9 @@ all include directories of the dependency are marked as system dependencies. The default value of `include_type` is `'preserve'`. -Additionally, it is also possible to check and change the `include_type` -state of an existing dependency object with the new `include_type()` and -`as_system()` methods. +Additionally, it is also possible to check and change the +`include_type` state of an existing dependency object with the new +`include_type()` and `as_system()` methods. ## Enhancements to `configure_file()` @@ -212,10 +216,10 @@ Simplify `native` flag behavior in `add_global_arguments`, - No native flag is the same as `native: false` -This further simplifies behavior to match the "build vs host" decision done in -last release with `c_args` vs `build_c_args`. The underlying motivation in both -cases is to execute the same commands whether the overall build is native or -cross. +This further simplifies behavior to match the "build vs host" decision +done in last release with `c_args` vs `build_c_args`. The underlying +motivation in both cases is to execute the same commands whether the +overall build is native or cross. ## Allow checking if a variable is a disabler @@ -225,15 +229,16 @@ and false otherwise. ## gtkdoc-check support -`gnome.gtkdoc()` now has a `check` keyword argument. If `true` runs it will run -`gtkdoc-check` when running unit tests. Note that this has the downside of -rebuilding the doc for each build, which is often very slow. It usually should -be enabled only in CI. +`gnome.gtkdoc()` now has a `check` keyword argument. If `true` runs it +will run `gtkdoc-check` when running unit tests. Note that this has +the downside of rebuilding the doc for each build, which is often very +slow. It usually should be enabled only in CI. ## `gnome.gtkdoc()` returns target object -`gnome.gtkdoc()` now returns a target object that can be passed as dependency to -other targets using generated doc files (e.g. in `content_files` of another doc). +`gnome.gtkdoc()` now returns a target object that can be passed as +dependency to other targets using generated doc files (e.g. in +`content_files` of another doc). ## Dist is now a top level command @@ -245,4 +250,3 @@ determine which kinds of archives to create: ```meson meson dist --formats=xztar,zip ``` - diff --git a/docs/markdown/Release-notes-for-0.53.0.md b/docs/markdown/Release-notes-for-0.53.0.md index b29759f..ec2924f 100644 --- a/docs/markdown/Release-notes-for-0.53.0.md +++ b/docs/markdown/Release-notes-for-0.53.0.md @@ -18,10 +18,11 @@ assert(fs.exists('important_file'), ## meson dist --include-subprojects -`meson dist` command line now gained `--include-subprojects` command line option. -When enabled, the source tree of all subprojects used by the current build will -also be included in the final tarball. This is useful to distribute self contained -tarball that can be built offline (i.e. `--wrap-mode=nodownload`). +`meson dist` command line now gained `--include-subprojects` command +line option. When enabled, the source tree of all subprojects used by +the current build will also be included in the final tarball. This is +useful to distribute self contained tarball that can be built offline +(i.e. `--wrap-mode=nodownload`). ## Added new Meson templates for `Dlang`, `Rust`, `Objective-C` @@ -31,8 +32,9 @@ Meson now ships with predefined project templates for `Dlang`, ## Add a new summary() function -A new function [`summary()`](Reference-manual.md#summary) has been added to -summarize build configuration at the end of the build process. +A new function [`summary()`](Reference-manual.md#summary) has been +added to summarize build configuration at the end of the build +process. Example: ```meson @@ -69,16 +71,19 @@ My Project 1.0 ## Generic Overrider for Dynamic Linker selection -Previous to meson 0.52.0 you set the dynamic linker using compiler specific -flags passed via language flags and hoped things worked out. In meson 0.52.0 -meson started detecting the linker and making intelligent decisions about -using it. Unfortunately this broke choosing a non-default linker. +Previous to meson 0.52.0 you set the dynamic linker using compiler +specific flags passed via language flags and hoped things worked out. +In meson 0.52.0 meson started detecting the linker and making +intelligent decisions about using it. Unfortunately this broke +choosing a non-default linker. -Now there is a generic mechanism for doing this. In 0.53.0, you can use the `LD` -environment variable. **In 0.53.1** this was changed to `<compiler_variable>_LD`, -such as `CC_LD`, `CXX_LD`, `D_LD`, etc due to regressions. The usual meson -[environment variable rules](https://mesonbuild.com/Running-Meson.html#environment-variables) -apply. Alternatively, you can add the following to a cross or native file: +Now there is a generic mechanism for doing this. In 0.53.0, you can +use the `LD` environment variable. **In 0.53.1** this was changed to +`<compiler_variable>_LD`, such as `CC_LD`, `CXX_LD`, `D_LD`, etc due +to regressions. The usual meson [environment variable +rules](https://mesonbuild.com/Running-Meson.html#environment-variables) +apply. Alternatively, you can add the following to a cross or native +file: In 0.53.0: @@ -105,10 +110,11 @@ And meson will select the linker if possible. ## `fortran_std` option -**new in 0.53.0** -Akin to the `c_std` and `cpp_std` options, the `fortran_std` option sets Fortran compilers to warn or error on non-Fortran standard code. -Only the Gfortran and Intel Fortran compilers have support for this option. -Other Fortran compilers ignore the `fortran_std` option. +**new in 0.53.0** Akin to the `c_std` and `cpp_std` options, the +`fortran_std` option sets Fortran compilers to warn or error on +non-Fortran standard code. Only the Gfortran and Intel Fortran +compilers have support for this option. Other Fortran compilers ignore +the `fortran_std` option. Supported values for `fortran_std` include: @@ -120,8 +126,9 @@ Supported values for `fortran_std` include: ## python.dependency() embed kwarg -Added the `embed` kwarg to the python module dependency function to select -the python library that can be used to embed python into an application. +Added the `embed` kwarg to the python module dependency function to +select the python library that can be used to embed python into an +application. ## Scalapack @@ -131,8 +138,9 @@ added in **0.53.0**: scalapack = dependency('scalapack') ``` -Historically and through today, typical Scalapack setups have broken and incomplete pkg-config or -FindScalapack.cmake. Meson handles finding Scalapack on setups including: +Historically and through today, typical Scalapack setups have broken +and incomplete pkg-config or FindScalapack.cmake. Meson handles +finding Scalapack on setups including: * Linux: Intel MKL or OpenMPI + Netlib * MacOS: Intel MKL or OpenMPI + Netlib @@ -165,8 +173,8 @@ d += {k : 43} ## Improved CMake subprojects support -With this release even more CMake projects are supported via -[CMake subprojects](CMake-module.md#cmake-subprojects) due to these internal +With this release even more CMake projects are supported via [CMake +subprojects](CMake-module.md#cmake-subprojects) due to these internal improvements: - Use the CMake file API for CMake >=3.14 @@ -177,14 +185,15 @@ improvements: ## compiler.get_linker_id() -since 0.53.0, `compiler.get_linker_id()` allows retrieving a lowercase name for the linker. -Since each compiler family can typically use a variety of linkers depending on operating system, -this helps users define logic for corner cases not otherwise easily handled. +since 0.53.0, `compiler.get_linker_id()` allows retrieving a lowercase +name for the linker. Since each compiler family can typically use a +variety of linkers depending on operating system, this helps users +define logic for corner cases not otherwise easily handled. ## CUDA dependency -Native support for compiling and linking against the CUDA Toolkit using -the `dependency` function: +Native support for compiling and linking against the CUDA Toolkit +using the `dependency` function: ```meson project('CUDA test', 'cpp', meson_version: '>= 0.53.0') @@ -208,4 +217,3 @@ scanning dependencies (--scan-dependencies): tests and benchmarks (--tests, --benchmarks, intro-tests.json, intro-benchmarks.json): - added the `protocol` key - diff --git a/docs/markdown/Release-notes-for-0.54.0.md b/docs/markdown/Release-notes-for-0.54.0.md index 0807d2e..103d103 100644 --- a/docs/markdown/Release-notes-for-0.54.0.md +++ b/docs/markdown/Release-notes-for-0.54.0.md @@ -7,14 +7,16 @@ short-description: Release notes for 0.54.0 ## Emscripten (emcc) now supports threads -In addition to properly setting the compile and linker arguments, a new meson -builtin has been added to control the PTHREAD_POOL_SIZE option, -`-D<lang>_thread_count`, which may be set to any integer value greater than 0. -If it set to 0 then the PTHREAD_POOL_SIZE option will not be passed. +In addition to properly setting the compile and linker arguments, a +new meson builtin has been added to control the PTHREAD_POOL_SIZE +option, `-D<lang>_thread_count`, which may be set to any integer value +greater than 0. If it set to 0 then the PTHREAD_POOL_SIZE option will +not be passed. ## Introduce dataonly for the pkgconfig module -This allows users to disable writing out the inbuilt variables to -the pkg-config file as they might actually not be required. + +This allows users to disable writing out the inbuilt variables to the +pkg-config file as they might actually not be required. One reason to have this is for architecture-independent pkg-config files in projects which also have architecture-dependent outputs. @@ -30,24 +32,27 @@ pkgg.generate( ## Consistently report file locations relative to cwd -The paths for filenames in error and warning locations are now consistently -reported relative to the current working directory (when possible), or as -absolute paths (when a relative path does not exist, e.g. a Windows path -starting with a different drive letter to the current working directory). +The paths for filenames in error and warning locations are now +consistently reported relative to the current working directory (when +possible), or as absolute paths (when a relative path does not exist, +e.g. a Windows path starting with a different drive letter to the +current working directory). -(The previous behaviour was to report a path relative to the source root for all -warnings and most errors, and relative to cwd for certain parser errors) +(The previous behaviour was to report a path relative to the source +root for all warnings and most errors, and relative to cwd for certain +parser errors) ## `dependency()` consistency -The first time a dependency is found, using `dependency('foo', ...)`, the return -value is now cached. Any subsequent call will return the same value as long as -version requested match, otherwise not-found dependency is returned. This means -that if a system dependency is first found, it won't fallback to a subproject -in a subsequent call any more and will rather return not-found instead if the -system version does not match. Similarly, if the first call returns the subproject -fallback dependency, it will also return the subproject dependency in a subsequent -call even if no fallback is provided. +The first time a dependency is found, using `dependency('foo', ...)`, +the return value is now cached. Any subsequent call will return the +same value as long as version requested match, otherwise not-found +dependency is returned. This means that if a system dependency is +first found, it won't fallback to a subproject in a subsequent call +any more and will rather return not-found instead if the system +version does not match. Similarly, if the first call returns the +subproject fallback dependency, it will also return the subproject +dependency in a subsequent call even if no fallback is provided. For example, if the system has `foo` version 1.0: ```meson @@ -66,8 +71,8 @@ d2 = dependency('foo', version : '>=2.0', required : false, ## Override `dependency()` It is now possible to override the result of `dependency()` to point -to any dependency object you want. The overriding is global and applies to -every subproject from there on. +to any dependency object you want. The overriding is global and +applies to every subproject from there on. For example, this subproject provides 2 libraries with version 2.0: @@ -89,28 +94,30 @@ foo_dep = dependency('foo', version : '>=2.0', fallback : ['foo', 'foo_dep']) bar_dep = dependency('bar') ``` -This used to mix system 1.0 version and subproject 2.0 dependencies, but thanks -to the override `bar_dep` is now set to the subproject's version instead. +This used to mix system 1.0 version and subproject 2.0 dependencies, +but thanks to the override `bar_dep` is now set to the subproject's +version instead. -Another case this can be useful is to force a subproject to use a specific dependency. -If the subproject does `dependency('foo')` but the main project wants to provide -its own implementation of `foo`, it can for example call -`meson.override_dependency('foo', declare_dependency(...))` before configuring the -subproject. +Another case this can be useful is to force a subproject to use a +specific dependency. If the subproject does `dependency('foo')` but +the main project wants to provide its own implementation of `foo`, it +can for example call `meson.override_dependency('foo', +declare_dependency(...))` before configuring the subproject. ## Simplified `dependency()` fallback -In the case a subproject `foo` calls `meson.override_dependency('foo-2.0', foo_dep)`, -the parent project can omit the dependency variable name in fallback keyword -argument: `dependency('foo-2.0', fallback : 'foo')`. +In the case a subproject `foo` calls +`meson.override_dependency('foo-2.0', foo_dep)`, the parent project +can omit the dependency variable name in fallback keyword argument: +`dependency('foo-2.0', fallback : 'foo')`. ## Backend agnostic compile command -A new `meson compile` command has been added to support backend agnostic -compilation. It accepts two arguments, `-j` and `-l`, which are used if -possible (`-l` does nothing with msbuild). A `-j` or `-l` value < 1 lets the -backend decide how many threads to use. For msbuild this means `-m`, for -ninja it means passing no arguments. +A new `meson compile` command has been added to support backend +agnostic compilation. It accepts two arguments, `-j` and `-l`, which +are used if possible (`-l` does nothing with msbuild). A `-j` or `-l` +value < 1 lets the backend decide how many threads to use. For msbuild +this means `-m`, for ninja it means passing no arguments. ```console meson builddir --backend vs @@ -122,7 +129,8 @@ meson builddir meson compile -C builddir -j3 # this is the same as `ninja -C builddir -j3` ``` -Additionally `meson compile` provides a `--clean` switch to clean the project. +Additionally `meson compile` provides a `--clean` switch to clean the +project. A complete list of arguments is always documented via `meson compile --help` @@ -131,16 +139,16 @@ A complete list of arguments is always documented via `meson compile --help` `add_languages()` gained a `native:` keyword, indicating if a native or cross compiler is to be used. -For the benefit of existing simple build definitions which don't contain any -`native: true` targets, without breaking backwards compatibility for build -definitions which assume that the native compiler is available after -`add_languages()`, if the `native:` keyword is absent the languages may be used -for either the build or host machine, but are never required for the build -machine. +For the benefit of existing simple build definitions which don't +contain any `native: true` targets, without breaking backwards +compatibility for build definitions which assume that the native +compiler is available after `add_languages()`, if the `native:` +keyword is absent the languages may be used for either the build or +host machine, but are never required for the build machine. -This changes the behaviour of the following meson fragment (when cross-compiling -but a native compiler is not available) from reporting an error at -`add_language` to reporting an error at `executable`. +This changes the behaviour of the following meson fragment (when +cross-compiling but a native compiler is not available) from reporting +an error at `add_language` to reporting an error at `executable`. ``` add_language('c') @@ -149,42 +157,48 @@ executable('main', 'main.c', native: true) ## Summary improvements -A new `list_sep` keyword argument has been added to `summary()` function. -If defined and the value is a list, elements will be separated by the provided -string instead of being aligned on a new line. +A new `list_sep` keyword argument has been added to `summary()` +function. If defined and the value is a list, elements will be +separated by the provided string instead of being aligned on a new +line. -The automatic `subprojects` section now also print the number of warnings encountered -during that subproject configuration, or the error message if the configuration failed. +The automatic `subprojects` section now also print the number of +warnings encountered during that subproject configuration, or the +error message if the configuration failed. ## Add a system type dependency for zlib -This allows zlib to be detected on macOS and FreeBSD without the use of -pkg-config or cmake, neither of which are part of the base install on those -OSes (but zlib is). +This allows zlib to be detected on macOS and FreeBSD without the use +of pkg-config or cmake, neither of which are part of the base install +on those OSes (but zlib is). -A side effect of this change is that `dependency('zlib')` also works with -cmake instead of requiring `dependency('ZLIB')`. +A side effect of this change is that `dependency('zlib')` also works +with cmake instead of requiring `dependency('ZLIB')`. ## Added 'name' method -Build target objects (as returned by executable(), library(), ...) now have a name() method. + +Build target objects (as returned by executable(), library(), ...) now +have a name() method. ## New option `--quiet` to `meson install` -Now you can run `meson install --quiet` and meson will not verbosely print -every file as it is being installed. As before, the full log is always -available inside the builddir in `meson-logs/install-log.txt`. +Now you can run `meson install --quiet` and meson will not verbosely +print every file as it is being installed. As before, the full log is +always available inside the builddir in `meson-logs/install-log.txt`. -When this option is passed, install scripts will have the environment variable -`MESON_INSTALL_QUIET` set. +When this option is passed, install scripts will have the environment +variable `MESON_INSTALL_QUIET` set. -Numerous speed-ups were also made for the install step, especially on Windows -where it is now 300% to 1200% faster than before depending on your workload. +Numerous speed-ups were also made for the install step, especially on +Windows where it is now 300% to 1200% faster than before depending on +your workload. ## Property support emscripten's wasm-ld -Before 0.54.0 we treated emscripten as both compiler and linker, which isn't -really true. It does have a linker, called wasm-ld (meson's name is ld.wasm). -This is a special version of clang's lld. This will now be detected properly. +Before 0.54.0 we treated emscripten as both compiler and linker, which +isn't really true. It does have a linker, called wasm-ld (meson's name +is ld.wasm). This is a special version of clang's lld. This will now +be detected properly. ## Skip sanity tests when cross compiling @@ -198,11 +212,12 @@ skip_sanity_check = true ## Support for overiding the linker with ldc and gdc -LDC (the llvm D compiler) and GDC (The Gnu D Compiler) now honor D_LD linker -variable (or d_ld in the cross file) and is able to pick different linkers. +LDC (the llvm D compiler) and GDC (The Gnu D Compiler) now honor D_LD +linker variable (or d_ld in the cross file) and is able to pick +different linkers. -GDC supports all of the same values as GCC, LDC supports ld.bfd, ld.gold, -ld.lld, ld64, link, and lld-link. +GDC supports all of the same values as GCC, LDC supports ld.bfd, +ld.gold, ld.lld, ld64, link, and lld-link. ## Native file properties @@ -212,42 +227,47 @@ As of Meson 0.54.0, the `--native-file nativefile.ini` can contain: * paths * properties -which are defined and used the same way as in cross files. -The `properties` are new for Meson 0.54.0, and are read like: +which are defined and used the same way as in cross files. The +`properties` are new for Meson 0.54.0, and are read like: ```meson x = meson.get_external_property('foobar', 'foo') ``` -where `foobar` is the property name, and the optional `foo` is the fallback string value. +where `foobar` is the property name, and the optional `foo` is the +fallback string value. -For cross-compiled projects, `get_external_property()` reads the cross-file unless `native: true` is specified. +For cross-compiled projects, `get_external_property()` reads the +cross-file unless `native: true` is specified. ## Changed the signal used to terminate a test process (group) -A test process (group) is now terminated via SIGTERM instead of SIGKILL -allowing the signal to be handled. However, it is now the responsibility of -the custom signal handler (if any) to ensure that any process spawned by the -top-level test processes is correctly killed. +A test process (group) is now terminated via SIGTERM instead of +SIGKILL allowing the signal to be handled. However, it is now the +responsibility of the custom signal handler (if any) to ensure that +any process spawned by the top-level test processes is correctly +killed. ## Dynamic Linker environment variables actually match docs -The docs have always claimed that the Dynamic Linker environment variable -should be `${COMPILER_VAR}_LD`, but that's only the case for about half of -the variables. The other half are different. In 0.54.0 the variables match. -The old variables are still supported, but are deprecated and raise a -deprecation warning. +The docs have always claimed that the Dynamic Linker environment +variable should be `${COMPILER_VAR}_LD`, but that's only the case for +about half of the variables. The other half are different. In 0.54.0 +the variables match. The old variables are still supported, but are +deprecated and raise a deprecation warning. ## Per subproject `default_library` and `werror` options -The `default_library` and `werror` built-in options can now be defined per subproject. -This is useful for example when building shared libraries in the main project, -but static link a subproject, or when the main project must build with no warnings -but some subprojects cannot. +The `default_library` and `werror` built-in options can now be defined +per subproject. This is useful for example when building shared +libraries in the main project, but static link a subproject, or when +the main project must build with no warnings but some subprojects +cannot. -Most of the time this would be used either by the parent project by setting -subproject's default_options (e.g. `subproject('foo', default_options: 'default_library=static')`), -or by the user using the command line `-Dfoo:default_library=static`. +Most of the time this would be used either by the parent project by +setting subproject's default_options (e.g. `subproject('foo', +default_options: 'default_library=static')`), or by the user using the +command line `-Dfoo:default_library=static`. The value is overridden in this order: - Value from parent project @@ -257,49 +277,53 @@ The value is overridden in this order: ## Environment Variables with Cross Builds -Previously in Meson, variables like `CC` effected both the host and build -platforms for native builds, but the just the build platform for cross builds. -Now `CC_FOR_BUILD` is used for the build platform in cross builds. +Previously in Meson, variables like `CC` effected both the host and +build platforms for native builds, but the just the build platform for +cross builds. Now `CC_FOR_BUILD` is used for the build platform in +cross builds. This old behavior is inconsistent with the way Autotools works, which undermines the purpose of distro-integration that is the only reason -environment variables are supported at all in Meson. The new behavior is not -quite the same, but doesn't conflict: meson doesn't always repond to an -environment when Autoconf would, but when it does it interprets it as Autotools -would. +environment variables are supported at all in Meson. The new behavior +is not quite the same, but doesn't conflict: meson doesn't always +repond to an environment when Autoconf would, but when it does it +interprets it as Autotools would. ## Added 'pkg_config_libdir' property -Allows to define a list of folders used by pkg-config for a cross build -and avoid a system directories use. + +Allows to define a list of folders used by pkg-config for a cross +build and avoid a system directories use. ## More new sample Meson templates for (`Java`, `Cuda`, and more) -Meson now ships with predefined project templates for `Java`, -`Cuda`, `Objective-C++`, and `C#`, we provided with associated -values for corresponding languages, available for both library, -and executable. +Meson now ships with predefined project templates for `Java`, `Cuda`, +`Objective-C++`, and `C#`, we provided with associated values for +corresponding languages, available for both library, and executable. ## Ninja version requirement bumped to 1.7 -Meson now uses the [Implicit outputs](https://ninja-build.org/manual.html#ref_outputs) -feature of Ninja for some types of targets that have multiple outputs which may +Meson now uses the [Implicit +outputs](https://ninja-build.org/manual.html#ref_outputs) feature of +Ninja for some types of targets that have multiple outputs which may not be listed on the command-line. This feature requires Ninja 1.7+. -Note that the latest version of [Ninja available in Ubuntu 16.04](https://packages.ubuntu.com/search?keywords=ninja-build&searchon=names&suite=xenial-backports§ion=all) -(the oldest Ubuntu LTS at the time of writing) is 1.7.1. If your distro does -not ship with a new-enough Ninja, you can download the latest release from -Ninja's GitHub page: https://github.com/ninja-build/ninja/releases +Note that the latest version of [Ninja available in Ubuntu +16.04](https://packages.ubuntu.com/search?keywords=ninja-build&searchon=names&suite=xenial-backports§ion=all) +(the oldest Ubuntu LTS at the time of writing) is 1.7.1. If your +distro does not ship with a new-enough Ninja, you can download the +latest release from Ninja's GitHub page: +https://github.com/ninja-build/ninja/releases ## Added `-C` argument to `meson init` command -The meson init assumes that it is run inside the project -root directory. If this isn't the case, you can now use -`-C` to specify the actual project source directory. +The meson init assumes that it is run inside the project root +directory. If this isn't the case, you can now use `-C` to specify the +actual project source directory. ## More than one argument to `message()` and `warning()` -Arguments passed to `message()` and `warning()` will be printed separated by -space. +Arguments passed to `message()` and `warning()` will be printed +separated by space. ## Added `has_tools` method to qt module @@ -325,24 +349,27 @@ repository. **Note**: the functionality of this module is governed by [Meson's rules on mixing build systems](Mixing-build-systems.md). -The `pkgconfig` module now generates uninstalled pc files as well. For any generated -`foo.pc` file, an extra `foo-uninstalled.pc` file is placed into -`<builddir>/meson-uninstalled`. They can be used to build applications against -libraries built by meson without installing them, by pointing `PKG_CONFIG_PATH` -to that directory. This is an experimental feature provided on a best-effort -basis, it might not work in all use-cases. +The `pkgconfig` module now generates uninstalled pc files as well. For +any generated `foo.pc` file, an extra `foo-uninstalled.pc` file is +placed into `<builddir>/meson-uninstalled`. They can be used to build +applications against libraries built by meson without installing them, +by pointing `PKG_CONFIG_PATH` to that directory. This is an +experimental feature provided on a best-effort basis, it might not +work in all use-cases. ## CMake find_package COMPONENTS support -It is now possible to pass components to the CMake dependency backend via the -new `components` kwarg in the `dependency` function. +It is now possible to pass components to the CMake dependency backend +via the new `components` kwarg in the `dependency` function. ## Added Microchip XC16 C compiler support + Make sure compiler executables are setup correctly in your path Compiler is available from the Microchip website for free ## Added Texas Instruments C2000 C/C++ compiler support + Make sure compiler executables are setup correctly in your path Compiler is available from Texas Instruments website for free @@ -361,6 +388,7 @@ be replicated by setting `unity_size` to a large value, such as 10000. ## Verbose mode for `meson compile` -The new option `--verbose` has been added to `meson compile` that will enable -more verbose compilation logs. Note that for VS backend it means that logs will -be less verbose by default (without `--verbose` option). +The new option `--verbose` has been added to `meson compile` that will +enable more verbose compilation logs. Note that for VS backend it +means that logs will be less verbose by default (without `--verbose` +option). diff --git a/docs/markdown/Release-notes-for-0.55.0.md b/docs/markdown/Release-notes-for-0.55.0.md index c566560..3e4fcc9 100644 --- a/docs/markdown/Release-notes-for-0.55.0.md +++ b/docs/markdown/Release-notes-for-0.55.0.md @@ -8,14 +8,15 @@ short-description: Release notes for 0.55.0 ## rpath removal now more careful On Linux-like systems, meson adds rpath entries to allow running apps -in the build tree, and then removes those build-time-only -rpath entries when installing. Rpath entries may also come -in via LDFLAGS and via .pc files. Meson used to remove those -latter rpath entries by accident, but is now more careful. +in the build tree, and then removes those build-time-only rpath +entries when installing. Rpath entries may also come in via LDFLAGS +and via .pc files. Meson used to remove those latter rpath entries by +accident, but is now more careful. ## Added ability to specify targets in `meson compile` -It's now possible to specify targets in `meson compile`, which will result in building only the requested targets. +It's now possible to specify targets in `meson compile`, which will +result in building only the requested targets. Usage: `meson compile [TARGET [TARGET...]]` `TARGET` has the following syntax: `[PATH/]NAME[:TYPE]`. @@ -35,10 +36,10 @@ can be invoked with `meson compile foo:shared_library foo:static_library bar`. ## Test protocol for gtest -Due to the popularity of Gtest (google test) among C and C++ developers meson -now supports a special protocol for gtest. With this protocol meson injects -arguments to gtests to output JUnit, reads that JUnit, and adds the output to -the JUnit it generates. +Due to the popularity of Gtest (google test) among C and C++ +developers meson now supports a special protocol for gtest. With this +protocol meson injects arguments to gtests to output JUnit, reads that +JUnit, and adds the output to the JUnit it generates. ## meson.add_*_script methods accept new types @@ -56,8 +57,8 @@ meson.add_postconf_script(find_program('foo'), files('bar')) ``` The install script variant is also able to accept custom_targets, -custom_target indexes, and build targets (executables, libraries), and can -use built executables a the script to run +custom_target indexes, and build targets (executables, libraries), and +can use built executables a the script to run ```meson installer = executable('installer', ...) @@ -67,11 +68,11 @@ meson.add_install_script('foo.py', installer) ## Machine file constants -Native and cross files now support string and list concatenation using the `+` -operator, and joining paths using the `/` operator. -Entries defined in the `[constants]` section can be used in any other section. -An entry defined in any other section can be used only within that same section and only -after it has been defined. +Native and cross files now support string and list concatenation using +the `+` operator, and joining paths using the `/` operator. Entries +defined in the `[constants]` section can be used in any other section. +An entry defined in any other section can be used only within that +same section and only after it has been defined. ```ini [constants] @@ -88,26 +89,27 @@ c = toolchain + '/gcc' ## Configure CMake subprojects with meson.subproject_options -Meson now supports passing configuration options to CMake and overriding -certain build details extracted from the CMake subproject. +Meson now supports passing configuration options to CMake and +overriding certain build details extracted from the CMake subproject. The new CMake configuration options object is very similar to the -[configuration data object](Reference-manual.md#configuration-data-object) object -returned by [`configuration_data`](Reference-manual.md#configuration_data). It +[configuration data +object](Reference-manual.md#configuration-data-object) object returned +by [`configuration_data`](Reference-manual.md#configuration_data). It is generated by the `subproject_options` function -All configuration options have to be set *before* the subproject is configured -and must be passed to the `subproject` method via the `options` key. Altering -the configuration object won't have any effect on previous `cmake.subproject` -calls. +All configuration options have to be set *before* the subproject is +configured and must be passed to the `subproject` method via the +`options` key. Altering the configuration object won't have any effect +on previous `cmake.subproject` calls. -**Note:** The `cmake_options` kwarg for the `subproject` function is now -deprecated since it is replaced by the new `options` system. +**Note:** The `cmake_options` kwarg for the `subproject` function is +now deprecated since it is replaced by the new `options` system. ## find_program: Fixes when the program has been overridden by executable -When a program has been overridden by an executable, the returned object of -find_program() had some issues: +When a program has been overridden by an executable, the returned +object of find_program() had some issues: ```meson # In a subproject: @@ -135,16 +137,16 @@ but only when needed to avoid command line length limits. ## `unstable-kconfig` module renamed to `unstable-keyval` -The `unstable-kconfig` module is now renamed to `unstable-keyval`. -We expect this module to become stable once it has some usage experience, +The `unstable-kconfig` module is now renamed to `unstable-keyval`. We +expect this module to become stable once it has some usage experience, specifically in the next or the following release ## Fatal warnings in `gnome.generate_gir()` -`gnome.generate_gir()` now has `fatal_warnings` keyword argument to abort when -a warning is produced. This is useful for example in CI environment where it's -important to catch potential issues. +`gnome.generate_gir()` now has `fatal_warnings` keyword argument to +abort when a warning is produced. This is useful for example in CI +environment where it's important to catch potential issues. ## b_ndebug support for D language compilers @@ -153,27 +155,29 @@ the compiler) when the b_ndebug flag is set. ## Meson test now produces JUnit xml from results -Meson will now generate a JUnit compatible XML file from test results. it -will be in the meson-logs directory and is called testlog.junit.xml. +Meson will now generate a JUnit compatible XML file from test results. +it will be in the meson-logs directory and is called +testlog.junit.xml. ## Config tool based dependencies no longer search PATH for cross compiling -Before 0.55.0 config tool based dependencies (llvm-config, cups-config, etc), -would search system $PATH if they weren't defined in the cross file. This has -been a source of bugs and has been deprecated. It is now removed, config tool -binaries must be specified in the cross file now or the dependency will not -be found. +Before 0.55.0 config tool based dependencies (llvm-config, +cups-config, etc), would search system $PATH if they weren't defined +in the cross file. This has been a source of bugs and has been +deprecated. It is now removed, config tool binaries must be specified +in the cross file now or the dependency will not be found. ## Rename has_exe_wrapper -> can_run_host_binaries -The old name was confusing as it didn't really match the behavior of the -function. The old name remains as an alias (the behavior hasn't changed), but -is now deprecated. +The old name was confusing as it didn't really match the behavior of +the function. The old name remains as an alias (the behavior hasn't +changed), but is now deprecated. ## String concatenation in meson_options.txt -It is now possible to use string concatenation (with the `+` opperator) in the -meson_options.txt file. This allows splitting long option descriptions. +It is now possible to use string concatenation (with the `+` +opperator) in the meson_options.txt file. This allows splitting long +option descriptions. ```meson option( @@ -187,53 +191,57 @@ option( ## Wrap fallback URL -Wrap files can now define `source_fallback_url` and `patch_fallback_url` to be -used in case the main server is temporaly down. +Wrap files can now define `source_fallback_url` and +`patch_fallback_url` to be used in case the main server is temporaly +down. ## Clang coverage support -llvm-cov is now used to generate coverage information when clang is used as -the compiler. +llvm-cov is now used to generate coverage information when clang is +used as the compiler. ## Local wrap source and patch files -It is now possible to use the `patch_filename` and `source_filename` value in a -`.wrap` file without `*_url` to specify a local source / patch file. All local -files must be located in the `subprojects/packagefiles` directory. The `*_hash` -entries are optional with this setup. +It is now possible to use the `patch_filename` and `source_filename` +value in a `.wrap` file without `*_url` to specify a local source / +patch file. All local files must be located in the +`subprojects/packagefiles` directory. The `*_hash` entries are +optional with this setup. ## Local wrap patch directory -Wrap files can now specify `patch_directory` instead of `patch_filename` in the -case overlay files are local. Every files in that directory, and subdirectories, -will be copied to the subproject directory. This can be used for example to add -`meson.build` files to a project not using Meson build system upstream. -The patch directory must be placed in `subprojects/packagefiles` directory. +Wrap files can now specify `patch_directory` instead of +`patch_filename` in the case overlay files are local. Every files in +that directory, and subdirectories, will be copied to the subproject +directory. This can be used for example to add `meson.build` files to +a project not using Meson build system upstream. The patch directory +must be placed in `subprojects/packagefiles` directory. ## Patch on all wrap types -`patch_*` keys are not limited to `wrap-file` any more, they can be specified for -all wrap types. +`patch_*` keys are not limited to `wrap-file` any more, they can be +specified for all wrap types. ## link_language argument added to all targets -Previously the `link_language` argument was only supposed to be allowed in -executables, because the linker used needs to be the linker for the language -that implements the main function. Unfortunately it didn't work in that case, -and, even worse, if it had been implemented properly it would have worked for -*all* targets. In 0.55.0 this restriction has been removed, and the bug fixed. -It now is valid for `executable` and all derivative of `library`. +Previously the `link_language` argument was only supposed to be +allowed in executables, because the linker used needs to be the linker +for the language that implements the main function. Unfortunately it +didn't work in that case, and, even worse, if it had been implemented +properly it would have worked for *all* targets. In 0.55.0 this +restriction has been removed, and the bug fixed. It now is valid for +`executable` and all derivative of `library`. ## meson dist --no-tests -`meson dist` has a new option `--no-tests` to skip build and tests of generated -packages. It can be used to not waste time for example when done in CI that -already does its own testing. +`meson dist` has a new option `--no-tests` to skip build and tests of +generated packages. It can be used to not waste time for example when +done in CI that already does its own testing. ## Force fallback for -A newly-added `--force-fallback-for` command line option can now be used to -force fallback for specific subprojects. +A newly-added `--force-fallback-for` command line option can now be +used to force fallback for specific subprojects. Example: @@ -243,32 +251,36 @@ meson builddir/ --force-fallback-for=foo,bar ## Implicit dependency fallback -`dependency('foo')` now automatically fallback if the dependency is not found on -the system but a subproject wrap file or directory exists with the same name. +`dependency('foo')` now automatically fallback if the dependency is +not found on the system but a subproject wrap file or directory exists +with the same name. -That means that simply adding `subprojects/foo.wrap` is enough to add fallback -to any `dependency('foo')` call. It is however requires that the subproject call -`meson.override_dependency('foo', foo_dep)` to specify which dependency object -should be used for `foo`. +That means that simply adding `subprojects/foo.wrap` is enough to add +fallback to any `dependency('foo')` call. It is however requires that +the subproject call `meson.override_dependency('foo', foo_dep)` to +specify which dependency object should be used for `foo`. ## Wrap file `provide` section -Wrap files can define the dependencies it provides in the `[provide]` section. -When `foo.wrap` provides the dependency `foo-1.0` any call do `dependency('foo-1.0')` -will automatically fallback to that subproject even if no `fallback` keyword -argument is given. See [Wrap documentation](Wrap-dependency-system-manual.md#provide_section). +Wrap files can define the dependencies it provides in the `[provide]` +section. When `foo.wrap` provides the dependency `foo-1.0` any call do +`dependency('foo-1.0')` will automatically fallback to that subproject +even if no `fallback` keyword argument is given. See [Wrap +documentation](Wrap-dependency-system-manual.md#provide_section). ## `find_program()` fallback -When a program cannot be found on the system but a wrap file has its name in the -`[provide]` section, that subproject will be used as fallback. +When a program cannot be found on the system but a wrap file has its +name in the `[provide]` section, that subproject will be used as +fallback. ## Test scripts are given the exe wrapper if needed -Meson will now set the `MESON_EXE_WRAPPER` as the properly wrapped and joined -representation. For Unix-like OSes this means python's shelx.join, on Windows -an implementation that attempts to properly quote windows argument is used. -This allow wrapper scripts to run test binaries, instead of just skipping. +Meson will now set the `MESON_EXE_WRAPPER` as the properly wrapped and +joined representation. For Unix-like OSes this means python's +shelx.join, on Windows an implementation that attempts to properly +quote windows argument is used. This allow wrapper scripts to run test +binaries, instead of just skipping. for example, if the wrapper is `['emulator', '--script']`, it will be passed as `MESON_EXE_WRAPPER="emulator --script"`. @@ -286,7 +298,8 @@ Usage: `meson compile [--vs-args=args] [--ninja-args=args]` These arguments use the following syntax: -If you only pass a single string, then it is considered to have all values separated by commas. Thus invoking the following command: +If you only pass a single string, then it is considered to have all +values separated by commas. Thus invoking the following command: ``` $ meson compile --ninja-args=-n,-d,explain @@ -294,7 +307,8 @@ $ meson compile --ninja-args=-n,-d,explain would add `-n`, `-d` and `explain` arguments to ninja invocation. -If you need to have commas or spaces in your string values, then you need to pass the value with proper shell quoting like this: +If you need to have commas or spaces in your string values, then you +need to pass the value with proper shell quoting like this: ``` $ meson compile "--ninja-args=['a,b', 'c d']" @@ -307,9 +321,12 @@ dumping the AST (--ast): **new in 0.55.0** ## `--backend=vs` now matches `-Db_vscrt=from_buildtype` behaviour in the Ninja backend -When `--buildtype=debugoptimized` is used with the Ninja backend, the VS CRT -option used is `/MD`, which is the [behaviour documented for all +When `--buildtype=debugoptimized` is used with the Ninja backend, the +VS CRT option used is `/MD`, which is the [behaviour documented for +all backends](https://mesonbuild.com/Builtin-options.html#b_vscrt-from_buildtype). -However, the Visual Studio backend was pass `/MT` in that case, which is inconsistent. +However, the Visual Studio backend was pass `/MT` in that case, which +is inconsistent. -If you need to use the MultiThreaded CRT, you should explicitly pass `-Db_vscrt=mt` +If you need to use the MultiThreaded CRT, you should explicitly pass +`-Db_vscrt=mt` diff --git a/docs/markdown/Release-notes-for-0.56.0.md b/docs/markdown/Release-notes-for-0.56.0.md index cef1dee..05f30bd 100644 --- a/docs/markdown/Release-notes-for-0.56.0.md +++ b/docs/markdown/Release-notes-for-0.56.0.md @@ -7,25 +7,28 @@ short-description: Release notes for 0.56.0 ## Python 3.5 support will be dropped in the next release -The final [Python 3.5 release was 3.5.10 in September](https://www.python.org/dev/peps/pep-0478/#id4). -This release series is now End-of-Life (EOL). The only LTS distribution that -still only ships Python 3.5 is Ubuntu 16.04, which will be -[EOL in April 2021](https://ubuntu.com/about/release-cycle). - -Python 3.6 has numerous features that we find useful such as improved support -for the `typing` module, f-string support, and better integration with the -`pathlib` module. - -As a result, we will begin requiring Python 3.6 or newer in Meson 0.57, which -is the next release. Starting with Meson 0.56, we now print a `NOTICE:` when -a `meson` command is run on Python 3.5 to inform users about this. This notice -has also been backported into the 0.55.2 stable release. +The final [Python 3.5 release was 3.5.10 in +September](https://www.python.org/dev/peps/pep-0478/#id4). This +release series is now End-of-Life (EOL). The only LTS distribution +that still only ships Python 3.5 is Ubuntu 16.04, which will be [EOL +in April 2021](https://ubuntu.com/about/release-cycle). + +Python 3.6 has numerous features that we find useful such as improved +support for the `typing` module, f-string support, and better +integration with the `pathlib` module. + +As a result, we will begin requiring Python 3.6 or newer in Meson +0.57, which is the next release. Starting with Meson 0.56, we now +print a `NOTICE:` when a `meson` command is run on Python 3.5 to +inform users about this. This notice has also been backported into the +0.55.2 stable release. ## `meson test` can now filter tests by subproject -You could always specify a list of tests to run by passing the names as -arguments to `meson test`. If there were multiple tests with that name (in the -same project or different subprojects), all of them would be run. Now you can: +You could always specify a list of tests to run by passing the names +as arguments to `meson test`. If there were multiple tests with that +name (in the same project or different subprojects), all of them would +be run. Now you can: 1. Run all tests with the specified name from a specific subproject: `meson test subprojname:testname` 1. Run all tests defined in a specific subproject: `meson test subprojectname:` @@ -42,56 +45,62 @@ $ meson test name1 name2 bar:name3 foo: ## Native (build machine) compilers not always required by `project()` -When cross-compiling, native (build machine) compilers for the languages -specified in `project()` are not required, if no targets use them. +When cross-compiling, native (build machine) compilers for the +languages specified in `project()` are not required, if no targets use +them. ## New `extra_files` key in target introspection -The target introspection (`meson introspect --targets`, `intro-targets.json`) -now has the new `extra_files` key which lists all files specified via the -`extra_files` kwarg of a build target (see `executable()`, etc.) +The target introspection (`meson introspect --targets`, +`intro-targets.json`) now has the new `extra_files` key which lists +all files specified via the `extra_files` kwarg of a build target (see +`executable()`, etc.) ## Preliminary AIX support -AIX is now supported when compiling with gcc. A number of features are not -supported yet. For example, only gcc is supported (not xlC). Archives with both -32-bit and 64-bit dynamic libraries are not generated automatically. The rpath -includes both the build and install rpath, no attempt is made to change the -rpath at install time. Most advanced features (eg. link\_whole) are not -supported yet. +AIX is now supported when compiling with gcc. A number of features are +not supported yet. For example, only gcc is supported (not xlC). +Archives with both 32-bit and 64-bit dynamic libraries are not +generated automatically. The rpath includes both the build and install +rpath, no attempt is made to change the rpath at install time. Most +advanced features (eg. link\_whole) are not supported yet. ## Wraps from subprojects are automatically promoted -It is not required to promote wrap files for subprojects into the main project -any more. When configuring a subproject, meson will look for any wrap file or -directory in the subproject's `subprojects/` directory and add them into the -global list of available subprojects, to be used by any future `subproject()` -call or `dependency()` fallback. If a subproject with the same name already exists, -the new wrap file or directory is ignored. That means that the main project can -always override any subproject's wrap files by providing their own, it also means -the ordering in which subprojects are configured matters, if 2 subprojects provide -foo.wrap only the one from the first subproject to be configured will be used. +It is not required to promote wrap files for subprojects into the main +project any more. When configuring a subproject, meson will look for +any wrap file or directory in the subproject's `subprojects/` +directory and add them into the global list of available subprojects, +to be used by any future `subproject()` call or `dependency()` +fallback. If a subproject with the same name already exists, the new +wrap file or directory is ignored. That means that the main project +can always override any subproject's wrap files by providing their +own, it also means the ordering in which subprojects are configured +matters, if 2 subprojects provide foo.wrap only the one from the first +subproject to be configured will be used. This new behavior can be disabled by passing `--wrap-mode=nopromote`. ## `meson.build_root()` and `meson.source_root()` are deprecated -Those function are common source of issue when used in a subproject because they -point to the parent project root which is rarely what is expected and is a -violation of subproject isolation. +Those function are common source of issue when used in a subproject +because they point to the parent project root which is rarely what is +expected and is a violation of subproject isolation. -`meson.current_source_dir()` and `meson.current_build_dir()` should be used instead -and have been available in all Meson versions. New functions `meson.project_source_root()` -and `meson.project_build_root()` have been added in Meson 0.56.0 to get the root -of the current (sub)project. +`meson.current_source_dir()` and `meson.current_build_dir()` should be +used instead and have been available in all Meson versions. New +functions `meson.project_source_root()` and +`meson.project_build_root()` have been added in Meson 0.56.0 to get +the root of the current (sub)project. ## `dep.as_link_whole()` -Dependencies created with `declare_dependency()` now has new method `as_link_whole()`. -It returns a copy of the dependency object with all link_with arguments changed -to link_whole. This is useful for example for fallback dependency from a -subproject built with `default_library=static`. +Dependencies created with `declare_dependency()` now has new method +`as_link_whole()`. It returns a copy of the dependency object with all +link_with arguments changed to link_whole. This is useful for example +for fallback dependency from a subproject built with +`default_library=static`. ```meson somelib = static_library('somelib', ...) @@ -128,11 +137,11 @@ Added support for `nvidia_hpc` NVidia HPC SDK compilers, which are currently in ## Project and built-in options can be set in native or cross files -A new set of sections has been added to the cross and native files, `[project -options]` and `[<subproject_name>:project options]`, where `subproject_name` -is the name of a subproject. Any options that are allowed in the project can -be set from this section. They have the lowest precedent, and will be -overwritten by command line arguments. +A new set of sections has been added to the cross and native files, +`[project options]` and `[<subproject_name>:project options]`, where +`subproject_name` is the name of a subproject. Any options that are +allowed in the project can be set from this section. They have the +lowest precedent, and will be overwritten by command line arguments. ```meson @@ -189,26 +198,28 @@ stabilised (so `unstable-keyval` is still accepted for example). ## CMake subproject cross compilation support -Meson now supports cross compilation for CMake subprojects. Meson will try to -automatically guess most of the required CMake toolchain variables from existing -entries in the cross and native files. These variables will be stored in an -automatically generate CMake toolchain file in the build directory. The -remaining variables that can't be guessed can be added by the user in the -new `[cmake]` cross/native file section. +Meson now supports cross compilation for CMake subprojects. Meson will +try to automatically guess most of the required CMake toolchain +variables from existing entries in the cross and native files. These +variables will be stored in an automatically generate CMake toolchain +file in the build directory. The remaining variables that can't be +guessed can be added by the user in the new `[cmake]` cross/native +file section. ## Machine file keys are stored case sensitive -Previous the keys were always lowered, which worked fine for the values that -were allowed in the machine files. With the addition of per-project options -we need to make these sensitive to case, as the options in meson_options.txt -are sensitive to case already. +Previous the keys were always lowered, which worked fine for the +values that were allowed in the machine files. With the addition of +per-project options we need to make these sensitive to case, as the +options in meson_options.txt are sensitive to case already. ## Consistency between `declare_dependency()` and `pkgconfig.generate()` variables -The `variables` keyword argument in `declare_dependency()` used to only support -dictionary and `pkgconfig.generate()` only list of strings. They now both support -dictionary and list of strings in the format `'name=value'`. This makes easier -to share a common set of variables for both: +The `variables` keyword argument in `declare_dependency()` used to +only support dictionary and `pkgconfig.generate()` only list of +strings. They now both support dictionary and list of strings in the +format `'name=value'`. This makes easier to share a common set of +variables for both: ```meson vars = {'foo': 'bar'} @@ -218,8 +229,9 @@ pkg.generate(..., variables: vars) ## Qt5 compile_translations now supports qresource preprocessing -When using qtmod.preprocess() in combination with qtmod.compile_translations() -to embed translations using rcc, it is no longer required to do this: +When using qtmod.preprocess() in combination with +qtmod.compile_translations() to embed translations using rcc, it is no +longer required to do this: ```meson ts_files = ['list', 'of', 'files'] @@ -233,16 +245,16 @@ Instead, use: lang_cpp = qtmod.compile_translations(qresource: 'lang.qrc') ``` -which will automatically detect and generate the needed compile_translations -targets. +which will automatically detect and generate the needed +compile_translations targets. ## Controlling subproject dependencies with `dependency(allow_fallback: ...)` As an alternative to the `fallback` keyword argument to `dependency`, you may use `allow_fallback`, which accepts a boolean value. If `true` -and the dependency is not found on the system, Meson will fallback -to a subproject that provides this dependency, even if the dependency -is optional. If `false`, Meson will not fallback even if a subproject +and the dependency is not found on the system, Meson will fallback to +a subproject that provides this dependency, even if the dependency is +optional. If `false`, Meson will not fallback even if a subproject provides this dependency. ## Custom standard library @@ -259,19 +271,19 @@ find_library for lookup as well as pkg-config. ## HDF5 dependency improvements -HDF5 has been improved so that the internal representations have been split. -This allows selecting pkg-config and config-tool dependencies separately. -Both work as proper dependencies of their type, so `get_variable` and similar -now work correctly. +HDF5 has been improved so that the internal representations have been +split. This allows selecting pkg-config and config-tool dependencies +separately. Both work as proper dependencies of their type, so +`get_variable` and similar now work correctly. It has also been fixed to use the selected compiler for the build instead of the default compiler. ## External projects -A new experimental module `unstable_external_project` has been added to build -code using other build systems than Meson. Currently only supporting projects -with a configure script that generates Makefiles. +A new experimental module `unstable_external_project` has been added +to build code using other build systems than Meson. Currently only +supporting projects with a configure script that generates Makefiles. ```meson project('My Autotools Project', 'c', @@ -299,21 +311,23 @@ mylib_dep = p.dependency('mylib') ## `meson subprojects` command -A new `--types` argument has been added to all subcommands to run the command only -on wraps with the specified types. For example this command will only print `Hello` -for each git subproject: `meson subprojects foreach --types git echo "Hello"`. -Multiple types can be set as comma separated list e.g. `--types git,file`. +A new `--types` argument has been added to all subcommands to run the +command only on wraps with the specified types. For example this +command will only print `Hello` for each git subproject: `meson +subprojects foreach --types git echo "Hello"`. Multiple types can be +set as comma separated list e.g. `--types git,file`. -Subprojects with no wrap file are now taken into account as well. This happens -for example for subprojects configured as git submodule, or downloaded manually -by the user and placed into the `subprojects/` directory. +Subprojects with no wrap file are now taken into account as well. This +happens for example for subprojects configured as git submodule, or +downloaded manually by the user and placed into the `subprojects/` +directory. -The `checkout` subcommand now always stash any pending changes before switching -branch. Note that `update` subcommand was already stashing changes before updating -the branch. +The `checkout` subcommand now always stash any pending changes before +switching branch. Note that `update` subcommand was already stashing +changes before updating the branch. -If the command fails on any subproject the execution continues with other -subprojects, but at the end an error code is now returned. +If the command fails on any subproject the execution continues with +other subprojects, but at the end an error code is now returned. The `update` subcommand has been reworked: - In the case the URL of `origin` is different as the `url` set in wrap file, @@ -336,22 +350,26 @@ The `update` subcommand has been reworked: ## Added CompCert C compiler -Added experimental support for the [CompCert formally-verified C compiler](https://github.com/AbsInt/CompCert). The current state of the implementation is good enough to build the [picolibc project](https://github.com/picolibc/picolibc) with CompCert, but might still need additional adjustments for other projects. +Added experimental support for the [CompCert formally-verified C +compiler](https://github.com/AbsInt/CompCert). The current state of +the implementation is good enough to build the [picolibc +project](https://github.com/picolibc/picolibc) with CompCert, but +might still need additional adjustments for other projects. ## Dependencies listed in test and benchmark introspection -The introspection data for tests and benchmarks now includes the target -ids for executables and built files that are needed by the test. IDEs can -use this feature to update the build more quickly before running a test. +The introspection data for tests and benchmarks now includes the +target ids for executables and built files that are needed by the +test. IDEs can use this feature to update the build more quickly +before running a test. ## `include_type` support for the CMake subproject object dependency method -The `dependency()` method of the CMake subproject object now also supports the -`include_type` kwarg which is similar to the sane kwarg in the `dependency()` -function. +The `dependency()` method of the CMake subproject object now also +supports the `include_type` kwarg which is similar to the sane kwarg +in the `dependency()` function. ## Deprecate Dependency.get_pkgconfig_variable and Dependency.get_configtool_variable These have been replaced with the more versatile `get_variable()` method already, and shouldn't be used anymore. - diff --git a/docs/markdown/Release-procedure.md b/docs/markdown/Release-procedure.md index caf4973..a7ef689 100644 --- a/docs/markdown/Release-procedure.md +++ b/docs/markdown/Release-procedure.md @@ -4,46 +4,50 @@ # Trunk -Meson operates under the principle that trunk should (in theory) be always -good enough for release. That is, all code merged in trunk must pass all unit -tests. Any broken code should either be fixed or reverted immediately. +Meson operates under the principle that trunk should (in theory) be +always good enough for release. That is, all code merged in trunk must +pass all unit tests. Any broken code should either be fixed or +reverted immediately. -People who are willing to tolerate the occasional glitch should be able to -use Meson trunk for their day to day development if they so choose. +People who are willing to tolerate the occasional glitch should be +able to use Meson trunk for their day to day development if they so +choose. # Major releases -Major releases are currently in the form 0.X.0, where X is an increasing -number. We aim to do a major release roughly once a month, though the -schedule is not set in stone. +Major releases are currently in the form 0.X.0, where X is an +increasing number. We aim to do a major release roughly once a month, +though the schedule is not set in stone. -Before a major release is made a stable branch will be made, and 0.X.0-rc1 -release candidate will be made. A new milestone for 0.X.0 will be made, and -all bugs effecting the RC will be assigned to this milestone. Patches fixing -bugs in the milestone will be picked to the stable branch, and normal -development will continue on the master branch. Every week after after this a -new release candidate will be made until all bugs are resolved in that -milestone. When all of the bugs are fixed the 0.X.0 release will be made. +Before a major release is made a stable branch will be made, and +0.X.0-rc1 release candidate will be made. A new milestone for 0.X.0 +will be made, and all bugs effecting the RC will be assigned to this +milestone. Patches fixing bugs in the milestone will be picked to the +stable branch, and normal development will continue on the master +branch. Every week after after this a new release candidate will be +made until all bugs are resolved in that milestone. When all of the +bugs are fixed the 0.X.0 release will be made. # Bugfix releases -Bugfix releases contain only minor fixes to major releases and are designated -by incrementing the last digit of the version number. The criteria for a bug -fix release is one of the following: +Bugfix releases contain only minor fixes to major releases and are +designated by incrementing the last digit of the version number. The +criteria for a bug fix release is one of the following: - release has a major regression compared to the previous release (making existing projects unbuildable) - the release has a serious bug causing data loss or equivalent - other unforeseen major issue -In these cases a bug fix release can be made. It shall contain _only_ the fix -for the issue (or issues) in question and other minor bug fixes. Only changes -that have already landed in trunk will be considered for inclusion. No new -functionality shall be added. +In these cases a bug fix release can be made. It shall contain _only_ +the fix for the issue (or issues) in question and other minor bug +fixes. Only changes that have already landed in trunk will be +considered for inclusion. No new functionality shall be added. # Requesting a bug fix release -The process for requesting that a bug fix release be made goes roughly as follows: +The process for requesting that a bug fix release be made goes roughly +as follows: - file a bug about the core issue - file a patch fixing it if possible @@ -56,9 +60,10 @@ The request should contain the following information: - whether it has already caused problems for real projects - an estimate of how many people and projects will be affected -There is no need to write a long and complicated request report. Something like the following is sufficient: +There is no need to write a long and complicated request report. +Something like the following is sufficient: > The latest release has a regression where trying to do Foo using Bar -breaks. This breaks all projects that use both, which includes at least [list -of affected projects]. This causes problems for X amount of people and -because of this we should do a bugfix release. +breaks. This breaks all projects that use both, which includes at +least [list of affected projects]. This causes problems for X amount +of people and because of this we should do a bugfix release. diff --git a/docs/markdown/Rewriter.md b/docs/markdown/Rewriter.md index 20b741f..cd52a11 100644 --- a/docs/markdown/Rewriter.md +++ b/docs/markdown/Rewriter.md @@ -4,9 +4,9 @@ short-description: Automatic modification of the build system files # Meson file rewriter -Since version 0.50.0, meson has the functionality to perform some basic -modification on the `meson.build` files from the command line. The currently -supported operations are: +Since version 0.50.0, meson has the functionality to perform some +basic modification on the `meson.build` files from the command line. +The currently supported operations are: - For build targets: - Add/Remove source files @@ -19,22 +19,23 @@ supported operations are: - Modify a select set of kwargs - Modify the default options list -The rewriter has both, a normal command line interface and a "script mode". The -normal CLI is mostly designed for everyday use. The "script mode", on the -other hand, is meant to be used by external programs (IDEs, graphical -frontends, etc.) +The rewriter has both, a normal command line interface and a "script +mode". The normal CLI is mostly designed for everyday use. The "script +mode", on the other hand, is meant to be used by external programs +(IDEs, graphical frontends, etc.) -The rewriter itself is considered stable, however the user interface and the -"script mode" API might change in the future. These changes may also break -backwards comaptibility to older releases. +The rewriter itself is considered stable, however the user interface +and the "script mode" API might change in the future. These changes +may also break backwards comaptibility to older releases. We are also open to suggestions for API improvements. ## Using the rewriter -All rewriter functions are accessed via `meson rewrite`. The meson rewriter -assumes that it is run inside the project root directory. If this isn't the -case, use `--sourcedir` to specify the actual project source directory. +All rewriter functions are accessed via `meson rewrite`. The meson +rewriter assumes that it is run inside the project root directory. If +this isn't the case, use `--sourcedir` to specify the actual project +source directory. ### Adding and removing sources @@ -67,17 +68,19 @@ src = ['main.cpp', 'fileA.cpp', 'fileB.cpp'] exe1 = executable('testExe', src) ``` -In this case, `exe1` could also have been used for the target name. This is -possible because the rewriter also searches for assignments and unique meson -IDs, which can be acquired with introspection. If there are multiple targets -with the same name, meson will do nothing and print an error message. +In this case, `exe1` could also have been used for the target name. +This is possible because the rewriter also searches for assignments +and unique meson IDs, which can be acquired with introspection. If +there are multiple targets with the same name, meson will do nothing +and print an error message. -For more information see the help output of the rewriter target command. +For more information see the help output of the rewriter target +command. ### Setting the project version -It is also possible to set kwargs of specific functions with the rewriter. The -general command for setting or removing kwargs is: +It is also possible to set kwargs of specific functions with the +rewriter. The general command for setting or removing kwargs is: ```bash meson rewrite kwargs {set/delete} <function type> <function ID> <key1> <value1> <key2> <value2> ... @@ -97,10 +100,10 @@ Currently, only the following function types are supported: For more information see the help output of the rewrite kwargs command. -Note msys bash may expand `/` to a path. Passing `//` will be converted to -`/` by msys bash but in order to keep usage shell-agnostic, the rewrite command -also allows `//` as the function ID such that it will work in both msys bash -and other shells. +Note msys bash may expand `/` to a path. Passing `//` will be +converted to `/` by msys bash but in order to keep usage +shell-agnostic, the rewrite command also allows `//` as the function +ID such that it will work in both msys bash and other shells. ### Setting the project default options @@ -112,9 +115,10 @@ meson rewrite default-options {set/delete} <opt1> <value1> <opt2> <value2> ... ## Limitations -Rewriting a meson file is not guaranteed to keep the indentation of the modified -functions. Additionally, comments inside a modified statement will be removed. -Furthermore, all source files will be sorted alphabetically. +Rewriting a meson file is not guaranteed to keep the indentation of +the modified functions. Additionally, comments inside a modified +statement will be removed. Furthermore, all source files will be +sorted alphabetically. For instance adding `e.c` to srcs in the following code @@ -150,9 +154,10 @@ srcs = [ ## Using the "script mode" -The "script mode" should be the preferred API for third party programs, since -it offers more flexibility and higher API stability. The "scripts" are stored -in JSON format and executed with `meson rewrite command <JSON file or string>`. +The "script mode" should be the preferred API for third party +programs, since it offers more flexibility and higher API stability. +The "scripts" are stored in JSON format and executed with `meson +rewrite command <JSON file or string>`. The JSON format is defined as follows: @@ -229,13 +234,14 @@ The format for the type `default_options` is defined as follows: } ``` -For operation `delete`, the values of the `options` can be anything (including `null`) +For operation `delete`, the values of the `options` can be anything +(including `null`) ## Extracting information -The rewriter also offers operation `info` for the types `target` and `kwargs`. -When this operation is used, meson will print a JSON dump to stderr, containing -all available information to the rewriter about the build target / function -kwargs in question. +The rewriter also offers operation `info` for the types `target` and +`kwargs`. When this operation is used, meson will print a JSON dump to +stderr, containing all available information to the rewriter about the +build target / function kwargs in question. The output format is currently experimental and may change in the future. diff --git a/docs/markdown/Run-targets.md b/docs/markdown/Run-targets.md index b584bf7..04959ab 100644 --- a/docs/markdown/Run-targets.md +++ b/docs/markdown/Run-targets.md @@ -4,9 +4,13 @@ short-description: Targets to run external commands # Run targets -Sometimes you need to have a target that just runs an external command. As an example you might have a build target that reformats your source code, runs `cppcheck` or something similar. In Meson this is accomplished with a so called *run target*. +Sometimes you need to have a target that just runs an external +command. As an example you might have a build target that reformats +your source code, runs `cppcheck` or something similar. In Meson this +is accomplished with a so called *run target*. -The recommended way of doing this is writing the command(s) you want to run to a script file. Here's an example script. +The recommended way of doing this is writing the command(s) you want +to run to a script file. Here's an example script. ```bash #!/bin/sh @@ -15,11 +19,21 @@ cd "${MESON_SOURCE_ROOT}" inspector_command -o "${MESON_BUILD_ROOT}/inspection_result.txt" ``` -Note the two environment variables `MESON_SOURCE_ROOT` and `MESON_BUILD_ROOT`. These are absolute paths to your project's source and build directories and they are automatically set up by Meson. In addition to these Meson also sets up the variable `MESON_SUBDIR`, which points to the subdirectory where the run command was specified. Most commands don't need to set up this. +Note the two environment variables `MESON_SOURCE_ROOT` and +`MESON_BUILD_ROOT`. These are absolute paths to your project's source +and build directories and they are automatically set up by Meson. In +addition to these Meson also sets up the variable `MESON_SUBDIR`, +which points to the subdirectory where the run command was specified. +Most commands don't need to set up this. -Note how the script starts by cd'ing into the source dir. Meson does not guarantee that the script is run in any specific directory. Whether you need to do the same depends on what your custom target wants to do. +Note how the script starts by cd'ing into the source dir. Meson does +not guarantee that the script is run in any specific directory. +Whether you need to do the same depends on what your custom target +wants to do. -To make this a run target we write it to a script file called `scripts/inspect.sh` and specify it in the top level Meson file like this. +To make this a run target we write it to a script file called +`scripts/inspect.sh` and specify it in the top level Meson file like +this. ```meson run_target('inspector', @@ -32,7 +46,8 @@ Run targets are not run by default. To run it run the following command. $ meson compile inspector ``` -All additional entries in `run_target`'s `command` array are passed unchanged to the inspector script, so you can do things like this: +All additional entries in `run_target`'s `command` array are passed +unchanged to the inspector script, so you can do things like this: ```meson run_target('inspector', diff --git a/docs/markdown/Running-Meson.md b/docs/markdown/Running-Meson.md index eb4da77..84dc6a3 100644 --- a/docs/markdown/Running-Meson.md +++ b/docs/markdown/Running-Meson.md @@ -4,22 +4,25 @@ short-description: Building a project with Meson # Running Meson -There are two different ways of invoking Meson. First, you can run it directly -from the source tree with the command `/path/to/source/meson.py`. Meson may -also be installed in which case the command is simply `meson`. In this manual -we only use the latter format for simplicity. +There are two different ways of invoking Meson. First, you can run it +directly from the source tree with the command +`/path/to/source/meson.py`. Meson may also be installed in which case +the command is simply `meson`. In this manual we only use the latter +format for simplicity. -At the time of writing only a command line version of Meson is available. This -means that Meson must be invoked using the terminal. If you wish to use the -MSVC compiler, you need to run Meson under "Visual Studio command prompt". +At the time of writing only a command line version of Meson is +available. This means that Meson must be invoked using the terminal. +If you wish to use the MSVC compiler, you need to run Meson under +"Visual Studio command prompt". -All available meson commands are listed on the [commands reference page](Commands.md). +All available meson commands are listed on the [commands reference +page](Commands.md). ## Configuring the build directory -Let us assume that we have a source tree that has a Meson build system. This -means that at the topmost directory has a file called `meson.build`. We run the -following commands to get the build started. +Let us assume that we have a source tree that has a Meson build +system. This means that at the topmost directory has a file called +`meson.build`. We run the following commands to get the build started. ```sh cd /path/to/source/root @@ -30,18 +33,18 @@ We invoke Meson with the `setup` command, giving it the location of the build directory. Meson uses [out of source builds](http://voices.canonical.com/jussi.pakkanen/2013/04/16/why-you-should-consider-using-separate-build-directories/). -Hint: The syntax of meson is `meson [command] [arguments] [options]`. The -`setup` command takes a `builddir` and a `srcdir` argument. If no `srcdir` is -given Meson will deduce the `srcdir` based on `pwd` and the location of -`meson.build`. +Hint: The syntax of meson is `meson [command] [arguments] [options]`. +The `setup` command takes a `builddir` and a `srcdir` argument. If no +`srcdir` is given Meson will deduce the `srcdir` based on `pwd` and +the location of `meson.build`. -Meson then loads the build configuration file and writes the corresponding -build backend in the build directory. By default Meson generates a *debug -build*, which turns on basic warnings and debug information and disables -compiler optimizations. +Meson then loads the build configuration file and writes the +corresponding build backend in the build directory. By default Meson +generates a *debug build*, which turns on basic warnings and debug +information and disables compiler optimizations. -Additionally, the invocation can pass options to meson. The list of options is -documented [here](Builtin-options.md). +Additionally, the invocation can pass options to meson. The list of +options is documented [here](Builtin-options.md). You can specify a different type of build with the `--buildtype` command line argument. It can have one of the following values. @@ -53,57 +56,61 @@ argument. It can have one of the following values. | `debugoptimized` | debug info is generated and the code is optimized (on most compilers this means `-g -O2`) | | `release` | full optimization, no debug info | -The build directory is mandatory. The reason for this is that it simplifies the -build process immensely. Meson will not under any circumstances write files -inside the source directory (if it does, it is a bug and should be fixed). This -means that the user does not need to add a bunch of files to their revision -control's ignore list. It also means that you can create arbitrarily many build -directories for any given source tree. +The build directory is mandatory. The reason for this is that it +simplifies the build process immensely. Meson will not under any +circumstances write files inside the source directory (if it does, it +is a bug and should be fixed). This means that the user does not need +to add a bunch of files to their revision control's ignore list. It +also means that you can create arbitrarily many build directories for +any given source tree. -For example, if we wanted to test building the source code with the Clang -compiler instead of the system default, we could just type the following -commands: +For example, if we wanted to test building the source code with the +Clang compiler instead of the system default, we could just type the +following commands: ```sh cd /path/to/source/root CC=clang CXX=clang++ meson setup buildclang ``` -This separation is even more powerful if your code has multiple configuration -options (such as multiple data backends). You can create a separate -subdirectory for each of them. You can also have build directories for -optimized builds, code coverage, static analysis and so on. They are all neatly -separated and use the same source tree. Changing between different -configurations is just a question of changing to the corresponding directory. +This separation is even more powerful if your code has multiple +configuration options (such as multiple data backends). You can create +a separate subdirectory for each of them. You can also have build +directories for optimized builds, code coverage, static analysis and +so on. They are all neatly separated and use the same source tree. +Changing between different configurations is just a question of +changing to the corresponding directory. -Unless otherwise mentioned, all following command line invocations are meant to -be run in the source directory. +Unless otherwise mentioned, all following command line invocations are +meant to be run in the source directory. -By default Meson will use the Ninja backend to build your project. If you wish -to use any of the other backends, you need to pass the corresponding argument -during configuration time. As an example, here is how you would use Meson to -generate a Visual studio solution. +By default Meson will use the Ninja backend to build your project. If +you wish to use any of the other backends, you need to pass the +corresponding argument during configuration time. As an example, here +is how you would use Meson to generate a Visual studio solution. ```sh meson setup <build dir> --backend=vs ``` -You can then open the generated solution with Visual Studio and compile it in -the usual way. A list of backends can be obtained with `meson setup --help`. +You can then open the generated solution with Visual Studio and +compile it in the usual way. A list of backends can be obtained with +`meson setup --help`. ## Environment variables -Sometimes you want to add extra compiler flags, this can be done by passing -them in environment variables when calling meson. See [the reference -tables](Reference-tables.md#compiler-and-linker-flag-environment-variables) for -a list of all the environment variables. Be aware however these environment -variables are only used for the native compiler and will not affect the -compiler used for cross-compiling, where the flags specified in the cross file -will be used. +Sometimes you want to add extra compiler flags, this can be done by +passing them in environment variables when calling meson. See [the +reference +tables](Reference-tables.md#compiler-and-linker-flag-environment-variables) +for a list of all the environment variables. Be aware however these +environment variables are only used for the native compiler and will +not affect the compiler used for cross-compiling, where the flags +specified in the cross file will be used. -Furthermore it is possible to stop meson from adding flags itself by using the -`--buildtype=plain` option, in this case you must provide the full compiler and -linker arguments needed. +Furthermore it is possible to stop meson from adding flags itself by +using the `--buildtype=plain` option, in this case you must provide +the full compiler and linker arguments needed. ## Building from the source @@ -117,31 +124,34 @@ See [`meson compile` description](Commands.md#compile) for more info. ### Building directly with ninja -By default Meson uses the [Ninja build system](https://ninja-build.org/) to -actually build the code. To start the build, simply type the following command. +By default Meson uses the [Ninja build +system](https://ninja-build.org/) to actually build the code. To start +the build, simply type the following command. ```sh ninja -C builddir ``` -The main usability difference between Ninja and Make is that Ninja will -automatically detect the number of CPUs in your computer and parallelize itself -accordingly. You can override the amount of parallel processes used with the -command line argument `-j <num processes>`. - -It should be noted that after the initial configure step `ninja` is the only -command you ever need to type to compile. No matter how you alter your source -tree (short of moving it to a completely new location), Meson will detect the -changes and regenerate itself accordingly. This is especially handy if you have -multiple build directories. Often one of them is used for development (the -"debug" build) and others only every now and then (such as a "static analysis" -build). Any configuration can be built just by `cd`'ing to the corresponding -directory and running Ninja. +The main usability difference between Ninja and Make is that Ninja +will automatically detect the number of CPUs in your computer and +parallelize itself accordingly. You can override the amount of +parallel processes used with the command line argument `-j <num +processes>`. + +It should be noted that after the initial configure step `ninja` is +the only command you ever need to type to compile. No matter how you +alter your source tree (short of moving it to a completely new +location), Meson will detect the changes and regenerate itself +accordingly. This is especially handy if you have multiple build +directories. Often one of them is used for development (the "debug" +build) and others only every now and then (such as a "static analysis" +build). Any configuration can be built just by `cd`'ing to the +corresponding directory and running Ninja. ## Running tests -Meson provides native support for running tests. The command to do that is -simple. +Meson provides native support for running tests. The command to do +that is simple. ```sh meson test -C builddir @@ -149,8 +159,8 @@ meson test -C builddir See [`meson test` description](Commands.md#test) for more info. -Meson does not force the use of any particular testing framework. You are free -to use GTest, Boost Test, Check or even custom executables. +Meson does not force the use of any particular testing framework. You +are free to use GTest, Boost Test, Check or even custom executables. Note: it can be also invoked directly with ninja with the following command: ```sh @@ -171,28 +181,30 @@ Note that Meson will only install build targets explicitly tagged as installable, as detailed in the [installing targets documentation](Installing.md). -By default Meson installs to `/usr/local`. This can be changed by passing the -command line argument `--prefix /your/prefix` to Meson during configure time. -Meson also supports the `DESTDIR` variable used in e.g. building packages. It -is used like this: +By default Meson installs to `/usr/local`. This can be changed by +passing the command line argument `--prefix /your/prefix` to Meson +during configure time. Meson also supports the `DESTDIR` variable used +in e.g. building packages. It is used like this: ```sh DESTDIR=/path/to/staging meson install -C builddir ``` -Note: it can be also invoked directly with ninja with the following command: +Note: it can be also invoked directly with ninja with the following +command: + ```sh ninja -C builddir install ``` ## Command line help -Meson has a standard command line help feature. It can be accessed with the -following command. +Meson has a standard command line help feature. It can be accessed +with the following command. meson --help ## Exit status -Meson exits with status 0 if successful, 1 for problems with the command line -or meson.build file, and 2 for internal errors. +Meson exits with status 0 if successful, 1 for problems with the +command line or meson.build file, and 2 for internal errors. diff --git a/docs/markdown/Rust-module.md b/docs/markdown/Rust-module.md index 0fdba94..dbe24ff 100644 --- a/docs/markdown/Rust-module.md +++ b/docs/markdown/Rust-module.md @@ -12,20 +12,20 @@ authors: **Note** Unstable modules make no backwards compatible API guarantees. -The rust module provides helper to integrate rust code into meson. The goal -is to make using rust in meson more pleasant, while still remaining mesonic, -this means that it attempts to make rust work more like meson, rather than -meson work more like rust. +The rust module provides helper to integrate rust code into meson. The +goal is to make using rust in meson more pleasant, while still +remaining mesonic, this means that it attempts to make rust work more +like meson, rather than meson work more like rust. ## Functions ### test(name: string, target: library | executable, dependencies: []Dependency) -This function creates a new rust unittest target from an existing rust based -target, which may be a library or executable. It does this by copying the -sources and arguments passed to the original target and adding the `--test` -argument to the compilation, then creates a new test target which calls that -executable, using the rust test protocol. +This function creates a new rust unittest target from an existing rust +based target, which may be a library or executable. It does this by +copying the sources and arguments passed to the original target and +adding the `--test` argument to the compilation, then creates a new +test target which calls that executable, using the rust test protocol. This accepts all of the keyword arguments as the [`test`](Reference-manual.md#test) function except `protocol`, it will set diff --git a/docs/markdown/Shipping-prebuilt-binaries-as-wraps.md b/docs/markdown/Shipping-prebuilt-binaries-as-wraps.md index bac19f9..73cf48b 100644 --- a/docs/markdown/Shipping-prebuilt-binaries-as-wraps.md +++ b/docs/markdown/Shipping-prebuilt-binaries-as-wraps.md @@ -1,8 +1,17 @@ # Shipping prebuilt binaries as wraps -A common dependency case, especially on Windows, is the need to provide dependencies as prebuilt binaries rather than Meson projects that you build from scratch. Common reasons include not having access to source code, not having the time and effort to rewrite a legacy system's build definitions to Meson or just the fact that compiling the dependency projects takes too long. +A common dependency case, especially on Windows, is the need to +provide dependencies as prebuilt binaries rather than Meson projects +that you build from scratch. Common reasons include not having access +to source code, not having the time and effort to rewrite a legacy +system's build definitions to Meson or just the fact that compiling +the dependency projects takes too long. -Packaging a project is straightforward. As an example let's look at a case where the project consists of one static library called `bob` and some headers. To create a binary dependency project we put the static library at the top level and headers in a subdirectory called `include`. The Meson build definition would look like the following. +Packaging a project is straightforward. As an example let's look at a +case where the project consists of one static library called `bob` and +some headers. To create a binary dependency project we put the static +library at the top level and headers in a subdirectory called +`include`. The Meson build definition would look like the following. ```meson project('binary dep', 'c') @@ -21,4 +30,7 @@ bob_dep = subproject('bob').get_variable('bin_dep') executable('prog', 'prog.c', dependencies : bob_dep) ``` -Note that often libraries compiled with different compilers (or even compiler flags) might not be compatible. If you do this, then you are responsible for verifying that your libraries are compatible, Meson will not check things for you. +Note that often libraries compiled with different compilers (or even +compiler flags) might not be compatible. If you do this, then you are +responsible for verifying that your libraries are compatible, Meson +will not check things for you. diff --git a/docs/markdown/Simd-module.md b/docs/markdown/Simd-module.md index 0fd1dda..29f3e95 100644 --- a/docs/markdown/Simd-module.md +++ b/docs/markdown/Simd-module.md @@ -3,14 +3,15 @@ This module provides helper functionality to build code with SIMD instructions. Available since 0.42.0. -**Note**:Â this module is unstable. It is only provided as a technology preview. -Its API may change in arbitrary ways between releases or it might be removed -from Meson altogether. +**Note**: this module is unstable. It is only provided as a technology +preview. Its API may change in arbitrary ways between releases or it +might be removed from Meson altogether. ## Usage -This module is designed for the use case where you have an algorithm with one -or more SIMD implementation and you choose which one to use at runtime. +This module is designed for the use case where you have an algorithm +with one or more SIMD implementation and you choose which one to use +at runtime. The module provides one method, `check`, which is used like this: @@ -27,20 +28,21 @@ The module provides one method, `check`, which is used like this: neon : 'simd_neon.c', compiler : cc) -Here the individual files contain the accelerated versions of the functions -in question. The `compiler` keyword argument takes the compiler you are -going to use to compile them. The function returns an array with two values. -The first value is a bunch of libraries that contain the compiled code. Any -SIMD code that the compiler can't compile (for example, Neon instructions on -an x86 machine) are ignored. You should pass this value to the desired target -using `link_with`. The second value is a `configuration_data` object that -contains true for all the values that were supported. For example if the -compiler did support sse2 instructions, then the object would have `HAVE_SSE2` -set to 1. +Here the individual files contain the accelerated versions of the +functions in question. The `compiler` keyword argument takes the +compiler you are going to use to compile them. The function returns an +array with two values. The first value is a bunch of libraries that +contain the compiled code. Any SIMD code that the compiler can't +compile (for example, Neon instructions on an x86 machine) are +ignored. You should pass this value to the desired target using +`link_with`. The second value is a `configuration_data` object that +contains true for all the values that were supported. For example if +the compiler did support sse2 instructions, then the object would have +`HAVE_SSE2` set to 1. Generating code to detect the proper instruction set at runtime is -straightforward. First you create a header with the configuration object and -then a chooser function that looks like this: +straightforward. First you create a header with the configuration +object and then a chooser function that looks like this: void (*fptr)(type_of_function_here) = NULL; @@ -61,9 +63,9 @@ then a chooser function that looks like this: fptr = default_function; } -Each source file provides two functions, the `xxx_available` function to query -whether the CPU currently in use supports the instruction set and -`xxx_accelerated_function` that is the corresponding accelerated +Each source file provides two functions, the `xxx_available` function +to query whether the CPU currently in use supports the instruction set +and `xxx_accelerated_function` that is the corresponding accelerated implementation. At the end of this function the function pointer points to the fastest diff --git a/docs/markdown/Simple-comparison.md b/docs/markdown/Simple-comparison.md index 5ac90e4..a8ce17b 100644 --- a/docs/markdown/Simple-comparison.md +++ b/docs/markdown/Simple-comparison.md @@ -1,6 +1,7 @@ # A simple comparison -In this experiment we generated one thousand C files with contents that looked like this. +In this experiment we generated one thousand C files with contents +that looked like this. ```c #include<stdio.h> @@ -9,34 +10,74 @@ In this experiment we generated one thousand C files with contents that looked l int func23() { return 0; } ``` -The function number was different in each file. In addition there was a main C file that just called each function in turn. We then generated build system files for *Meson*, *CMake*, *SCons*, *Premake* and *Autotools* that compiled these files into a single executable. +The function number was different in each file. In addition there was +a main C file that just called each function in turn. We then +generated build system files for *Meson*, *CMake*, *SCons*, *Premake* +and *Autotools* that compiled these files into a single executable. -With this we measured three different things. The first is configuration time, that is, the time the build system takes to generate necessary build files. This is usually called the *configure step*. The time was measured in seconds. +With this we measured three different things. The first is +configuration time, that is, the time the build system takes to +generate necessary build files. This is usually called the *configure +step*. The time was measured in seconds. -The second thing to measure was the build time. This should be limited by the compiler and in the optimal case should be the same for every build system. Four parallel processes were used in this test. +The second thing to measure was the build time. This should be limited +by the compiler and in the optimal case should be the same for every +build system. Four parallel processes were used in this test. -The third thing we measured was the empty build time. This measures how much time the build system takes to check the states of all source files because if any of them could potentially cause a rebuild. +The third thing we measured was the empty build time. This measures +how much time the build system takes to check the states of all source +files because if any of them could potentially cause a rebuild. -Since CMake has two different backends, Make and Ninja, we ran the tests on both of them. All tests were run on a 2011 era Macbook Pro running Ubuntu 13/04. The tests were run multiple times and we always took the fastest time. +Since CMake has two different backends, Make and Ninja, we ran the +tests on both of them. All tests were run on a 2011 era Macbook Pro +running Ubuntu 13/04. The tests were run multiple times and we always +took the fastest time. Here are the results for configuration time.  -The reason SCons got zero seconds on this test is because you cannot separate configure and build steps. They run as one unit. Autotools is the clear loser of this test as it is over an order of magnitude slower than the second slowest one. This configuration time includes both autogen and configure. All other systems take less than one second to do this setup, which is fast enough for a human being to interpret as instantaneous. +The reason SCons got zero seconds on this test is because you cannot +separate configure and build steps. They run as one unit. Autotools is +the clear loser of this test as it is over an order of magnitude +slower than the second slowest one. This configuration time includes +both autogen and configure. All other systems take less than one +second to do this setup, which is fast enough for a human being to +interpret as instantaneous.  -Build times are a bit more even. SCons is the slowest, being almost ten seconds slower than the second slowest. Some of it is work from the configure step but it still has the worst performance. Premake is the fastest Make-based build system narrowly beating out Autotools. Both Ninja-based build systems are faster than all non-Ninja ones with Meson being slightly faster. In practice the difference is minimal. The advantages of Ninja can be seen by comparing CMake's times when using Make or Ninja. It is possible to shave off 3.5 seconds (over 20%) of the total build time just by changing the backend. The project's CMake configuration files don't need any changes. +Build times are a bit more even. SCons is the slowest, being almost +ten seconds slower than the second slowest. Some of it is work from +the configure step but it still has the worst performance. Premake is +the fastest Make-based build system narrowly beating out Autotools. +Both Ninja-based build systems are faster than all non-Ninja ones with +Meson being slightly faster. In practice the difference is minimal. +The advantages of Ninja can be seen by comparing CMake's times when +using Make or Ninja. It is possible to shave off 3.5 seconds (over +20%) of the total build time just by changing the backend. The +project's CMake configuration files don't need any changes.  -Empty build times reflect the performance of regular build times. SCons is again the slowest taking over three seconds compared to Meson, which takes only 0.03 seconds, a difference of two orders of magnitude. Even Autotools, the fastest Make-based system, is almost one order of magnitude slower. Ninja holds the top spots just like in the previous test. +Empty build times reflect the performance of regular build times. +SCons is again the slowest taking over three seconds compared to +Meson, which takes only 0.03 seconds, a difference of two orders of +magnitude. Even Autotools, the fastest Make-based system, is almost +one order of magnitude slower. Ninja holds the top spots just like in +the previous test. Conclusions ----- -Build system performance matters. Even with this extremely simple example we can find differences between various popular build systems. As the project size increases, these differences grow even larger. (The author has witnessed no-op build times of 30 seconds for Make versus less than one second for Ninja when compiling the Clang compiler.) Keeping incremental build times low is one of the major keys of programmer productivity as it allows developers to iterate faster and stay in the creative zone. +Build system performance matters. Even with this extremely simple +example we can find differences between various popular build systems. +As the project size increases, these differences grow even larger. +(The author has witnessed no-op build times of 30 seconds for Make +versus less than one second for Ninja when compiling the Clang +compiler.) Keeping incremental build times low is one of the major +keys of programmer productivity as it allows developers to iterate +faster and stay in the creative zone. Original scripts ----- diff --git a/docs/markdown/SourceSet-module.md b/docs/markdown/SourceSet-module.md index 4b34ff7..af31570 100644 --- a/docs/markdown/SourceSet-module.md +++ b/docs/markdown/SourceSet-module.md @@ -8,10 +8,10 @@ authors: # Source set module -This module provides support for building many targets against a single set -of files; the choice of which files to include in each target depends on the -contents of a dictionary or a `configuration_data` object. The module can -be loaded with: +This module provides support for building many targets against a +single set of files; the choice of which files to include in each +target depends on the contents of a dictionary or a +`configuration_data` object. The module can be loaded with: ``` meson ssmod = import('sourceset') @@ -51,9 +51,9 @@ executable('exe', sources: sources, dependencies: dependencies()) ``` Sourcesets can be used with a single invocation of the `apply` method, -similar to the example above, but the module is especially useful -when multiple executables are generated by applying the same rules to -many different configurations. +similar to the example above, but the module is especially useful when +multiple executables are generated by applying the same rules to many +different configurations. *Added 0.51.0* @@ -71,9 +71,9 @@ Create and return a new source set object. ## `source_set` object -The `source_set` object provides methods to add files to a source set and -to query it. The source set becomes immutable after any method but `add` -is called. +The `source_set` object provides methods to add files to a source set +and to query it. The source set becomes immutable after any method but +`add` is called. ### Methods @@ -86,27 +86,31 @@ source_set.add([when: varnames_and_deps], source_set.add(sources_and_deps) ``` -Add a *rule* to a source set. A rule determines the conditions under which -some source files or dependency objects are included in a build configuration. -All source files must be present in the source tree or they can be created -in the build tree via `configure_file`, `custom_target` or `generator`. +Add a *rule* to a source set. A rule determines the conditions under +which some source files or dependency objects are included in a build +configuration. All source files must be present in the source tree or +they can be created in the build tree via `configure_file`, +`custom_target` or `generator`. `varnames_and_deps` is a list of conditions for the rule, which can be -either strings or dependency objects (a dependency object is anything that -has a `found()` method). If *all* the strings evaluate to true and all -dependencies are found, the rule will evaluate to true; `apply()` -will then include the contents of the `if_true` keyword argument in its -result. Otherwise, that is if any of the strings in the positional - arguments evaluate to false or any dependency is not found, `apply()` -will instead use the contents of the `if_false` keyword argument. - -Dependencies can also appear in `sources_and_deps`. In this case, a -missing dependency will simply be ignored and will *not* disable the rule, -similar to how the `dependencies` keyword argument works in build targets. - -**Note**: It is generally better to avoid mixing source sets and disablers. -This is because disablers will cause the rule to be dropped altogether, -and the `list_of_alt_sources` would not be taken into account anymore. +either strings or dependency objects (a dependency object is anything +that has a `found()` method). If *all* the strings evaluate to true +and all dependencies are found, the rule will evaluate to true; +`apply()` will then include the contents of the `if_true` keyword +argument in its result. Otherwise, that is if any of the strings in +the positional arguments evaluate to false or any dependency is not +found, `apply()` will instead use the contents of the `if_false` +keyword argument. + +Dependencies can also appear in `sources_and_deps`. In this case, a +missing dependency will simply be ignored and will *not* disable the +rule, similar to how the `dependencies` keyword argument works in +build targets. + +**Note**: It is generally better to avoid mixing source sets and +disablers. This is because disablers will cause the rule to be dropped +altogether, and the `list_of_alt_sources` would not be taken into +account anymore. #### `add_all()` @@ -118,9 +122,9 @@ source_set.add_all(source_set1, source_set2, ...) Add one or more source sets to another. -For each source set listed in the arguments, `apply()` will -consider their rules only if the conditions in `varnames_and_deps` are -evaluated positively. For example, the following: +For each source set listed in the arguments, `apply()` will consider +their rules only if the conditions in `varnames_and_deps` are +evaluated positively. For example, the following: ``` meson sources_b = ssmod.source_set() @@ -144,7 +148,7 @@ list source_set.all_sources(...) Returns a list of all sources that were placed in the source set using `add` (including nested source sets) and that do not have a not-found -dependency. If a rule has a not-found dependency, only the `if_false` +dependency. If a rule has a not-found dependency, only the `if_false` sources are included (if any). **Returns**: a list of file objects @@ -166,16 +170,17 @@ using `add` (including nested source sets) and that were found. source_files source_set.apply(conf_data[, strict: false]) ``` -Match the source set against a dictionary or a `configuration_data` object -and return a *source configuration* object. A source configuration object -allows you to retrieve the sources and dependencies for a specific configuration. +Match the source set against a dictionary or a `configuration_data` +object and return a *source configuration* object. A source +configuration object allows you to retrieve the sources and +dependencies for a specific configuration. By default, all the variables that were specified in the rules have to -be present in `conf_data`. However, in some cases the convention is +be present in `conf_data`. However, in some cases the convention is that `false` configuration symbols are absent in `conf_data`; this is -the case for example when the configuration was loaded from a Kconfig file. -In that case you can specify the `strict: false` keyword argument, which -will treat absent variables as false. +the case for example when the configuration was loaded from a Kconfig +file. In that case you can specify the `strict: false` keyword +argument, which will treat absent variables as false. **Returns**: a [source configuration][`source_configuration` object] diff --git a/docs/markdown/Style-guide.md b/docs/markdown/Style-guide.md index 240a675..f204a9a 100644 --- a/docs/markdown/Style-guide.md +++ b/docs/markdown/Style-guide.md @@ -22,18 +22,19 @@ Let say you would like to refer to your executable so something like `my_exe`. ## Dependency usage -The `dependency` function is the recommended way to handle dependencies. If your wrap files -have the necessary `[provide]` entries, everything will work automatically both when -compiling your own and when using system dependencies. +The `dependency` function is the recommended way to handle +dependencies. If your wrap files have the necessary `[provide]` +entries, everything will work automatically both when compiling your +own and when using system dependencies. You should only need `subproject` when you need to extract non dependencies/programs. ## Naming options There are two ways of naming project options. As an example for -booleans the first one is `foo` and the second one is -`enable-foo`. The former style is recommended, because in Meson -options have strong type, rather than being just strings. +booleans the first one is `foo` and the second one is `enable-foo`. +The former style is recommended, because in Meson options have strong +type, rather than being just strings. You should try to name options the same as is common in other projects. This is especially important for yielding options, because @@ -54,10 +55,11 @@ platform are isolated in one place. # Sorting source paths -The source file arrays should all be sorted. This makes it easier to spot -errors and often reduces merge conflicts. Furthermore, the paths should be -sorted with a natural sorting algorithm, so that numbers are sorted in an -intuitive way (`1, 2, 3, 10, 20` instead of `1, 10, 2, 20, 3`). +The source file arrays should all be sorted. This makes it easier to +spot errors and often reduces merge conflicts. Furthermore, the paths +should be sorted with a natural sorting algorithm, so that numbers are +sorted in an intuitive way (`1, 2, 3, 10, 20` instead of `1, 10, 2, +20, 3`). Numbers should also be sorted before characters (`a111` before `ab0`). Furthermore, strings should be sorted case insensitive. diff --git a/docs/markdown/Subprojects.md b/docs/markdown/Subprojects.md index 9afbe1b..98c9b1f 100644 --- a/docs/markdown/Subprojects.md +++ b/docs/markdown/Subprojects.md @@ -25,8 +25,9 @@ supported but not guaranteed to work. ## A subproject example -Usually dependencies consist of some header files plus a library to link against. -To declare this internal dependency use `declare_dependency` function. +Usually dependencies consist of some header files plus a library to +link against. To declare this internal dependency use +`declare_dependency` function. As an example, suppose we have a simple project that provides a shared library. Its `meson.build` would look like this. @@ -46,12 +47,14 @@ libsimple_dep = declare_dependency(include_directories : inc, ### Naming convention for dependency variables -Ideally the dependency variable name should be of `<project_name>_dep` form. -This way one can just use it without even looking inside build definitions of that subproject. +Ideally the dependency variable name should be of `<project_name>_dep` +form. This way one can just use it without even looking inside build +definitions of that subproject. -In cases where there are multiple dependencies need to be declared, the default one -should be named as `<project_name>_dep` (e.g. `gtest_dep`), and others can have -`<project_name>_<other>_<name>_dep` form (e.g. `gtest_main_dep` - gtest with main function). +In cases where there are multiple dependencies need to be declared, +the default one should be named as `<project_name>_dep` (e.g. +`gtest_dep`), and others can have `<project_name>_<other>_<name>_dep` +form (e.g. `gtest_main_dep` - gtest with main function). There may be exceptions to these rules where common sense should be applied. @@ -59,10 +62,11 @@ There may be exceptions to these rules where common sense should be applied. *New in 0.54.0* -In some cases a project may define special variables via pkg-config or cmake -that a caller needs to know about. Meson provides a `dependency.get_variable` -method to hide what kind of dependency is provided, and this is available to -subprojects as well. Use the `variables` keyword to add a dict of strings: +In some cases a project may define special variables via pkg-config or +cmake that a caller needs to know about. Meson provides a +`dependency.get_variable` method to hide what kind of dependency is +provided, and this is available to subprojects as well. Use the +`variables` keyword to add a dict of strings: ```meson my_dep = declare_dependency(..., variables : {'var': 'value', 'number': '3'}) @@ -74,8 +78,8 @@ Which another project can access via: var = my_dep.get_variable(internal : 'var', cmake : 'CMAKE_VAR') ``` -The values of the dict must be strings, as pkg-config and cmake will return -variables as strings. +The values of the dict must be strings, as pkg-config and cmake will +return variables as strings. ### Build options in subproject @@ -89,8 +93,8 @@ as a subproject, use the `is_subproject` function. ## Using a subproject -All subprojects must be inside `subprojects` directory. -The `subprojects` directory must be at the top level of your project. +All subprojects must be inside `subprojects` directory. The +`subprojects` directory must be at the top level of your project. Subproject declaration must be in your top level `meson.build`. ### A simple example @@ -171,12 +175,13 @@ executable('my_project', install : true) ``` -With this setup when libsimple is provided by the system, we use it. When -that is not the case we use the embedded version (the one from subprojects). +With this setup when libsimple is provided by the system, we use it. +When that is not the case we use the embedded version (the one from +subprojects). -Note that `libsimple_dep` can point to an external or an internal dependency but -you don't have to worry about their differences. Meson will take care -of the details for you. +Note that `libsimple_dep` can point to an external or an internal +dependency but you don't have to worry about their differences. Meson +will take care of the details for you. ### Subprojects depending on other subprojects @@ -269,28 +274,29 @@ the following command-line options: *Since 0.49.0* -`meson subprojects` has various subcommands to manage all subprojects. If the -subcommand fails on any subproject the execution continues with other subprojects. -All subcommands accept `--sourcedir` argument pointing to the root source dir -of the main project. +`meson subprojects` has various subcommands to manage all subprojects. +If the subcommand fails on any subproject the execution continues with +other subprojects. All subcommands accept `--sourcedir` argument +pointing to the root source dir of the main project. -*Since 0.56.0* all subcommands accept `--types <file|git|hg|svn>` argument to -run the subcommands only on subprojects of the given types. Multiple types can -be set as comma separated list e.g. `--types git,file`. +*Since 0.56.0* all subcommands accept `--types <file|git|hg|svn>` +argument to run the subcommands only on subprojects of the given +types. Multiple types can be set as comma separated list e.g. `--types +git,file`. -*Since 0.56.0* If the subcommand fails on any subproject an error code is returned -at the end instead of retuning success. +*Since 0.56.0* If the subcommand fails on any subproject an error code +is returned at the end instead of retuning success. ### Download subprojects *Since 0.49.0* -Meson will automatically download needed subprojects during configure, unless -**--wrap-mode=nodownload** option is passed. It is sometimes preferable to -download all subprojects in advance, so the meson configure can be performed -offline. The command-line `meson subprojects download` can be used for that, it -will download all missing subprojects, but will not update already fetched -subprojects. +Meson will automatically download needed subprojects during configure, +unless **--wrap-mode=nodownload** option is passed. It is sometimes +preferable to download all subprojects in advance, so the meson +configure can be performed offline. The command-line `meson +subprojects download` can be used for that, it will download all +missing subprojects, but will not update already fetched subprojects. ### Update subprojects @@ -330,11 +336,11 @@ To pull latest version of all your subprojects at once, just run the command: *Since 0.49.0* -The command-line `meson subprojects checkout <branch_name>` will checkout a -branch, or create one with `-b` argument, in every git subprojects. This is -useful when starting local changes across multiple subprojects. It is still your -responsibility to commit and push in each repository where you made local -changes. +The command-line `meson subprojects checkout <branch_name>` will +checkout a branch, or create one with `-b` argument, in every git +subprojects. This is useful when starting local changes across +multiple subprojects. It is still your responsibility to commit and +push in each repository where you made local changes. To come back to the revision set in wrap file (i.e. master), just run `meson subprojects checkout` with no branch name. @@ -346,9 +352,9 @@ To come back to the revision set in wrap file (i.e. master), just run *Since 0.51.0* The command-line `meson subprojects foreach <command> [...]` will -execute a command in each subproject directory. For example this can be useful -to check the status of subprojects (e.g. with `git status` or `git diff`) before -performing other actions on them. +execute a command in each subproject directory. For example this can +be useful to check the status of subprojects (e.g. with `git status` +or `git diff`) before performing other actions on them. ## Why must all subprojects be inside a single directory? diff --git a/docs/markdown/Syntax.md b/docs/markdown/Syntax.md index 4f17ac8..30682bd 100644 --- a/docs/markdown/Syntax.md +++ b/docs/markdown/Syntax.md @@ -18,8 +18,9 @@ have multiple statements on one line as in e.g. *C*. Function and method calls' argument lists can be split over multiple lines. Meson will autodetect this case and do the right thing. -In other cases, *(added 0.50)* you can get multi-line statements by ending the -line with a `\`. Apart from line ending whitespace has no syntactic meaning. +In other cases, *(added 0.50)* you can get multi-line statements by +ending the line with a `\`. Apart from line ending whitespace has no +syntactic meaning. ## Variables @@ -365,10 +366,11 @@ The following methods are defined for all arrays: ## Dictionaries -Dictionaries are delimited by curly braces. A dictionary can contain an -arbitrary number of key: value pairs. Keys are required to be strings, but values can -be objects of any type. Prior to *0.53.0* keys were required to be literal -strings, i.e., you could not use a variable containing a string value as a key. +Dictionaries are delimited by curly braces. A dictionary can contain +an arbitrary number of key: value pairs. Keys are required to be +strings, but values can be objects of any type. Prior to *0.53.0* keys +were required to be literal strings, i.e., you could not use a +variable containing a string value as a key. ```meson my_dict = {'foo': 42, 'bar': 'baz'} @@ -403,8 +405,8 @@ if 'foo' not in my_dict endif ``` -*Since 0.53.0* Keys can be any expression evaluating to a string value, not limited -to string literals any more. +*Since 0.53.0* Keys can be any expression evaluating to a string +value, not limited to string literals any more. ```meson d = {'a' + 'b' : 42} @@ -616,24 +618,25 @@ subdir('tests') ## User-defined functions and methods -Meson does not currently support user-defined functions or -methods. The addition of user-defined functions would make Meson +Meson does not currently support user-defined functions or methods. +The addition of user-defined functions would make Meson Turing-complete which would make it harder to reason about and more difficult to integrate with tools like IDEs. More details about this are [in the -FAQ](FAQ.md#why-is-meson-not-just-a-python-module-so-i-could-code-my-build-setup-in-python). If -because of this limitation you find yourself copying and pasting code -a lot you may be able to use a [`foreach` loop +FAQ](FAQ.md#why-is-meson-not-just-a-python-module-so-i-could-code-my-build-setup-in-python). +If because of this limitation you find yourself copying and pasting +code a lot you may be able to use a [`foreach` loop instead](#foreach-statements). ## Stability Promises Meson is very actively developed and continuously improved. There is a -possibility that future enhancements to the Meson build system will require -changes to the syntax. Such changes might be the addition of new reserved -keywords, changing the meaning of existing keywords or additions around the -basic building blocks like statements and fundamental types. It is planned -to stabilize the syntax with the 1.0 release. +possibility that future enhancements to the Meson build system will +require changes to the syntax. Such changes might be the addition of +new reserved keywords, changing the meaning of existing keywords or +additions around the basic building blocks like statements and +fundamental types. It is planned to stabilize the syntax with the 1.0 +release. ## Grammar diff --git a/docs/markdown/Threads.md b/docs/markdown/Threads.md index 1bf9f83..b12d4c5 100644 --- a/docs/markdown/Threads.md +++ b/docs/markdown/Threads.md @@ -4,7 +4,9 @@ short-description: Enabling thread support # Threads -Meson has a very simple notational shorthand for enabling thread support on your build targets. First you obtain the thread dependency object like this: +Meson has a very simple notational shorthand for enabling thread +support on your build targets. First you obtain the thread dependency +object like this: ```meson thread_dep = dependency('threads') diff --git a/docs/markdown/Tutorial.md b/docs/markdown/Tutorial.md index 85e345a..c1942c2 100644 --- a/docs/markdown/Tutorial.md +++ b/docs/markdown/Tutorial.md @@ -48,8 +48,9 @@ project('tutorial', 'c') executable('demo', 'main.c') ``` -That is all. Note that unlike Autotools you [do not need to add any source -headers to the list of sources](FAQ.md#do-i-need-to-add-my-headers-to-the-sources-list-like-in-autotools). +That is all. Note that unlike Autotools you [do not need to add any +source headers to the list of +sources](FAQ.md#do-i-need-to-add-my-headers-to-the-sources-list-like-in-autotools). We are now ready to build our application. First we need to initialize the build by going into the source directory and issuing @@ -117,7 +118,7 @@ use GTK+. The new version looks like this. #include <gtk/gtk.h> // -// Should provided the active view for a GTK application +// Should provided the active view for a GTK application // static void activate(GtkApplication* app, gpointer user_data) { @@ -177,10 +178,10 @@ $ meson compile ``` Once you have set up your build directory the first time, you don't -ever need to run the `meson` command again. You always just run -`meson compile`. Meson will automatically detect when you have done changes to -build definitions and will take care of everything so users don't have -to care. In this case the following output is produced. +ever need to run the `meson` command again. You always just run `meson +compile`. Meson will automatically detect when you have done changes +to build definitions and will take care of everything so users don't +have to care. In this case the following output is produced. [1/1] Regenerating build files The Meson build system diff --git a/docs/markdown/Unit-tests.md b/docs/markdown/Unit-tests.md index 60fcad2..92014bb 100644 --- a/docs/markdown/Unit-tests.md +++ b/docs/markdown/Unit-tests.md @@ -4,8 +4,8 @@ short-description: Meson's own unit-test system # Unit tests -Meson comes with a fully functional unit test system. To use it simply build -an executable and then use it in a test. +Meson comes with a fully functional unit test system. To use it simply +build an executable and then use it in a test. ```meson e = executable('prog', 'testprog.c') @@ -40,17 +40,19 @@ can be disabled as discussed in [test()](Reference-manual.md#test). ## Coverage -If you enable coverage measurements by giving Meson the command line flag -`-Db_coverage=true`, you can generate coverage reports after running the -tests (running the tests is required to gather the list of functions that get -called). Meson will autodetect what coverage generator tools you have -installed and will generate the corresponding targets. These targets are -`coverage-xml` and `coverage-text` which are both provided by -[Gcovr](http://gcovr.com) (version 3.3 or higher) and `coverage-html`, which -requires [Lcov](https://ltp.sourceforge.io/coverage/lcov.php) and -[GenHTML](https://linux.die.net/man/1/genhtml) or [Gcovr](http://gcovr.com). -As a convenience, a high-level `coverage` target is also generated which will -produce all 3 coverage report types, if possible. +If you enable coverage measurements by giving Meson the command line +flag `-Db_coverage=true`, you can generate coverage reports after +running the tests (running the tests is required to gather the list of +functions that get called). Meson will autodetect what coverage +generator tools you have installed and will generate the corresponding +targets. These targets are `coverage-xml` and `coverage-text` which +are both provided by [Gcovr](http://gcovr.com) (version 3.3 or higher) +and `coverage-html`, which requires +[Lcov](https://ltp.sourceforge.io/coverage/lcov.php) and +[GenHTML](https://linux.die.net/man/1/genhtml) or +[Gcovr](http://gcovr.com). As a convenience, a high-level `coverage` +target is also generated which will produce all 3 coverage report +types, if possible. The output of these commands is written to the log directory `meson-logs` in your build directory. @@ -58,21 +60,23 @@ your build directory. ## Parallelism To reduce test times, Meson will by default run multiple unit tests in -parallel. It is common to have some tests which can not be run in parallel -because they require unique hold on some resource such as a file or a D-Bus -name. You have to specify these tests with a keyword argument. +parallel. It is common to have some tests which can not be run in +parallel because they require unique hold on some resource such as a +file or a D-Bus name. You have to specify these tests with a keyword +argument. ```meson test('unique test', t, is_parallel : false) ``` -Meson will then make sure that no other unit test is running at the same -time. Non-parallel tests take longer to run so it is recommended that you -write your unit tests to be parallel executable whenever possible. +Meson will then make sure that no other unit test is running at the +same time. Non-parallel tests take longer to run so it is recommended +that you write your unit tests to be parallel executable whenever +possible. -By default Meson uses as many concurrent processes as there are cores on the -test machine. You can override this with the environment variable -`MESON_TESTTHREADS` like this. +By default Meson uses as many concurrent processes as there are cores +on the test machine. You can override this with the environment +variable `MESON_TESTTHREADS` like this. ```console $ MESON_TESTTHREADS=5 meson test @@ -82,10 +86,10 @@ $ MESON_TESTTHREADS=5 meson test *(added in version 0.52.0)* -Tests can be assigned a priority that determines when a test is *started*. -Tests with higher priority are started first, tests with lower priority -started later. The default priority is 0, meson makes no guarantee on the -ordering of tests with identical priority. +Tests can be assigned a priority that determines when a test is +*started*. Tests with higher priority are started first, tests with +lower priority started later. The default priority is 0, meson makes +no guarantee on the ordering of tests with identical priority. ```meson test('started second', t, priority : 0) @@ -93,34 +97,35 @@ test('started third', t, priority : -50) test('started first', t, priority : 1000) ``` -Note that the test priority only affects the starting order of tests and -subsequent tests are affected by how long it takes previous tests to -complete. It is thus possible that a higher-priority test is still running -when lower-priority tests with a shorter runtime have completed. +Note that the test priority only affects the starting order of tests +and subsequent tests are affected by how long it takes previous tests +to complete. It is thus possible that a higher-priority test is still +running when lower-priority tests with a shorter runtime have +completed. ## Skipped tests and hard errors Sometimes a test can only determine at runtime that it can not be run. -For the default `exitcode` testing protocol, the GNU standard approach in -this case is to exit the program with error code 77. Meson will detect this -and report these tests as skipped rather than failed. This behavior was added -in version 0.37.0. +For the default `exitcode` testing protocol, the GNU standard approach +in this case is to exit the program with error code 77. Meson will +detect this and report these tests as skipped rather than failed. This +behavior was added in version 0.37.0. -For TAP-based tests, skipped tests should print a single line starting with -`1..0 # SKIP`. +For TAP-based tests, skipped tests should print a single line starting +with `1..0 # SKIP`. -In addition, sometimes a test fails set up so that it should fail even if it -is marked as an expected failure. The GNU standard approach in this case is -to exit the program with error code 99. Again, Meson will detect this and -report these tests as `ERROR`, ignoring the setting of `should_fail`. This -behavior was added in version 0.50.0. +In addition, sometimes a test fails set up so that it should fail even +if it is marked as an expected failure. The GNU standard approach in +this case is to exit the program with error code 99. Again, Meson will +detect this and report these tests as `ERROR`, ignoring the setting of +`should_fail`. This behavior was added in version 0.50.0. ## Testing tool -The goal of the meson test tool is to provide a simple way to run tests in a -variety of different ways. The tool is designed to be run in the build -directory. +The goal of the meson test tool is to provide a simple way to run +tests in a variety of different ways. The tool is designed to be run +in the build directory. The simplest thing to do is just to run all tests. @@ -162,9 +167,10 @@ Multiple suites are specified like: $ meson test --suite foo --suite bar ``` -NOTE: If you choose to specify both suite(s) and specific test name(s), the -test name(s) must be contained in the suite(s). This however is redundant-- -it would be more useful to specify either specific test names or suite(s). +NOTE: If you choose to specify both suite(s) and specific test +name(s), the test name(s) must be contained in the suite(s). This +however is redundant-- it would be more useful to specify either +specific test names or suite(s). ### Other test options @@ -193,25 +199,26 @@ Meson also supports running the tests under GDB. Just doing this: $ meson test --gdb testname ``` -Meson will launch `gdb` all set up to run the test. Just type `run` in the -GDB command prompt to start the program. +Meson will launch `gdb` all set up to run the test. Just type `run` in +the GDB command prompt to start the program. -The second use case is a test that segfaults only rarely. In this case you -can invoke the following command: +The second use case is a test that segfaults only rarely. In this case +you can invoke the following command: ```console $ meson test --gdb --repeat=10000 testname ``` -This runs the test up to 10 000 times under GDB automatically. If the program -crashes, GDB will halt and the user can debug the application. Note that -testing timeouts are disabled in this case so `meson test` will not kill -`gdb` while the developer is still debugging it. The downside is that if the -test binary freezes, the test runner will wait forever. +This runs the test up to 10 000 times under GDB automatically. If the +program crashes, GDB will halt and the user can debug the application. +Note that testing timeouts are disabled in this case so `meson test` +will not kill `gdb` while the developer is still debugging it. The +downside is that if the test binary freezes, the test runner will wait +forever. -Sometimes, the GDB binary is not in the PATH variable or the user wants to -use a GDB replacement. Therefore, the invoked GDB program can be specified -*(added 0.52.0)*: +Sometimes, the GDB binary is not in the PATH variable or the user +wants to use a GDB replacement. Therefore, the invoked GDB program can +be specified *(added 0.52.0)*: ```console $ meson test --gdb --gdb-path /path/to/gdb testname @@ -221,41 +228,43 @@ $ meson test --gdb --gdb-path /path/to/gdb testname $ meson test --print-errorlogs ``` -Meson will report the output produced by the failing tests along with other -useful information as the environmental variables. This is useful, for -example, when you run the tests on Travis-CI, Jenkins and the like. +Meson will report the output produced by the failing tests along with +other useful information as the environmental variables. This is +useful, for example, when you run the tests on Travis-CI, Jenkins and +the like. -For further information see the command line help of Meson by running `meson -test -h`. +For further information see the command line help of Meson by running +`meson test -h`. ## Legacy notes -If `meson test` does not work for you, you likely have a old version of -Meson. In that case you should call `mesontest` instead. If `mesontest` -doesn't work either you have a very old version prior to 0.37.0 and should -upgrade. +If `meson test` does not work for you, you likely have a old version +of Meson. In that case you should call `mesontest` instead. If +`mesontest` doesn't work either you have a very old version prior to +0.37.0 and should upgrade. ## Test outputs -Meson will write several different files with detailed results of running -tests. These will be written into $builddir/meson-logs/ +Meson will write several different files with detailed results of +running tests. These will be written into $builddir/meson-logs/ ### testlog.json -This is not a proper json file, but a file containing one valid json object -per line. This is file is designed so each line is streamed out as each test -is run, so it can be read as a stream while the test harness is running +This is not a proper json file, but a file containing one valid json +object per line. This is file is designed so each line is streamed out +as each test is run, so it can be read as a stream while the test +harness is running ### testlog.junit.xml -This is a valid JUnit XML description of all tests run. It is not streamed -out, and is written only once all tests complete running. +This is a valid JUnit XML description of all tests run. It is not +streamed out, and is written only once all tests complete running. -When tests use the `tap` protocol each test will be recorded as a testsuite -container, with each case named by the number of the result. +When tests use the `tap` protocol each test will be recorded as a +testsuite container, with each case named by the number of the result. -When tests use the `gtest` protocol meson will inject arguments to the test -to generate it's own JUnit XML, which meson will include as part of this XML -file. +When tests use the `gtest` protocol meson will inject arguments to the +test to generate it's own JUnit XML, which meson will include as part +of this XML file. *New in 0.55.0* diff --git a/docs/markdown/Unity-builds.md b/docs/markdown/Unity-builds.md index 533a421..833383d 100644 --- a/docs/markdown/Unity-builds.md +++ b/docs/markdown/Unity-builds.md @@ -4,7 +4,12 @@ short-description: Unity builds are a technique for reducing build times # Unity builds -Unity builds are a technique for cutting down build times. The way it works is relatively straightforward. Suppose we have source files `src1.c`, `src2.c` and `src3.c`. Normally we would run the compiler three times, once for each file. In a unity build we instead compile all these sources in a single unit. The simplest approach is to create a new source file that looks like this. +Unity builds are a technique for cutting down build times. The way it +works is relatively straightforward. Suppose we have source files +`src1.c`, `src2.c` and `src3.c`. Normally we would run the compiler +three times, once for each file. In a unity build we instead compile +all these sources in a single unit. The simplest approach is to create +a new source file that looks like this. ```c #include<src1.c> @@ -12,8 +17,23 @@ Unity builds are a technique for cutting down build times. The way it works is r #include<src3.c> ``` -This is then compiled rather than the individual files. The exact speedup depends on the code base, of course, but it is not uncommon to obtain more than 50% speedup in compile times. This happens even though the Unity build uses only one CPU whereas individual compiles can be run in parallel. Unity builds can also lead to faster code, because the compiler can do more aggressive optimizations (e.g. inlining). +This is then compiled rather than the individual files. The exact +speedup depends on the code base, of course, but it is not uncommon to +obtain more than 50% speedup in compile times. This happens even +though the Unity build uses only one CPU whereas individual compiles +can be run in parallel. Unity builds can also lead to faster code, +because the compiler can do more aggressive optimizations (e.g. +inlining). -The downside is that incremental builds are as slow as full rebuilds (because that is what they are). Unity compiles also use more memory, which may become an issue in certain scenarios. There may also be some bugs in the source that need to be fixed before Unity compiles work. As an example, if both `src1.c` and `src2.c` contain a static function or variable of the same name, there will be a clash. +The downside is that incremental builds are as slow as full rebuilds +(because that is what they are). Unity compiles also use more memory, +which may become an issue in certain scenarios. There may also be some +bugs in the source that need to be fixed before Unity compiles work. +As an example, if both `src1.c` and `src2.c` contain a static function +or variable of the same name, there will be a clash. -Meson has built-in support for unity builds. To enable them, just pass `--unity on` on the command line or enable unity builds with the GUI. No code changes are necessary apart from the potential clash issue discussed above. Meson will automatically generate all the necessary inclusion files for you. +Meson has built-in support for unity builds. To enable them, just pass +`--unity on` on the command line or enable unity builds with the GUI. +No code changes are necessary apart from the potential clash issue +discussed above. Meson will automatically generate all the necessary +inclusion files for you. diff --git a/docs/markdown/Use-of-Python.md b/docs/markdown/Use-of-Python.md index 1803503..e69a397 100644 --- a/docs/markdown/Use-of-Python.md +++ b/docs/markdown/Use-of-Python.md @@ -1,21 +1,48 @@ # Use of Python -Meson is implemented in Python. This has both positive and negative sides. The main thing people seem to be mindful about is the dependency on Python to build source code. This page discusses various aspects of this problem. +Meson is implemented in Python. This has both positive and negative +sides. The main thing people seem to be mindful about is the +dependency on Python to build source code. This page discusses various +aspects of this problem. # Dependency hell -There have been many Python programs that are difficult to maintain on multiple platforms. The reasons come mostly from dependencies. The program may use dependencies that are hard to compile on certain platforms, are outdated, conflict with other dependencies, not available on a given Python version and so on. +There have been many Python programs that are difficult to maintain on +multiple platforms. The reasons come mostly from dependencies. The +program may use dependencies that are hard to compile on certain +platforms, are outdated, conflict with other dependencies, not +available on a given Python version and so on. -Meson avoids dependency problems with one simple rule: Meson is not allowed to have any dependencies outside the Python basic library. The only thing you need is Python 3 (and possibly Ninja). +Meson avoids dependency problems with one simple rule: Meson is not +allowed to have any dependencies outside the Python basic library. The +only thing you need is Python 3 (and possibly Ninja). ## Reimplementability -Meson has been designed in such a way that the implementation language is never exposed in the build definitions. This makes it possible (and maybe even easy) to reimplement Meson in any other programming language. There are currently no plans to reimplement Meson, but we will make sure that Python is not exposed inside the build definitions. +Meson has been designed in such a way that the implementation language +is never exposed in the build definitions. This makes it possible (and +maybe even easy) to reimplement Meson in any other programming +language. There are currently no plans to reimplement Meson, but we +will make sure that Python is not exposed inside the build +definitions. ## Cross platform tooling -There is no one technical solution or programming language that works natively on all operating systems currently in use. When Autotools was designed in the late 80s, Unix shell was available pretty much anywhere. This is no longer the case. - -It is also the case that as any project gets larger, sooner or later it requires code generation, scripting or other tooling. This seems to be inevitable. Because there is no scripting language that would be available everywhere, these tools either need to be rewritten for each platform (which is a lot of work and is prone to errors) or the project needs to take a dependency on _something_. - -Any project that uses Meson (at least the current version) can rely on the fact that Python 3 will always be available, because you can't compile the project without it. All tooling can then be done in Python 3 with the knowledge that it will run on any platform without any extra dependencies (modulo the usual porting work). This reduces maintenance effort on multiplatform projects by a fair margin. +There is no one technical solution or programming language that works +natively on all operating systems currently in use. When Autotools was +designed in the late 80s, Unix shell was available pretty much +anywhere. This is no longer the case. + +It is also the case that as any project gets larger, sooner or later +it requires code generation, scripting or other tooling. This seems to +be inevitable. Because there is no scripting language that would be +available everywhere, these tools either need to be rewritten for each +platform (which is a lot of work and is prone to errors) or the +project needs to take a dependency on _something_. + +Any project that uses Meson (at least the current version) can rely on +the fact that Python 3 will always be available, because you can't +compile the project without it. All tooling can then be done in Python +3 with the knowledge that it will run on any platform without any +extra dependencies (modulo the usual porting work). This reduces +maintenance effort on multiplatform projects by a fair margin. diff --git a/docs/markdown/Using-multiple-build-directories.md b/docs/markdown/Using-multiple-build-directories.md index ab6cf3c..557f344 100644 --- a/docs/markdown/Using-multiple-build-directories.md +++ b/docs/markdown/Using-multiple-build-directories.md @@ -1,44 +1,86 @@ # Using multiple build directories -One of the main design goals of Meson has been to build all projects out-of-source. This means that *all* files generated during the build are placed in a separate subdirectory. This goes against common Unix tradition where you build your projects in-source. Building out of source gives two major advantages. - -First of all this makes for very simple `.gitignore` files. In classical build systems you may need to have tens of lines of definitions, most of which contain wildcards. When doing out of source builds all of this busywork goes away. A common ignore file for a Meson project only contains a few lines that are the build directory and IDE project files. - -Secondly this makes it very easy to clean your projects: just delete the build subdirectory and you are done. There is no need to guess whether you need to run `make clean`, `make distclean`, `make mrproper` or something else. When you delete a build subdirectory there is no possible way to have any lingering state from your old builds. +One of the main design goals of Meson has been to build all projects +out-of-source. This means that *all* files generated during the build +are placed in a separate subdirectory. This goes against common Unix +tradition where you build your projects in-source. Building out of +source gives two major advantages. + +First of all this makes for very simple `.gitignore` files. In +classical build systems you may need to have tens of lines of +definitions, most of which contain wildcards. When doing out of source +builds all of this busywork goes away. A common ignore file for a +Meson project only contains a few lines that are the build directory +and IDE project files. + +Secondly this makes it very easy to clean your projects: just delete +the build subdirectory and you are done. There is no need to guess +whether you need to run `make clean`, `make distclean`, `make +mrproper` or something else. When you delete a build subdirectory +there is no possible way to have any lingering state from your old +builds. The true benefit comes from somewhere else, though. ## Multiple build directories for the same source tree -Since a build directory is fully self contained and treats the source tree as a read-only piece of data, it follows that you can have arbitrarily many build trees for any source tree at the same time. Since all build trees can have different configuration, this is extremely powerful. Now you might be wondering why one would want to have multiple build setups at the same time. Let's examine this by setting up a hypothetical project. +Since a build directory is fully self contained and treats the source +tree as a read-only piece of data, it follows that you can have +arbitrarily many build trees for any source tree at the same time. +Since all build trees can have different configuration, this is +extremely powerful. Now you might be wondering why one would want to +have multiple build setups at the same time. Let's examine this by +setting up a hypothetical project. -The first thing to do is to set up the default build, that is, the one we are going to use over 90% of the time. In this we use the system compiler and build with debug enabled and no optimizations so it builds as fast as possible. This is the default project type for Meson, so setting it up is simple. +The first thing to do is to set up the default build, that is, the one +we are going to use over 90% of the time. In this we use the system +compiler and build with debug enabled and no optimizations so it +builds as fast as possible. This is the default project type for +Meson, so setting it up is simple. mkdir builddir meson builddir -Another common setup is to build with debug and optimizations to, for example, run performance tests. Setting this up is just as simple. +Another common setup is to build with debug and optimizations to, for +example, run performance tests. Setting this up is just as simple. mkdir buildopt meson --buildtype=debugoptimized buildopt -For systems where the default compiler is GCC, we would like to compile with Clang, too. So let's do that. +For systems where the default compiler is GCC, we would like to +compile with Clang, too. So let's do that. mkdir buildclang CC=clang CXX=clang++ meson buildclang -You can add cross builds, too. As an example, let's set up a Linux -> Windows cross compilation build using MinGW. +You can add cross builds, too. As an example, let's set up a Linux -> +Windows cross compilation build using MinGW. mkdir buildwine meson --cross-file=mingw-cross.txt buildwine -The cross compilation file sets up Wine so that not only can you compile your application, you can also run the unit test suite just by issuing the command `meson test`. - -To compile any of these build types, just cd into the corresponding build directory and run `meson compile` or instruct your IDE to do the same. Note that once you have set up your build directory once, you can just run Ninja and Meson will ensure that the resulting build is fully up to date according to the source. Even if you have not touched one of the directories in weeks and have done major changes to your build configuration, Meson will detect this and bring the build directory up to date (or print an error if it can't do that). This allows you to do most of your work in the default directory and use the others every now and then without having to babysit your build directories. +The cross compilation file sets up Wine so that not only can you +compile your application, you can also run the unit test suite just by +issuing the command `meson test`. + +To compile any of these build types, just cd into the corresponding +build directory and run `meson compile` or instruct your IDE to do the +same. Note that once you have set up your build directory once, you +can just run Ninja and Meson will ensure that the resulting build is +fully up to date according to the source. Even if you have not touched +one of the directories in weeks and have done major changes to your +build configuration, Meson will detect this and bring the build +directory up to date (or print an error if it can't do that). This +allows you to do most of your work in the default directory and use +the others every now and then without having to babysit your build +directories. ## Specialized uses -Separate build directories allows easy integration for various different kinds of tools. As an example, Clang comes with a static analyzer. It is meant to be run from scratch on a given source tree. The steps to run it with Meson are very simple. +Separate build directories allows easy integration for various +different kinds of tools. As an example, Clang comes with a static +analyzer. It is meant to be run from scratch on a given source tree. +The steps to run it with Meson are very simple. rm -rf buildscan mkdir buildscan @@ -46,4 +88,6 @@ Separate build directories allows easy integration for various different kinds o cd buildscan scan-build ninja -These commands are the same for every single Meson project, so they could even be put in a script turning static analysis into a single command. +These commands are the same for every single Meson project, so they +could even be put in a script turning static analysis into a single +command. diff --git a/docs/markdown/Using-the-WrapDB.md b/docs/markdown/Using-the-WrapDB.md index d8ea31c..baccfdc 100644 --- a/docs/markdown/Using-the-WrapDB.md +++ b/docs/markdown/Using-the-WrapDB.md @@ -1,10 +1,24 @@ # Using the WrapDB -The Wrap database is a web service that provides Meson build definitions to projects that do not have it natively. Using it is simple. The service can be found [here](https://wrapdb.mesonbuild.com). - -The front page lists all projects that are on the service. Select the one you want and click it. The detail page lists available versions by branch and revision id. The branch names come from upstream releases and revision ids are version numbers internal to the database. Whenever the packaging is updated a new revision is released to the service a new revision with a bigger revision id is added. Usually you want to select the newest branch with the highest revision id. - -You can get the actual wrap file which tells Meson how to fetch the project by clicking on the download link on the page. As an example, the wrap file for [zlib-1.2.8, revision 4](https://wrapdb.mesonbuild.com/v1/projects/zlib/1.2.8/4/get_wrap) looks like this. You can find detailed documentation about it in [the Wrap manual](Wrap-dependency-system-manual.md). +The Wrap database is a web service that provides Meson build +definitions to projects that do not have it natively. Using it is +simple. The service can be found +[here](https://wrapdb.mesonbuild.com). + +The front page lists all projects that are on the service. Select the +one you want and click it. The detail page lists available versions by +branch and revision id. The branch names come from upstream releases +and revision ids are version numbers internal to the database. +Whenever the packaging is updated a new revision is released to the +service a new revision with a bigger revision id is added. Usually you +want to select the newest branch with the highest revision id. + +You can get the actual wrap file which tells Meson how to fetch the +project by clicking on the download link on the page. As an example, +the wrap file for [zlib-1.2.8, revision +4](https://wrapdb.mesonbuild.com/v1/projects/zlib/1.2.8/4/get_wrap) +looks like this. You can find detailed documentation about it in [the +Wrap manual](Wrap-dependency-system-manual.md). [wrap-file] directory = zlib-1.2.8 @@ -17,12 +31,17 @@ You can get the actual wrap file which tells Meson how to fetch the project by c patch_filename = zlib-1.2.8-4-wrap.zip patch_hash = 2327a42c8f73a4289ee8c9cd4abc43b324d0decc28d6e609e927f0a50321af4a -Add this file to your project with the name `subprojects/zlib.wrap`. Then you can use it in your `meson.build` file with this directive: +Add this file to your project with the name `subprojects/zlib.wrap`. +Then you can use it in your `meson.build` file with this directive: zproj = subproject('zlib') -When Meson encounters this it will automatically download, unpack and patch the source files. +When Meson encounters this it will automatically download, unpack and +patch the source files. ## Contributing build definitions -The contents of the Wrap database are tracked in git repos of the [Mesonbuild project](https://github.com/mesonbuild). The actual process is simple and described in [submission documentation](Adding-new-projects-to-wrapdb.md). +The contents of the Wrap database are tracked in git repos of the +[Mesonbuild project](https://github.com/mesonbuild). The actual +process is simple and described in [submission +documentation](Adding-new-projects-to-wrapdb.md). diff --git a/docs/markdown/Using-with-Visual-Studio.md b/docs/markdown/Using-with-Visual-Studio.md index c66cf3c..3c97ee5 100644 --- a/docs/markdown/Using-with-Visual-Studio.md +++ b/docs/markdown/Using-with-Visual-Studio.md @@ -4,22 +4,24 @@ short-description: How to use meson in Visual Studio # Using with Visual Studio -In order to generate Visual Studio projects, Meson needs to know the settings -of your installed version of Visual Studio. The only way to get this -information is to run Meson under the Visual Studio Command Prompt. +In order to generate Visual Studio projects, Meson needs to know the +settings of your installed version of Visual Studio. The only way to +get this information is to run Meson under the Visual Studio Command +Prompt. -You can always find the Visual Studio Command Prompt by searching from the -Start Menu. However, the name is different for each Visual Studio version. With -Visual Studio 2019, look for "x64 Native Tools Command Prompt for VS 2019". -The next steps are [the same as always](https://mesonbuild.com/Running-Meson.html#configuring-the-build-directory): +You can always find the Visual Studio Command Prompt by searching from +the Start Menu. However, the name is different for each Visual Studio +version. With Visual Studio 2019, look for "x64 Native Tools Command +Prompt for VS 2019". The next steps are [the same as +always](https://mesonbuild.com/Running-Meson.html#configuring-the-build-directory): 1. `cd` into your source directory 1. `meson setup builddir`, which will create and setup the build directory 1. `meson compile -C builddir`, to compile your code. You can also use `ninja -C builddir` here if you are using the default Ninja backend. -If you wish to generate Visual Studio project files, pass `--backend vs`. -At the time of writing the Ninja backend is more mature than the VS backend so -you might want to use it for serious work. +If you wish to generate Visual Studio project files, pass `--backend +vs`. At the time of writing the Ninja backend is more mature than the +VS backend so you might want to use it for serious work. # Using Clang-CL with Visual Studio diff --git a/docs/markdown/Vala.md b/docs/markdown/Vala.md index c7d44b0..d3edce0 100644 --- a/docs/markdown/Vala.md +++ b/docs/markdown/Vala.md @@ -29,17 +29,18 @@ runtime type system. ## Using libraries -Meson uses the [`dependency()`](Reference-manual.md#dependency) function to find -the relevant VAPI, C headers and linker flags when it encounters a Vala source -file in a build target. Vala needs a VAPI file and a C header or headers to use -a library. The VAPI file helps map Vala code to the library's C programming -interface. It is the -[`pkg-config`](https://www.freedesktop.org/wiki/Software/pkg-config/) tool that -makes finding these installed files all work seamlessly behind the scenes. When -a `pkg-config` file doesn't exist for the library then the -[`find_library()`](Reference-manual.md#find_library) method of the [compiler -object](Reference-manual.md#compiler-object) needs to be used. Examples are -given later. + +Meson uses the [`dependency()`](Reference-manual.md#dependency) +function to find the relevant VAPI, C headers and linker flags when it +encounters a Vala source file in a build target. Vala needs a VAPI +file and a C header or headers to use a library. The VAPI file helps +map Vala code to the library's C programming interface. It is the +[`pkg-config`](https://www.freedesktop.org/wiki/Software/pkg-config/) +tool that makes finding these installed files all work seamlessly +behind the scenes. When a `pkg-config` file doesn't exist for the +library then the [`find_library()`](Reference-manual.md#find_library) +method of the [compiler object](Reference-manual.md#compiler-object) +needs to be used. Examples are given later. Note Vala uses libraries that follow the C Application Binary Interface (C ABI). The library, however, could be written in C, Vala, Rust, Go, C++ or any other @@ -72,26 +73,29 @@ sources = files('app.vala') executable('app_name', sources, dependencies: dependencies) ``` -GTK+ is the graphical toolkit used by GNOME, elementary OS and other desktop -environments. The binding to the library, the VAPI file, is distributed with -Vala. +GTK+ is the graphical toolkit used by GNOME, elementary OS and other +desktop environments. The binding to the library, the VAPI file, is +distributed with Vala. -Other libraries may have a VAPI that is distributed with the library itself. -Such libraries will have their VAPI file installed along with their other -development files. The VAPI is installed in Vala's standard search path and so -works just as seamlessly using the `dependency()` function. +Other libraries may have a VAPI that is distributed with the library +itself. Such libraries will have their VAPI file installed along with +their other development files. The VAPI is installed in Vala's +standard search path and so works just as seamlessly using the +`dependency()` function. ### Targeting a version of GLib -Meson's [`dependency()`](Reference-manual.md#dependency) function allows a -version check of a library. This is often used to check a minimum version is -installed. When setting a minimum version of GLib, Meson will also pass this to -the Vala compiler using the `--target-glib` option. -This is needed when using GTK+'s user interface definition files with Vala's -`[GtkTemplate]`, `[GtkChild]` and `[GtkCallback]` attributes. This requires -`--target-glib 2.38`, or a newer version, to be passed to Vala. With Meson this -is simply done with: +Meson's [`dependency()`](Reference-manual.md#dependency) function +allows a version check of a library. This is often used to check a +minimum version is installed. When setting a minimum version of GLib, +Meson will also pass this to the Vala compiler using the +`--target-glib` option. + +This is needed when using GTK+'s user interface definition files with +Vala's `[GtkTemplate]`, `[GtkChild]` and `[GtkCallback]` attributes. +This requires `--target-glib 2.38`, or a newer version, to be passed +to Vala. With Meson this is simply done with: ```meson project('vala app', 'vala', 'c') @@ -107,9 +111,9 @@ sources = files('app.vala') executable('app_name', sources, dependencies: dependencies) ``` -Using `[GtkTemplate]` also requires the GTK+ user interface definition files to -be built in to the binary as GResources. For completeness, the next example -shows this: +Using `[GtkTemplate]` also requires the GTK+ user interface definition +files to be built in to the binary as GResources. For completeness, +the next example shows this: ```meson project('vala app', 'vala', 'c') @@ -133,17 +137,19 @@ executable('app_name', sources, dependencies: dependencies) ### Adding to Vala's search path -So far we have covered the cases where the VAPI file is either distributed with -Vala or the library. A VAPI can also be included in the source files of your -project. The convention is to put it in the `vapi` directory of your project. -This is needed when a library does not have a VAPI or your project needs to link -to another component in the project that uses the C ABI. For example if part of -the project is written in C. +So far we have covered the cases where the VAPI file is either +distributed with Vala or the library. A VAPI can also be included in +the source files of your project. The convention is to put it in the +`vapi` directory of your project. + +This is needed when a library does not have a VAPI or your project +needs to link to another component in the project that uses the C ABI. +For example if part of the project is written in C. -The Vala compiler's `--vapidir` option is used to add the project directory to -the VAPI search path. In Meson this is done with the `add_project_arguments()` -function: +The Vala compiler's `--vapidir` option is used to add the project +directory to the VAPI search path. In Meson this is done with the +`add_project_arguments()` function: ```meson project('vala app', 'vala', 'c') @@ -163,30 +169,33 @@ sources = files('app.vala') executable('app_name', sources, dependencies: dependencies) ``` -If the VAPI is for an external library then make sure that the VAPI name -corresponds to the pkg-config file name. +If the VAPI is for an external library then make sure that the VAPI +name corresponds to the pkg-config file name. -The [`vala-extra-vapis` repository](https://gitlab.gnome.org/GNOME/vala-extra-vapis) -is a community maintained repository of VAPIs that are not distributed. +The [`vala-extra-vapis` +repository](https://gitlab.gnome.org/GNOME/vala-extra-vapis) is a +community maintained repository of VAPIs that are not distributed. Developers use the repository to share early work on new bindings and -improvements to existing bindings. So the VAPIs can frequently change. It is -recommended VAPIs from this repository are copied in to your project's source -files. +improvements to existing bindings. So the VAPIs can frequently change. +It is recommended VAPIs from this repository are copied in to your +project's source files. -This also works well for starting to write new bindings before they are shared -with the `vala-extra-vapis` repository. +This also works well for starting to write new bindings before they +are shared with the `vala-extra-vapis` repository. ### Libraries without pkg-config files + A library that does not have a corresponding pkg-config file may mean -`dependency()` is unsuitable for finding the C and Vala interface files. In this -case it is necessary to use the `find_library()` method of the compiler object. +`dependency()` is unsuitable for finding the C and Vala interface +files. In this case it is necessary to use the `find_library()` method +of the compiler object. -The first example uses Vala's POSIX binding. There is no pkg-config file because -POSIX includes the standard C library on Unix systems. All that is needed is the -VAPI file, `posix.vapi`. This is included with Vala and installed in Vala's -standard search path. Meson just needs to be told to only find the library for -the Vala compiler: +The first example uses Vala's POSIX binding. There is no pkg-config +file because POSIX includes the standard C library on Unix systems. +All that is needed is the VAPI file, `posix.vapi`. This is included +with Vala and installed in Vala's standard search path. Meson just +needs to be told to only find the library for the Vala compiler: ```meson project('vala app', 'vala', 'c') @@ -202,10 +211,11 @@ sources = files('app.vala') executable('app_name', sources, dependencies: dependencies) ``` -The next example shows how to link with a C library where no additional VAPI is -needed. The standard maths functions are already bound in `glib-2.0.vapi`, but -the GNU C library requires linking to the maths library separately. In this -example Meson is told to find the library only for the C compiler: +The next example shows how to link with a C library where no +additional VAPI is needed. The standard maths functions are already +bound in `glib-2.0.vapi`, but the GNU C library requires linking to +the maths library separately. In this example Meson is told to find +the library only for the C compiler: ```meson project('vala app', 'vala', 'c') @@ -220,12 +230,15 @@ sources = files('app.vala') executable('app_name', sources, dependencies: dependencies) ``` -The `required: false` means the build will continue when using another C library -that does not separate the maths library. See [Add math library (-lm) -portably](howtox.md#add-math-library-lm-portably). -The final example shows how to use a library that does not have a pkg-config -file and the VAPI is in the `vapi` directory of your project source files: +The `required: false` means the build will continue when using another +C library that does not separate the maths library. See [Add math +library (-lm) portably](howtox.md#add-math-library-lm-portably). + +The final example shows how to use a library that does not have a +pkg-config file and the VAPI is in the `vapi` directory of your +project source files: + ```meson project('vala app', 'vala', 'c') @@ -252,13 +265,18 @@ keyword added to include the project VAPI directory. This is not added automatically by `add_project_arguments()`. ### Working with the Vala Preprocessor -Passing arguments to [Vala's preprocessor](https://wiki.gnome.org/Projects/Vala/Manual/Preprocessor) requires specifying the language as `vala`. For example, the following statement sets the preprocessor symbol `USE_FUSE`: + +Passing arguments to [Vala's +preprocessor](https://wiki.gnome.org/Projects/Vala/Manual/Preprocessor) +requires specifying the language as `vala`. For example, the following +statement sets the preprocessor symbol `USE_FUSE`: ```meson add_project_arguments('-D', 'USE_FUSE', language: 'vala') ``` -If you need to pass an argument to the C pre-processor then specify the language as c. For example to set FUSE_USE_VERSION to 26 use: +If you need to pass an argument to the C pre-processor then specify +the language as c. For example to set FUSE_USE_VERSION to 26 use: ```meson add_project_arguments('-DFUSE_USE_VERSION=26', language: 'c') @@ -268,9 +286,10 @@ add_project_arguments('-DFUSE_USE_VERSION=26', language: 'c') ### Changing C header and VAPI names -Meson's [`library`](Reference-manual.md#library) target automatically outputs -the C header and the VAPI. They can be renamed by setting the `vala_header` and -`vala_vapi` arguments respectively: + +Meson's [`library`](Reference-manual.md#library) target automatically +outputs the C header and the VAPI. They can be renamed by setting the +`vala_header` and `vala_vapi` arguments respectively: ```meson foo_lib = shared_library('foo', 'foo.vala', @@ -280,26 +299,29 @@ foo_lib = shared_library('foo', 'foo.vala', install: true, install_dir: [true, true, true]) ``` -In this example, the second and third elements of the `install_dir` array -indicate the destination with `true` to use default directories (i.e. `include` -and `share/vala/vapi`). + +In this example, the second and third elements of the `install_dir` +array indicate the destination with `true` to use default directories +(i.e. `include` and `share/vala/vapi`). ### GObject Introspection and language bindings -A 'binding' allows another programming language to use a library written in -Vala. Because Vala uses the GObject type system as its runtime type system it is -very easy to use introspection to generate a binding. A Meson build of a Vala -library can generate the GObject introspection metadata. The metadata is then -used in separate projects with [language specific -tools](https://wiki.gnome.org/Projects/Vala/LibraryWritingBindings) to generate -a binding. - -The main form of metadata is a GObject Introspection Repository (GIR) XML file. -GIRs are mostly used by languages that generate bindings at compile time. -Languages that generate bindings at runtime mostly use a typelib file, which is -generated from the GIR. - -Meson can generate a GIR as part of the build. For a Vala library the + +A 'binding' allows another programming language to use a library +written in Vala. Because Vala uses the GObject type system as its +runtime type system it is very easy to use introspection to generate a +binding. A Meson build of a Vala library can generate the GObject +introspection metadata. The metadata is then used in separate projects +with [language specific +tools](https://wiki.gnome.org/Projects/Vala/LibraryWritingBindings) to +generate a binding. + +The main form of metadata is a GObject Introspection Repository (GIR) +XML file. GIRs are mostly used by languages that generate bindings at +compile time. Languages that generate bindings at runtime mostly use a +typelib file, which is generated from the GIR. + +Meson can generate a GIR as part of the build. For a Vala library the `vala_gir` option has to be set for the `library`: ```meson @@ -310,12 +332,12 @@ foo_lib = shared_library('foo', 'foo.vala', install_dir: [true, true, true, true]) ``` -The `true` value in `install_dir` tells Meson to use the default directory (i.e. -`share/gir-1.0` for GIRs). The fourth element in the `install_dir` array -indicates where the GIR file will be installed. +The `true` value in `install_dir` tells Meson to use the default +directory (i.e. `share/gir-1.0` for GIRs). The fourth element in the +`install_dir` array indicates where the GIR file will be installed. -To then generate a typelib file use a custom target with the `g-ir-compiler` -program and a dependency on the library: +To then generate a typelib file use a custom target with the +`g-ir-compiler` program and a dependency on the library: ```meson g_ir_compiler = find_program('g-ir-compiler') diff --git a/docs/markdown/Windows-module.md b/docs/markdown/Windows-module.md index 8c01a41..a7131a7 100644 --- a/docs/markdown/Windows-module.md +++ b/docs/markdown/Windows-module.md @@ -7,10 +7,10 @@ Windows. ### compile_resources -Compiles Windows `rc` files specified in the positional -arguments. Returns an opaque object that you put in the list of -sources for the target you want to have the resources in. This method -has the following keyword argument. +Compiles Windows `rc` files specified in the positional arguments. +Returns an opaque object that you put in the list of sources for the +target you want to have the resources in. This method has the +following keyword argument. - `args` lists extra arguments to pass to the resource compiler - `depend_files` lists resource files that the resource script depends on diff --git a/docs/markdown/Wrap-best-practices-and-tips.md b/docs/markdown/Wrap-best-practices-and-tips.md index bdff9ee..70b0225 100644 --- a/docs/markdown/Wrap-best-practices-and-tips.md +++ b/docs/markdown/Wrap-best-practices-and-tips.md @@ -43,9 +43,9 @@ internal_inc = include_directories('.') # At top level meson.build Some platforms (e.g. iOS) requires linking everything in your main app statically. In other cases you might want shared libraries. They are -also faster during development due to Meson's relinking -optimization. However building both library types on all builds is -slow and wasteful. +also faster during development due to Meson's relinking optimization. +However building both library types on all builds is slow and +wasteful. Your project should use the `library` method that can be toggled between shared and static with the `default_library` builtin option. @@ -139,21 +139,20 @@ quickly run afoul of the [One Definition Rule (ODR)](https://en.wikipedia.org/wiki/One_Definition_Rule) in C++, as you have more than one definition of a symbol, yielding undefined behavior. While C does not have a strict ODR rule, there is no -language in the standard which guarantees such behavior to -work. Violations of the ODR can lead to weird idiosyncratic failures -such as segfaults. In the overwhelming number of cases, exposing -library sources via the `sources` argument in `declare_dependency` is -thus incorrect. If you wish to get full cross-library performance, -consider building `mysupportlib` as a static library instead and -employing LTO. +language in the standard which guarantees such behavior to work. +Violations of the ODR can lead to weird idiosyncratic failures such as +segfaults. In the overwhelming number of cases, exposing library +sources via the `sources` argument in `declare_dependency` is thus +incorrect. If you wish to get full cross-library performance, consider +building `mysupportlib` as a static library instead and employing LTO. There are exceptions to this rule. If there are some natural -constraints on how your library is to be used, you can expose -sources. For instance, the WrapDB module for GoogleTest directly -exposes the sources of GTest and GMock. This is valid, as GTest and -GMock will only ever be used in *terminal* link targets. A terminal -target is the final target in a dependency link chain, for instance -`myexe` in the last example, whereas `mylibrary` is an intermediate -link target. For most libraries this rule is not applicable though, as -you cannot in general control how others consume your library, and as -such should not expose sources. +constraints on how your library is to be used, you can expose sources. +For instance, the WrapDB module for GoogleTest directly exposes the +sources of GTest and GMock. This is valid, as GTest and GMock will +only ever be used in *terminal* link targets. A terminal target is the +final target in a dependency link chain, for instance `myexe` in the +last example, whereas `mylibrary` is an intermediate link target. For +most libraries this rule is not applicable though, as you cannot in +general control how others consume your library, and as such should +not expose sources. diff --git a/docs/markdown/Wrap-dependency-system-manual.md b/docs/markdown/Wrap-dependency-system-manual.md index 61a8390..3bf22ee 100644 --- a/docs/markdown/Wrap-dependency-system-manual.md +++ b/docs/markdown/Wrap-dependency-system-manual.md @@ -30,12 +30,13 @@ static library). To use this kind of a project as a dependency you could just copy and extract it inside your project's `subprojects` directory. -However there is a simpler way. You can specify a Wrap file that tells Meson -how to download it for you. If you then use this subproject in your build, -Meson will automatically download and extract it during build. This makes -subproject embedding extremely easy. +However there is a simpler way. You can specify a Wrap file that tells +Meson how to download it for you. If you then use this subproject in +your build, Meson will automatically download and extract it during +build. This makes subproject embedding extremely easy. -All wrap files must have a name of `<project_name>.wrap` form and be in `subprojects` dir. +All wrap files must have a name of `<project_name>.wrap` form and be +in `subprojects` dir. Currently Meson has four kinds of wraps: - wrap-file @@ -45,10 +46,11 @@ Currently Meson has four kinds of wraps: ## wrap format -Wrap files are written in ini format, with a single header containing the type -of wrap, followed by properties describing how to obtain the sources, validate -them, and modify them if needed. An example wrap-file for the wrap named -`libfoobar` would have a filename `libfoobar.wrap` and would look like this: +Wrap files are written in ini format, with a single header containing +the type of wrap, followed by properties describing how to obtain the +sources, validate them, and modify them if needed. An example +wrap-file for the wrap named `libfoobar` would have a filename +`libfoobar.wrap` and would look like this: ```ini [wrap-file] @@ -68,9 +70,12 @@ revision = head ``` ## Accepted configuration properties for wraps -- `directory` - name of the subproject root directory, defaults to the name of the wrap. -Since *0.55.0* those can be used in all wrap types, they were previously reserved to `wrap-file`: +- `directory` - name of the subproject root directory, defaults to the + name of the wrap. + +Since *0.55.0* those can be used in all wrap types, they were +previously reserved to `wrap-file`: - `patch_url` - download url to retrieve an optional overlay archive - `patch_fallback_url` - fallback URL to be used when download from `patch_url` fails *Since: 0.55.0* @@ -90,9 +95,10 @@ Since *0.55.0* those can be used in all wrap types, they were previously reserve directory. Since *0.55.0* it is possible to use only the `source_filename` and -`patch_filename` value in a .wrap file (without `source_url` and `patch_url`) to -specify a local archive in the `subprojects/packagefiles` directory. The `*_hash` -entries are optional when using this method. This method should be preferred over +`patch_filename` value in a .wrap file (without `source_url` and +`patch_url`) to specify a local archive in the +`subprojects/packagefiles` directory. The `*_hash` entries are +optional when using this method. This method should be preferred over the old `packagecache` approach described below. Since *0.49.0* if `source_filename` or `patch_filename` is found in the @@ -136,16 +142,17 @@ thousands of lines of code. Once you have a working build definition, just zip up the Meson build files (and others you have changed) and put them somewhere where you can download them. -Prior to *0.55.0* Meson build patches were only supported for wrap-file mode. -When using wrap-git, the repository must contain all Meson build definitions. -Since *0.55.0* Meson build patches are supported for any wrap modes, including -wrap-git. +Prior to *0.55.0* Meson build patches were only supported for +wrap-file mode. When using wrap-git, the repository must contain all +Meson build definitions. Since *0.55.0* Meson build patches are +supported for any wrap modes, including wrap-git. ## `provide` section *Since *0.55.0* -Wrap files can define the dependencies it provides in the `[provide]` section. +Wrap files can define the dependencies it provides in the `[provide]` +section. ```ini [provide] @@ -177,27 +184,31 @@ if not foo_dep.found() endif ``` -- Sometimes not-found dependency is preferable to a fallback when the feature is - not explicitly requested by the user. In that case - `dependency('foo-1.0', required: get_option('foo_opt'))` will only fallback - when the user sets `foo_opt` to `enabled` instead of `auto`. - -If it is desired to fallback for an optional dependency, the `fallback` -or `allow_fallback` keyword arguments must be passed explicitly. *Since -0.56.0*, `dependency('foo-1.0', required: get_option('foo_opt'), -allow_fallback: true)` will use the fallback even when `foo_opt` is set -to `auto`. On version *0.55.0* the same effect could be achieved with -`dependency('foo-1.0', required: get_option('foo_opt'), fallback: 'foo')`. - -This mechanism assumes the subproject calls `meson.override_dependency('foo-1.0', foo_dep)` -so Meson knows which dependency object should be used as fallback. Since that -method was introduced in version *0.54.0*, as a transitional aid for projects -that do not yet make use of it the variable name can be provided in the wrap file -with entries in the format `foo-1.0 = foo_dep`. +- Sometimes not-found dependency is preferable to a fallback when the + feature is not explicitly requested by the user. In that case + `dependency('foo-1.0', required: get_option('foo_opt'))` will only + fallback when the user sets `foo_opt` to `enabled` instead of + `auto`. + +If it is desired to fallback for an optional dependency, the +`fallback` or `allow_fallback` keyword arguments must be passed +explicitly. *Since 0.56.0*, `dependency('foo-1.0', required: +get_option('foo_opt'), allow_fallback: true)` will use the fallback +even when `foo_opt` is set to `auto`. On version *0.55.0* the same +effect could be achieved with `dependency('foo-1.0', required: +get_option('foo_opt'), fallback: 'foo')`. + +This mechanism assumes the subproject calls +`meson.override_dependency('foo-1.0', foo_dep)` so Meson knows which +dependency object should be used as fallback. Since that method was +introduced in version *0.54.0*, as a transitional aid for projects +that do not yet make use of it the variable name can be provided in +the wrap file with entries in the format `foo-1.0 = foo_dep`. For example when using a recent enough version of glib that uses -`meson.override_dependency()` to override `glib-2.0`, `gobject-2.0` and `gio-2.0`, -a wrap file would look like: +`meson.override_dependency()` to override `glib-2.0`, `gobject-2.0` +and `gio-2.0`, a wrap file would look like: + ```ini [wrap-git] url=https://gitlab.gnome.org/GNOME/glib.git @@ -207,7 +218,9 @@ revision=glib-2-62 dependency_names = glib-2.0, gobject-2.0, gio-2.0 ``` -With older version of glib dependency variable names need to be specified: +With older version of glib dependency variable names need to be +specified: + ```ini [wrap-git] url=https://gitlab.gnome.org/GNOME/glib.git @@ -219,25 +232,32 @@ gobject-2.0=gobject_dep gio-2.0=gio_dep ``` -Programs can also be provided by wrap files, with the `program_names` key: +Programs can also be provided by wrap files, with the `program_names` +key: + ```ini [provide] program_names = myprog, otherprog ``` -With such wrap file, `find_program('myprog')` will automatically fallback to use -the subproject, assuming it uses `meson.override_find_program('myprog')`. +With such wrap file, `find_program('myprog')` will automatically +fallback to use the subproject, assuming it uses +`meson.override_find_program('myprog')`. ## Using wrapped projects -Wraps provide a convenient way of obtaining a project into your subproject directory. -Then you use it as a regular subproject (see [subprojects](Subprojects.md)). +Wraps provide a convenient way of obtaining a project into your +subproject directory. Then you use it as a regular subproject (see +[subprojects](Subprojects.md)). ## Getting wraps Usually you don't want to write your wraps by hand. -There is an online repository called [WrapDB](https://wrapdb.mesonbuild.com) that provides -many dependencies ready to use. You can read more about WrapDB [here](Using-the-WrapDB.md). +There is an online repository called +[WrapDB](https://wrapdb.mesonbuild.com) that provides many +dependencies ready to use. You can read more about WrapDB +[here](Using-the-WrapDB.md). -There is also a Meson subcommand to get and manage wraps (see [using wraptool](Using-wraptool.md)). +There is also a Meson subcommand to get and manage wraps (see [using +wraptool](Using-wraptool.md)). diff --git a/docs/markdown/Wrap-review-guidelines.md b/docs/markdown/Wrap-review-guidelines.md index 389328b..c81a8fa 100644 --- a/docs/markdown/Wrap-review-guidelines.md +++ b/docs/markdown/Wrap-review-guidelines.md @@ -9,14 +9,15 @@ guarantee that the package will get accepted. Use common sense. ## Setting up the tools -The [mesonwrap repository](https://github.com/mesonbuild/mesonwrap) provides tools -to maintain the WrapDB. Read-only features such can be used by anyone without Meson admin rights. +The [mesonwrap repository](https://github.com/mesonbuild/mesonwrap) +provides tools to maintain the WrapDB. Read-only features such can be +used by anyone without Meson admin rights. ## Personal access token -Some tools require access to the Github API. -A [personal access token](https://github.com/settings/tokens) may be required -if the freebie Github API quota is exhausted. `public_repo` scope is required +Some tools require access to the Github API. A [personal access +token](https://github.com/settings/tokens) may be required if the +freebie Github API quota is exhausted. `public_repo` scope is required for write operations. ``` @@ -31,7 +32,8 @@ github_token = <github token> mesonwrap review zlib --pull-request=1 [--approve] ``` -Since not every check can be automated please pay attention to the following during the review: +Since not every check can be automated please pay attention to the +following during the review: - Download link points to an authoritative upstream location. - Version branch is created from master. diff --git a/docs/markdown/fallback-wraptool.md b/docs/markdown/fallback-wraptool.md index 9f4814b..d4f5af2 100644 --- a/docs/markdown/fallback-wraptool.md +++ b/docs/markdown/fallback-wraptool.md @@ -22,8 +22,8 @@ To install a wrap, go to your source root, make sure that the This will stage the subproject ready to use. If you have multiple subprojects you need to download them all manually. -Specifying branch name is optional. If not specified, the list -of potential branches is sorted alphabetically and the last branch is +Specifying branch name is optional. If not specified, the list of +potential branches is sorted alphabetically and the last branch is used. *Note* The tool was added in 0.32.0, for versions older than that you diff --git a/docs/markdown/howtox.md b/docs/markdown/howtox.md index 0d1a2a2..fa99864 100644 --- a/docs/markdown/howtox.md +++ b/docs/markdown/howtox.md @@ -12,35 +12,41 @@ When first running Meson, set it in an environment variable. $ CC=mycc meson <options> ``` -Note that environment variables like `CC` only works in native builds. The `CC` -refers to the compiler for the host platform, that is the compiler used to -compile programs that run on the machine we will eventually install the project -on. The compiler used to build things that run on the machine we do the -building can be specified with `CC_FOR_BUILD`. You can use it in cross builds. +Note that environment variables like `CC` only works in native builds. +The `CC` refers to the compiler for the host platform, that is the +compiler used to compile programs that run on the machine we will +eventually install the project on. The compiler used to build things +that run on the machine we do the building can be specified with +`CC_FOR_BUILD`. You can use it in cross builds. -Note that environment variables are never the idiomatic way to do anything with -Meson, however. It is better to use the native and cross files. And the tools -for the host platform in cross builds can only be specified with a cross file. +Note that environment variables are never the idiomatic way to do +anything with Meson, however. It is better to use the native and cross +files. And the tools for the host platform in cross builds can only be +specified with a cross file. -There is a table of all environment variables supported [Here](Reference-tables.md#compiler-and-linker-selection-variables) +There is a table of all environment variables supported +[Here](Reference-tables.md#compiler-and-linker-selection-variables) ## Set linker *New in 0.53.0* -Like the compiler, the linker is selected via the `<compiler variable>_LD` -environment variable, or through the `<compiler entry>_ld` entry in a native -or cross file. You must be aware of whether you're using a compiler that -invokes the linker itself (most compilers including GCC and Clang) or a -linker that is invoked directly (when using MSVC or compilers that act like -it, including Clang-Cl). With the former `c_ld` or `CC_LD` should be the value -to pass to the compiler's special argument (such as `-fuse-ld` with clang and -gcc), with the latter it should be an executable, such as `lld-link.exe`. - -*NOTE* In meson 0.53.0 the `ld` entry in the cross/native file and the `LD` -environment variable were used, this resulted in a large number of regressions -and was changed in 0.53.1 to `<lang>_ld` and `<comp variable>_LD`. +Like the compiler, the linker is selected via the `<compiler +variable>_LD` environment variable, or through the `<compiler +entry>_ld` entry in a native or cross file. You must be aware of +whether you're using a compiler that invokes the linker itself (most +compilers including GCC and Clang) or a linker that is invoked +directly (when using MSVC or compilers that act like it, including +Clang-Cl). With the former `c_ld` or `CC_LD` should be the value to +pass to the compiler's special argument (such as `-fuse-ld` with clang +and gcc), with the latter it should be an executable, such as +`lld-link.exe`. + +*NOTE* In meson 0.53.0 the `ld` entry in the cross/native file and the +`LD` environment variable were used, this resulted in a large number +of regressions and was changed in 0.53.1 to `<lang>_ld` and `<comp +variable>_LD`. ```console $ CC=clang CC_LD=lld meson <options> @@ -60,7 +66,8 @@ c = 'clang' c_ld = 'lld' ``` -There is a table of all environment variables supported [Here](Reference-tables.md#compiler-and-linker-selection-variables) +There is a table of all environment variables supported +[Here](Reference-tables.md#compiler-and-linker-selection-variables) ## Set default C/C++ language version @@ -90,8 +97,8 @@ executable(..., dependencies : thread_dep) ## Set extra compiler and linker flags from the outside (when e.g. building distro packages) The behavior is the same as with other build systems, with environment -variables during first invocation. Do not use these when you need to rebuild -the source +variables during first invocation. Do not use these when you need to +rebuild the source ```console $ CFLAGS=-fsomething LDFLAGS=-Wl,--linker-flag meson <options> @@ -245,9 +252,10 @@ executable(..., install : true, install_dir : get_option('libexecdir')) ## Use existing `Find<name>.cmake` files -Meson can use the CMake `find_package()` ecosystem if CMake is installed. -To find a dependency with custom `Find<name>.cmake`, set the `cmake_module_path` -property to the path in your project where the CMake scripts are stored. +Meson can use the CMake `find_package()` ecosystem if CMake is +installed. To find a dependency with custom `Find<name>.cmake`, set +the `cmake_module_path` property to the path in your project where the +CMake scripts are stored. Example for a `FindCmakeOnlyDep.cmake` in a `cmake` subdirectory: |