diff options
Diffstat (limited to 'docs')
100 files changed, 1644 insertions, 608 deletions
diff --git a/docs/extensions/refman_links.py b/docs/extensions/refman_links.py index 5c22a0a..865668b 100644 --- a/docs/extensions/refman_links.py +++ b/docs/extensions/refman_links.py @@ -1,11 +1,13 @@ from pathlib import Path from json import loads +import os import re from hotdoc.core.exceptions import HotdocSourceException from hotdoc.core.extension import Extension from hotdoc.core.tree import Page from hotdoc.core.project import Project +from hotdoc.core.symbols import * from hotdoc.run_hotdoc import Application from hotdoc.core.formatter import Formatter from hotdoc.utils.loggable import Logger, warn, info @@ -52,6 +54,35 @@ class RefmanLinksExtension(Extension): with valid links to the correct URL. To reference objects / types use the [[@object]] syntax. ''' + for key, value in self._data.items(): + path = os.path.relpath(value, self.app.config.get_invoke_dir()).split('#')[0] + if path == page.link.ref: + if key.startswith('@'): + res = self.create_symbol( + ClassSymbol, + display_name=key[1:], + filename=path, + unique_name=key) + res.link = Link(value, res.display_name, res.unique_name) + elif '.' in key: + res = self.create_symbol( + MethodSymbol, + parameters=[], + display_name=key.split('.')[-1], + parent_name=f'@{key.split(".")[-2]}', + filename=path, + unique_name=key) + res.link = Link(value, key, res.unique_name) + else: + res = self.create_symbol( + FunctionSymbol, + parameters=[], + display_name=key, + filename=path, + unique_name=key) + res.link = Link(value, res.display_name, res.unique_name) + page.symbols.append(res) + link_regex = re.compile(r'(\[\[#?@?([ \n\t]*[a-zA-Z0-9_]+[ \n\t]*\.)*[ \n\t]*[a-zA-Z0-9_]+[ \n\t]*\]\])(.)?', re.MULTILINE) for m in link_regex.finditer(page.formatted_contents): i = m.group(1) @@ -103,6 +134,10 @@ class RefmanLinksExtension(Extension): ext.formatter.formatting_page_signal.connect(self._formatting_page_cb) info('Meson refman extension LOADED') + def create_symbol(self, *args, **kwargs): + kwargs['language'] = 'meson' + return super(RefmanLinksExtension, self).create_symbol(*args, **kwargs) + @staticmethod def get_dependencies() -> T.List[T.Type[Extension]]: return [] # In case this extension has dependencies on other extensions diff --git a/docs/markdown/Adding-new-projects-to-wrapdb.md b/docs/markdown/Adding-new-projects-to-wrapdb.md index 7c28b49..e690a8b 100644 --- a/docs/markdown/Adding-new-projects-to-wrapdb.md +++ b/docs/markdown/Adding-new-projects-to-wrapdb.md @@ -51,6 +51,37 @@ If the project name is too generic or ambiguous (e.g. `benchmark`), consider using `organization-project` naming format (e.g. `google-benchmark`). +## Overriding dependencies in the submitted project + +Ideally the project you submit should make a call to `meson.override_dependency` +for each dependency you would like to expose, with the first argument +matching the pkg-config file name. This abstracts away the +need to know and keep track of the variable names downstream. + +For instance, the Apache Arrow project exposes multiple dependencies like +its base `arrow` library, along with an `arrow-compute` library. The +project generates `arrow.pc` and `arrow-compute.pc` files for pkg-config +respectively, so internally the project also calls: + +```meson +arrow_dep = declare_dependency(...) +meson.override_dependency('arrow', arrow_dep) + +arrow_compute_dep = declare_dependency(...) +meson.override_dependency('arrow-compute', arrow_compute_dep) +``` +Note that `meson.override_dependency` was introduced in Meson version +0.54.0. If your project supports older versions of Meson, you should +add a condition to only call that function in versions where it is +available: + +```meson +if meson.version().version_compare('>=0.54.0') + meson.override_dependency('arrow', arrow_dep) + meson.override_dependency('arrow-compute', arrow_compute_dep) +endif +``` + ## How to contribute a new wrap If the project already uses Meson build system, then only a wrap file @@ -83,22 +114,41 @@ shasum -a 256 path/to/libfoo-1.0.0.tar.gz Next you need to add the entries that define what dependencies the current project provides. This is important, as it is what makes -Meson's automatic dependency resolver work. It is done by adding a -`provide` entry at the end of the `upstream.wrap` file. Using the Ogg -library as an example, this is what it would look like: +Meson's automatic dependency resolver work. + +Assuming the project that you are creating +a wrap file for has called `meson.override_dependency`, then you +can declare those overridden dependencies in the `provide` section +of the wrap file: + +```ini +[provide] +dependency_names = arrow, arrow_compute +``` + +In the case that you do not control the upstream Meson configuration +and it does not already make a call to `meson.override_dependency`, +then you can still expose dependency variables in the wrap file, using +a syntax like: ```ini [provide] -ogg = ogg_dep +arrow = arrow_dep +arrow_compute = arrow_compute_dep ``` -The `ogg` part on the left refers to the dependency name, which should -be the same as its Pkg-Config name. `ogg_dep` on the right refers to -the variable in the build definitions that provides the dependency. -Most commonly it holds the result of a `declare_dependency` call. If a -variable of that name is not defined, Meson will exit with a hard -error. For further details see [the main Wrap -manual](Wrap-dependency-system-manual.md). +The `arrow` and `arrow_compute` parts on the left refer to the dependency +names, which should be the same as their Pkg-Config name. `arrow_dep` and +`arrow_compute_dep` on the right refer to the variables in the build +definition that provide the dependencies. Most commonly, they hold the +result of a `declare_dependency` call. If a variable of that name is +not defined, Meson will exit with a hard error. For further details see +[the main Wrap manual](Wrap-dependency-system-manual.md). + +However, it is strongly advised in such cases to request that the upstream +repository use `meson.override_dependency` for its next release, so that +the variable names chosen in the upstream configuration file can be +decoupled from the wrap file contents. Now you can create the build files, if the upstream project does not contain any, and work on them until the project builds correctly. diff --git a/docs/markdown/Build-options.md b/docs/markdown/Build-options.md index 190705d..ee12f55 100644 --- a/docs/markdown/Build-options.md +++ b/docs/markdown/Build-options.md @@ -244,6 +244,10 @@ project which also has an option called `some_option`, then calling `yield` is `false`, `get_option` returns the value of the subproject's option. +*Since 1.8.0* `-Dsub:some_option=anothervalue`, when used with a +yielding option, sets the value separately from the option +it yields to. + ## Built-in build options diff --git a/docs/markdown/Builtin-options.md b/docs/markdown/Builtin-options.md index faf7a60..ee576c3 100644 --- a/docs/markdown/Builtin-options.md +++ b/docs/markdown/Builtin-options.md @@ -72,31 +72,33 @@ 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 | -| -------------------------------------- | ------------- | ----------- | -------------- | ----------------- | +| Option | Default value | Description | Is per machine | Per subproject (since) | +| -------------------------------------- | ------------- | ----------- | -------------- | ---------------------- | | auto_features {enabled, disabled, auto} | auto | Override value of all 'auto' features | no | no | | backend {ninja, vs,<br>vs2010, vs2012, vs2013, vs2015, vs2017, vs2019, vs2022, xcode, none} | ninja | Backend to use | no | no | | genvslite {vs2022} | vs2022 | Setup multi-buildtype ninja build directories and Visual Studio solution | no | no | -| buildtype {plain, debug,<br>debugoptimized, release, minsize, custom} | debug | Build type to use | no | no | -| debug | true | Enable debug symbols and other information | no | no | -| default_both_libraries {shared, static, auto} | shared | Default library type for both_libraries | no | no | -| default_library {shared, static, both} | shared | Default library type | no | yes | +| buildtype {plain, debug,<br>debugoptimized, release, minsize, custom} | debug | Build type to use | no | 1.8.0 | +| debug | true | Enable debug symbols and other information | no | 1.8.0 | +| default_both_libraries {shared, static, auto} | shared | Default library type for both_libraries | no | 1.8.0 | +| default_library {shared, static, both} | shared | Default library type | no | 0.54.0 | | errorlogs | true | Whether to print the logs from failing tests. | no | no | | install_umask {preserve, 0000-0777} | 022 | Default umask to apply on permissions of installed files | no | no | | layout {mirror,flat} | mirror | Build directory layout | no | no | -| optimization {plain, 0, g, 1, 2, 3, s} | 0 | Optimization level | no | no | +| namingscheme {platform, classic} | classic | Library naming scheme to use | no | 1.10.0 | +| optimization {plain, 0, g, 1, 2, 3, s} | 0 | Optimization level | no | 1.8.0 | | pkg_config_path {OS separated path} | '' | Additional paths for pkg-config to search before builtin paths | yes | no | | prefer_static | false | Whether to try static linking before shared linking | no | no | | cmake_prefix_path | [] | Additional prefixes for cmake to search before builtin paths | yes | no | | stdsplit | true | Split stdout and stderr in test logs | no | no | -| strip | false | Strip targets on install | no | no | -| unity {on, off, subprojects} | off | Unity build | no | no | -| unity_size {>=2} | 4 | Unity file block size | no | no | -| warning_level {0, 1, 2, 3, everything} | 1 | Set the warning level. From 0 = compiler default to everything = highest | no | yes | -| werror | false | Treat warnings as errors | no | yes | +| strip | false | Strip targets on install | no | 1.8.0 | +| unity {on, off, subprojects} | off | Unity build | no | 1.8.0 | +| unity_size {>=2} | 4 | Unity file block size | no | 1.8.0 | +| warning_level {0, 1, 2, 3, everything} | 1 | Set the warning level. From 0 = compiler default to everything = highest | no | 0.56.0 | +| werror | false | Treat warnings as errors | no | 0.54.0 | | 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 | | vsenv | false | Activate Visual Studio environment | no | no | +| os2_emxomf | false | Use OMF format on OS/2 | no | no | (For the Rust language only, `warning_level=0` disables all warnings). @@ -150,6 +152,10 @@ the two-way mapping: All other combinations of `debug` and `optimization` set `buildtype` to `'custom'`. +Note that `-Ddebug=false` does not cause the compiler preprocessor macro +`NDEBUG` to be defined. +The macro can be defined using the base option `b_ndebug`, described below. + #### Details for `warning_level` Exact flags per warning level is compiler specific, but there is an approximate @@ -198,6 +204,16 @@ When `default_both_libraries` is 'auto', passing a [[@both_libs]] dependency in [[both_libraries]] will link the static dependency with the static lib, and the shared dependency with the shared lib. +#### Details for `os2_emxomf` + +The `--os2-emxomf` argument is supported since `1.10.0`, `-Dos2_emxomf=true` +syntax is supported since `1.10.0`. + +Setting the `os2_emxomf` option to `true` forces to use emxomf toolchains in +order to generate OMF files instead of aout toolchains. + +`os2_emxomf` is `false` by default. + ## Base options These are set in the same way as universal options, either by @@ -298,7 +314,10 @@ or compiler being used: | cpp_rtti | true | true, false | Whether to enable RTTI (runtime type identification) | | cpp_thread_count | 4 | integer value ≥ 0 | Number of threads to use with emcc when using threads | | cpp_winlibs | see below | free-form comma-separated list | Standard Windows libs to link against | +| cpp_importstd | false | true or false | Whether to use `import std` | | fortran_std | none | [none, legacy, f95, f2003, f2008, f2018] | Fortran language standard to use | +| rust_dynamic_std | false | true, false | Whether to link dynamically to the Rust standard library *(Added in 1.9.0)* | +| rust_nightly | auto | enabled, disabled, auto | Nightly Rust compiler (enabled=required, disabled=don't use nightly feature, auto=use nightly feature if available) *(Added in 1.10.0)* | | cuda_ccbindir | | filesystem path | CUDA non-default toolchain directory to use (-ccbin) *(Added in 0.57.1)* | The default values of `c_winlibs` and `cpp_winlibs` are in @@ -366,11 +385,10 @@ 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 and statically linking a subproject, -or when the main project must build with no warnings but some subprojects -cannot. +Several built-in options and all compiler options can be defined per subproject. +This is useful, for example, when building shared libraries in the main project +and statically linking 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 in the parent project by setting subproject's default_options (e.g. `subproject('foo', @@ -378,12 +396,35 @@ default_options: 'default_library=static')`), or by the user through the command line: `-Dfoo:default_library=static`. The value is overridden in this order: -- Value from parent project -- Value from subproject's default_options if set -- Value from subproject() default_options if set -- Value from command line if set - -Since *0.56.0* `warning_level` can also be defined per subproject. +- `opt=value` from parent project's `default_options` +- `opt=value` from subproject's `default_options` +- `opt=value` from machine file +- `opt=value` from command line +- `subp:opt=value` from parent project's default options +- `opt=value` from `subproject()` `default_options` +- `subp:opt=value` from machine file +- `subp:opt=value` from command line + +### Old behavior + +Between *0.54.0* and *1.7.x* only a few options could be defined per subproject: +* `default_library` and `werror` since *0.54.0*; +* `warning_level` since *0.56.0*; +* compiler options since *0.63.0* + +The value was overridden in this order: + +- `opt=value` from parent project's `default_options` +- `opt=value` from machine file +- `opt=value` from command line +- `opt=value` from subproject's `default_options` +- `subp:opt=value` from parent project's default options +- `opt=value` from `subproject()` `default_options` +- `subp:opt=value` from machine file +- `subp:opt=value` from command line + +In other word, the subproject's `default_options` had a *higher* priority +than `opt=value` from machine file or command line. ## Module options @@ -422,6 +463,7 @@ install prefix. For example: if the install prefix is `/usr` and the | platlibdir | | Directory path | Directory for site-specific, platform-specific files (Since 0.60.0) | | purelibdir | | Directory path | Directory for site-specific, non-platform-specific files (Since 0.60.0) | | allow_limited_api | true | true, false | Disables project-wide use of the Python Limited API (Since 1.3.0) | +| build_config | | File path | Specifies the Python build configuration file (PEP 739) (Since 1.10.0) | *Since 0.60.0* The `python.platlibdir` and `python.purelibdir` options are used by the python module methods `python.install_sources()` and diff --git a/docs/markdown/CMake-module.md b/docs/markdown/CMake-module.md index f8275c9..982fa35 100644 --- a/docs/markdown/CMake-module.md +++ b/docs/markdown/CMake-module.md @@ -138,8 +138,8 @@ and supports the following methods: `include_type` kwarg *(new in 0.56.0)* controls the include type of the returned dependency object similar to the same kwarg in the [[dependency]] function. - - `include_directories(target)` returns a Meson [[@inc]] - object for the specified target. Using this method is not necessary + - `include_directories(target)` returns an array of Meson [[@inc]] + objects for the specified target. Using this method is not necessary if the dependency object is used. - `target(target)` returns the raw build target. - `target_type(target)` returns the type of the target as a string diff --git a/docs/markdown/Codegen-module.md b/docs/markdown/Codegen-module.md new file mode 100644 index 0000000..0f6d524 --- /dev/null +++ b/docs/markdown/Codegen-module.md @@ -0,0 +1,144 @@ +--- +short-description: Common Code Generators Module +authors: + - name: Dylan Baker + email: dylan@pnwbakers.com + years: [2024, 2025] +... + +# Codegen Module + +*(New in 1.10.0)* + +This module provides wrappers around common code generators, such as flex/lex and yacc/bison. This purpose of this is to make it easier and more pleasant to use *common* code generators in a mesonic way. + +## Functions + +### lex() + +```meson +lex_gen = codegen.lex(implementations : ['flex', 'reflex'], flex_version : ['>= 2.6', '< 3'], reflex_version : '!= 1.4.2') +``` + +This function provides fine grained control over what implementation(s) and version(s) of lex are acceptable for a given project (These are set per-subproject). It returns a [new object](#lexgenerator), which can be used to generate code. + +It accepts the following keyword arguments: + + - `implementations`: a string array of acceptable implementations to use. May include: `lex`, `flex`, `reflex`, or `win_flex`. + - `lex_version`: a string array of version constraints to apply to the `lex` binary + - `flex_version`: a string array of version constraints to apply to the `flex` binary + - `reflex_version`: a string array of version constraints to apply to the `relex` binary + - `win_flex_version`: a string array of version constraints to apply to the `win_flex` binary + - `required`: A boolean or feature option + - `disabler`: Return a disabler if not found + - `native`: Is this generator for the host or build machine? + +### yacc() + +```meson +yacc = codegen.yacc(implementations : ['bison', 'win_bison']) +``` + +This function provides fine grained controls over which implementation(s) and version(s) of the parser generator to use. + +Accepts the following keyword arguments: + + - `implementations`: a string array of acceptable implementations to use. May include: `yacc`, `byacc`, `bison`, or `win_bison`. + - `yacc_version`: a string array of version constraints to apply to the `yacc` binary + - `byacc_version`: a string array of version constraints to apply to the `byacc` binary + - `bison_version`: a string array of version constraints to apply to the `bison` binary + - `win_bison_version`: a string array of version constraints to apply to the `win_bison` binary + - `required`: A boolean or feature option + - `disabler`: Return a disabler if not found + - `native`: Is this generator for the host or build machine? + +## Returned Objects + +### LexGenerator + +#### lex.implementation + +```meson +lex = codegen.lex() +impl = lex.implementation() +``` + +Returns the string name of the lex implementation chosen. May be one of: + +- lex +- flex +- reflex +- win_flex + +#### lex.generate + +```meson +lex = codegen.lex() +lex.generate('lexer.l') +``` + +This function wraps flex, lex, reflex (but not RE/flex), and win_flex (on Windows). When using win_flex it will automatically add the `--wincompat` argument. + +This requires an input file, which may be a string, File, or generated source. It additionally takes the following options keyword arguments: + +- `args`: An array of extra arguments to pass the lexer +- `plainname`: If set to true then `@PLAINNAME@` will be used as the source base, otherwise `@BASENAME@`. +- `source`: the name of the source output. If this is unset Meson will use `{base}.{ext}` with an extension of `cpp` if the input has an extension of `.ll`, or `c` otherwise, with base being determined by the `plainname` argument. +- `header`: The optional output name for a header file. If this is unset no header is added +- `table`: The optional output name for a table file. If this is unset no table will be generated + +The outputs will be in the form `source [header] [table]`, which means those can be accessed by indexing the output of the `lex` call: + +```meson +lex = codegen.lex() +l1 = lex.generate('lexer.l', header : '@BASENAME@.h', table : '@BASENAME@.tab.h') +headers = [l1[1], l1[2]] # [header, table] + +l2 = lex.generate('lexer.l', table : '@BASENAME@.tab.h') +table = l2[1] +``` + +### YaccGenerator + +#### yacc.implementation + +```meson +yacc = codegen.yacc() +impl = yacc.implementation() +``` + +Returns the string name of the yacc implementation chosen. May be one of: + +- yacc +- bison +- byacc +- win_bison + +#### yacc.generate + +```meson +yacc = codegen.yacc() +yacc.generate('parser.y') +``` + +This function wraps bison, yacc, byacc, and win_bison (on Windows), and attempts to abstract away the differences between them + +This requires an input file, which may be a string, File, or generated source. It additionally takes the following options keyword arguments: + +- `version`: Version constraints on the lexer +- `args`: An array of extra arguments to pass the lexer +- `plainname`: If set to true then `@PLAINNAME@` will be used as the source base, otherwise `@BASENAME@`. +- `source`: the name of the source output. If this is unset Meson will use `{base}.{ext}` with an extension of `cpp` if the input has an extension of `.yy` or `c` otherwise, with base being determined by the `plainname` argument. +- `header`: the name of the header output. If this is unset Meson will use `{base}.{ext}` with an extension of `hpp` if the input has an extension of `.yy` or `h` otherwise, with base being determined by the `plainname` argument. +- `locations`: The name of the locations file, if one is generated. Due to the way yacc works this must be duplicated in the file and in the command. + +The outputs will be in the form `source header [locations]`, which means those can be accessed by indexing the output of the `yacc` call: + +```meson +yacc = codegen.yacc() +p1 = yacc.generate('parser.y', header : '@BASENAME@.h', locations : 'locations.h') +headers = [p1[1], p1[2]] # [header, locations] + +p2 = yacc.generate('parser.yy', locations : 'locations.hpp') +locations = p2[1] +``` diff --git a/docs/markdown/Commands.md b/docs/markdown/Commands.md index 247f2d7..339dd93 100644 --- a/docs/markdown/Commands.md +++ b/docs/markdown/Commands.md @@ -493,6 +493,12 @@ or `--check-only` option). input instead of reading it from a file. This cannot be used with `--recursive` or `--inline` arguments. +*Since 1.9.0* Using `-` as source file with `--editor-config` now requires +`--source-file-path` argument to ensure consistent results. + +*Since 1.10.0* When `--check-diff` is specified, instead of silently exiting +with an error code, `meson format` will print a diff of the formatting changes. + #### Differences with `muon fmt` diff --git a/docs/markdown/Creating-releases.md b/docs/markdown/Creating-releases.md index 44c127e..7b97aec 100644 --- a/docs/markdown/Creating-releases.md +++ b/docs/markdown/Creating-releases.md @@ -104,7 +104,7 @@ following example. `meson.build`: ```meson project('tig', 'c', - version : run_command('version.sh', 'get-vcs').stdout.strip()) + version : run_command('version.sh', 'get-vcs').stdout().strip()) meson.add_dist_script('version.sh', 'set-dist', meson.project_version()) ``` diff --git a/docs/markdown/Cross-compilation.md b/docs/markdown/Cross-compilation.md index 64196f3..65daa22 100644 --- a/docs/markdown/Cross-compilation.md +++ b/docs/markdown/Cross-compilation.md @@ -139,6 +139,22 @@ 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. +Note that `exe_wrapper` in the cross file is handled separately +from the `exe_wrapper` argument in +[`add_test_setup`](Reference-manual_functions.md#add_test_setup_exe_wrapper) +and [`meson test --wrapper`](Unit-tests.md#other-test-options) +command line argument. Meson must have `exe_wrapper` specified in the +cross file or else it will skip tests that attempt to run cross +compiled binaries. Only the cross file `exe_wrapper` value will be +stored in the `MESON_EXE_WRAPPER` environment variable. If another +wrapper is given in the test setup with `exe_wrapper` or as a +`meson test --wrapper` command line argument, then meson will prepend +the additional wrapper before the cross file wrapper like the +following command: +``` +[prepend_wrapper] <cross_file_wrapper> <exe_binary> <args...> +``` + ### Properties In addition to the properties allowed in [all machine @@ -173,12 +189,12 @@ remember to specify the args as an array and not as a single string *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 +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 +*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. @@ -357,7 +373,7 @@ myvar = meson.get_external_property('somekey') 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 +`$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 diff --git a/docs/markdown/Dependencies.md b/docs/markdown/Dependencies.md index f7bf901..4d94d58 100644 --- a/docs/markdown/Dependencies.md +++ b/docs/markdown/Dependencies.md @@ -388,6 +388,9 @@ additional toolkit libraries that need to be explicitly linked to. If the CUDA Toolkit cannot be found in the default paths on your system, you can set the path using `CUDA_PATH` explicitly. +Cuda does not honor the `prefer_static` option, and will link statically unless +the `static` keyword argument is set to `false`. + ## CUPS `method` may be `auto`, `config-tool`, `pkg-config`, `cmake` or `extraframework`. diff --git a/docs/markdown/Design-rationale.md b/docs/markdown/Design-rationale.md index 4133979..c520773 100644 --- a/docs/markdown/Design-rationale.md +++ b/docs/markdown/Design-rationale.md @@ -34,9 +34,9 @@ may not work. In some cases the executable file is a binary whereas at other times it is a wrapper shell script that invokes the real binary which resides in a hidden subdirectory. GDB invocation fails if the binary is a script but succeeds if it is not. The user has to remember -the type of each one of his executables (which is an implementation -detail of the build system) just to be able to debug them. Several -other such pain points can be found in [this blog +the type of each executable (which is an implementation detail of the +build system) just to be able to debug them. Several other such pain +points can be found in [this blog post](http://voices.canonical.com/jussi.pakkanen/2011/09/13/autotools/). Given these idiosyncrasies it is no wonder that most people don't want @@ -132,7 +132,7 @@ and so on. Sometimes you just have to compile files with only given compiler flags and no others, or install files in weird places. The system must -allow the user to do this if he really wants to. +allow the user to do this. Overview of the solution -- @@ -151,7 +151,7 @@ passing around compiler flags and linker flags. In the proposed system the user just declares that a given build target uses a given external dependency. The build system then takes care of passing all flags and settings to their proper locations. This means that the user can focus -on his own code rather than marshalling command line arguments from +on their own code rather than marshalling command line arguments from one place to another. A DSL is more work than the approach taken by SCons, which is to diff --git a/docs/markdown/Fs-module.md b/docs/markdown/Fs-module.md index 7ba4832..91c706e 100644 --- a/docs/markdown/Fs-module.md +++ b/docs/markdown/Fs-module.md @@ -206,13 +206,26 @@ 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 +suffix. ```meson fs.stem('foo/bar/baz.dll') # baz fs.stem('foo/bar/baz.dll.a') # baz.dll ``` +### suffix + +*since 1.9.0* + +Returns the last dot-separated portion of the final component of the path +including the dot, if any. + +```meson +fs.suffix('foo/bar/baz.dll') # .dll +fs.suffix('foo/bar/baz.dll.a') # .a +fs.suffix('foo/bar') # (empty) +``` + ### read - `read(path, encoding: 'utf-8')` *(since 0.57.0)*: return a [string](Syntax.md#strings) with the contents of the given `path`. diff --git a/docs/markdown/Getting-meson_zh.md b/docs/markdown/Getting-meson_zh.md index 4a4cb34..da0bdd5 100644 --- a/docs/markdown/Getting-meson_zh.md +++ b/docs/markdown/Getting-meson_zh.md @@ -1,6 +1,6 @@ # 获取Meson -Meson基于Python3运行，要求Python版本3.5以上。 如果你的操作系统提供包管理器, 你应该用包管理器安装meson；如果没有包管理器，你应该在[Python主页]下载合适的Python3。相关请参阅[特殊平台的安装特例](#特殊平台的安装特例). +Meson基于Python3运行，要求Python版本3.7以上。 如果你的操作系统提供包管理器, 你应该用包管理器安装python；如果没有包管理器，你应该在[Python主页]下载合适的Python3。相关请参阅[特殊平台的安装特例](#特殊平台的安装特例). ## 下载Meson diff --git a/docs/markdown/Gnome-module.md b/docs/markdown/Gnome-module.md index e8953ef..84bcc61 100644 --- a/docs/markdown/Gnome-module.md +++ b/docs/markdown/Gnome-module.md @@ -280,6 +280,8 @@ one XML file. * `object_manager`: *(Added 0.40.0)* if true generates object manager code * `annotations`: *(Added 0.43.0)* list of lists of 3 strings for the annotation for `'ELEMENT', 'KEY', 'VALUE'` * `docbook`: *(Added 0.43.0)* prefix to generate `'PREFIX'-NAME.xml` docbooks +* `rst`: *(Added 1.9.0)* prefix to generate `'PREFIX'-NAME.rst` reStructuredTexts +* `markdown`: *(Added 1.9.0)* prefix to generate `'PREFIX'-NAME.md` markdowns * `build_by_default`: causes, when set to true, to have this target be built by default, that is, when invoking plain `meson compile`, the default value is true for all built target types @@ -289,8 +291,9 @@ one XML 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. +The list can then contain other custom targets for the generated documentation +files depending if the keyword argument is passed (in order): the docbook +target, the reStructuredText target and the markdown target. Earlier versions return a single custom target representing all the outputs. Generally, you should just add this list of targets to a top diff --git a/docs/markdown/Installing.md b/docs/markdown/Installing.md index 0a7ca9f..5c34eba 100644 --- a/docs/markdown/Installing.md +++ b/docs/markdown/Installing.md @@ -170,6 +170,7 @@ time, please help extending the list of well known categories. * `pkgconfig.generate()`, * `gnome.generate_gir()` - `.gir` file, * `gnome.generate_vapi()` - `.vapi` file (*Since 0.64.0*), + * `gnome.generate_vapi()` - `.deps` file (*Since 1.9.1*), * Files installed into `libdir` and with `.a` or `.pc` extension, * File installed into `includedir`, * Generated header files installed with `gnome.compile_resources()`, diff --git a/docs/markdown/Overview.md b/docs/markdown/Overview.md index 7bee937..66758fd 100644 --- a/docs/markdown/Overview.md +++ b/docs/markdown/Overview.md @@ -6,11 +6,11 @@ short-description: Overview of the Meson build system Meson is a build system that is designed to be as user-friendly as possible without sacrificing performance. The main tool for this is a -custom language that the user uses to describe the structure of his -build. The main design goals of this language has been simplicity, -clarity and conciseness. Much inspiration was drawn from the Python -programming language, which is considered very readable, even to -people who have not programmed in Python before. +custom language used to describe the structure of the build. The main +design goals of this language have been simplicity, clarity and +conciseness. Much inspiration was drawn from the Python programming +language, which is considered very readable, even to people who have +not programmed in Python before. Another main idea has been to provide first class support for modern programming tools and best practices. These include features as varied diff --git a/docs/markdown/Pkgconfig-module.md b/docs/markdown/Pkgconfig-module.md index 80882cb..eb41026 100644 --- a/docs/markdown/Pkgconfig-module.md +++ b/docs/markdown/Pkgconfig-module.md @@ -44,9 +44,12 @@ keyword arguments. `${PREFIX}/include/foobar-1`, the correct value for this argument would be `foobar-1` - `requires` list of strings, pkgconfig-dependencies or libraries that - `pkgconfig.generate()` was used on to put in the `Requires` field + `pkgconfig.generate()` was used on to put in the `Requires` field. + *Since 1.9.0* internal dependencies are supported if `pkgconfig.generate()` + was used on the underlying library. - `requires_private` the same as `requires` but for the `Requires.private` field - `url` a string with a url for the library +- `license` (*Since 1.9.0*) a string with a SPDX license to add to the generated file. - `variables` a list of strings with custom variables to add to the generated file. The strings must be in the form `name=value` and may reference other pkgconfig variables, @@ -90,6 +93,9 @@ application. That will cause pkg-config to prefer those builddir. This is an experimental feature provided on a best-effort basis, it might not work in all use-cases. +*Since 1.9.0* you can specify a license identifier. To use the current project +licence, simply use `license: meson.project_license()` as argument to `generate()`. + ### Implicit dependencies The exact rules followed to find dependencies that are implicitly diff --git a/docs/markdown/Qt6-module.md b/docs/markdown/Qt6-module.md index ebe42a5..972a6a9 100644 --- a/docs/markdown/Qt6-module.md +++ b/docs/markdown/Qt6-module.md @@ -134,7 +134,7 @@ lrelease, it takes no positional arguments, and the following keyword arguments: - `qresource` string: rcc source file to extract ts_files from; cannot be used with ts_files kwarg. - `rcc_extra_arguments` string[]: any additional arguments to `rcc` (optional), - when used with `qresource. + when used with `qresource`. Returns either: a list of custom targets for the compiled translations, or, if using a `qresource` file, a single custom target diff --git a/docs/markdown/Reference-tables.md b/docs/markdown/Reference-tables.md index a5d2785..4a3bf28 100644 --- a/docs/markdown/Reference-tables.md +++ b/docs/markdown/Reference-tables.md @@ -42,6 +42,7 @@ These are return values of the `get_id` (Compiler family) and | ti | Texas Instruments C/C++ Compiler | | | valac | Vala compiler | | | xc16 | Microchip XC16 C compiler | | +| xc32-gcc | Microchip XC32 C/C++ compiler | gcc | | cython | The Cython compiler | | | nasm | The NASM compiler (Since 0.64.0) | | | yasm | The YASM compiler (Since 0.64.0) | | @@ -58,6 +59,7 @@ These are return values of the `get_linker_id` method in a compiler object. | Value | Linker family | | ----- | --------------- | | ld.bfd | The GNU linker | +| ld.eld | Qualcomm's embedded linker | | ld.gold | The GNU gold linker | | ld.lld | The LLVM linker, with the GNU interface | | ld.mold | The fast MOLD linker | @@ -72,6 +74,7 @@ These are return values of the `get_linker_id` method in a compiler object. | optlink | optlink (used with DMD) | | rlink | The Renesas linker, used with CCrx only | | xc16-ar | The Microchip linker, used with XC16 only | +| ld.xc32 | The Microchip linker, used with XC32 only | | ar2000 | The Texas Instruments linker, used with C2000 only | | ti-ar | The Texas Instruments linker | | ar6000 | The Texas Instruments linker, used with C6000 only | @@ -125,6 +128,7 @@ set in the cross file. | msp430 | 16 bit MSP430 processor | | parisc | HP PA-RISC processor | | pic24 | 16 bit Microchip PIC24 | +| pic32 | 32 bit Microchip PIC32 | | ppc | 32 bit PPC processors | | ppc64 | 64 bit PPC processors | | riscv32 | 32 bit RISC-V Open ISA | @@ -171,6 +175,7 @@ These are provided by the `.system()` method call. | openbsd | | | windows | Native Windows (not Cygwin or MSYS2) | | sunos | illumos and Solaris | +| os/2 | OS/2 | Any string not listed above is not guaranteed to remain stable in future releases. @@ -292,6 +297,7 @@ which are supported by GCC, Clang, and other compilers. | const | | constructor | | constructor_priority | +| counted_by⁸ | | deprecated | | destructor | | error | @@ -347,6 +353,8 @@ which are supported by GCC, Clang, and other compilers. ⁷ *New in 1.5.0* +⁸ *New in 1.10.0* + ### MSVC __declspec These values are supported using the MSVC style `__declspec` annotation, diff --git a/docs/markdown/Release-notes-for-0.38.0.md b/docs/markdown/Release-notes-for-0.38.0.md index 5aaca0a..7be99ab 100644 --- a/docs/markdown/Release-notes-for-0.38.0.md +++ b/docs/markdown/Release-notes-for-0.38.0.md @@ -106,7 +106,7 @@ the check is now ~40% faster. ## Array indexing now supports fallback values The second argument to the array -[[list.get]] function is now returned +[[array.get]] function is now returned if the specified index could not be found ```meson diff --git a/docs/markdown/Release-notes-for-1.10.0.md b/docs/markdown/Release-notes-for-1.10.0.md new file mode 100644 index 0000000..aa4d133 --- /dev/null +++ b/docs/markdown/Release-notes-for-1.10.0.md @@ -0,0 +1,289 @@ +--- +title: Release 1.10.0 +short-description: Release notes for 1.10.0 +... + +# New features + +Meson 1.10.0 was released on 08 December 2025 +## Support for the `counted_by` attribute + +`compiler.has_function_attribute()` now supports for the new `counted_by` +attribute. + +## Added a `values()` method for dictionaries + +Mesons built-in [[@dict]] type now supports the [[dict.values]] method +to retrieve the dictionary values as an array, analogous to the +[[dict.keys]] method. + +```meson +dict = { 'b': 'world', 'a': 'hello' } + +[[#dict.keys]] # Returns ['a', 'b'] +[[#dict.values]] # Returns ['hello', 'world'] +``` + +## Add cmd_array method to ExternalProgram + +Added a new `cmd_array()` method to the `ExternalProgram` object that returns +an array containing the command(s) for the program. This is particularly useful +in cases like pyInstaller where the Python command is `meson.exe runpython`, +and the full path should not be used but rather the command array. + +The method returns a list of strings representing the complete command needed +to execute the external program, which may differ from just the full path +returned by `full_path()` in cases where wrapper commands or interpreters are +involved. + +## Microchip XC32 compiler support + +The Microchip XC32 compiler is now supported. + +## Added OS/2 support + +Meson now supports OS/2 system. Especially, `shortname` kwarg and +`os2_emxomf` builtin option are introduced. + +`shortname` is used to specify a short DLL name fitting to a 8.3 rule. + +```meson +lib = library('foo_library', + ... + shortname: 'foo', + ... +) +``` + +This will generate `foo.dll` not `foo_library.dll` on OS/2. If +`shortname` is not used, `foo_libr.dll` which is truncated up to 8 +characters is generated. + +`os2_emxomf` is used to generate OMF files with OMF tool-chains. + +``` +meson setup --os2-emxomf builddir +``` + +This will generate OMF object files and `.lib` library files. If +`--os2-emxomf` is not used, AOUT object files and `.a` library files are +generated. + +## Android cross file generator + +The `env2mfile` command now supports a `--android` argument. When +specified, it tells the cross file generator to create cross files for +all Android toolchains located on the current machines. + +This typically creates many files, so the `-o` argument specifies the +output directory. A typical use case goes like this: + +``` +meson env2mfile --android -o androidcross +meson setup --cross-file \ + androidcross/android-29.0.14033849-android35-aarch64-cross.txt \ + builddir +``` + +## Array `.slice()` method + +Arrays now have a `.slice()` method which allows for subsetting of arrays. + +## `-Db_vscrt` on clang + +`-Db_vscrt` will now link the appropriate runtime library, and set +the appropriate preprocessor symbols, also when the compiler is clang. +This is only supported when using `link.exe` or `lld-link.exe` as the +linker. + +## Added `build_subdir` arg to various targets + +`custom_target()`, `build_target()` and `configure_file()` now support +the `build_subdir` argument. This directs Meson to place the build +result within the specified sub-directory path of the build directory. + +```meson +configure_file(input : files('config.h.in'), + output : 'config.h', + build_subdir : 'config-subdir', + install_dir : 'share/appdir', + configuration : conf) +``` + +This places the build result, `config.h`, in a sub-directory named +`config-subdir`, creating it if necessary. To prevent collisions +within the build directory, `build_subdir` is not allowed to match a +file or directory in the source directory nor contain '..' to refer to +the parent of the build directory. `build_subdir` does not affect the +install directory path at all; `config.h` will be installed as +`share/appdir/config.h`. `build_subdir` may contain multiple levels of +directory names. + +This allows construction of files within the build system that have +any required trailing path name components as well as building +multiple files with the same basename from the same source directory. + +## Support for Cargo workspaces + +When parsing `Cargo.toml` files, Meson now recognizes workspaces +and will process all the required members and any requested optional +members of the workspace. + +For the time being it is recommended to regroup all Cargo dependencies inside a +single workspace invoked from the main Meson project. When invoking multiple +different Cargo subprojects from Meson, feature resolution of common +dependencies might be wrong. + +## Experimental Codegen module + +A new module wrapping some common code generators has been added. Currently it supports lex/flex and yacc/bison. + +## Methods from compiler object now accept strings for include_directories + +The various [[@compiler]] methods with a `include_directories` keyword argument +now accept strings or array of strings, in addition to [[@inc]] objects +generated from [[include_directories]] function, as it was already the case for +[[build_target]] family of functions. + +## `meson format` has a new `--check-diff` option + +When using `meson format --check-only` to verify formatting in CI, it would +previously silently exit with an error code if the code was not formatted +correctly. + +A new `--check-diff` option has been added which will instead print a diff of +the required changes and then exit with an error code. + +## `-Db_thinlto_cache` now supported for GCC + +`-Db_thinlto_cache` is now supported for GCC 15's incremental LTO, as is +`-Db_thinlto_cache_dir`. + +## Using `meson.get_compiler()` to get a language from another project is marked broken + +Meson currently will return a compiler instance from the `meson.get_compiler()` +call, if that language has been initialized in any project. This can result in +situations where a project can only work as a subproject, or if a dependency is +provided by a subproject rather than by a pre-built dependency. + +## Experimental C++ import std support + +**Note**: this feature is experimental and not guaranteed to be + backwards compatible or even exist at all in future Meson releases. + +Meson now supports `import std`, a new, modular way of using the C++ +standard library. This support is enabled with the new `cpp_importstd` +option. It defaults to `false`, but you can set it to `true` either +globally or per-target using `override_options` in the usual way. + +The implementation has many limitations. The biggest one is that the +same module file is used on _all_ targets. That means you can not mix +multiple different C++ standards versions as the compiled module file +can only be used with the same compiler options as were used to build +it. This feature only works with the Ninja backend. + +As `import std` is a major new feature in compilers, expect to +encounter toolchain issues when using it. For an example [see +here](https://gcc.gnu.org/bugzilla/show_bug.cgi?id=122614). + +## Common `Cargo.lock` for all Cargo subprojects + +Whenever Meson finds a `Cargo.lock` file in the toplevel directory +of the project, it will use it to resolve the versions of Cargo +subprojects in preference to per-subproject `Cargo.lock` files. +Per-subproject lock files are only used if the invoking project +did not have a `Cargo.lock` file itself. + +If you wish to experiment with Cargo subprojects, it is recommended +to use `cargo` to set up `Cargo.lock` and `Cargo.toml` files, +encompassing all Rust targets, in the toplevel source directory. +Cargo subprojects remain unstable and subject to change. + +## Add a configure log in meson-logs + +Add a second log file `meson-setup.txt` which contains the configure logs +displayed on stdout during the meson `setup` stage. +It allows user to navigate through the setup logs without searching in the terminal +or the extensive information of `meson-log.txt`. + +## Added new `namingscheme` option + +Traditionally Meson has named output targets so that they don't clash +with each other. This has meant, among other things, that on Windows +Meson uses a nonstandard `.a` suffix for static libraries because both +static libraries and import libraries have the suffix `.lib`. + +There is now an option `namingscheme` that can be set to +`platform`. This new platform native naming scheme that replicates +what Rust does. That is, shared libraries on Windows get a suffix +`.dll`, static libraries get `.lib` and import libraries have the name +`.dll.lib`. + +We expect to change the default value of this option to `platform` in +a future major version. Until that happens we reserve the right to +alter how `platform` actually names its output files. + +## Rewriter improvements + +The [rewriter](Rewriter.md) added support for writing the `project()` +`license_files` argument and for reading dict-valued kwargs. + +It also removed the unused but mandatory `value` arguments to the +`default-options delete` and `kwargs delete` CLI subcommands. To allow +scripts to continue supporting previous releases, these arguments are +still accepted (with a warning) if they're all equal to the empty string. + +## Passing `-C default-linker-libraries` to rustc + +When calling rustc, Meson now passes the `-C default-linker-libraries` option. +While rustc passes the necessary libraries for Rust programs, they are rarely +enough for mixed Rust/C programs. + +## `rustc` will receive `-C embed-bitcode=no` and `-C lto` command line options + +With this release, Meson passes command line arguments to `rustc` to +enable LTO when the `b_lto` built-in option is set to true. As an +optimization, Meson also passes `-C embed-bitcode=no` when LTO is +disabled; note that this is incompatible with passing `-C lto` via +`rust_args`. + +## New method to handle GNU and Windows symbol visibility for C/C++/ObjC/ObjC++ + +Defining public API of a cross platform C/C++/ObjC/ObjC++ library is often +painful and requires copying macro snippets into every projects, typically using +`__declspec(dllexport)`, `__declspec(dllimport)` or +`__attribute__((visibility("default")))`. + +Meson can now generate a header file that defines exactly what's needed for +all supported platforms: +[`snippets.symbol_visibility_header()`](Snippets-module.md#symbol_visibility_header). + +## Vala BuildTarget dependency enhancements + +A BuildTarget that has Vala sources can now get a File dependency for its +generated header, vapi, and gir files. + +```meson +lib = library('foo', 'foo.vala') +lib_h = lib.vala_header() +lib_s = static_lib('static', 'static.c', lib_h) + +lib_vapi = lib.vala_vapi() + +custom_target( + 'foo-typelib', + command : ['g-ir-compiler', '--output', '@OUTPUT@', '@INPUT@'], + input : lib.vala_gir(), + output : 'Foo-1.0.typelib' +) +``` + +`static.c` will not start compilation until `lib.h` is generated. + +## `i18n.xgettext` now accepts CustomTarget and CustomTargetIndex as sources + +Previously, [[@custom_tgt]] were accepted but silently ignored, and +[[@custom_idx]] were not accepted. + +Now, they both can be used, and the generated outputs will be scanned to extract +translation strings. diff --git a/docs/markdown/Release-notes-for-1.8.0.md b/docs/markdown/Release-notes-for-1.8.0.md new file mode 100644 index 0000000..4289e91 --- /dev/null +++ b/docs/markdown/Release-notes-for-1.8.0.md @@ -0,0 +1,134 @@ +--- +title: Release 1.8.0 +short-description: Release notes for 1.8.0 +... + +# New features + +Meson 1.8.0 was released on 28 April 2025 +## New argument `android_exe_type` for executables + +Android application executables actually need to be linked +as a shared object, which is loaded from a pre-warmed JVM. +Meson projects can now specify a new argument `android_exe_type` +and set it to `application`, in order produce such a shared library +only on Android targets. + +This makes it possible to use the same `meson.build` file +for both Android and non-Android systems. + +## Changes to the b_sanitize option + +Before 1.8 the `b_sanitize` option was a combo option, which is an enumerated +set of values. In 1.8 this was changed to a free-form array of options where +available sanitizers are not hardcoded anymore but instead verified via a +compiler check. + +This solves a number of longstanding issues such as: + + - Sanitizers may be supported by a compiler, but not on a specific platform + (OpenBSD). + - New sanitizers are not recognized by Meson. + - Using sanitizers in previously-unsupported combinations. + +To not break backwards compatibility, calling `get_option('b_sanitize')` +continues to return the configured value as a string, with a guarantee that +`address,undefined` remains ordered. + +## New C standard `c2y` (and `gnu2y`) + +The `c2y` standard and its companion `gnu2y` are now supported +when using either Clang 19.0.0 or newer, or GCC 15.0.0 or newer. + +## i18n module xgettext + +There is a new `xgettext` function in `i18n` module that acts as a +wrapper around `xgettext`. It allows to extract strings to translate from +source files. + +This function is convenient, because: +- It can find the sources files from a build target; +- It will use an intermediate file when the number of source files is too + big to be handled directly from the command line; +- It is able to get strings to translate from the dependencies of the given + targets. + +## `version_compare` now accept multiple compare strings + +Is it now possible to compare version against multiple values, to check for +a range of version for instance. + +```meson +'1.5'.version_compare('>=1', '<2') +``` + +## Improvements to Objective-C and Objective-C++ + +Meson does not assume anymore that gcc/g++ always support +Objective-C and Objective-C++, and instead checks that they +can actually do a basic compile. + +Furthermore, Objective-C and Objective-C++ now support the +same language standards as C and C++ respectively. + +## Per project subproject options rewrite + +You can now define per-subproject values for all shared configuration +options. As an example you might want to enable optimizations on only +one subproject: + + meson configure -Dnumbercruncher:optimization=3 + +Subproject specific values can be removed with -U + + meson configure -Unumbercruncher:optimization + +This is a major change in how options are handled, and the +implementation will evolve over the next few releases of Meson. If +this change causes an error in your builds, please [report an issue on +GitHub](https://github.com/mesonbuild/meson/issues/new). + +We have tried to keep backwards compatibility as much as possible, but +this may lead to some build breakage. + +## `objects` added correctly to Rust executables + +Any objects included in a Rust executable were previously ignored. They +are now added correctly. + +## `rust.test` now supports `link_whole` + +The `test` function in the `rust` module now supports the `link_whole` +keyword argument in addition to `link_with` and `dependencies`. + +## Meson can run "rustdoc" on Rust projects + +Meson now defines a `rustdoc` target if the project +uses the Rust programming language. The target runs rustdoc on all Rust +sources, using the `rustdoc` program from the same Rust toolchain as the +`rustc` compiler. + +## The Wayland module is stable + +The Wayland module has been tested in several projects and had the +last breaking change in Meson 0.64.0; it is now marked as stable. + +## New `swift_std` compiler option + +A new compiler option allows to set the language version that is passed +to swiftc (`none`, `4`, `4.2`, `5` or `6`). + +## New option to execute a slice of tests + +When tests take a long time to run a common strategy is to slice up the tests +into multiple sets, where each set is executed on a separate machine. You can +now use the `--slice i/n` argument for `meson test` to create `n` slices and +execute the `ith` slice. + +## Valgrind now fails tests if errors are found + +Valgrind does not reflect an error in its exit code by default, meaning +a test may silently pass despite memory errors. Meson now exports +`VALGRIND_OPTS` such that Valgrind will exit with status 1 to indicate +an error if `VALGRIND_OPTS` is not set in the environment. + diff --git a/docs/markdown/Release-notes-for-1.9.0.md b/docs/markdown/Release-notes-for-1.9.0.md new file mode 100644 index 0000000..aad105f --- /dev/null +++ b/docs/markdown/Release-notes-for-1.9.0.md @@ -0,0 +1,138 @@ +--- +title: Release 1.9.0 +short-description: Release notes for 1.9.0 +... + +# New features + +Meson 1.9.0 was released on 24 August 2025 +## Array `.flatten()` method + +Arrays now have a `.flatten()` method, which turns nested arrays into a single +flat array. This provides the same effect that Meson often does to arrays +internally, such as when passed to most function arguments. + +## `clang-tidy`'s auto-generated targets correctly select source files + +In previous versions, the target would run `clang-tidy` on _every_ C-like source files (.c, .h, .cpp, .hpp). It did not work correctly because some files, especially headers, are not intended to be consumed as is. + +It will now run only on source files participating in targets. + +## Added Qualcomm's embedded linker, eld + +Qualcomm recently open-sourced their embedded linker. +https://github.com/qualcomm/eld + +Meson users can now use this linker. + +## Added suffix function to the FS module + +The basename and stem were already available. For completeness, expose also the +suffix. + +## Support response files for custom targets + +When using the Ninja backend, Meson can now pass arguments to supported tools +through response files. + +In this release it's enabled only for the Gnome module, fixing calling +`gnome.mkenums()` with a large set of files on Windows (requires +Glib 2.59 or higher). + +## meson format now has a --source-file-path argument when reading from stdin + +This argument is mandatory to mix stdin reading with the use of editor config. +It allows to know where to look for the .editorconfig, and to use the right +section of .editorconfig based on the parsed file name. + +## Added license keyword to pkgconfig.generate + +When specified, it will add a `License:` attribute to the generated .pc file. + +## pkgconfig.generate supports internal dependencies in `requires` + +Internal dependencies can now be specified to `requires` if +pkgconfig.generate was called on the underlying library. + +## New experimental option `rust_dynamic_std` + +A new option `rust_dynamic_std` can be used to link Rust programs so +that they use a dynamic library for the Rust `libstd`. + +Right now, `staticlib` crates cannot be produced if `rust_dynamic_std` is +true, but this may change in the future. + +## Rust and non-Rust sources in the same target + +Meson now supports creating a single target with Rust and non Rust +sources mixed together. In this case, if specified, `link_language` +must be set to `rust`. + +## Explicitly setting Swift module name is now supported + +It is now possible to set the Swift module name for a target via the +*swift_module_name* target kwarg, overriding the default inferred from the +target name. + +```meson +lib = library('foo', 'foo.swift', swift_module_name: 'Foo') +``` + +## Top-level statement handling in Swift libraries + +The Swift compiler normally treats modules with a single source +file (and files named main.swift) to run top-level code at program +start. This emits a main symbol which is usually undesirable in a +library target. Meson now automatically passes the *-parse-as-library* +flag to the Swift compiler in case of single-file library targets to +disable this behavior unless the source file is called main.swift. + +## Swift compiler receives select C family compiler options + +Meson now passes select few C family (C/C++/Obj-C/Obj-C++) compiler +options to the Swift compiler, notably *-std=*, in order to improve +the compatibility of C code as interpreted by the C compiler and the +Swift compiler. + +NB: This does not include any of the options set in the target's +c_flags. + +## Swift/C++ interoperability is now supported + +It is now possible to create Swift executables that can link to C++ or +Objective-C++ libraries. To enable this feature, set the target kwarg +_swift\_interoperability\_mode_ to 'cpp'. + +To import C++ code, specify a bridging header in the Swift target's +sources, or use another way such as adding a directory containing a +Clang module map to its include path. + +Note: Enabling C++ interoperability in a library target is a breaking +change. Swift libraries that enable it need their consumers to enable +it as well, as per [the Swift documentation][1]. + +Swift 5.9 is required to use this feature. Xcode 15 is required if the +Xcode backend is used. + +```meson +lib = static_library('mylib', 'mylib.cpp') +exe = executable('prog', 'main.swift', 'mylib.h', link_with: lib, swift_interoperability_mode: 'cpp') +``` + +[1]: https://www.swift.org/documentation/cxx-interop/project-build-setup/#vending-packages-that-enable-c-interoperability + +## Support for MASM in Visual Studio backends + +Previously, assembling `.masm` files with Microsoft's Macro Assembler is only +available on the Ninja backend. This now also works on Visual Studio backends. + +Note that building ARM64EC code using `ml64.exe` is currently unimplemented in +both of the backends. If you need mixing x64 and Arm64 in your project, please +file an issue on GitHub. + +## Limited support for WrapDB v1 + +WrapDB v1 has been discontinued for several years, Meson will now print a +deprecation warning if a v1 URL is still being used. Wraps can be updated to +latest version using `meson wrap update` command. + diff --git a/docs/markdown/Rewriter.md b/docs/markdown/Rewriter.md index 82f8635..546666f 100644 --- a/docs/markdown/Rewriter.md +++ b/docs/markdown/Rewriter.md @@ -94,7 +94,8 @@ 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> ... +meson rewrite kwargs set <function type> <function ID> <key1> <value1> <key2> <value2> ... +meson rewrite kwargs delete <function type> <function ID> <key1> <key2> ... ``` For instance, setting the project version can be achieved with this command: @@ -116,14 +117,23 @@ 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. +*Before 1.10.0*, the `delete` command expected `<key> <value>` pairs as +in `set`; the `<value>` was ignored. For backward compatibility, Meson +accepts this syntax with a warning if all `<value>`s are the empty string. + ### Setting the project default options For setting and deleting default options, use the following command: ```bash -meson rewrite default-options {set/delete} <opt1> <value1> <opt2> <value2> ... +meson rewrite default-options set <opt1> <value1> <opt2> <value2> ... +meson rewrite default-options delete <opt1> <opt2> ... ``` +*Before 1.10.0*, the `delete` command expected `<opt> <value>` pairs as +in `set`; the `<value>` was ignored. For backward compatibility, Meson +accepts this syntax with a warning if all `<value>`s are the empty string. + ## Limitations Rewriting a Meson file is not guaranteed to keep the indentation of @@ -229,6 +239,9 @@ The format for the type `target` is defined as follows: } ``` +For operation `delete`, the values of the `options` can be anything +(including `null`). + ### Default options modification format The format for the type `default_options` is defined as follows: @@ -246,7 +259,7 @@ The format for the type `default_options` is defined as follows: ``` For operation `delete`, the values of the `options` can be anything -(including `null`) +(including `null`). ## Extracting information diff --git a/docs/markdown/Rust-module.md b/docs/markdown/Rust-module.md index 35eaf39..5ce0fdc 100644 --- a/docs/markdown/Rust-module.md +++ b/docs/markdown/Rust-module.md @@ -137,7 +137,7 @@ were never turned on by Meson. ```ini [properties] -bindgen_clang_arguments = ['-target', 'x86_64-linux-gnu'] +bindgen_clang_arguments = ['--target', 'x86_64-linux-gnu'] ``` ### proc_macro() diff --git a/docs/markdown/Rust.md b/docs/markdown/Rust.md index d30fe68..67bbdec 100644 --- a/docs/markdown/Rust.md +++ b/docs/markdown/Rust.md @@ -27,14 +27,20 @@ feature is stabilized. ## Mixing Rust and non-Rust sources -Meson currently does not support creating a single target with Rust and non Rust -sources mixed together, therefore one must compile multiple libraries and link -them. +*(Since 1.9.0)* Rust supports mixed targets, but only supports using +`rustc` as the linker for such targets. If you need to use a non-Rust +linker, or support Meson < 1.9.0, see below. + +Until Meson 1.9.0, Meson did not support creating a single target with +Rust and non Rust sources mixed together. One had to compile a separate +Rust `static_library` or `shared_library`, and link it into the C build +target (e.g., a library or an executable). ```meson rust_lib = static_library( 'rust_lib', sources : 'lib.rs', + rust_abi: 'c', ... ) @@ -44,7 +50,6 @@ c_lib = static_library( link_with : rust_lib, ) ``` -This is an implementation detail of Meson, and is subject to change in the future. ## Mixing Generated and Static sources @@ -83,7 +88,7 @@ Meson will generate a `rust-project.json` file in the root of the build directory if there are any rust targets in the project. Most IDEs will need to be configured to use the file as it's not in the source root (Meson does not write files into the source directory). [See the upstream -docs](https://rust-analyzer.github.io/manual.html#non-cargo-based-projects) for +docs](https://rust-analyzer.github.io/book/non_cargo_based_projects.html) for more information on how to configure that. ## Linking with standard libraries @@ -93,3 +98,11 @@ target is a proc macro or dylib, or it depends on a dylib, in which case [`-C prefer-dynamic`](https://doc.rust-lang.org/rustc/codegen-options/index.html#prefer-dynamic) will be passed to the Rust compiler, and the standard libraries will be dynamically linked. + +## Multiple targets for the same crate name + +For library targets that have `rust_abi: 'rust'`, the crate name is derived from the +target name. First, dashes, spaces and dots are replaced with underscores. Second, +*since 1.10.0* anything after the first `+` is dropped. This allows creating multiple +targets for the same crate name, for example when the same crate is built multiple +times with different features, or for both the build and the host machine. diff --git a/docs/markdown/Snippets-module.md b/docs/markdown/Snippets-module.md new file mode 100644 index 0000000..15d5e9f --- /dev/null +++ b/docs/markdown/Snippets-module.md @@ -0,0 +1,111 @@ +--- +short-description: Code snippets module +... + +# Snippets module + +*(new in 1.10.0)* + +This module provides helpers to generate commonly useful code snippets. + +## Functions + +### symbol_visibility_header() + +```meson +snippets.symbol_visibility_header(header_name, + namespace: str + api: str + compilation: str + static_compilation: str + static_only: bool +) +``` + +Generate a header file that defines macros to be used to mark all public APIs +of a library. Depending on the platform, this will typically use +`__declspec(dllexport)`, `__declspec(dllimport)` or +`__attribute__((visibility("default")))`. It is compatible with C, C++, +ObjC and ObjC++ languages. The content of the header is static regardless +of the compiler used. + +The first positional argument is the name of the header file to be generated. +It also takes the following keyword arguments: + +- `namespace`: Prefix for generated macros, defaults to the current project name. + It will be converted to upper case with all non-alphanumeric characters replaced + by an underscore `_`. It is only used for `api`, `compilation` and + `static_compilation` default values. +- `api`: Name of the macro used to mark public APIs. Defaults to `<NAMESPACE>_API`. +- `compilation`: Name of a macro defined only when compiling the library. + Defaults to `<NAMESPACE>_COMPILATION`. +- `static_compilation`: Name of a macro defined only when compiling or using + static library. Defaults to `<NAMESPACE>_STATIC_COMPILATION`. +- `static_only`: If set to true, `<NAMESPACE>_STATIC_COMPILATION` is defined + inside the generated header. In that case the header can only be used for + building a static library. By default it is `true` when `default_library=static`, + and `false` otherwise. [See below for more information](#static_library) + +Projects that define multiple shared libraries should typically have +one header per library, with a different namespace. + +The generated header file should be installed using `install_headers()`. + +`meson.build`: +```meson +project('mylib', 'c') +subdir('mylib') +``` + +`mylib/meson.build`: +```meson +snippets = import('snippets') +apiheader = snippets.symbol_visibility_header('apiconfig.h') +install_headers(apiheader, 'lib.h', subdir: 'mylib') +lib = library('mylib', 'lib.c', + gnu_symbol_visibility: 'hidden', + c_args: ['-DMYLIB_COMPILATION'], +) +``` + +`mylib/lib.h` +```c +#include <mylib/apiconfig.h> +MYLIB_API int do_stuff(); +``` + +`mylib/lib.c` +```c +#include "lib.h" +int do_stuff() { + return 0; +} +``` + +#### Static library + +When building both static and shared libraries on Windows (`default_library=both`), +`-D<NAMESPACE>_STATIC_COMPILATION` must be defined only for the static library, +using `c_static_args`. This causes Meson to compile the library twice. + +```meson +if host_system == 'windows' + static_arg = ['-DMYLIB_STATIC_COMPILATION'] +else + static_arg = [] +endif +lib = library('mylib', 'lib.c', + gnu_symbol_visibility: 'hidden', + c_args: ['-DMYLIB_COMPILATION'], + c_static_args: static_arg +) +``` + +`-D<NAMESPACE>_STATIC_COMPILATION` C-flag must be defined when compiling +applications that use the library API. It typically should be defined in +`declare_dependency(..., compile_args: [])` and +`pkgconfig.generate(..., extra_cflags: [])`. + +Note that when building both shared and static libraries on Windows, +applications cannot currently rely on `pkg-config` to define this macro. +See https://github.com/mesonbuild/meson/pull/14829. diff --git a/docs/markdown/Syntax.md b/docs/markdown/Syntax.md index 05f5038..f4a2e17 100644 --- a/docs/markdown/Syntax.md +++ b/docs/markdown/Syntax.md @@ -566,7 +566,7 @@ executable('exe1', 'foo.c', 'bar.c', 'foobar.c') Because of an internal implementation detail, the following syntax is currently also supported, even though the first argument of -[[executable]] is a single [[@str]] and not a [[@list]]: +[[executable]] is a single [[@str]] and not a [[@array]]: ```meson # WARNING: This example is only valid because of an internal diff --git a/docs/markdown/Users.md b/docs/markdown/Users.md index a515b24..5b9821b 100644 --- a/docs/markdown/Users.md +++ b/docs/markdown/Users.md @@ -2,7 +2,7 @@ title: Users ... -# Notable projects using Meson +# Notable projects and organizations using Meson If you're aware of a notable project that uses Meson, please [file a pull-request](https://github.com/mesonbuild/meson/edit/master/docs/markdown/Users.md) @@ -11,181 +11,47 @@ for it. For other projects using Meson, you may be interested in this Some additional projects are listed in the [`meson` GitHub topic](https://github.com/topics/meson). - - [2048.cpp](https://github.com/plibither8/2048.cpp), a fully featured terminal version of the game "2048" written in C++ - - [aawordsearch](https://github.com/theimpossibleastronaut/aawordsearch), generate wordsearch puzzles using random words in different languages - - [Adwaita Manager](https://github.com/AdwCustomizerTeam/AdwCustomizer), change the look of Adwaita, with ease - - [Aravis](https://github.com/AravisProject/aravis), a glib/gobject based library for video acquisition using Genicam cameras - - [Akira](https://github.com/akiraux/Akira), a native Linux app for UI and UX design built in Vala and Gtk - - [AQEMU](https://github.com/tobimensch/aqemu), a Qt GUI for QEMU virtual machines, since version 0.9.3 - - [Arduino sample project](https://github.com/jpakkane/mesonarduino) - - [Asteria](https://github.com/lhmouse/asteria), another scripting language - - [Audacious](https://github.com/audacious-media-player), a lightweight and versatile audio player - - [bolt](https://gitlab.freedesktop.org/bolt/bolt), userspace daemon to enable security levels for Thunderbolt™ 3 on Linux - - [bsdutils](https://github.com/dcantrell/bsdutils), alternative to GNU coreutils using software from FreeBSD - - [Bubblewrap](https://github.com/containers/bubblewrap), unprivileged sandboxing tool - - [Budgie Desktop](https://github.com/budgie-desktop/budgie-desktop), a desktop environment built on GNOME technologies - - [Bzip2](https://gitlab.com/federicomenaquintero/bzip2), the bzip2 compressor/decompressor - - [Cage](https://github.com/Hjdskes/cage), a Wayland kiosk - - [canfigger](https://github.com/andy5995/canfigger), simple configuration file parser library - - [casync](https://github.com/systemd/casync), Content-Addressable Data Synchronization Tool - - [cglm](https://github.com/recp/cglm), a highly optimized graphics math library for C - - [cinnamon-desktop](https://github.com/linuxmint/cinnamon-desktop), the cinnamon desktop library - - [Cozy](https://github.com/geigi/cozy), a modern audio book player for Linux and macOS using GTK+ 3 - - [Criterion](https://github.com/Snaipe/Criterion), extensible cross-platform C and C++ unit testing framework - - [dav1d](https://code.videolan.org/videolan/dav1d), an AV1 decoder - - [dbus-broker](https://github.com/bus1/dbus-broker), Linux D-Bus Message Broker - - [DOSBox Staging](https://github.com/dosbox-staging/dosbox-staging), DOS/x86 emulator - - [DPDK](http://dpdk.org/browse/dpdk), Data Plane Development Kit, a set of libraries and drivers for fast packet processing - - [DXVK](https://github.com/doitsujin/dxvk), a Vulkan-based Direct3D 11 implementation for Linux using Wine +## [Xorg](https://www.x.org) + + - [Xserver](https://gitlab.freedesktop.org/xorg/xserver), the X.org display server + +## [Gnome](https://www.gnome.org) + + - [GTK](https://gitlab.gnome.org/GNOME/gtk), the multi-platform toolkit used by GNOME + - [GLib](https://gitlab.gnome.org/GNOME/glib), cross-platform C library used by GTK+ and GStreamer + +## [Enlightenment](https://www.enlightenment.org/) + - [EFL](https://www.enlightenment.org/about-efl), multiplatform set of libraries, used by the Enlightenment windows manager and other projects - - [Enlightenment](https://www.enlightenment.org/), windows manager, compositor and minimal desktop for Linux - - [elementary OS](https://github.com/elementary/), Linux desktop oriented distribution - - [Emeus](https://github.com/ebassi/emeus), constraint based layout manager for GTK+ - - [Entangle](https://entangle-photo.org/), tethered camera control and capture desktop application - - [ESP8266 Arduino sample project](https://github.com/trilader/arduino-esp8266-meson), sample project for using the ESP8266 Arduino port with Meson - - [FeedReader](https://github.com/jangernert/FeedReader), a modern desktop application designed to complement existing web-based RSS accounts - - [Flecs](https://github.com/SanderMertens/flecs), a Fast and Lightweight ECS (Entity Component System) C library - - [Foliate](https://github.com/johnfactotum/foliate), a simple and modern GTK eBook reader, built with GJS and Epub.js - - [Fractal](https://wiki.gnome.org/Apps/Fractal/), a Matrix messaging client for GNOME - - [Frida](https://github.com/frida/frida-core), a dynamic binary instrumentation toolkit - - [fwupd](https://github.com/hughsie/fwupd), a simple daemon to allow session software to update firmware - - [GameMode](https://github.com/FeralInteractive/gamemode), a daemon/lib combo for Linux that allows games to request a set of optimisations be temporarily applied to the host OS - - [Geary](https://wiki.gnome.org/Apps/Geary), an email application built around conversations, for the GNOME 3 desktop + +## [Elementary OS](https://github.com/elementary/) + +## [cinnamon-desktop](https://github.com/linuxmint/cinnamon-desktop) + + - [Nemo](https://github.com/linuxmint/nemo), the file manager for the Cinnamon desktop environment + +## [Budgie Desktop](https://github.com/budgie-desktop/budgie-desktop) + +## Other Notable projects + + - [FreeType](https://freetype.org/), widely used open source font rendering engine - [GIMP](https://gitlab.gnome.org/GNOME/gimp), an image manipulation program (master branch) - - [Git](https://git-scm.com/), ["the information manager from hell"](https://github.com/git/git/commit/e83c5163316f89bfbde7d9ab23ca2e25604af290) - - [GLib](https://gitlab.gnome.org/GNOME/glib), cross-platform C library used by GTK+ and GStreamer - - [Glorytun](https://github.com/angt/glorytun), a multipath UDP tunnel - - [GNOME Boxes](https://gitlab.gnome.org/GNOME/gnome-boxes), a GNOME hypervisor - - [GNOME Builder](https://gitlab.gnome.org/GNOME/gnome-builder), an IDE for the GNOME platform - - [GNOME MPV](https://github.com/gnome-mpv/gnome-mpv), GNOME frontend to the mpv video player - - [GNOME Recipes](https://gitlab.gnome.org/GNOME/recipes), application for cooking recipes - - [GNOME Software](https://gitlab.gnome.org/GNOME/gnome-software), an app store for GNOME - - [GNOME Twitch](https://github.com/vinszent/gnome-twitch), an app for viewing Twitch streams on GNOME desktop - - [GNOME Usage](https://gitlab.gnome.org/GNOME/gnome-usage), a GNOME application for visualizing system resources - - [GNOME Web](https://gitlab.gnome.org/GNOME/epiphany), a browser for a simple, clean, beautiful view of the web - - [GNU FriBidi](https://github.com/fribidi/fribidi), the open source implementation of the Unicode Bidirectional Algorithm - - [Graphene](https://ebassi.github.io/graphene/), a thin type library for graphics - - [Grilo](https://git.gnome.org/browse/grilo) and [Grilo plugins](https://git.gnome.org/browse/grilo-plugins), the Grilo multimedia framework - [GStreamer](https://gitlab.freedesktop.org/gstreamer/gstreamer), multimedia framework - - [GTK+](https://gitlab.gnome.org/GNOME/gtk), the multi-platform toolkit used by GNOME - - [GtkDApp](https://gitlab.com/csoriano/GtkDApp), an application template for developing Flatpak apps with Gtk+ and D - - [GVfs](https://git.gnome.org/browse/gvfs/), a userspace virtual filesystem designed to work with the I/O abstraction of GIO - - [Hardcode-Tray](https://github.com/bil-elmoussaoui/Hardcode-Tray), fixes hardcoded tray icons in Linux + - [Git](https://git-scm.com/), ["the information manager from hell"](https://github.com/git/git/commit/e83c5163316f89bfbde7d9ab23ca2e25604af290) - [HarfBuzz](https://github.com/harfbuzz/harfbuzz), a text shaping engine - - [HelenOS](http://helenos.org), a portable microkernel-based multiserver operating system - [HexChat](https://github.com/hexchat/hexchat), a cross-platform IRC client in C - - [IGT](https://gitlab.freedesktop.org/drm/igt-gpu-tools), Linux kernel graphics driver test suite - - [i3](https://i3wm.org), improved tiling window manager - - [inih](https://github.com/benhoyt/inih) (INI Not Invented Here), a small and simple .INI file parser written in C - - [Irssi](https://github.com/irssi/irssi), a terminal chat client in C - - [iSH](https://github.com/tbodt/ish), Linux shell for iOS - - [Janet](https://github.com/janet-lang/janet), a functional and imperative programming language and bytecode interpreter - - [json](https://github.com/nlohmann/json), JSON for Modern C++ - - [JsonCpp](https://github.com/open-source-parsers/jsoncpp), a C++ library for interacting with JSON - - [Json-glib](https://gitlab.gnome.org/GNOME/json-glib), GLib-based JSON manipulation library - - [Kiwix libraries](https://github.com/kiwix/kiwix-lib) - - [Knot Resolver](https://gitlab.labs.nic.cz/knot/knot-resolver), Full caching DNS resolver implementation - - [Ksh](https://github.com/att/ast), a Korn Shell - - [Lc0](https://github.com/LeelaChessZero/lc0), LeelaChessZero is a UCI-compliant chess engine designed to play chess via neural network - - [Le](https://github.com/kirushyk/le), machine learning framework - - [libcamera](https://git.linuxtv.org/libcamera.git/), a library to handle complex cameras on Linux, ChromeOS and Android - - [Libdrm](https://gitlab.freedesktop.org/mesa/drm), a library for abstracting DRM kernel interfaces - - [libdwarf](https://www.prevanders.net/dwarf.html), a multiplatform DWARF parser library - - [libeconf](https://github.com/openSUSE/libeconf), Enhanced config file parsing library, which merges config files placed in several locations into one - - [Libepoxy](https://github.com/anholt/libepoxy/), a library for handling OpenGL function pointer management - - [libfuse](https://github.com/libfuse/libfuse), the reference implementation of the Linux FUSE (Filesystem in Userspace) interface - - [Libgit2-glib](https://git.gnome.org/browse/libgit2-glib), a GLib wrapper for libgit2 - - [libglvnd](https://gitlab.freedesktop.org/glvnd/libglvnd), Vendor neutral OpenGL dispatch library for Unix-like OSes - - [Libhttpseverywhere](https://git.gnome.org/browse/libhttpseverywhere), a library to enable httpseverywhere on any desktop app - - [libmodulemd](https://github.com/fedora-modularity/libmodulemd), a GObject Introspected library for managing [Fedora Project](https://getfedora.org/) module metadata - - [Libosmscout](https://github.com/Framstag/libosmscout), a C++ library for offline map rendering, routing and location -lookup based on OpenStreetMap data - - [libratbag](https://github.com/libratbag/libratbag), provides a DBus daemon to configure input devices, mainly gaming mice - - [libspng](https://github.com/randy408/libspng), a C library for reading and writing Portable Network Graphics (PNG) -format files - - [libSRTP](https://github.com/cisco/libsrtp) (from Cisco Systems), a library for SRTP (Secure Realtime Transport Protocol) - - [libui](https://github.com/andlabs/libui), a simple and portable (but not inflexible) GUI library in C that uses the native GUI technologies of each platform it supports - - [Libva](https://github.com/intel/libva), an implementation for the VA (VIdeo Acceleration) API - - [libvips](https://github.com/libvips/libvips), a fast image processing library with low memory needs - - [Libvirt](https://libvirt.org), a toolkit to manage virtualization platforms - - [Libzim](https://github.com/openzim/libzim), the reference implementation for the ZIM file format - - [Linux PAM](https://github.com/linux-pam/linux-pam), The Pluggable Authentication Modules project for Linux - [LXC](https://github.com/lxc/lxc), Linux container runtime - - [Marker](https://github.com/fabiocolacio/Marker), a GTK-3 markdown editor - - [mcfgthread](https://github.com/lhmouse/mcfgthread), cornerstone library for C++11 threading on mingw-w64 + - [Linux PAM](https://github.com/linux-pam/linux-pam), The Pluggable Authentication Modules project for Linux - [Mesa](https://mesa3d.org/), an open source graphics driver project - - [Miniz](https://github.com/richgel999/miniz), a zlib replacement library - - [MiracleCast](https://github.com/albfan/miraclecast), connect external monitors to your system via WiFi-Display specification aka Miracast - [mpv](https://github.com/mpv-player/mpv), a free, open source, and cross-platform media player - - [mrsh](https://github.com/emersion/mrsh), a minimal POSIX shell - - [Nautilus](https://gitlab.gnome.org/GNOME/nautilus), the GNOME file manager - - [Nemo](https://github.com/linuxmint/nemo), the file manager for the Cinnamon desktop environment - - [netatalk](https://netatalk.io/), a free and open source AFP file server for Mac and Apple II - - [NetPanzer](https://github.com/netpanzer/netpanzer), a 2D online multiplayer tactical warfare game designed for fast action combat - [NumPy](https://numpy.org/), a Python package for scientific computing - - [nvme-cli](https://github.com/linux-nvme/nvme-cli), NVMe management command line interface - - [oomd](https://github.com/facebookincubator/oomd), a userspace Out-Of-Memory (OOM) killer for Linux systems - [OpenH264](https://github.com/cisco/openh264), open source H.264 codec - - [OpenHMD](https://github.com/OpenHMD/OpenHMD), a free and open source API and drivers for immersive technology, such as head mounted displays with built in head tracking - [OpenRC](https://github.com/OpenRC/openrc), an init system for Unix-like operating systems - - [OpenTitan](https://github.com/lowRISC/opentitan), an open source silicon Root of Trust (RoT) project - - [Orc](https://gitlab.freedesktop.org/gstreamer/orc), the Optimized Inner Loop Runtime Compiler - - [OTS](https://github.com/khaledhosny/ots), the OpenType Sanitizer, parses and serializes OpenType files (OTF, TTF) and WOFF and WOFF2 font files, validating and sanitizing them as it goes. Used by Chromium and Firefox - - [Outlier](https://github.com/kerolasa/outlier), a small Hello World style Meson example project - - [p11-kit](https://github.com/p11-glue/p11-kit), PKCS#11 module aggregator - [Pacman](https://gitlab.archlinux.org/pacman/pacman.git), a package manager for Arch Linux - - [Pango](https://git.gnome.org/browse/pango/), an Internationalized text layout and rendering library - - [Parzip](https://github.com/jpakkane/parzip), a multithreaded reimplementation of Zip - - [Peek](https://github.com/phw/peek), simple animated GIF screen recorder with an easy to use interface - [PicoLibc](https://github.com/keith-packard/picolibc), a standard C library for small embedded systems with limited RAM - [PipeWire](https://github.com/PipeWire/pipewire), a framework for video and audio for containerized applications - - [Pistache](https://github.com/pistacheio/pistache), a high performance REST toolkit written in C++ - - [Pithos](https://github.com/pithos/pithos), a Pandora Radio client - - [Pitivi](https://github.com/pitivi/pitivi/), a nonlinear video editor - - [Planner](https://github.com/alainm23/planner), task manager with Todoist support designed for GNU/Linux - - [Playerctl](https://github.com/acrisci/playerctl), mpris command-line controller and library for spotify, vlc, audacious, bmp, cmus, and others - - [Polari](https://gitlab.gnome.org/GNOME/polari), an IRC client - [PostgreSQL](https://www.postgresql.org/), an advanced open source relational database - - [qboot](https://github.com/bonzini/qboot), a minimal x86 firmware for booting Linux kernels - [QEMU](https://qemu.org), a processor emulator and virtualizer - - [radare2](https://github.com/radare/radare2), unix-like reverse engineering framework and commandline tools (not the default) - - [refivar](https://github.com/nvinson/refivar), A reimplementation of efivar in Rust - - [Rizin](https://rizin.re), Free and Open Source Reverse Engineering Framework - - [rmw](https://theimpossibleastronaut.com/rmw-website/), safe-remove utility for the command line - - [RxDock](https://gitlab.com/rxdock/rxdock), a protein-ligand docking software designed for high throughput virtual screening (fork of rDock) - [SciPy](https://scipy.org/), an open-source software for mathematics, science, and engineering - - [scrcpy](https://github.com/Genymobile/scrcpy), a cross platform application that provides display and control of Android devices connected on USB or over TCP/IP - - [Sequeler](https://github.com/Alecaddd/sequeler), a friendly SQL client for Linux, built with Vala and Gtk - - [Siril](https://gitlab.com/free-astro/siril), an image processing software for amateur astronomy - - [slapt-get](https://github.com/jaos/slapt-get), an APT like system for Slackware package management - - [Spot](https://github.com/xou816/spot), Rust based Spotify client for the GNOME desktop - - [SSHFS](https://github.com/libfuse/sshfs), allows you to mount a remote filesystem using SFTP - - [sway](https://github.com/swaywm/sway), i3-compatible Wayland compositor - - [Sysprof](https://git.gnome.org/browse/sysprof), a profiling tool - [systemd](https://github.com/systemd/systemd), the init system - - [szl](https://github.com/dimkr/szl), a lightweight, embeddable scripting language - - [Taisei Project](https://taisei-project.org/), an open-source Touhou Project clone and fangame - - [Terminology](https://github.com/billiob/terminology), a terminal emulator based on the Enlightenment Foundation Libraries - - [ThorVG](https://www.thorvg.org/), vector-based scenes and animations library - - [Tilix](https://github.com/gnunn1/tilix), a tiling terminal emulator for Linux using GTK+ 3 - - [Tizonia](https://github.com/tizonia/tizonia-openmax-il), a command-line cloud music player for Linux with support for Spotify, Google Play Music, YouTube, SoundCloud, TuneIn, Plex servers and Chromecast devices - - [Fossil Logic](https://github.com/fossillogic), Fossil Logic is a cutting-edge software development company specializing in C/C++, Python, programming, Android development using Kotlin, and SQL solutions - - [UFJF-MLTK](https://github.com/mateus558/UFJF-Machine-Learning-Toolkit), A C++ cross-platform framework for machine learning algorithms development and testing - - [Vala Language Server](https://github.com/benwaffle/vala-language-server), code intelligence engine for the Vala and Genie programming languages - - [Valum](https://github.com/valum-framework/valum), a micro web framework written in Vala - - [Venom](https://github.com/naxuroqa/Venom), a modern Tox client for the GNU/Linux desktop - - [vkQuake](https://github.com/Novum/vkQuake), a port of id Software's Quake using Vulkan instead of OpenGL for rendering - - [VMAF](https://github.com/Netflix/vmaf) (by Netflix), a perceptual video quality assessment based on multi-method fusion - - [Wayland](https://gitlab.freedesktop.org/wayland/wayland) and [Weston](https://gitlab.freedesktop.org/wayland/weston), a next generation display server - - [wlroots](https://gitlab.freedesktop.org/wlroots/wlroots), a modular Wayland compositor library - - [xi-gtk](https://github.com/eyelash/xi-gtk), a GTK+ front-end for the Xi editor - - [Xorg](https://gitlab.freedesktop.org/xorg/xserver), the X.org display server (not the default yet) - - [X Test Suite](https://gitlab.freedesktop.org/xorg/test/xts), The X.org test suite - - [zathura](https://github.com/pwmt/zathura), a highly customizable and functional document viewer based on the -girara user interface library and several document libraries - - [Zrythm](https://git.sr.ht/~alextee/zrythm), a cross-platform digital audio workstation written in C using GTK4 - - [ZStandard](https://github.com/facebook/zstd/commit/4dca56ed832c6a88108a2484a8f8ff63d8d76d91), a compression algorithm developed at Facebook (not used by default) - -Note that a more up-to-date list of GNOME projects that use Meson can -be found -[here](https://wiki.gnome.org/Initiatives/GnomeGoals/MesonPorting). + - [Wayland](https://gitlab.freedesktop.org/wayland/wayland), common display protocol diff --git a/docs/markdown/Vala.md b/docs/markdown/Vala.md index fdc4fba..ff7a7c7 100644 --- a/docs/markdown/Vala.md +++ b/docs/markdown/Vala.md @@ -304,6 +304,40 @@ 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`). +### Depending on C header + +*(since 1.10.0)* + +Given the previous example, + +```meson +foo_lib = shared_library(...) +foo_h = foo_lib.vala_header() +``` + +This header can now be used like any other generated header to create an +order-only dependency. + + +### Depending on VAPI header + +*(since 1.10.0)* + +Given the previous example, + +```meson +foo_lib = shared_library(...) +foo_vapi = foo_lib.vala_vapi() +``` + +### Depending on generated GIR + +*(since 1.10.0)* + +```meson +foo_lib = shared_library(..., vala_gir : 'foo.gir') +foo_gir = foo_lib.vala_gir() +``` ### GObject Introspection and language bindings @@ -339,6 +373,21 @@ directory (i.e. `share/gir-1.0` for GIRs). The fourth element in the To then generate a typelib file use a custom target with the `g-ir-compiler` program and a dependency on the library: +*Since Meson 1.10*, use the `.vala_gir()` method to get a handle to the generated `.gir` file: + +```meson +g_ir_compiler = find_program('g-ir-compiler') +custom_target('foo typelib', command: [g_ir_compiler, '--output', '@OUTPUT@', '@INPUT@'], + input: foo_lib.vala_gir(), + output: 'Foo-1.0.typelib', + install: true, + install_dir: get_option('libdir') / 'girepository-1.0') +``` + + +*Before Meson 1.10*, calculating the path to the input is required, as is adding a +manual dependency to the vala target: + ```meson g_ir_compiler = find_program('g-ir-compiler') custom_target('foo typelib', command: [g_ir_compiler, '--output', '@OUTPUT@', '@INPUT@'], diff --git a/docs/markdown/Wrap-dependency-system-manual.md b/docs/markdown/Wrap-dependency-system-manual.md index 73358e7..4a7250d 100644 --- a/docs/markdown/Wrap-dependency-system-manual.md +++ b/docs/markdown/Wrap-dependency-system-manual.md @@ -322,8 +322,8 @@ foo-bar-1.0 = foo_bar_dep **Note**: This is experimental and has no backwards or forwards compatibility guarantees. See [Meson's rules on mixing build systems](Mixing-build-systems.md). -Cargo subprojects automatically override the `<package_name>-<version>-rs` dependency -name: +Cargo subprojects automatically call `override_dependency` with the name +`<package_name>-<version>-<suffix>`, where every part is defeined as follows: - `package_name` is defined in `[package] name = ...` section of the `Cargo.toml`. - `version` is the API version deduced from `[package] version = ...` as follow: * `x.y.z` -> 'x' @@ -331,9 +331,9 @@ name: * `0.0.x` -> '0' It allows to make different dependencies for incompatible versions of the same crate. -- `-rs` suffix is added to distinguish from regular system dependencies, for - example `gstreamer-1.0` is a system pkg-config dependency and `gstreamer-0.22-rs` - is a Cargo dependency. +- the suffix is `-rs` for `rlib` and `dylib` crate types. The suffix is added to + distinguish Rust crates from C-ABI dependencies; for example `gstreamer-1.0` + is a system pkg-config dependency and `gstreamer-0.22-rs` is a Cargo dependency. That means the `.wrap` file should have `dependency_names = foo-1-rs` in their `[provide]` section when `Cargo.toml` has package name `foo` and version `1.2`. @@ -361,10 +361,21 @@ Some naming conventions need to be respected: This is typically used as `extra_args += ['--cfg', 'foo']`. - The `extra_deps` variable is pre-defined and can be used to add extra dependencies. This is typically used as `extra_deps += dependency('foo')`. - -Since *1.5.0* Cargo wraps can also be provided with `Cargo.lock` file at the root -of (sub)project source tree. Meson will automatically load that file and convert -it into a series of wraps definitions. +- The `features` variable is pre-defined and contains the list of features enabled + on this crate. + +Since *1.5.0* Cargo wraps can also be provided with `Cargo.lock` file at the +root of (sub)project source tree. Meson will automatically load that file, looking +for crates found on `crates.io` or in a git repository, and will convert those +crates into a series of wraps definitions. Since *1.11.0* the overlay directory +(`patch_directory`) is automatically detected, using the same directory as the +dependency name for `crates.io` URLs, and the final component of the URL +(possibly with the `.git` suffix removed) for "git" URLs. + +Since *1.10.0* Workspace Cargo.toml are supported. For the time being it is +recommended to regroup all Cargo dependencies inside a single workspace invoked +from the main Meson project. When invoking multiple different Cargo subprojects +from Meson, feature resolution of common dependencies might be wrong. ## Using wrapped projects diff --git a/docs/markdown/Yaml-RefMan.md b/docs/markdown/Yaml-RefMan.md index 2872791..cce844b 100644 --- a/docs/markdown/Yaml-RefMan.md +++ b/docs/markdown/Yaml-RefMan.md @@ -150,9 +150,9 @@ optargs: ... varargs: - name: Some name # [required] - type: str | list[str | int] # [required] - description: Some helpful text # [required] + name: Some name # [required] + type: str | array[str | int] # [required] + description: Some helpful text # [required] since: 0.42.0 deprecated: 100.99.0 min_varargs: 1 diff --git a/docs/markdown/_Sidebar.md b/docs/markdown/_Sidebar.md index ce73d5a..eb6afb6 100644 --- a/docs/markdown/_Sidebar.md +++ b/docs/markdown/_Sidebar.md @@ -9,6 +9,7 @@ ### [Modules](Module-reference.md) +* [codegen](Codegen-module.md) * [gnome](Gnome-module.md) * [i18n](i18n-module.md) * [pkgconfig](Pkgconfig-module.md) diff --git a/docs/markdown/i18n-module.md b/docs/markdown/i18n-module.md index da6fce7..767e0c8 100644 --- a/docs/markdown/i18n-module.md +++ b/docs/markdown/i18n-module.md @@ -83,14 +83,14 @@ i18n.xgettext(name, sources..., args: [...], recursive: false) ``` Invokes the `xgettext` program on given sources, to generate a `.pot` file. -This function is to be used when the `gettext` function workflow it not suitable +This function is to be used when the `gettext` function workflow is not suitable for your project. For example, it can be used to produce separate `.pot` files for each executable. Positional arguments are the following: * name `str`: the name of the resulting pot file. -* sources `list[str|File|build_tgt|custom_tgt]`: +* sources `array[str|File|build_tgt|custom_tgt|custom_idx]`: source files or targets. May be a list of `string`, `File`, [[@build_tgt]], or [[@custom_tgt]] returned from other calls to this function. @@ -120,4 +120,7 @@ included to generate the final pot file. Therefore, adding a dependency to source target will automatically add the translations of that dependency to the needed translations for that source target. +*New in 1.10.0* sources can be result of [[@custom_tgt]] or [[@custom_idx]]. +Before 1.10.0, custom targets were silently ignored. + *Added 1.8.0* diff --git a/docs/markdown/index.md b/docs/markdown/index.md index cbb7901..ea168c2 100644 --- a/docs/markdown/index.md +++ b/docs/markdown/index.md @@ -51,9 +51,7 @@ a web chat. The channel to use is `#mesonbuild` either via Matrix ([web interface](https://app.element.io/#/room/#mesonbuild:matrix.org)) or [OFTC IRC](https://www.oftc.net/). -Other methods of communication include the [mailing -list](https://groups.google.com/forum/#!forum/mesonbuild) (hosted by -Google Groups) and the +For general discussion, please use the [Discussions](https://github.com/mesonbuild/meson/discussions) section of the Meson GitHub repository. diff --git a/docs/markdown/snippets/android-exe-type.md b/docs/markdown/snippets/android-exe-type.md deleted file mode 100644 index ce4d946..0000000 --- a/docs/markdown/snippets/android-exe-type.md +++ /dev/null @@ -1,10 +0,0 @@ -## New argument `android_exe_type` for executables - -Android application executables actually need to be linked -as a shared object, which is loaded from a pre-warmed JVM. -Meson projects can now specify a new argument `android_exe_type` -and set it to `application`, in order produce such a shared library -only on Android targets. - -This makes it possible to use the same `meson.build` file -for both Android and non-Android systems. diff --git a/docs/markdown/snippets/b_sanitizer_changes.md b/docs/markdown/snippets/b_sanitizer_changes.md deleted file mode 100644 index f726d70..0000000 --- a/docs/markdown/snippets/b_sanitizer_changes.md +++ /dev/null @@ -1,17 +0,0 @@ -## Changes to the b_sanitize option - -Before 1.8 the `b_sanitize` option was a combo option, which is an enumerated -set of values. In 1.8 this was changed to a free-form array of options where -available sanitizers are not hardcoded anymore but instead verified via a -compiler check. - -This solves a number of longstanding issues such as: - - - Sanitizers may be supported by a compiler, but not on a specific platform - (OpenBSD). - - New sanitizers are not recognized by Meson. - - Using sanitizers in previously-unsupported combinations. - -To not break backwards compatibility, calling `get_option('b_sanitize')` -continues to return the configured value as a string, with a guarantee that -`address,undefined` remains ordered. diff --git a/docs/markdown/snippets/c2y.md b/docs/markdown/snippets/c2y.md deleted file mode 100644 index 4b647f8..0000000 --- a/docs/markdown/snippets/c2y.md +++ /dev/null @@ -1,4 +0,0 @@ -## New C standard `c2y` (and `gnu2y`) - -The `c2y`` standard and its companion `gnu2y` are now supported -when using either Clang 19.0.0 or newer, or GCC 15.0.0 or newer. diff --git a/docs/markdown/snippets/i18n_xgettext.md b/docs/markdown/snippets/i18n_xgettext.md deleted file mode 100644 index 0ad0a14..0000000 --- a/docs/markdown/snippets/i18n_xgettext.md +++ /dev/null @@ -1,12 +0,0 @@ -## i18n module xgettext - -There is a new `xgettext` function in `i18n` module that acts as a -wrapper around `xgettext`. It allows to extract strings to translate from -source files. - -This function is convenient, because: -- It can find the sources files from a build target; -- It will use an intermediate file when the number of source files is too - big to be handled directly from the command line; -- It is able to get strings to translate from the dependencies of the given - targets. diff --git a/docs/markdown/snippets/multiple_version_compare.md b/docs/markdown/snippets/multiple_version_compare.md deleted file mode 100644 index 5e8c758..0000000 --- a/docs/markdown/snippets/multiple_version_compare.md +++ /dev/null @@ -1,8 +0,0 @@ -## `version_compare` now accept multiple compare strings - -Is it now possible to compare version against multiple values, to check for -a range of version for instance. - -```meson -'1.5'.version_compare('>=1', '<2') -``` diff --git a/docs/markdown/snippets/objc-cpp.md b/docs/markdown/snippets/objc-cpp.md deleted file mode 100644 index 3d22ccb..0000000 --- a/docs/markdown/snippets/objc-cpp.md +++ /dev/null @@ -1,8 +0,0 @@ -## Improvements to Objective-C and Objective-C++ - -Meson does not assume anymore that gcc/g++ always support -Objective-C and Objective-C++, and instead checks that they -can actually do a basic compile. - -Furthermore, Objective-C and Objective-C++ now support the -same language standards as C and C++ respectively. diff --git a/docs/markdown/snippets/optionrefactor.md b/docs/markdown/snippets/optionrefactor.md deleted file mode 100644 index 53dbdbc..0000000 --- a/docs/markdown/snippets/optionrefactor.md +++ /dev/null @@ -1,19 +0,0 @@ -## Per project subproject options rewrite - -You can now define per-subproject values for all shared configuration -options. As an example you might want to enable optimizations on only -one subproject: - - meson configure -Dnumbercruncher:optimization=3 - -Subproject specific values can be removed with -U - - meson configure -Unumbercruncher:optimization - -This is a major change in how options are handled, and the -implementation will evolve over the next few releases of Meson. If -this change causes an error in your builds, please [report an issue on -GitHub](https://github.com/mesonbuild/meson/issues/new). - -We have tried to keep backwards compatibility as much as possible, but -this may lead to some build breakage. diff --git a/docs/markdown/snippets/rust-objects.md b/docs/markdown/snippets/rust-objects.md deleted file mode 100644 index 575e1f6..0000000 --- a/docs/markdown/snippets/rust-objects.md +++ /dev/null @@ -1,4 +0,0 @@ -## `objects` added correctly to Rust executables - -Any objects included in a Rust executable were previously ignored. They -are now added correctly. diff --git a/docs/markdown/snippets/rust-test-link-whole.md b/docs/markdown/snippets/rust-test-link-whole.md deleted file mode 100644 index f3d006d..0000000 --- a/docs/markdown/snippets/rust-test-link-whole.md +++ /dev/null @@ -1,4 +0,0 @@ -## `rust.test` now supports `link_whole` - -The `test` function in the `rust` module now supports the `link_whole` -keyword argument in addition to `link_with` and `dependencies`. diff --git a/docs/markdown/snippets/rustdoc.md b/docs/markdown/snippets/rustdoc.md deleted file mode 100644 index b0b64aa..0000000 --- a/docs/markdown/snippets/rustdoc.md +++ /dev/null @@ -1,6 +0,0 @@ -## Meson can run "rustdoc" on Rust projects - -Meson now defines a `rustdoc` target if the project -uses the Rust programming language. The target runs rustdoc on all Rust -sources, using the `rustdoc` program from the same Rust toolchain as the -`rustc` compiler. diff --git a/docs/markdown/snippets/stabilized-wayland.md b/docs/markdown/snippets/stabilized-wayland.md deleted file mode 100644 index 3b132e6..0000000 --- a/docs/markdown/snippets/stabilized-wayland.md +++ /dev/null @@ -1,4 +0,0 @@ -## The Wayland module is stable - -The Wayland module has been tested in several projects and had the -last breaking change in Meson 0.64.0; it is now marked as stable. diff --git a/docs/markdown/snippets/swift-std.md b/docs/markdown/snippets/swift-std.md deleted file mode 100644 index 64fe70c..0000000 --- a/docs/markdown/snippets/swift-std.md +++ /dev/null @@ -1,4 +0,0 @@ -## New `swift_std` compiler option - -A new compiler option allows to set the language version that is passed -to swiftc (`none`, `4`, `4.2`, `5` or `6`). diff --git a/docs/markdown/snippets/test-slicing.md b/docs/markdown/snippets/test-slicing.md deleted file mode 100644 index 180b9ac..0000000 --- a/docs/markdown/snippets/test-slicing.md +++ /dev/null @@ -1,6 +0,0 @@ -## New option to execute a slice of tests - -When tests take a long time to run a common strategy is to slice up the tests -into multiple sets, where each set is executed on a separate machine. You can -now use the `--slice i/n` argument for `meson test` to create `n` slices and -execute the `ith` slice. diff --git a/docs/markdown/snippets/update_xc32_for_v5.md b/docs/markdown/snippets/update_xc32_for_v5.md new file mode 100644 index 0000000..1263948 --- /dev/null +++ b/docs/markdown/snippets/update_xc32_for_v5.md @@ -0,0 +1,4 @@ +## XC32 support now aware of v5.00 features + +XC32 features introduced in v5.00 can now be used. This includes +support for LTO auto and the C2x and CPP23 standards. diff --git a/docs/markdown/snippets/valgrind_test.md b/docs/markdown/snippets/valgrind_test.md deleted file mode 100644 index 0787300..0000000 --- a/docs/markdown/snippets/valgrind_test.md +++ /dev/null @@ -1,6 +0,0 @@ -## Valgrind now fails tests if errors are found - -Valgrind does not reflect an error in its exit code by default, meaning -a test may silently pass despite memory errors. Meson now exports -`VALGRIND_OPTS` such that Valgrind will exit with status 1 to indicate -an error if `VALGRIND_OPTS` is not set in the environment. diff --git a/docs/meson.build b/docs/meson.build index c476b59..f79f5f9 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -135,6 +135,8 @@ documentation = hotdoc.generate_doc(meson.project_name(), extra_extension: meson.current_source_dir() / 'extensions' / 'refman_links.py', refman_data_file: refman_md[1], fatal_warnings: true, + devhelp_activate: true, + devhelp_online: 'https://mesonbuild.com/', ) run_target('upload', @@ -146,4 +148,4 @@ run_target('upload', depends: documentation, ) -test('validate_links', find_program('./validatelinks.py'), args: meson.current_source_dir() / 'markdown' / 'Users.md') +test('validate_links', find_program('./validatelinks.py'), args: meson.current_source_dir() / 'markdown' / 'Users.md', timeout: 65) diff --git a/docs/refman/generatormd.py b/docs/refman/generatormd.py index 854712d..ebf57fa 100644 --- a/docs/refman/generatormd.py +++ b/docs/refman/generatormd.py @@ -44,6 +44,7 @@ _OBJ_ID_MAP = { ObjectType.ELEMENTARY: 'elementary', ObjectType.BUILTIN: 'builtin', ObjectType.MODULE: 'module', + ObjectType.FUNCTIONS: 'functions', ObjectType.RETURNED: 'returned', } @@ -299,7 +300,7 @@ class GeneratorMD(GeneratorBase): def _write_functions(self) -> None: data = {'functions': [self._gen_func_or_method(x) for x in self.functions]} - self._write_template(data, 'root.functions') + self._write_template(data, f'root.{_OBJ_ID_MAP[ObjectType.FUNCTIONS]}') def _root_refman_docs(self) -> None: def gen_obj_links(objs: T.List[Object]) -> T.List[T.Dict[str, str]]: @@ -330,6 +331,7 @@ class GeneratorMD(GeneratorBase): self._write_template(data, 'root') self._write_template({**dummy, 'name': 'Elementary types'}, f'root.{_OBJ_ID_MAP[ObjectType.ELEMENTARY]}', 'dummy') self._write_template({**dummy, 'name': 'Builtin objects'}, f'root.{_OBJ_ID_MAP[ObjectType.BUILTIN]}', 'dummy') + self._write_functions() self._write_template({**dummy, 'name': 'Returned objects'}, f'root.{_OBJ_ID_MAP[ObjectType.RETURNED]}', 'dummy') if self.enable_modules: @@ -339,7 +341,8 @@ class GeneratorMD(GeneratorBase): def generate(self) -> None: mlog.log('Generating markdown files...') with mlog.nested(): - self._write_functions() + for fun in self.functions: + self._write_template(self._gen_func_or_method(fun), f'root.{_OBJ_ID_MAP[ObjectType.FUNCTIONS]}.{fun.name}', 'func') for obj in self.objects: if not self.enable_modules and (obj.obj_type == ObjectType.MODULE or obj.defined_by_module is not None): continue @@ -383,7 +386,7 @@ class GeneratorMD(GeneratorBase): data[f'{obj.name}.{m.name}'] = f'{obj_file}#{obj.name}{m.name}' # Functions - funcs_file = self._gen_filename('root.functions', extension='html') + funcs_file = self._gen_filename(f'root.{_OBJ_ID_MAP[ObjectType.FUNCTIONS]}', extension='html') for fn in self.functions: data[fn.name] = f'{funcs_file}#{fn.name}' diff --git a/docs/refman/model.py b/docs/refman/model.py index 51d4ca2..1360d89 100644 --- a/docs/refman/model.py +++ b/docs/refman/model.py @@ -78,7 +78,8 @@ class ObjectType(Enum): ELEMENTARY = 0 BUILTIN = 1 MODULE = 2 - RETURNED = 3 + FUNCTIONS = 3 + RETURNED = 4 @dataclass class Object(NamedObject, FetureCheck): diff --git a/docs/refman/templates/meson.vim.mustache b/docs/refman/templates/meson.vim.mustache index d8f009e..a0c0513 100644 --- a/docs/refman/templates/meson.vim.mustache +++ b/docs/refman/templates/meson.vim.mustache @@ -27,7 +27,7 @@ endif let s:cpo_save = &cpo set cpo&vim -" http://mesonbuild.com/Syntax.html +" https://mesonbuild.com/Syntax.html syn keyword mesonConditional elif else if endif syn keyword mesonRepeat foreach endforeach syn keyword mesonOperator and not or in @@ -54,7 +54,7 @@ syn match mesonEscape "\\N{\a\+\%(\s\a\+\)*}" contained syn match mesonEscape "\\$" " Meson only supports integer numbers -" http://mesonbuild.com/Syntax.html#numbers +" https://mesonbuild.com/Syntax.html#numbers syn match mesonNumber "\<\d\+\>" syn match mesonNumber "\<0x\x\+\>" syn match mesonNumber "\<0o\o\+\>" diff --git a/docs/sitemap.txt b/docs/sitemap.txt index 21f495e..a71e954 100644 --- a/docs/sitemap.txt +++ b/docs/sitemap.txt @@ -38,6 +38,7 @@ index.md Code-formatting.md Modules.md CMake-module.md + Codegen-module.md Cuda-module.md Dlang-module.md External-Project-module.md @@ -55,6 +56,7 @@ index.md Qt6-module.md Rust-module.md Simd-module.md + Snippets-module.md SourceSet-module.md Windows-module.md i18n-module.md @@ -88,6 +90,9 @@ index.md Wrap-best-practices-and-tips.md Shipping-prebuilt-binaries-as-wraps.md Release-notes.md + Release-notes-for-1.10.0.md + Release-notes-for-1.9.0.md + Release-notes-for-1.8.0.md Release-notes-for-1.7.0.md Release-notes-for-1.6.0.md Release-notes-for-1.5.0.md diff --git a/docs/theme/extra/templates/navbar_links.html b/docs/theme/extra/templates/navbar_links.html index 65a21a2..ac4a6fe 100644 --- a/docs/theme/extra/templates/navbar_links.html +++ b/docs/theme/extra/templates/navbar_links.html @@ -7,6 +7,7 @@ <ul class="dropdown-menu" id="modules-menu"> @for tup in [ \ ("CMake-module.html","CMake"), \ + ("Codegen-module.html","Codegen"), \ ("Cuda-module.html","CUDA"), \ ("Dlang-module.html","Dlang"), \ ("External-Project-module.html","External Project"), \ @@ -25,6 +26,7 @@ ("Qt6-module.html","Qt6"), \ ("Rust-module.html","Rust"), \ ("Simd-module.html","Simd"), \ + ("Snippets-module.html","Snippets"), \ ("SourceSet-module.html","SourceSet"), \ ("Wayland-module.html","Wayland"), \ ("Windows-module.html","Windows")]: diff --git a/docs/yaml/builtins/meson.yaml b/docs/yaml/builtins/meson.yaml index 516e41c..eac8368 100644 --- a/docs/yaml/builtins/meson.yaml +++ b/docs/yaml/builtins/meson.yaml @@ -139,7 +139,7 @@ methods: to install only a subset of the files. By default the script has no install tag which means it is not being run when `meson install --tags` argument is specified. - + dry_run: type: bool since: 1.1.0 @@ -447,12 +447,12 @@ methods: description: Returns the version string specified in [[project]] function call. - name: project_license - returns: list[str] + returns: array[str] since: 0.45.0 description: Returns the array of licenses specified in [[project]] function call. - name: project_license_files - returns: list[file] + returns: array[file] since: 1.1.0 description: Returns the array of license files specified in the [[project]] function call. @@ -498,10 +498,10 @@ methods: posargs: env: - type: env | str | list[str] | dict[str] | dict[list[str]] + type: env | str | array[str] | dict[str] | dict[array[str]] description: | The [[@env]] object to add. - Since *0.62.0* list of strings is allowed in dictionary values. In that + Since *0.62.0* array of strings is allowed in dictionary values. In that case values are joined using the separator. kwargs: separator: diff --git a/docs/yaml/elementary/array.yml b/docs/yaml/elementary/array.yml new file mode 100644 index 0000000..7183d1a --- /dev/null +++ b/docs/yaml/elementary/array.yml @@ -0,0 +1,74 @@ +name: array +long_name: Array +description: An array of elements. See [arrays](Syntax.md#arrays). +is_container: true + +methods: +- name: contains + returns: bool + description: | + Returns `true` if the array contains the object + given as argument, `false` otherwise + + arg_flattening: false + + posargs: + item: + type: any + description: The item to check + +- name: get + returns: any + description: | + returns the object at the given index, + negative indices count from the back of the array, indexing out of + bounds returns the `fallback` value *(since 0.38.0)* or, if it is + not specified, causes a fatal error + + arg_flattening: false + + posargs: + index: + type: int + description: Index of the array position to query. Negative values start at the end of the array + + optargs: + fallback: + type: any + description: Fallback value that is returned if the index is out of range. + +- name: slice + returns: array[any] + since: 1.10.0 + description: | + Return a selection of the elements of the array starting at index `start` + and continuing with `step` size jumps until `stop`. Negative indices count + from the back of the array. The step size cannot be zero, but may be + negative. If it is negative, `start` and `stop` default to the end and + beginning of the array, respectively. If `step` is positive, `start` + defaults to 0 and `stop` defaults to the length of the array. Either both + or none of `start` and `stop` must be provided to prevent ambiguity. + + optargs: + start: + type: int + description: The lower bound of the slice + + stop: + type: int + description: The upper bound of the slice + + kwargs: + step: + type: int + default: 1 + description: The step size + +- name: length + returns: int + description: Returns the current size of the array. + +- name: flatten + returns: array[any] + since: 1.9.0 + description: Returns a flattened copy of the array, with all nested arrays removed. diff --git a/docs/yaml/elementary/dict.yml b/docs/yaml/elementary/dict.yml index 19263df..525fbee 100644 --- a/docs/yaml/elementary/dict.yml +++ b/docs/yaml/elementary/dict.yml @@ -44,5 +44,12 @@ methods: description: Fallback value that is returned if the key is not in the [[@dict]]. - name: keys - returns: list[str] - description: Returns an array of keys in the dictionary. + returns: array[str] + description: Returns an array of keys in the dictionary, sorted in ascending order. + +- name: values + returns: array[any] + since: 1.10.0 + description: | + Returns an array of values in the dictionary, sorted by the + corresponding keys in ascending order. diff --git a/docs/yaml/elementary/list.yml b/docs/yaml/elementary/list.yml deleted file mode 100644 index 1ffb6d2..0000000 --- a/docs/yaml/elementary/list.yml +++ /dev/null @@ -1,42 +0,0 @@ -name: list -long_name: List -description: An array of elements. See [arrays](Syntax.md#arrays). -is_container: true - -methods: -- name: contains - returns: bool - description: | - Returns `true` if the array contains the object - given as argument, `false` otherwise - - arg_flattening: false - - posargs: - item: - type: any - description: The item to check - -- name: get - returns: any - description: | - returns the object at the given index, - negative indices count from the back of the array, indexing out of - bounds returns the `fallback` value *(since 0.38.0)* or, if it is - not specified, causes a fatal error - - arg_flattening: false - - posargs: - index: - type: int - description: Index of the list position to query. Negative values start at the end of the list - - optargs: - fallback: - type: any - description: Fallback value that is returned if the index is out of range. - -- name: length - returns: int - description: Returns the current size of the array / list. diff --git a/docs/yaml/elementary/str.yml b/docs/yaml/elementary/str.yml index 44aa742..c2b6c35 100644 --- a/docs/yaml/elementary/str.yml +++ b/docs/yaml/elementary/str.yml @@ -203,7 +203,7 @@ methods: # str.split - name: split - returns: list[str] + returns: array[str] description: | Splits the string at the specified character (or whitespace if not set) and returns the parts in an @@ -224,7 +224,7 @@ methods: description: Specifies the character / substring where to split the string. - name: splitlines - returns: list[str] + returns: array[str] since: 1.2.0 description: | Splits the string into an array of lines. @@ -250,7 +250,7 @@ methods: returns: str description: | The opposite of split, - for example `'.'.join(['a', 'b', 'c']` yields `'a.b.c'`. + for example `'.'.join(['a', 'b', 'c'])` yields `'a.b.c'`. example: | ```meson @@ -270,7 +270,7 @@ methods: The strings to join with the current string. Before Meson *0.60.0* this function only accepts a single positional - argument of the type [[list[str]]]. + argument of the type [[array[str]]]. # str.underscorify - name: underscorify diff --git a/docs/yaml/functions/_build_target_base.yaml b/docs/yaml/functions/_build_target_base.yaml index 1721b29..1129533 100644 --- a/docs/yaml/functions/_build_target_base.yaml +++ b/docs/yaml/functions/_build_target_base.yaml @@ -43,13 +43,13 @@ kwargs: description: precompiled header file to use for the given language <lang>_args: - type: list[str] + type: array[str] description: | compiler flags to use for the given language; eg: `cpp_args` for C++ vala_args: - type: list[str | file] + type: array[str | file] description: | Compiler flags for Vala. Unlike other languages this may contain Files @@ -74,7 +74,7 @@ kwargs: but which will be removed on install dependencies: - type: list[dep] + type: array[dep] description: | one or more dependency objects created with @@ -83,10 +83,12 @@ kwargs: (for deps built by the project) extra_files: - type: str | file | custom_tgt | custom_idx + type: str | file description: | Not used for the build itself but are shown as source files in IDEs - that group files by targets (such as Visual Studio) + that group files by targets (such as Visual Studio). + + These may only be static sources. gui_app: type: bool @@ -98,7 +100,7 @@ kwargs: 0.56.0, use `win_subsystem` instead. link_args: - type: list[str] + type: array[str] description: | Flags to use during linking. You can use UNIX-style flags here for all platforms. @@ -125,7 +127,7 @@ kwargs: *(broken until 0.55.0)* link_whole: - type: list[lib | custom_tgt | custom_idx] + type: array[lib | custom_tgt | custom_idx] since: 0.40.0 description: | Links all contents of the given static libraries whether they are used or @@ -133,18 +135,18 @@ kwargs: '/WHOLEARCHIVE' MSVC linker option. This allows the linked target to re-export symbols from all objects in the static libraries. - *(since 0.41.0)* If passed a list that list will be flattened. + *(since 0.41.0)* If passed an array that array will be flattened. *(since 0.51.0)* This argument also accepts outputs produced by custom targets. The user must ensure that the output is a library in the correct format. link_with: - type: list[lib | custom_tgt | custom_idx] + type: array[lib | custom_tgt | custom_idx] description: | One or more shared or static libraries - (built by this project) that this target should be linked with. *(since 0.41.0)* If passed a - list this list will be flattened. *(since 0.51.0)* The arguments can also be custom targets. + (built by this project) that this target should be linked with. *(since 0.41.0)* If passed an + array that array will be flattened. *(since 0.51.0)* The arguments can also be custom targets. In this case Meson will assume that merely adding the output file in the linker command line is sufficient to make linking work. If this is not sufficient, then the build system writer must write all other steps manually. @@ -156,7 +158,7 @@ kwargs: description: Controls whether Meson adds the current source and build directories to the include path include_directories: - type: list[inc | str] + type: array[inc | str] description: | one or more objects created with the [[include_directories]] function, or *(since 0.50.0)* strings, which will be transparently expanded to include directory objects @@ -175,7 +177,7 @@ kwargs: something like this: `install_dir : get_option('libdir') / 'projectname-1.0'`. install_mode: - type: list[str | int] + type: array[str | int] since: 0.47.0 description: | Specify the file mode in symbolic format @@ -198,7 +200,7 @@ kwargs: (but *not* before that). On Windows, this argument has no effect. objects: - type: list[extracted_obj | file | str] + type: array[extracted_obj | file | str] description: | List of object files that should be linked in this target. @@ -208,7 +210,7 @@ kwargs: object files had to be placed in `sources`. name_prefix: - type: str | list[void] + type: str | array[void] description: | The string that will be used as the prefix for the target output filename by overriding the default (only used for @@ -219,7 +221,7 @@ kwargs: Set this to `[]`, or omit the keyword argument for the default behaviour. name_suffix: - type: str | list[void] + type: str | array[void] description: | The string that will be used as the extension for the target by overriding the default. By default on Windows this is @@ -235,7 +237,7 @@ kwargs: Set this to `[]`, or omit the keyword argument for the default behaviour. override_options: - type: list[str] | dict[str | bool | int | list[str]] + type: array[str] | dict[str | bool | int | array[str]] since: 0.40.0 description: | takes an array of strings in the same format as `project`'s `default_options` @@ -253,10 +255,12 @@ kwargs: `default`, `internal`, `hidden`, `protected` or `inlineshidden`, which is the same as `hidden` but also includes things like C++ implicit constructors as specified in the GCC manual. Ignored on compilers that - do not support GNU visibility arguments. + do not support GNU visibility arguments. See also + [`snippets.symbol_visibility_header()`](Snippets-module.md#symbol_visibility_header) + method to help with defining public API. d_import_dirs: - type: list[inc | str] + type: array[inc | str] since: 0.62.0 description: | the directories to add to the string search path (i.e. `-J` switch for DMD). @@ -268,11 +272,11 @@ kwargs: description: When set to true, the D modules are compiled in debug mode. d_module_versions: - type: list[str | int] + type: array[str | int] description: List of module version identifiers set when compiling D sources. d_debug: - type: list[str] + type: array[str] description: | The [D version identifiers](https://dlang.org/spec/version.html#version) to add during the compilation of D source files. @@ -323,8 +327,50 @@ kwargs: type: dict[str] since: 1.2.0 description: | - On rust targets this provides a map of library names to the crate name - with which it would be available inside the rust code. + On rust targets this allows giving custom names to the crates that are + linked into the target. For example, passing a dependency map of + `{ 'gtk4': 'gtk' }` has the same effect of writing `gtk.package = "gtk4"` + in the `dependencies` section of a Cargo.toml file, or + `extern crate gtk4 as gtk` inside Rust code. + + *Since 1.10.0*, the keys can be either crate names or target names. + + vala_header: + type: str + description: | + On Vala targets, this provides a way to override the name of the generated + C compatible header for targets that generate them. - This allows renaming similar to the dependency renaming feature of cargo - or `extern crate foo as bar` inside rust code. + If it is not set the default will be calculated from the target's name. + + vala_vapi: + type: str + description: | + On Vala targets, this provides a way to override the name of the generated + VAPI file. + + If it is not set the default will be calculated from the target's name. + + vala_gir: + type: str + description: | + If set, generates a GIR file with the given name. If this is unset then + no GIR file will be generated. + + build_subdir: + type: str + since: 1.10.0 + description: + Places the build results in a subdirectory of the given name + rather than directly into the build directory. This does not + affect the install directory, which uses install_dir. + + This allows inserting a directory name into the build path, + either when needed to use the build result while building other + targets or as a way to support multiple targets with the same + basename by using unique build_subdir values for each one. + + To prevent collisions within the build directory, build_subdir + is not allowed to match a file or directory in the source + directory, nor contain '..' to refer to the parent of the build + directory. diff --git a/docs/yaml/functions/add_global_arguments.yaml b/docs/yaml/functions/add_global_arguments.yaml index 3b26d10..25e4eef 100644 --- a/docs/yaml/functions/add_global_arguments.yaml +++ b/docs/yaml/functions/add_global_arguments.yaml @@ -15,11 +15,11 @@ varargs: kwargs: language: - type: list[str] + type: array[str] required: true description: | Specifies the language(s) that the arguments should be - applied to. If a list of languages is given, the arguments are added + applied to. If an array of languages is given, the arguments are added to each of the corresponding compiler command lines. Note that there is no way to remove an argument set in this way. If you have an argument that is only used in a subset of targets, you have to specify diff --git a/docs/yaml/functions/add_test_setup.yaml b/docs/yaml/functions/add_test_setup.yaml index 3d666c7..a29b137 100644 --- a/docs/yaml/functions/add_test_setup.yaml +++ b/docs/yaml/functions/add_test_setup.yaml @@ -18,7 +18,7 @@ posargs: kwargs: env: - type: env | list[str] | dict[str] + type: env | array[str] | dict[str] description: | environment variables to set , such as `['NAME1=value1', 'NAME2=value2']`, @@ -26,7 +26,7 @@ kwargs: environment juggling. *(Since 0.52.0)* A dictionary is also accepted. exe_wrapper: - type: list[str | external_program] + type: array[str | external_program] description: The command or script followed by the arguments to it gdb: @@ -52,9 +52,9 @@ kwargs: without the `--setup` option. exclude_suites: - type: list[str] + type: array[str] since: 0.57.0 description: - A list of test suites that should be excluded when using this setup. + An array of test suites that should be excluded when using this setup. Suites specified in the `--suite` option - to `meson test` will always run, overriding `add_test_setup` if necessary.
\ No newline at end of file + to `meson test` will always run, overriding `add_test_setup` if necessary. diff --git a/docs/yaml/functions/benchmark.yaml b/docs/yaml/functions/benchmark.yaml index 7a555a4..fe69f28 100644 --- a/docs/yaml/functions/benchmark.yaml +++ b/docs/yaml/functions/benchmark.yaml @@ -28,11 +28,11 @@ posargs: kwargs: args: - type: list[str | file | tgt | external_program] + type: array[str | file | tgt | external_program] description: Arguments to pass to the executable env: - type: env | list[str] | dict[str] + type: env | array[str] | dict[str] description: | environment variables to set, such as `['NAME1=value1', 'NAME2=value2']`, or an [[@env]] object which allows more sophisticated @@ -46,11 +46,11 @@ kwargs: executable returns a non-zero return value (i.e. reports an error) suite: - type: str | list[str] + type: str | array[str] description: | - `'label'` (or list of labels `['label1', 'label2']`) + `'label'` (or array of labels `['label1', 'label2']`) attached to this test. The suite name is qualified by a (sub)project - name resulting in `(sub)project_name:label`. In the case of a list + name resulting in `(sub)project_name:label`. In the case of an array of strings, the suite names will be `(sub)project_name:label1`, `(sub)project_name:label2`, etc. @@ -70,7 +70,7 @@ kwargs: for the test depends: - type: list[build_tgt | custom_tgt] + type: array[build_tgt | custom_tgt] since: 0.46.0 description: | specifies that this test depends on the specified diff --git a/docs/yaml/functions/build_target.yaml b/docs/yaml/functions/build_target.yaml index a56fe75..f883e87 100644 --- a/docs/yaml/functions/build_target.yaml +++ b/docs/yaml/functions/build_target.yaml @@ -26,9 +26,9 @@ description: | build_target(<arguments and keyword arguments>, target_type : 'executable') ``` - The lists for the kwargs (such as `sources`, `objects`, and `dependencies`) are - always flattened, which means you can freely nest and add lists while - creating the final list. + The arrays for the kwargs (such as `sources`, `objects`, and `dependencies`) are + always flattened, which means you can freely nest and add arrays while + creating the final array. The returned object also has methods that are documented in [[@build_tgt]]. diff --git a/docs/yaml/functions/configure_file.yaml b/docs/yaml/functions/configure_file.yaml index 20b96aa..32cb559 100644 --- a/docs/yaml/functions/configure_file.yaml +++ b/docs/yaml/functions/configure_file.yaml @@ -12,10 +12,12 @@ description: | A dictionary can be passed instead of a [[@cfg_data]] object. - When a list of strings is passed to the `command:` keyword argument, + When an array of strings is passed to the `command:` keyword argument, it takes any source or configured file as the `input:` and assumes that the `output:` is produced when the specified command is run. + You can install the outputted file with the `install_dir:` kwarg, see below. + *(since 0.47.0)* When the `copy:` keyword argument is set to `true`, this function will copy the file provided in `input:` to a file in the build directory with the name `output:` in the current directory. @@ -34,7 +36,7 @@ kwargs: file specified as `output`. command: - type: list[str | file] + type: array[str | file] description: | As explained above, if specified, Meson does not create the file itself but rather runs the specified command, which allows @@ -103,7 +105,7 @@ kwargs: string, the file is not installed. install_mode: - type: list[str | int] + type: array[str | int] since: 0.47.0 description: | Specify the file mode in symbolic format @@ -153,3 +155,21 @@ kwargs: description: | When specified, macro guards will be used instead of '#pragma once'. The macro guard name will be the specified name. + + build_subdir: + type: str + since: 1.10.0 + description: + Places the build results in a subdirectory of the given name + rather than directly into the build directory. This does not + affect the install directory, which uses install_dir. + + This allows inserting a directory name into the build path, + either when needed to use the build result while building other + targets or as a way to support multiple targets with the same + basename by using unique build_subdir values for each one. + + To prevent collisions within the build directory, build_subdir + is not allowed to match a file or directory in the source + directory, nor contain '..' to refer to the parent of the build + directory. diff --git a/docs/yaml/functions/custom_target.yaml b/docs/yaml/functions/custom_target.yaml index 585d260..5836bb7 100644 --- a/docs/yaml/functions/custom_target.yaml +++ b/docs/yaml/functions/custom_target.yaml @@ -12,10 +12,16 @@ description: | custom_target('foo', output: 'file.txt', ...) ``` + The files passed to `output:` cannot contain path separators. See the + [manual on custom build targets](Custom-build-targets.md#details-on-command-invocation) for + an explanation on where output files should be placed. + + You can install the outputted files with the `install_dir:` kwarg, see below. + *Since 0.60.0* the name argument is optional and defaults to the basename of the first output (`file.txt` in the example above). - The list of strings passed to the `command` keyword argument accept + The array of strings passed to the `command` keyword argument accept the following special string substitutions: - `@INPUT@`: the full path to the input passed to `input`. If more than @@ -103,7 +109,7 @@ kwargs: There are some compilers that can't be told to write their output to a file but instead write it to standard output. When this argument is set to true, Meson captures `stdout` and writes it - to the target file. Note that your command argument list may not + to the target file. Note that your command argument array may not contain `@OUTPUT@` when capture mode is active. console: @@ -118,7 +124,7 @@ kwargs: serializing all targets in this pool. command: - type: list[str | file | exe | external_program] + type: array[str | file | exe | external_program] description: | Command to run to create outputs from inputs. The command may be strings or the return value of functions that return file-like @@ -132,7 +138,7 @@ kwargs: -arg2'` as the latter will *not* work. depend_files: - type: list[str | file] + type: array[str | file] description: | files ([[@str]], [[@file]], or the return value of [[configure_file]] that @@ -140,7 +146,7 @@ kwargs: argument. Useful for adding regen dependencies. depends: - type: list[build_tgt | custom_tgt | custom_idx] + type: array[build_tgt | custom_tgt | custom_idx] description: | Specifies that this target depends on the specified target(s), even though it does not take any of them as a command @@ -162,8 +168,8 @@ kwargs: are also accepted. input: - type: list[str | file] - description: List of source files. *(since 0.41.0)* the list is flattened. + type: array[str | file] + description: Array of source files. *(since 0.41.0)* the array is flattened. install: type: bool @@ -171,7 +177,7 @@ kwargs: the install step (see `install_dir` for details). install_dir: - type: str | list[str | bool] + type: str | array[str | bool] description: | If only one install_dir is provided, all outputs are installed there. *Since 0.40.0* Allows you to specify the installation directory for each @@ -195,17 +201,17 @@ kwargs: This would install `second.file` to `otherdir` and not install `first.file`. install_mode: - type: list[str | int] + type: array[str | int] since: 0.47.0 description: | The file mode and optionally the owner/uid and group/gid. See the `install_mode` kwarg of [[install_data]] for more information. install_tag: - type: list[str] + type: array[str] since: 0.60.0 description: | - A list of strings, one per output, used by the `meson install --tags` command + An array of strings, one per output, used by the `meson install --tags` command to install only a subset of the files. By default all outputs have no install tag which means they are not being @@ -214,12 +220,13 @@ kwargs: outputs that have no tag or are not installed. output: - type: list[str] - description: List of output files. + type: array[str] + description: | + Array of output files. These cannot contain path separators. env: since: 0.57.0 - type: env | list[str] | dict[str] + type: env | array[str] | dict[str] description: | environment variables to set, such as `{'NAME1': 'value1', 'NAME2': 'value2'}` or `['NAME1=value1', 'NAME2=value2']`, @@ -234,4 +241,4 @@ kwargs: There are some compilers that can't be told to read their input from a file and instead read it from standard input. When this argument is set to `true`, Meson feeds the input file to `stdin`. Note that - your argument list may not contain `@INPUT@` when feed mode is active. + your argument array may not contain `@INPUT@` when feed mode is active. diff --git a/docs/yaml/functions/debug.yaml b/docs/yaml/functions/debug.yaml index a64bd92..4a4508c 100644 --- a/docs/yaml/functions/debug.yaml +++ b/docs/yaml/functions/debug.yaml @@ -5,10 +5,10 @@ description: Write the argument string to the meson build log. posargs: message: - type: str | int | bool | list[str | int | bool] | dict[str | int | bool] + type: str | int | bool | array[str | int | bool] | dict[str | int | bool] description: The message to print varargs: name: msg - type: str | int | bool | list[str | int | bool] | dict[str | int | bool] + type: str | int | bool | array[str | int | bool] | dict[str | int | bool] description: Additional parameters will be separated by spaces diff --git a/docs/yaml/functions/declare_dependency.yaml b/docs/yaml/functions/declare_dependency.yaml index 848082d..15d1606 100644 --- a/docs/yaml/functions/declare_dependency.yaml +++ b/docs/yaml/functions/declare_dependency.yaml @@ -12,41 +12,41 @@ description: | kwargs: compile_args: - type: list[str] + type: array[str] description: Compile arguments to use. dependencies: - type: list[dep] + type: array[dep] description: Other dependencies needed to use this dependency. include_directories: - type: list[inc | str] + type: array[inc | str] description: | the directories to add to header search path, must be [[@inc]] objects or *(since 0.50.0)* plain strings. link_args: - type: list[str] + type: array[str] description: Link arguments to use. link_with: - type: list[lib] + type: array[lib] description: Libraries to link against. link_whole: - type: list[lib] + type: array[lib] since: 0.46.0 description: Libraries to link fully, same as [[executable]]. sources: - type: list[str | file | custom_tgt | custom_idx | generated_list] + type: array[str | file | custom_tgt | custom_idx | generated_list] description: | sources to add to targets (or generated header files that should be built before sources including them are built) extra_files: - type: list[str | file] + type: array[str | file] since: 1.2.0 description: | extra files to add to targets. @@ -59,31 +59,31 @@ kwargs: such as `1.2.3`. Defaults to the project version. variables: - type: dict[str] | list[str] + type: dict[str] | array[str] since: 0.54.0 description: | a dictionary of arbitrary strings, this is meant to be used in subprojects where special variables would be provided via cmake or - pkg-config. *since 0.56.0* it can also be a list of `'key=value'` strings. + pkg-config. *since 0.56.0* it can also be an array of `'key=value'` strings. d_module_versions: - type: str | int | list[str | int] + type: str | int | array[str | int] since: 0.62.0 description: | The [D version identifiers](https://dlang.org/spec/version.html#version) to add during the compilation of D source files. d_import_dirs: - type: list[inc | str] + type: array[inc | str] since: 0.62.0 description: | the directories to add to the string search path (i.e. `-J` switch for DMD). Must be [[@inc]] objects or plain strings. objects: - type: list[extracted_obj] + type: array[extracted_obj] since: 1.1.0 description: | - a list of object files, to be linked directly into the targets that use the + an array of object files, to be linked directly into the targets that use the dependency. diff --git a/docs/yaml/functions/dependency.yaml b/docs/yaml/functions/dependency.yaml index a19deab..c337769 100644 --- a/docs/yaml/functions/dependency.yaml +++ b/docs/yaml/functions/dependency.yaml @@ -78,7 +78,7 @@ varargs: kwargs: default_options: - type: list[str] | dict[str | bool | int | list[str]] + type: array[str] | dict[str | bool | int | array[str]] since: 0.38.0 description: | An array of default option values @@ -103,7 +103,7 @@ kwargs: for more details. fallback: - type: list[str] | str + type: array[str] | str description: | Manually specifies a subproject fallback to use in case the dependency is not found in the system. @@ -120,7 +120,7 @@ kwargs: in this case the subproject must use `meson.override_dependency('dependency_name', subproj_dep)` to specify the dependency object used in the superproject. - If the value is an empty list, it has the same effect as + If the value is an empty array it has the same effect as `allow_fallback: false`. language: @@ -174,21 +174,26 @@ kwargs: libraries instead of dynamic ones (note that this is not supported by all dependency backends) + Leaving this value unset will result in an implementation defined default + value. For most dependencies this means the value of the `prefer_static` + option, but some custom dependencies have their own method for determining + the most useful default option. + *Since 0.60.0* it also sets `default_library` option accordingly on the fallback subproject if it was not set explicitly in `default_options` keyword argument. - *Since 0.63.0* when the `prefer_static` option is set to `true` the default - value is `true` otherwise the default value is `false`. + *Since 0.63.0* when the `prefer_static` option is used to calculate the + default value. version: - type: list[str] | str + type: array[str] | str since: 0.37.0 description: | Specifies the required version, a string containing a comparison operator followed by the version string, examples include `>1.0.0`, `<=2.3.5` or `3.1.4` for exact matching. - You can also specify multiple restrictions by passing a list to this + You can also specify multiple restrictions by passing an array to this keyword argument, such as: `['>=3.14.0', '<=4.1.0']`. These requirements are never met if the version is unknown. diff --git a/docs/yaml/functions/environment.yaml b/docs/yaml/functions/environment.yaml index 4c18ffc..1f6e198 100644 --- a/docs/yaml/functions/environment.yaml +++ b/docs/yaml/functions/environment.yaml @@ -7,12 +7,12 @@ arg_flattening: false optargs: env: - type: str | list[str] | dict[str] | dict[list[str]] + type: str | array[str] | dict[str] | dict[array[str]] since: 0.52.0 description: | If provided, each key/value pair is added into the [[@env]] object as if [[env.set]] method was called for each of them. - Since *0.62.0* list of strings is allowed in dictionary values. In that + Since *0.62.0* arrays of strings are allowed in dictionary values. In that case values are joined using the separator. kwargs: diff --git a/docs/yaml/functions/executable.yaml b/docs/yaml/functions/executable.yaml index df71b79..c819a38 100644 --- a/docs/yaml/functions/executable.yaml +++ b/docs/yaml/functions/executable.yaml @@ -4,9 +4,9 @@ description: | Creates a new executable. The first argument specifies its name and the remaining positional arguments define the input files to use. - The lists for the kwargs (such as `sources`, `objects`, and `dependencies`) are - always flattened, which means you can freely nest and add lists while - creating the final list. + The arrays for the kwargs (such as `sources`, `objects`, and `dependencies`) are + always flattened, which means you can freely nest and add arrays while + creating the final array. The returned object also has methods that are documented in [[@exe]]. @@ -37,15 +37,18 @@ kwargs: since: 0.45.0 description: | when set to true causes the target's symbols to be - dynamically exported, allowing modules built using the - [[shared_module]] function to refer to functions, - variables and other symbols defined in the executable itself. Implies - the `implib` argument. + dynamically exported, allowing modules built using the + [[shared_module]] function to refer to functions, + variables and other symbols defined in the executable itself. implib: type: bool | str since: 0.42.0 description: | + When set to a string, that will be the name of a generated import library. + + *Since 1.10.0* passing a boolean value is deprecated. + When set to true, an import library is generated for the executable (the name of the import library is based on *exe_name*). Alternatively, when set to a string, that gives the base name for diff --git a/docs/yaml/functions/files.yaml b/docs/yaml/functions/files.yaml index ca72745..4d701e1 100644 --- a/docs/yaml/functions/files.yaml +++ b/docs/yaml/functions/files.yaml @@ -1,5 +1,5 @@ name: files -returns: list[file] +returns: array[file] description: | This command takes the strings given to it in arguments and returns corresponding File objects that you can use as sources for build diff --git a/docs/yaml/functions/find_program.yaml b/docs/yaml/functions/find_program.yaml index 1899941..110f5df 100644 --- a/docs/yaml/functions/find_program.yaml +++ b/docs/yaml/functions/find_program.yaml @@ -24,7 +24,7 @@ description: | (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. Since *0.50.0* if the "python3" + script as part of an array of commands. Since *0.50.0* if the "python3" program is requested and it is not found in the system, Meson will return its current interpreter. @@ -98,7 +98,7 @@ kwargs: instead of a not-found object. version: - type: str | list[str] + type: str | array[str] since: 0.52.0 description: | Specifies the required version, see @@ -117,12 +117,12 @@ kwargs: If this is unspecified, `program_name --version` will be used. dirs: - type: list[str] + type: array[str] since: 0.53.0 - description: extra list of absolute paths where to look for program names. + description: extra array of absolute paths where to look for program names. default_options: - type: list[str] | dict[str | bool | int | list[str]] + type: array[str] | dict[str | bool | int | array[str]] since: 1.3.0 description: | An array of default option values diff --git a/docs/yaml/functions/generator.yaml b/docs/yaml/functions/generator.yaml index 6079d30..c505394 100644 --- a/docs/yaml/functions/generator.yaml +++ b/docs/yaml/functions/generator.yaml @@ -45,12 +45,12 @@ posargs: kwargs: arguments: - type: list[str] - description: A list of template strings that will be the command line arguments passed to the executable. + type: array[str] + description: An array of template strings that will be the command line arguments passed to the executable. depends: # Not sure why this is not just `target` - type: list[build_tgt | custom_tgt | custom_idx] + type: array[build_tgt | custom_tgt | custom_idx] since: 0.51.0 description: | An array of build targets that must be built before @@ -68,9 +68,9 @@ kwargs: recompilation, output: - type: list[str] + type: array[str] description: | - Template string (or list of template strings) defining + Template string (or array of template strings) defining how an output file name is (or multiple output names are) generated from a single source file name. diff --git a/docs/yaml/functions/get_option.yaml b/docs/yaml/functions/get_option.yaml index 0934758..e23e380 100644 --- a/docs/yaml/functions/get_option.yaml +++ b/docs/yaml/functions/get_option.yaml @@ -1,5 +1,5 @@ name: get_option -returns: str | int | bool | feature | list[str | int | bool] +returns: str | int | bool | feature | array[str | int | bool] description: | Obtains the value of the [project build option](Build-options.md) specified in the positional argument. @@ -20,6 +20,11 @@ description: | See [`feature` options](Build-options.md#features) documentation for more details. + For options that are [specified + per-machine](Builtin-options.md#specifying-options-per-machine) + `get_option()` retrieves the value of the option for the + build machine if the argument starts with `build.`. + posargs: option_name: type: str diff --git a/docs/yaml/functions/install_data.yaml b/docs/yaml/functions/install_data.yaml index 9ed09a7..516ca14 100644 --- a/docs/yaml/functions/install_data.yaml +++ b/docs/yaml/functions/install_data.yaml @@ -2,6 +2,9 @@ name: install_data returns: void description: | Installs files from the source tree that are listed as positional arguments. + Please note that this can only install static files from the source tree. + Generated files are installed via the `install_dir:` kwarg on the respective + generators, such as `custom_target()` or `configure_file()`. See [Installing](Installing.md) for more examples. @@ -25,7 +28,7 @@ kwargs: If omitted, the directory defaults to `{datadir}/{projectname}` *(since 0.45.0)*. install_mode: - type: list[str | int] + type: array[str | int] since: 0.38.0 description: | specify the file mode in symbolic format and @@ -58,16 +61,16 @@ kwargs: This is equivalent to GNU Automake's `nobase` option. rename: - type: list[str] + type: array[str] since: 0.46.0 description: | - If specified renames each source file into corresponding file from `rename` list. + If specified renames each source file into corresponding file from `rename` array. Nested paths are allowed and they are - joined with `install_dir`. Length of `rename` list must be equal to + joined with `install_dir`. Length of `rename` array must be equal to the number of sources. sources: - type: list[file | str] + type: array[file | str] description: Additional files to install. follow_symlinks: diff --git a/docs/yaml/functions/install_emptydir.yaml b/docs/yaml/functions/install_emptydir.yaml index df84f60..4f77f59 100644 --- a/docs/yaml/functions/install_emptydir.yaml +++ b/docs/yaml/functions/install_emptydir.yaml @@ -16,7 +16,7 @@ varargs: kwargs: install_mode: - type: list[str | int] + type: array[str | int] description: | Specify the file mode in symbolic format and optionally the owner/uid and group/gid for the created directory. diff --git a/docs/yaml/functions/install_headers.yaml b/docs/yaml/functions/install_headers.yaml index 0ac4fc5..42f6462 100644 --- a/docs/yaml/functions/install_headers.yaml +++ b/docs/yaml/functions/install_headers.yaml @@ -9,6 +9,10 @@ description: | argument. As an example if this has the value `myproj` then the headers would be installed to `/{prefix}/include/myproj`. + Please note that this can only install static files from the source tree. + Generated files are installed via the `install_dir:` kwarg on the respective + generators, such as `custom_target()` or `configure_file(). + example: | For example, this will install `common.h` and `kola.h` into `/{prefix}/include`: @@ -57,7 +61,7 @@ kwargs: Incompatible with the `install_dir` kwarg. install_mode: - type: list[str | int] + type: array[str | int] since: 0.47.0 description: | Specify the file mode in symbolic format diff --git a/docs/yaml/functions/install_man.yaml b/docs/yaml/functions/install_man.yaml index 8d9ba60..1deef59 100644 --- a/docs/yaml/functions/install_man.yaml +++ b/docs/yaml/functions/install_man.yaml @@ -20,7 +20,7 @@ warnings: kwargs: install_mode: - type: list[str | int] + type: array[str | int] since: 0.47.0 description: | Specify the file mode in symbolic format diff --git a/docs/yaml/functions/install_subdir.yaml b/docs/yaml/functions/install_subdir.yaml index 19abee3..3420f5e 100644 --- a/docs/yaml/functions/install_subdir.yaml +++ b/docs/yaml/functions/install_subdir.yaml @@ -66,7 +66,7 @@ posargs: kwargs: install_mode: - type: list[str | int] + type: array[str | int] since: 0.47.0 description: | Specify the file mode in symbolic format @@ -83,16 +83,16 @@ kwargs: tag which means they are not being installed when `--tags` argument is specified. exclude_files: - type: list[str] + type: array[str] description: | - A list of file names that should not be installed. + An array of file names that should not be installed. Names are interpreted as paths relative to the `subdir_name` location. exclude_directories: - type: list[str] + type: array[str] since: 0.47.0 description: | - A list of directory names that should not be installed. + An array of directory names that should not be installed. Names are interpreted as paths relative to the `subdir_name` location. install_dir: diff --git a/docs/yaml/functions/library.yaml b/docs/yaml/functions/library.yaml index 1d406f1..4a4611c 100644 --- a/docs/yaml/functions/library.yaml +++ b/docs/yaml/functions/library.yaml @@ -40,13 +40,13 @@ kwargs: type being build. <lang>_static_args: - type: list[str] + type: array[str] since: 1.3.0 description: Arguments that are only passed to a static library vala_static_args: - type: list[str | file] + type: array[str | file] since: 1.3.0 description: Arguments that are only passed to a static library @@ -54,13 +54,13 @@ kwargs: Like `vala_args`, [[files]] is allowed in addition to string <lang>_shared_args: - type: list[str] + type: array[str] since: 1.3.0 description: Arguments that are only passed to a shared library vala_shared_args: - type: list[str | file] + type: array[str | file] since: 1.3.0 description: Arguments that are only passed to a shared library diff --git a/docs/yaml/functions/message.yaml b/docs/yaml/functions/message.yaml index e480457..339dfc4 100644 --- a/docs/yaml/functions/message.yaml +++ b/docs/yaml/functions/message.yaml @@ -6,11 +6,11 @@ arg_flattening: false posargs: text: - type: str | int | bool | list[str | int | bool] | dict[str | int | bool] + type: str | int | bool | array[str | int | bool] | dict[str | int | bool] description: The message to print. varargs: name: more_text since: 0.54.0 - type: str | int | bool | list[str | int | bool] | dict[str | int | bool] + type: str | int | bool | array[str | int | bool] | dict[str | int | bool] description: Additional text that will be printed separated by spaces. diff --git a/docs/yaml/functions/project.yaml b/docs/yaml/functions/project.yaml index 5be8cac..0db8c03 100644 --- a/docs/yaml/functions/project.yaml +++ b/docs/yaml/functions/project.yaml @@ -13,9 +13,9 @@ description: | would probably want to use the name _libfoobar_ instead of _The Foobar Library_. - It may be followed by the list of programming languages that the project uses. + It may be followed by the array of programming languages that the project uses. - *(since 0.40.0)* The list of languages is optional. + *(since 0.40.0)* The array 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. @@ -24,7 +24,7 @@ description: | Supported values for languages are `c`, `cpp` (for `C++`), `cuda`, `cython`, `d`, `objc`, `objcpp`, `fortran`, `java`, `cs` (for `C#`), - `vala` and `rust`. + `swift`, `nasm`, `masm`, `linearasm`, `vala` and `rust`. posargs: project_name: @@ -38,22 +38,26 @@ varargs: kwargs: default_options: - type: list[str] | dict[str | bool | int | list[str]] + type: array[str] | dict[str | bool | int | array[str]] description: | Accepts strings in the form `key=value` which have the same format as options to `meson configure`. For example to set the default project type you would set this: `default_options : ['buildtype=debugoptimized']`. Note that these settings are only used when running Meson for the first - time. Global options such as `buildtype` can only be specified in - the master project, settings in subprojects are ignored. Project - specific options are used normally even in subprojects. + time. Note that some options can override the default behavior; for example, using `c_args` here means that the `CFLAGS` environment variable is not used. Consider using [[add_project_arguments()]] instead. + Also note that not all options are taken into account when + building as a subproject, and the exact set of options + that are per-subproject has increased over time; for more + information, see [core options](Builtin-options.md#core-options) + and [compiler options](Builtin-options.md#compiler-options). + *(since 1.2.0)*: A dictionary may now be passed. version: @@ -72,7 +76,7 @@ kwargs: Usually something like `>=0.28.0`. license: - type: str | list[str] + type: str | array[str] description: | Takes a string or array of strings describing the license(s) the code is under. @@ -94,7 +98,7 @@ kwargs: value in your Meson build files with `meson.project_license()`. license_files: - type: str | list[str] + type: str | array[str] since: 1.1.0 description: | Takes a string or array of strings with the paths to the license file(s) diff --git a/docs/yaml/functions/run_command.yaml b/docs/yaml/functions/run_command.yaml index 5803f82..1c9cc53 100644 --- a/docs/yaml/functions/run_command.yaml +++ b/docs/yaml/functions/run_command.yaml @@ -40,7 +40,7 @@ kwargs: empty string. env: - type: env | list[str] | dict[str] + type: env | array[str] | dict[str] since: 0.50.0 description: | environment variables to set, diff --git a/docs/yaml/functions/run_target.yaml b/docs/yaml/functions/run_target.yaml index 3ede1c9..bf670d8 100644 --- a/docs/yaml/functions/run_target.yaml +++ b/docs/yaml/functions/run_target.yaml @@ -31,25 +31,25 @@ posargs: kwargs: command: - type: list[exe| external_program | custom_tgt | file | str] + type: array[exe| external_program | custom_tgt | file | str] description: | - A list containing the command to run and the arguments - to pass to it. Each list item may be a string or a target. For + An array containing the command to run and the arguments + to pass to it. Each array element may be a string or a target. For instance, passing the return value of [[executable]] as the first item will run that executable, or passing a string as the first item will find that command in `PATH` and run it. depends: - type: list[build_tgt | custom_tgt | custom_idx] + type: array[build_tgt | custom_tgt | custom_idx] description: | - A list of targets that this target depends on but which + An array of targets that this target depends on but which are not listed in the command array (because, for example, the script does file globbing internally, custom_idx was not possible as a type between 0.60 and 1.4.0). env: since: 0.57.0 - type: env | list[str] | dict[str] + type: env | array[str] | dict[str] description: | environment variables to set, such as `{'NAME1': 'value1', 'NAME2': 'value2'}` or `['NAME1=value1', 'NAME2=value2']`, diff --git a/docs/yaml/functions/shared_library.yaml b/docs/yaml/functions/shared_library.yaml index f633aca..c3ea77a 100644 --- a/docs/yaml/functions/shared_library.yaml +++ b/docs/yaml/functions/shared_library.yaml @@ -29,13 +29,13 @@ kwargs: `soversion` is not defined, it is set to `3`. darwin_versions: - type: str | int | list[str] + type: str | int | array[str] since: 0.48.0 description: | Defines the `compatibility version` and `current version` for the dylib on macOS. - If a list is specified, it must be + If an array is specified, it must be either zero, one, or two elements. If only one element is specified - or if it's not a list, the specified value will be used for setting + or if it's not an array the specified value will be used for setting both compatibility version and current version. If unspecified, the `soversion` will be used as per the aforementioned rules. @@ -54,3 +54,9 @@ kwargs: Set the specific ABI to compile (when compiling rust). - 'rust' (default): Create a "dylib" crate. - 'c': Create a "cdylib" crate. + + shortname: + type: str + since: 1.10.0 + description: | + A string specifying a DLL name fitting to 8.3 limit on OS/2 of this shared library. diff --git a/docs/yaml/functions/structured_sources.yaml b/docs/yaml/functions/structured_sources.yaml index a5f0a83..0dbf585 100644 --- a/docs/yaml/functions/structured_sources.yaml +++ b/docs/yaml/functions/structured_sources.yaml @@ -10,7 +10,7 @@ description: | posargs: root: - type: list[str | file | custom_tgt | custom_idx | generated_list] + type: array[str | file | custom_tgt | custom_idx | generated_list] description: Sources to put at the root of the generated structure optargs: diff --git a/docs/yaml/functions/subdir.yaml b/docs/yaml/functions/subdir.yaml index 428563b..96e17ba 100644 --- a/docs/yaml/functions/subdir.yaml +++ b/docs/yaml/functions/subdir.yaml @@ -21,6 +21,6 @@ posargs: kwargs: if_found: - type: list[dep] + type: array[dep] since: 0.44.0 description: Only enter the subdir if all [[dep.found]] methods return `true`. diff --git a/docs/yaml/functions/subproject.yaml b/docs/yaml/functions/subproject.yaml index bccac79..508837c 100644 --- a/docs/yaml/functions/subproject.yaml +++ b/docs/yaml/functions/subproject.yaml @@ -42,7 +42,7 @@ posargs: kwargs: default_options: - type: list[str] | dict[str | bool | int | list[str]] + type: array[str] | dict[str | bool | int | array[str]] since: 0.37.0 description: | An array of default option values diff --git a/docs/yaml/functions/summary.yaml b/docs/yaml/functions/summary.yaml index cf63dcd..b531282 100644 --- a/docs/yaml/functions/summary.yaml +++ b/docs/yaml/functions/summary.yaml @@ -16,7 +16,7 @@ description: | - an integer, boolean or string - *since 0.57.0* an external program or a dependency - *since 0.58.0* a feature option - - a list of those. + - an array of those. Instead of calling summary as `summary(key, value)`, it is also possible to directly pass a dictionary to the [[summary]] function, as seen in the example @@ -38,7 +38,7 @@ example: | summary({'Some boolean': false, 'Another boolean': true, 'Some string': 'Hello World', - 'A list': ['string', 1, true], + 'An array': ['string', 1, true], }, section: 'Configuration') ``` @@ -56,7 +56,7 @@ example: | Some boolean : False Another boolean: True Some string : Hello World - A list : string + An array : string 1 True ``` @@ -65,7 +65,7 @@ arg_flattening: false posargs: key_or_dict: - type: str | dict[str | bool | int | dep | external_program | list[str | bool | int | dep | external_program]] + type: str | dict[str | bool | int | dep | external_program | array[str | bool | int | dep | external_program]] description: | The name of the new entry, or a dict containing multiple entries. If a dict is passed it is equivalent to calling summary() once for each @@ -74,7 +74,7 @@ posargs: optargs: value: - type: str | bool | int | dep | external_program | list[str | bool | int | dep | external_program] + type: str | bool | int | dep | external_program | array[str | bool | int | dep | external_program] description: | The value to print for the `key`. Only valid if `key_or_dict` is a str. @@ -92,5 +92,5 @@ kwargs: type: str since: 0.54.0 description: | - The separator to use when printing list values in this summary. If no - separator is given, each list item will be printed on its own line. + The separator to use when printing array values in this summary. If no + separator is given, each array item will be printed on its own line. diff --git a/docs/yaml/functions/vcs_tag.yaml b/docs/yaml/functions/vcs_tag.yaml index 3a35684..bf223e7 100644 --- a/docs/yaml/functions/vcs_tag.yaml +++ b/docs/yaml/functions/vcs_tag.yaml @@ -22,7 +22,7 @@ description: | kwargs: command: - type: list[exe | external_program | custom_tgt | file | str] + type: array[exe | external_program | custom_tgt | file | str] description: | The command to execute, see [[custom_target]] for details on how this command must be specified. @@ -71,7 +71,7 @@ kwargs: The subdirectory to install the generated file to (e.g. `share/myproject`). install_mode: - type: list[str | int] + type: array[str | int] since: 1.7.0 description: | Specify the file mode in symbolic format diff --git a/docs/yaml/objects/build_tgt.yaml b/docs/yaml/objects/build_tgt.yaml index 73b9b5d..3fed56c 100644 --- a/docs/yaml/objects/build_tgt.yaml +++ b/docs/yaml/objects/build_tgt.yaml @@ -77,3 +77,27 @@ methods: objects feature compatible with [[@external_program]] objects. This simplifies use-cases where an executable is used instead of an [[@external_program]]. + +- name: vala_header + returns: file + since: 1.10.0 + description: | + Returns a [[@file]] object pointing to a C compatible header generated by + the vala compiler, if this target does not generate a vala header then it is + an error to call this method. + +- name: vala_vapi + returns: file + since: 1.10.0 + description: | + Returns a [[@file]] object pointing to a VAPI header generated by the vala + compiler, if this target does not generate a VAPI file then it is an error + to call this method. + +- name: vala_gir + returns: file + since: 1.10.0 + description: | + Returns a [[@file]] object pointing to a GIR file generated by the vala + compiler, if this target does not generate a GIR file then it is an error + to call this method. diff --git a/docs/yaml/objects/cfg_data.yaml b/docs/yaml/objects/cfg_data.yaml index 03abb17..36f9755 100644 --- a/docs/yaml/objects/cfg_data.yaml +++ b/docs/yaml/objects/cfg_data.yaml @@ -114,7 +114,7 @@ methods: description: The name of the variable to query - name: keys - returns: list[str] + returns: array[str] since: 0.57.0 description: | Returns an array of keys of diff --git a/docs/yaml/objects/compiler.yaml b/docs/yaml/objects/compiler.yaml index 43831d2..c676180 100644 --- a/docs/yaml/objects/compiler.yaml +++ b/docs/yaml/objects/compiler.yaml @@ -45,9 +45,9 @@ methods: description: You have found a bug if you can see this! kwargs: args: - type: list[str] + type: array[str] description: | - Used to pass a list of compiler arguments. + Used to pass an array of compiler arguments. Defining include paths for headers not in the default include path via `-Isome/path/to/header` is generally supported, however, usually not recommended. @@ -61,16 +61,19 @@ methods: description: You have found a bug if you can see this! kwargs: include_directories: - type: inc | list[inc] + type: array[inc | str] since: 0.38.0 - description: Extra directories for header searches. + description: | + Extra directories for header searches, created with the + [[include_directories]] function. + *(Since 1.10.0)* Strings are also accepted. - name: _dependencies returns: void description: You have found a bug if you can see this! kwargs: dependencies: - type: dep | list[dep] + type: dep | array[dep] description: Additionally dependencies required for compiling and / or linking. - name: _prefix @@ -78,7 +81,7 @@ methods: description: You have found a bug if you can see this! kwargs: prefix: - type: str | list[str] + type: str | array[str] description: | Used to add `#include`s and other things that are required for the symbol to be declared. Since 1.0.0 an array is accepted @@ -184,7 +187,7 @@ methods: description: Returns the compiler's version number as a string. - name: cmd_array - returns: list[str] + returns: array[str] description: Returns an array containing the command(s) for the compiler. @@ -441,10 +444,10 @@ methods: *(since 0.47.0)* The value of a `feature` option can also be passed here. has_headers: - type: list[str] + type: array[str] since: 0.50.0 description: | - List of headers that must be found as well. + An array of headers that must be found as well. This check is equivalent to checking each header with a [[compiler.has_header]] call. @@ -468,7 +471,7 @@ methods: description: If `true`, this method will return a [[@disabler]] on a failed check. dirs: - type: list[str] + type: array[str] description: | Additional directories to search in. @@ -478,19 +481,20 @@ methods: # does not work, since all _common kwargs need to be prefixed `header_` here # kwargs_inherit: compiler._common header_args: - type: list[str] + type: array[str] since: 0.51.0 description: | When the `has_headers` kwarg is also used, this argument is passed to [[compiler.has_header]] as `args`. header_include_directories: - type: inc | list[inc] + type: array[inc | str] since: 0.51.0 description: | When the `has_headers` kwarg is also used, this argument is passed to [[compiler.has_header]] as `include_directories`. + *(Since 1.10.0)* Strings are also accepted. header_dependencies: - type: dep | list[dep] + type: dep | array[dep] since: 0.51.0 description: | When the `has_headers` kwarg is also used, this argument is passed to @@ -539,7 +543,7 @@ methods: - compiler._required - name: get_supported_arguments - returns: list[str] + returns: array[str] since: 0.43.0 varargs_inherit: compiler.has_multi_arguments description: | @@ -558,11 +562,11 @@ methods: - `'require'`: Abort if at least one argument is not supported - name: first_supported_argument - returns: list[str] + returns: array[str] since: 0.43.0 varargs_inherit: compiler.has_multi_arguments description: | - Given a list of strings, returns a single-element list containing the first + Given an array of strings, returns a single-element array containing the first argument that passes the [[compiler.has_argument]] test or an empty array if none pass. @@ -601,7 +605,7 @@ methods: - compiler._required - name: get_supported_link_arguments - returns: list[str] + returns: array[str] since: 0.46.0 varargs_inherit: compiler.has_multi_link_arguments description: | @@ -621,11 +625,11 @@ methods: # - `'require'`: Abort if at least one argument is not supported - name: first_supported_link_argument - returns: list[str] + returns: array[str] since: 0.46.0 varargs_inherit: compiler.has_multi_link_arguments description: | - Given a list of strings, returns the first argument that passes the + Given an array of strings, returns the first argument that passes the [[compiler.has_link_argument]] test or an empty array if none pass. - name: has_function_attribute @@ -645,7 +649,7 @@ methods: - compiler._required - name: get_supported_function_attributes - returns: list[str] + returns: array[str] since: 0.48.0 description: | Returns an array containing any names that are supported GCC style attributes. @@ -666,10 +670,10 @@ methods: operating systems. - name: preprocess - returns: list[custom_idx] + returns: array[custom_idx] since: 0.64.0 description: | - Preprocess a list of source files but do not compile them. The preprocessor + Preprocess an array of source files but do not compile them. The preprocessor will receive the same arguments (include directories, defines, etc) as with normal compilation. That includes for example args added with `add_project_arguments()`, or on the command line with `-Dc_args=-DFOO`. @@ -694,15 +698,15 @@ methods: the source filename and `@BASENAME@` is replaced by the source filename without its extension. compile_args: - type: list[str] + type: array[str] description: | Extra flags to pass to the preprocessor dependencies: - type: dep | list[dep] + type: dep | array[dep] description: Additionally dependencies required. since: 1.1.0 depends: - type: list[build_tgt | custom_tgt] + type: array[build_tgt | custom_tgt] description: | Specifies that this target depends on the specified target(s). These targets should be built before starting diff --git a/docs/yaml/objects/custom_tgt.yaml b/docs/yaml/objects/custom_tgt.yaml index 5102ab9..60e067c 100644 --- a/docs/yaml/objects/custom_tgt.yaml +++ b/docs/yaml/objects/custom_tgt.yaml @@ -25,9 +25,9 @@ methods: custom target's output argument. - name: to_list - returns: list[custom_idx] + returns: array[custom_idx] since: 0.54.0 description: | - Returns a list of opaque objects that references this target, + Returns an array of opaque objects that references this target, and can be used as a source in other targets. This can be used to iterate outputs with `foreach` loop. diff --git a/docs/yaml/objects/dep.yaml b/docs/yaml/objects/dep.yaml index ffd19f7..fdf5fe5 100644 --- a/docs/yaml/objects/dep.yaml +++ b/docs/yaml/objects/dep.yaml @@ -34,11 +34,11 @@ methods: kwargs: define_variable: - type: list[str] + type: array[str] since: 0.44.0 description: | You can also redefine a - variable by passing a list to this kwarg + variable by passing an array to this kwarg that can affect the retrieved variable: `['prefix', '/'])`. *(Since 1.3.0)* Multiple variables can be specified in pairs. @@ -224,7 +224,7 @@ methods: description: The default value to return when the variable does not exist pkgconfig_define: - type: list[str] + type: array[str] description: See [[dep.get_pkgconfig_variable]] - name: as_static @@ -250,4 +250,3 @@ methods: recursive: type: bool description: If true, this is recursively applied to dependencies -
\ No newline at end of file diff --git a/docs/yaml/objects/external_program.yaml b/docs/yaml/objects/external_program.yaml index 4c24497..db5d39f 100644 --- a/docs/yaml/objects/external_program.yaml +++ b/docs/yaml/objects/external_program.yaml @@ -56,3 +56,8 @@ methods: ```meson run_command(find_program('foo'), 'arg1', 'arg2') ``` + +- name: cmd_array + returns: array[str] + description: Returns an array containing the command(s) for the program. + since: 1.10.0 diff --git a/docs/yaml/objects/generator.yaml b/docs/yaml/objects/generator.yaml index fbef95f..3dbcdd5 100644 --- a/docs/yaml/objects/generator.yaml +++ b/docs/yaml/objects/generator.yaml @@ -9,20 +9,20 @@ methods: - name: process returns: generated_list description: | - Takes a list of files, causes them to be processed and returns an object containing the result + Takes an array of files, causes them to be processed and returns an object containing the result which can then, for example, be passed into a build target definition. varargs: name: source min_varargs: 1 type: str | file | custom_tgt | custom_idx | generated_list - description: List of sources to process. + description: sources to process. kwargs: extra_args: - type: list[str] + type: array[str] description: | - If present, will be used to replace an entry `@EXTRA_ARGS@` in the argument list. + If present, will be used to replace an entry `@EXTRA_ARGS@` in the argument array. preserve_path_from: type: str @@ -36,7 +36,7 @@ methods: directory}/one.out`. env: - type: env | list[str] | dict[str] + type: env | array[str] | dict[str] since: 1.3.0 description: | environment variables to set, such as |