diff options
Diffstat (limited to 'docs')
29 files changed, 503 insertions, 99 deletions
diff --git a/docs/markdown/Build-options.md b/docs/markdown/Build-options.md index 2d53e287b..429b9b2ca 100644 --- a/docs/markdown/Build-options.md +++ b/docs/markdown/Build-options.md @@ -20,6 +20,9 @@ option('integer_opt', type : 'integer', min : 0, max : 5, value : 3) # Since 0.4 option('free_array_opt', type : 'array', value : ['one', 'two']) # Since 0.44.0 option('array_opt', type : 'array', choices : ['one', 'two', 'three'], value : ['one', 'two']) option('some_feature', type : 'feature', value : 'enabled') # Since 0.47.0 +option('long_desc', type : 'string', value : 'optval', + description : 'An option with a very long description' + + 'that does something in a specific context') # Since 0.55.0 ``` For built-in options, see [Built-in options][builtin_opts]. diff --git a/docs/markdown/Contributing.md b/docs/markdown/Contributing.md index 53329389b..b16f61542 100644 --- a/docs/markdown/Contributing.md +++ b/docs/markdown/Contributing.md @@ -174,7 +174,7 @@ contents of an additional file into the CI log on failure. Projects needed by unit tests are in the `test cases/unit` subdirectory. They are not run as part of `./run_project_tests.py`. -#### Configuring project tests +### Configuring project tests The (optional) `test.json` file, in the root of a test case, is used for configuring the test. All of the following root entries in the `test.json` @@ -209,17 +209,20 @@ Exanple `test.json`: { "opt1": "qwert", "opt2": "false" }, { "opt1": "bad" } ] + }, + "tools": { + "cmake": ">=3.11" } } ``` -##### env +#### env The `env` key contains a dictionary which specifies additional environment variables to be set during the configure step of the test. `@ROOT@` is replaced with the absolute path of the source directory. -##### installed +#### installed The `installed` dict contains a list of dicts, describing which files are expected to be installed. Each dict contains the following keys: @@ -277,7 +280,7 @@ the platform matches. The following values for `platform` are currently supporte | `cygwin` | Matches when the platform is cygwin | | `!cygwin` | Not `cygwin` | -##### matrix +#### matrix The `matrix` section can be used to define a test matrix to run project tests with different meson options. @@ -318,12 +321,40 @@ The above example will produce the following matrix entries: - `opt1=qwert` - `opt1=qwert opt2=true` -##### do_not_set_opts +#### do_not_set_opts Currently supported values are: - `prefix` - `libdir` +#### tools + +This section specifies a dict of tool requirements in a simple key-value format. +If a tool is specified, it has to be present in the environment, and the version +requirement must be fulfilled. Otherwise, the entire test is skipped (including +every element in the test matrix). + +#### stdout + +The `stdout` key contains a list of dicts, describing the expected stdout. + +Each dict contains the following keys: + +- `line` +- `match` (optional) + +Each item in the list is matched, in order, against the remaining actual stdout +lines, after any previous matches. If the actual stdout is exhausted before +every item in the list is matched, the expected output has not been seen, and +the test has failed. + +The `match` element of the dict determines how the `line` element is matched: + +| Type | Description | +| -------- | ----------------------- | +| `literal` | Literal match (default) | +| `re` | regex match | + ### Skipping integration tests Meson uses several continuous integration testing systems that have slightly diff --git a/docs/markdown/Cross-compilation.md b/docs/markdown/Cross-compilation.md index 4c4b7bfcc..1c53dcf3f 100644 --- a/docs/markdown/Cross-compilation.md +++ b/docs/markdown/Cross-compilation.md @@ -231,13 +231,10 @@ The main *meson* object provides two functions to determine cross compilation status. ```meson -meson.is_cross_build() # returns true when cross compiling -meson.has_exe_wrapper() # returns true if an exe wrapper has been defined +meson.is_cross_build() # returns true when cross compiling +meson.can_run_host_binaries() # returns true if the host binaries can be run, either with a wrapper or natively ``` -Note that the latter gives undefined return value when doing a native -build. - You can run system checks on both the system compiler or the cross compiler. You just have to specify which one to use. diff --git a/docs/markdown/Dependencies.md b/docs/markdown/Dependencies.md index 17c999114..a8f6d8a5d 100644 --- a/docs/markdown/Dependencies.md +++ b/docs/markdown/Dependencies.md @@ -76,7 +76,7 @@ and config-tool based variables. ```meson foo_dep = dependency('foo') -var = foo.get_variable(cmake : 'CMAKE_VAR', pkgconfig : 'pkg-config-var', configtool : 'get-var', default_value : 'default') +var = foo_dep.get_variable(cmake : 'CMAKE_VAR', pkgconfig : 'pkg-config-var', configtool : 'get-var', default_value : 'default') ``` It accepts the keywords 'cmake', 'pkgconfig', 'pkgconfig_define', @@ -242,6 +242,9 @@ libgcrypt_dep = dependency('libgcrypt', version: '>= 1.8') gpgme_dep = dependency('gpgme', version: '>= 1.0') ``` +*Since 0.55.0* Meson won't search $PATH any more for a config tool binary when +cross compiling if the config tool did not have an entry in the cross file. + ## AppleFrameworks Use the `modules` keyword to list frameworks required, e.g. diff --git a/docs/markdown/IDE-integration.md b/docs/markdown/IDE-integration.md index a6c6f4bc6..f51075e24 100644 --- a/docs/markdown/IDE-integration.md +++ b/docs/markdown/IDE-integration.md @@ -29,16 +29,16 @@ watch for changes in this directory to know when something changed. The `meson-info` directory should contain the following files: -| File | Description | -| ---- | ----------- | -| `intro-benchmarks.json` | Lists all benchmarks | -| `intro-buildoptions.json` | Contains a full list of meson configuration options for the project | -| `intro-buildsystem_files.json` | Full list of all meson build files | -| `intro-dependencies.json` | Lists all dependencies used in the project | -| `intro-installed.json` | Contains mapping of files to their installed location | -| `intro-projectinfo.json` | Stores basic information about the project (name, version, etc.) | -| `intro-targets.json` | Full list of all build targets | -| `intro-tests.json` | Lists all tests with instructions how to run them | +| File | Description | +| ------------------------------ | ------------------------------------------------------------------- | +| `intro-benchmarks.json` | Lists all benchmarks | +| `intro-buildoptions.json` | Contains a full list of meson configuration options for the project | +| `intro-buildsystem_files.json` | Full list of all meson build files | +| `intro-dependencies.json` | Lists all dependencies used in the project | +| `intro-installed.json` | Contains mapping of files to their installed location | +| `intro-projectinfo.json` | Stores basic information about the project (name, version, etc.) | +| `intro-targets.json` | Full list of all build targets | +| `intro-tests.json` | Lists all tests with instructions how to run them | The content of the JSON files is further specified in the remainder of this document. @@ -99,15 +99,15 @@ for actual compilation. The following table shows all valid types for a target. -| value of `type` | Description | -| --------------- | ----------- | -| `executable` | This target will generate an executable file | -| `static library` | Target for a static library | -| `shared library` | Target for a shared library | +| value of `type` | Description | +| ---------------- | --------------------------------------------------------------------------------------------- | +| `executable` | This target will generate an executable file | +| `static library` | Target for a static library | +| `shared library` | Target for a shared library | | `shared module` | A shared library that is meant to be used with dlopen rather than linking into something else | -| `custom` | A custom target | -| `run` | A Meson run target | -| `jar` | A Java JAR target | +| `custom` | A custom target | +| `run` | A Meson run target | +| `jar` | A Java JAR target | ### Using `--targets` without a build directory @@ -275,11 +275,62 @@ command line. Use `meson introspect -h` to see all available options. This API can also work without a build directory for the `--projectinfo` command. +# AST of a `meson.build` + +Since meson *0.55.0* it is possible to dump the AST of a `meson.build` as a JSON +object. The interface for this is `meson introspect --ast /path/to/meson.build`. + +Each node of the AST has at least the following entries: + +| Key | Description | +| ------------ | ------------------------------------------------------- | +| `node` | Type of the node (see following table) | +| `lineno` | Line number of the node in the file | +| `colno` | Column number of the node in the file | +| `end_lineno` | Marks the end of the node (may be the same as `lineno`) | +| `end_colno` | Marks the end of the node (may be the same as `colno`) | + +Possible values for `node` with additional keys: + +| Node type | Additional keys | +| -------------------- | ------------------------------------------------ | +| `BooleanNode` | `value`: bool | +| `IdNode` | `value`: str | +| `NumberNode` | `value`: int | +| `StringNode` | `value`: str | +| `ContinueNode` | | +| `BreakNode` | | +| `ArgumentNode` | `positional`: node list; `kwargs`: accept_kwargs | +| `ArrayNode` | `args`: node | +| `DictNode` | `args`: node | +| `EmptyNode` | | +| `OrNode` | `left`: node; `right`: node | +| `AndNode` | `left`: node; `right`: node | +| `ComparisonNode` | `left`: node; `right`: node; `ctype`: str | +| `ArithmeticNode` | `left`: node; `right`: node; `op`: str | +| `NotNode` | `right`: node | +| `CodeBlockNode` | `lines`: node list | +| `IndexNode` | `object`: node; `index`: node | +| `MethodNode` | `object`: node; `args`: node; `name`: str | +| `FunctionNode` | `args`: node; `name`: str | +| `AssignmentNode` | `value`: node; `var_name`: str | +| `PlusAssignmentNode` | `value`: node; `var_name`: str | +| `ForeachClauseNode` | `items`: node; `block`: node; `varnames`: list | +| `IfClauseNode` | `ifs`: node list; `else`: node | +| `IfNode` | `condition`: node; `block`: node | +| `UMinusNode` | `right`: node | +| `TernaryNode` | `condition`: node; `true`: node; `false`: node | + +We do not guarantee the stability of this format since it is heavily linked to +the internal Meson AST. However, breaking changes (removal of a node type or the +removal of a key) are unlikely and will be announced in the release notes. + + # Existing integrations - [Gnome Builder](https://wiki.gnome.org/Apps/Builder) - [KDevelop](https://www.kdevelop.org) - [Eclipse CDT](https://www.eclipse.org/cdt/) (experimental) -- [Meson Cmake Wrapper](https://github.com/prozum/meson-cmake-wrapper) (for cmake IDEs) +- [Meson Cmake Wrapper](https://github.com/prozum/meson-cmake-wrapper) (for cmake IDEs) (currently unmaintained !!) - [Meson-UI](https://github.com/michaelbadcrumble/meson-ui) (Meson build GUI) - [Meson Syntax Highlighter](https://plugins.jetbrains.com/plugin/13269-meson-syntax-highlighter) plugin for JetBrains IDEs. diff --git a/docs/markdown/Kconfig-module.md b/docs/markdown/Keyval-module.md index 5807f8d9a..643265e3b 100644 --- a/docs/markdown/Kconfig-module.md +++ b/docs/markdown/Keyval-module.md @@ -1,15 +1,15 @@ --- -short-description: Unstable kconfig module +short-description: Unstable keyval module authors: - name: Mark Schulte, Paolo Bonzini years: [2017, 2019] has-copyright: false ... -# Unstable kconfig module +# keyval module -This module parses Kconfig output files to allow use of kconfig -configurations in meson projects. +This module parses files consisting of a series of `key=value` lines. One use +of this module is to load kconfig configurations in meson projects. **Note**:Â this does not provide kconfig frontend tooling to generate a configuration. You still need something such as kconfig frontends (see @@ -23,20 +23,23 @@ chosen the configuration options), output a ".config" file. The module may be imported as follows: ``` meson -kconfig = import('unstable-kconfig') +keyval = import('unstable-keyval') ``` The following functions will then be available as methods on the object -with the name `kconfig`. You can, of course, replace the name -`kconfig` with anything else. +with the name `keyval`. You can, of course, replace the name +`keyval` with anything else. -### kconfig.load() +### keyval.load() -This function loads a kconfig output file and returns a dictionary object. +This function loads a file consisting of a series of `key=value` lines +and returns a dictionary object. -`kconfig.load()` makes no attempt at parsing the values in the -file. Therefore, true boolean values will be represented as the string "y" -and integer values will have to be converted with `.to_int()`. +`keyval.load()` makes no attempt at parsing the values in the file. +In particular boolean and integer values will be represented as strings, +and strings will keep any quoting that is present in the input file. It +can be useful to create a [`configuration_data()`](#configuration_data) +object from the dictionary and use methods such as `get_unquoted()`. Kconfig frontends usually have ".config" as the default name for the configuration file. However, placing the configuration file in the source diff --git a/docs/markdown/Precompiled-headers.md b/docs/markdown/Precompiled-headers.md index d9ac7a42c..05b50bcc1 100644 --- a/docs/markdown/Precompiled-headers.md +++ b/docs/markdown/Precompiled-headers.md @@ -51,7 +51,7 @@ Using precompiled headers with GCC and derivatives -- Once you have a file to precompile, you can enable the use of pch for -a give target with a *pch* keyword argument. As an example, let's assume +a given target with a *pch* keyword argument. As an example, let's assume you want to build a small C binary with precompiled headers. Let's say the source files of the binary use the system headers `stdio.h` and `string.h`. Then you create a header file `pch/myexe_pch.h` with this diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index 5156b5b45..9b5d65741 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -600,8 +600,12 @@ be passed to [shared and static libraries](#library). depends on such as a symbol visibility map. The purpose is to automatically trigger a re-link (but not a re-compile) of the target when this file changes. -- `link_language` since 0.51.0 makes the linker for this target - be for the specified language. This is helpful for multi-language targets. +- `link_language` since 0.51.0 (broken until 0.55.0) makes the linker for this + target be for the specified language. It is generally unnecessary to set + this, as meson will detect the right linker to use in most cases. There are + only two cases where this is needed. One, your main function in an + executable is not in the language meson picked, or second you want to force + a library to use only one ABI. - `link_whole` links all contents of the given static libraries whether they are used by not, equivalent to the `-Wl,--whole-archive` argument flag of GCC, available since 0.40.0. @@ -1609,6 +1613,13 @@ object](#build-target-object) returned by object](#external-program-object) returned by [`find_program()`](#find_program). +*Since 0.55.0* When cross compiling, if an exe_wrapper is needed and defined +the environment variable `MESON_EXE_WRAPPER` will be set to the string value +of that wrapper (implementation detail: using `mesonlib.join_args`). Test +scripts may use this to run cross built binaries. If your test needs +`MESON_EXE_WRAPPER` in cross build situations it is your responsibility to +return code 77 to tell the harness to report "skip" + By default, environment variable [`MALLOC_PERTURB_`](http://man7.org/linux/man-pages/man3/mallopt.3.html) is automatically set by `meson test` to a random value between 1..255. @@ -1662,11 +1673,14 @@ test(..., env: nomalloc, ...) before test is executed even if they have `build_by_default : false`. Since 0.46.0 -- `protocol` specifies how the test results are parsed and can be one - of `exitcode` (the executable's exit code is used by the test harness - to record the outcome of the test) or `tap` ([Test Anything - Protocol](https://www.testanything.org/)). For more on the Meson test - harness protocol read [Unit Tests](Unit-tests.md). Since 0.50.0 +- `protocol` *(Since 0.50.0)* specifies how the test results are parsed and can + be one of `exitcode`, `tap`, or `gtest`. For more information about test + harness protocol read [Unit Tests](Unit-tests.md). The following values are + accepted: + - `exitcode`: the executable's exit code is used by the test harness + to record the outcome of the test) + - `tap` ([Test Anything Protocol](https://www.testanything.org/)) + - `gtest`. *(Since 0.55.0)* for Google Tests. - `priority` specifies the priority of a test. Tests with a higher priority are *started* before tests with a lower priority. @@ -1735,6 +1749,8 @@ the following methods. 0.49.0, the function only accepted a single argument. Since 0.54.0 the `MESON_SOURCE_ROOT` and `MESON_BUILD_ROOT` environment variables are set when dist scripts are run. + *(Since 0.55.0)* The output of `configure_file`, `files`, and `find_program` + as well as strings. - `add_install_script(script_name, arg1, arg2, ...)` causes the script given as an argument to be run during the install step, this script @@ -1742,6 +1758,9 @@ the following methods. `MESON_BUILD_ROOT`, `MESON_INSTALL_PREFIX`, `MESON_INSTALL_DESTDIR_PREFIX`, and `MESONINTROSPECT` set. All positional arguments are passed as parameters. + *(Since 0.55.0)* The output of `configure_file`, `files`, `find_program`, + `custom_target`, indexes of `custom_target`, `executable`, `library`, and + other built targets as well as strings. *(added 0.54)* If `meson install` is called with the `--quiet` option, the environment variable `MESON_INSTALL_QUIET` will be set. @@ -1772,6 +1791,8 @@ the following methods. executable given as an argument after all project files have been generated. This script will have the environment variables `MESON_SOURCE_ROOT` and `MESON_BUILD_ROOT` set. + *(Since 0.55.0)* The output of `configure_file`, `files`, and `find_program` + as well as strings. - `backend()` *(added 0.37.0)* returns a string representing the current backend: `ninja`, `vs2010`, `vs2015`, `vs2017`, `vs2019`, @@ -1822,10 +1843,14 @@ the following methods. If `native: false` or not specified, variable is retrieved from the cross-file if cross-compiling, and from the native-file when not cross-compiling. -- `has_exe_wrapper()` returns true when doing a cross build if there - is a wrapper command that can be used to execute cross built - binaries (for example when cross compiling from Linux to Windows, - one can use `wine` as the wrapper). +- `can_run_host_binaries()` returns true if the build machine can run + binaries compiled for the host. This returns true unless you are + cross compiling, need a helper to run host binaries, and don't have one. + For example when cross compiling from Linux to Windows, one can use `wine` + as the helper. *New in 0.55.0* + +- `has_exe_wrapper()` alias of `can_run_host_binaries` + *Deprecated since 0.55.0* - `install_dependency_manifest(output_name)` installs a manifest file containing a list of all subprojects, their versions and license @@ -1846,7 +1871,9 @@ the following methods. specifies that whenever `find_program` is used to find a program named `progname`, Meson should not look it up on the system but instead return `program`, which may either be the result of - `find_program`, `configure_file` or `executable`. + `find_program`, `configure_file` or `executable`. *Since 0.55.0* if a version + check is passed to `find_program` for a program that has been overridden with + an executable, the current project version is used. If `program` is an `executable`, it cannot be used during configure. @@ -2460,6 +2487,12 @@ and has the following methods: - `path()` which returns a string pointing to the script or executable **NOTE:** You should not need to use this method. Passing the object itself should work in all cases. For example: `run_command(obj, arg1, arg2)` + *Since 0.55.0* this method has been deprecated in favor of `full_path()` for + consistency with other returned objects. + +- `full_path()` *Since 0.55.0* which returns a string pointing to the script or + executable **NOTE:** You should not need to use this method. Passing the object + itself should work in all cases. For example: `run_command(obj, arg1, arg2)`. ### `environment` object diff --git a/docs/markdown/Reference-tables.md b/docs/markdown/Reference-tables.md index dfae33902..c42d608ca 100644 --- a/docs/markdown/Reference-tables.md +++ b/docs/markdown/Reference-tables.md @@ -81,6 +81,7 @@ set in the cross file. | alpha | DEC Alpha processor | | arc | 32 bit ARC processor | | arm | 32 bit ARM processor | +| avr | Atmel AVR processor | | e2k | MCST Elbrus processor | | c2000 | 32 bit C2000 processor | | ia64 | Itanium processor | diff --git a/docs/markdown/Release-notes-for-0.54.0.md b/docs/markdown/Release-notes-for-0.54.0.md index 2c8880c08..3202b5712 100644 --- a/docs/markdown/Release-notes-for-0.54.0.md +++ b/docs/markdown/Release-notes-for-0.54.0.md @@ -14,7 +14,7 @@ If it set to 0 then the PTHREAD_POOL_SIZE option will not be passed. ## Introduce dataonly for the pkgconfig module This allows users to disable writing out the inbuilt variables to -the pkg-config file as they might actualy not be required. +the pkg-config file as they might actually not be required. One reason to have this is for architecture-independent pkg-config files in projects which also have architecture-dependent outputs. diff --git a/docs/markdown/Syntax.md b/docs/markdown/Syntax.md index cf0516cff..666d50e59 100644 --- a/docs/markdown/Syntax.md +++ b/docs/markdown/Syntax.md @@ -588,3 +588,73 @@ FAQ](FAQ.md#why-is-meson-not-just-a-python-module-so-i-could-code-my-build-setup because of this limitation you find yourself copying and pasting code a lot you may be able to use a [`foreach` loop instead](#foreach-statements). + +Stability Promises +-- + +Meson is very actively developed and continuously improved. There is a +possibility that future enhancements to the Meson build system will require +changes to the syntax. Such changes might be the addition of new reserved +keywords, changing the meaning of existing keywords or additions around the +basic building blocks like statements and fundamental types. It is planned +to stabilize the syntax with the 1.0 release. + +Grammar +-- + +This is the full Meson grammar, as it is used to parse Meson build definition files: + +``` +additive_expression: multiplicative_expression | (additive_expression additive_operator multiplicative_expression) +additive_operator: "+" | "-" +argument_list: positional_arguments ["," keyword_arguments] | keyword_arguments +array_literal: "[" [expression_list] "]" +assignment_expression: conditional_expression | (logical_or_expression assignment_operator assignment_expression) +assignment_operator: "=" | "*=" | "/=" | "%=" | "+=" | "-=" +boolean_literal: "true" | "false" +build_definition: (NEWLINE | statement)* +condition: expression +conditional_expression: logical_or_expression | (logical_or_expression "?" expression ":" assignment_expression +decimal_literal: DECIMAL_NUMBER +DECIMAL_NUMBER: /[1-9][0-9]*/ +dictionary_literal: "{" [key_value_list] "}" +equality_expression: relational_expression | (equality_expression equality_operator relational_expression) +equality_operator: "==" | "!=" +expression: assignment_expression +expression_list: expression ("," expression)* +expression_statememt: expression +function_expression: id_expression "(" [argument_list] ")" +hex_literal: "0x" HEX_NUMBER +HEX_NUMBER: /[a-fA-F0-9]+/ +id_expression: IDENTIFIER +IDENTIFIER: /[a-zA-Z_][a-zA-Z_0-9]*/ +identifier_list: id_expression ("," id_expression)* +integer_literal: decimal_literal | octal_literal | hex_literal +iteration_statement: "foreach" identifier_list ":" id_expression NEWLINE (statement | jump_statement)* "endforeach" +jump_statement: ("break" | "continue") NEWLINE +key_value_item: expression ":" expression +key_value_list: key_value_item ("," key_value_item)* +keyword_item: id_expression ":" expression +keyword_arguments: keyword_item ("," keyword_item)* +literal: integer_literal | string_literal | boolean_literal | array_literal | dictionary_literal +logical_and_expression: equality_expression | (logical_and_expression "and" equality_expression) +logical_or_expression: logical_and_expression | (logical_or_expression "or" logical_and_expression) +method_expression: postfix_expression "." function_expression +multiplicative_expression: unary_expression | (multiplicative_expression multiplicative_operator unary_expression) +multiplicative_operator: "*" | "/" | "%" +octal_literal: "0o" OCTAL_NUMBER +OCTAL_NUMBER: /[0-7]+/ +positional_arguments: expression ("," expression)* +postfix_expression: primary_expression | subscript_expression | function_expression | method_expression +primary_expression: literal | ("(" expression ")") | id_expression +relational_expression: additive_expression | (relational_expression relational_operator additive_expression) +relational_operator: ">" | "<" | ">=" | "<=" | "in" | ("not" "in") +selection_statement: "if" condition NEWLINE (statement)* ("elif" condition NEWLINE (statement)*)* ["else" (statement)*] "endif" +statement: (expression_statement | selection_statement | iteration_statement) NEWLINE +string_literal: ("'" STRING_SIMPLE_VALUE "'") | ("'''" STRING_MULTILINE_VALUE "'''") +STRING_MULTILINE_VALUE: \.*?(''')\ +STRING_SIMPLE_VALUE: \.*?(?<!\\)(\\\\)*?'\ +subscript_expression: postfix_expression "[" expression "]" +unary_expression: postfix_expression | (unary_operator unary_expression) +unary_operator: "not" | "+" | "-" +``` diff --git a/docs/markdown/Unit-tests.md b/docs/markdown/Unit-tests.md index 0785549a5..bd91dbb6b 100644 --- a/docs/markdown/Unit-tests.md +++ b/docs/markdown/Unit-tests.md @@ -4,20 +4,24 @@ short-description: Meson's own unit-test system # Unit tests -Meson comes with a fully functional unit test system. To use it simply build an executable and then use it in a test. +Meson comes with a fully functional unit test system. To use it simply build +an executable and then use it in a test. ```meson e = executable('prog', 'testprog.c') test('name of test', e) ``` -You can add as many tests as you want. They are run with the command `ninja test`. +You can add as many tests as you want. They are run with the command `ninja +test`. -Meson captures the output of all tests and writes it in the log file `meson-logs/testlog.txt`. +Meson captures the output of all tests and writes it in the log file +`meson-logs/testlog.txt`. ## Test parameters -Some tests require the use of command line arguments or environment variables. These are simple to define. +Some tests require the use of command line arguments or environment +variables. These are simple to define. ```meson test('command line test', exe, args : ['first', 'second']) @@ -29,38 +33,46 @@ Note how you need to specify multiple values as an array. ### MALLOC_PERTURB_ By default, environment variable -[`MALLOC_PERTURB_`](http://man7.org/linux/man-pages/man3/mallopt.3.html) -is set to a random value between 1..255. This can help find memory -leaks on configurations using glibc, including with non-GCC compilers. -This feature can be disabled as discussed in [test()](Reference-manual.md#test). +[`MALLOC_PERTURB_`](http://man7.org/linux/man-pages/man3/mallopt.3.html) is +set to a random value between 1..255. This can help find memory leaks on +configurations using glibc, including with non-GCC compilers. This feature +can be disabled as discussed in [test()](Reference-manual.md#test). ## Coverage If you enable coverage measurements by giving Meson the command line flag -`-Db_coverage=true`, you can generate coverage reports after running the tests -(running the tests is required to gather the list of functions that get -called). Meson will autodetect what coverage generator tools you have installed -and will generate the corresponding targets. These targets are `coverage-xml` -and `coverage-text` which are both provided by [Gcovr](http://gcovr.com) -(version 3.3 or higher) and `coverage-html`, which requires -[Lcov](https://ltp.sourceforge.io/coverage/lcov.php) and -[GenHTML](https://linux.die.net/man/1/genhtml) or -[Gcovr](http://gcovr.com). As a convenience, a high-level `coverage` target is -also generated which will produce all 3 coverage report types, if possible. - -The output of these commands is written to the log directory `meson-logs` in your build directory. +`-Db_coverage=true`, you can generate coverage reports after running the +tests (running the tests is required to gather the list of functions that get +called). Meson will autodetect what coverage generator tools you have +installed and will generate the corresponding targets. These targets are +`coverage-xml` and `coverage-text` which are both provided by +[Gcovr](http://gcovr.com) (version 3.3 or higher) and `coverage-html`, which +requires [Lcov](https://ltp.sourceforge.io/coverage/lcov.php) and +[GenHTML](https://linux.die.net/man/1/genhtml) or [Gcovr](http://gcovr.com). +As a convenience, a high-level `coverage` target is also generated which will +produce all 3 coverage report types, if possible. + +The output of these commands is written to the log directory `meson-logs` in +your build directory. ## Parallelism -To reduce test times, Meson will by default run multiple unit tests in parallel. It is common to have some tests which can not be run in parallel because they require unique hold on some resource such as a file or a D-Bus name. You have to specify these tests with a keyword argument. +To reduce test times, Meson will by default run multiple unit tests in +parallel. It is common to have some tests which can not be run in parallel +because they require unique hold on some resource such as a file or a D-Bus +name. You have to specify these tests with a keyword argument. ```meson test('unique test', t, is_parallel : false) ``` -Meson will then make sure that no other unit test is running at the same time. Non-parallel tests take longer to run so it is recommended that you write your unit tests to be parallel executable whenever possible. +Meson will then make sure that no other unit test is running at the same +time. Non-parallel tests take longer to run so it is recommended that you +write your unit tests to be parallel executable whenever possible. -By default Meson uses as many concurrent processes as there are cores on the test machine. You can override this with the environment variable `MESON_TESTTHREADS` like this. +By default Meson uses as many concurrent processes as there are cores on the +test machine. You can override this with the environment variable +`MESON_TESTTHREADS` like this. ```console $ MESON_TESTTHREADS=5 ninja test @@ -70,7 +82,10 @@ $ MESON_TESTTHREADS=5 ninja test *(added in version 0.52.0)* -Tests can be assigned a priority that determines when a test is *started*. Tests with higher priority are started first, tests with lower priority started later. The default priority is 0, meson makes no guarantee on the ordering of tests with identical priority. +Tests can be assigned a priority that determines when a test is *started*. +Tests with higher priority are started first, tests with lower priority +started later. The default priority is 0, meson makes no guarantee on the +ordering of tests with identical priority. ```meson test('started second', t, priority : 0) @@ -78,23 +93,37 @@ test('started third', t, priority : -50) test('started first', t, priority : 1000) ``` -Note that the test priority only affects the starting order of tests and subsequent tests are affected by how long it takes previous tests to complete. It is thus possible that a higher-priority test is still running when lower-priority tests with a shorter runtime have completed. +Note that the test priority only affects the starting order of tests and +subsequent tests are affected by how long it takes previous tests to +complete. It is thus possible that a higher-priority test is still running +when lower-priority tests with a shorter runtime have completed. ## Skipped tests and hard errors Sometimes a test can only determine at runtime that it can not be run. -For the default `exitcode` testing protocol, the GNU standard approach in this case is to exit the program with error code 77. Meson will detect this and report these tests as skipped rather than failed. This behavior was added in version 0.37.0. +For the default `exitcode` testing protocol, the GNU standard approach in +this case is to exit the program with error code 77. Meson will detect this +and report these tests as skipped rather than failed. This behavior was added +in version 0.37.0. -For TAP-based tests, skipped tests should print a single line starting with `1..0 # SKIP`. +For TAP-based tests, skipped tests should print a single line starting with +`1..0 # SKIP`. -In addition, sometimes a test fails set up so that it should fail even if it is marked as an expected failure. The GNU standard approach in this case is to exit the program with error code 99. Again, Meson will detect this and report these tests as `ERROR`, ignoring the setting of `should_fail`. This behavior was added in version 0.50.0. +In addition, sometimes a test fails set up so that it should fail even if it +is marked as an expected failure. The GNU standard approach in this case is +to exit the program with error code 99. Again, Meson will detect this and +report these tests as `ERROR`, ignoring the setting of `should_fail`. This +behavior was added in version 0.50.0. ## Testing tool -The goal of the meson test tool is to provide a simple way to run tests in a variety of different ways. The tool is designed to be run in the build directory. +The goal of the meson test tool is to provide a simple way to run tests in a +variety of different ways. The tool is designed to be run in the build +directory. -The simplest thing to do is just to run all tests, which is equivalent to running `ninja test`. +The simplest thing to do is just to run all tests, which is equivalent to +running `ninja test`. ```console $ meson test @@ -125,7 +154,8 @@ Tests belonging to a suite `suite` can be run as follows $ meson test --suite (sub)project_name:suite ``` -Since version *0.46*, `(sub)project_name` can be omitted if it is the top-level project. +Since version *0.46*, `(sub)project_name` can be omitted if it is the +top-level project. Multiple suites are specified like: @@ -145,7 +175,8 @@ Sometimes you need to run the tests multiple times, which is done like this: $ meson test --repeat=10 ``` -Invoking tests via a helper executable such as Valgrind can be done with the `--wrap` argument +Invoking tests via a helper executable such as Valgrind can be done with the +`--wrap` argument ```console $ meson test --wrap=valgrind testname @@ -163,17 +194,25 @@ Meson also supports running the tests under GDB. Just doing this: $ meson test --gdb testname ``` -Meson will launch `gdb` all set up to run the test. Just type `run` in the GDB command prompt to start the program. +Meson will launch `gdb` all set up to run the test. Just type `run` in the +GDB command prompt to start the program. -The second use case is a test that segfaults only rarely. In this case you can invoke the following command: +The second use case is a test that segfaults only rarely. In this case you +can invoke the following command: ```console $ meson test --gdb --repeat=10000 testname ``` -This runs the test up to 10 000 times under GDB automatically. If the program crashes, GDB will halt and the user can debug the application. Note that testing timeouts are disabled in this case so `meson test` will not kill `gdb` while the developer is still debugging it. The downside is that if the test binary freezes, the test runner will wait forever. +This runs the test up to 10 000 times under GDB automatically. If the program +crashes, GDB will halt and the user can debug the application. Note that +testing timeouts are disabled in this case so `meson test` will not kill +`gdb` while the developer is still debugging it. The downside is that if the +test binary freezes, the test runner will wait forever. -Sometimes, the GDB binary is not in the PATH variable or the user wants to use a GDB replacement. Therefore, the invoked GDB program can be specified *(added 0.52.0)*: +Sometimes, the GDB binary is not in the PATH variable or the user wants to +use a GDB replacement. Therefore, the invoked GDB program can be specified +*(added 0.52.0)*: ```console $ meson test --gdb --gdb-path /path/to/gdb testname @@ -183,12 +222,41 @@ $ meson test --gdb --gdb-path /path/to/gdb testname $ meson test --print-errorlogs ``` -Meson will report the output produced by the failing tests along with other useful information as the environmental variables. This is useful, for example, when you run the tests on Travis-CI, Jenkins and the like. +Meson will report the output produced by the failing tests along with other +useful information as the environmental variables. This is useful, for +example, when you run the tests on Travis-CI, Jenkins and the like. -For further information see the command line help of Meson by running `meson test -h`. +For further information see the command line help of Meson by running `meson +test -h`. ## Legacy notes -If `meson test` does not work for you, you likely have a old version of Meson. -In that case you should call `mesontest` instead. If `mesontest` doesn't work -either you have a very old version prior to 0.37.0 and should upgrade. +If `meson test` does not work for you, you likely have a old version of +Meson. In that case you should call `mesontest` instead. If `mesontest` +doesn't work either you have a very old version prior to 0.37.0 and should +upgrade. + +## Test outputs + +Meson will write several different files with detailed results of running +tests. These will be written into $builddir/meson-logs/ + +### testlog.json + +This is not a proper json file, but a file containing one valid json object +per line. This is file is designed so each line is streamed out as each test +is run, so it can be read as a stream while the test harness is running + +### testlog.junit.xml + +This is a valid JUnit XML description of all tests run. It is not streamed +out, and is written only once all tests complete running. + +When tests use the `tap` protocol each test will be recorded as a testsuite +container, with each case named by the number of the result. + +When tests use the `gtest` protocol meson will inject arguments to the test +to generate it's own JUnit XML, which meson will include as part of this XML +file. + +*New in 0.55.0* diff --git a/docs/markdown/Users.md b/docs/markdown/Users.md index bfc8a7a32..41d8dfa58 100644 --- a/docs/markdown/Users.md +++ b/docs/markdown/Users.md @@ -124,6 +124,7 @@ format files - [Terminology](https://github.com/billiob/terminology), a terminal emulator based on the Enlightenment Foundation Libraries - [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 + - [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 - [VMAF](https://github.com/Netflix/vmaf) (by Netflix), a perceptual video quality assessment based on multi-method fusion diff --git a/docs/markdown/howtox.md b/docs/markdown/howtox.md index 8231d3d9a..84546b73c 100644 --- a/docs/markdown/howtox.md +++ b/docs/markdown/howtox.md @@ -260,3 +260,28 @@ The `cmake_module_path` property is only needed for custom CMake scripts. System wide CMake scripts are found automatically. More information can be found [here](Dependencies.md#cmake) + +## Get a default not-found dependency? + +```meson +null_dep = dependency('', required : false) +``` + +This can be used in cases where you want a default value, but might override it +later. + +```meson +# Not needed on Windows! +my_dep = dependency('', required : false) +if host_machine.system() in ['freebsd', 'netbsd', 'openbsd', 'dragonfly'] + my_dep = dependency('some dep', required : false) +elif host_machine.system() == 'linux' + my_dep = dependency('some other dep', required : false) +endif + +executable( + 'myexe', + my_sources, + deps : [my_dep] +) +``` diff --git a/docs/markdown/snippets/add_foo_script_type_additions.md b/docs/markdown/snippets/add_foo_script_type_additions.md new file mode 100644 index 000000000..88a88b226 --- /dev/null +++ b/docs/markdown/snippets/add_foo_script_type_additions.md @@ -0,0 +1,24 @@ +## meson.add_*_script methods accept new types + +All three (`add_install_script`, `add_dist_script`, and +`add_postconf_script`) now accept ExternalPrograms (as returned by +`find_program`), Files, and the output of `configure_file`. The dist and +postconf methods cannot accept other types because of when they are run. +While dist could, in theory, take other dependencies, it would require more +extensive changes, particularly to the backend. + +```meson +meson.add_install_script(find_program('foo'), files('bar')) +meson.add_dist_script(find_program('foo'), files('bar')) +meson.add_postconf_script(find_program('foo'), files('bar')) +``` + +The install script variant is also able to accept custom_targets, +custom_target indexes, and build targets (executables, libraries), and can +use built executables a the script to run + +```meson +installer = executable('installer', ...) +meson.add_install_script(installer, ...) +meson.add_install_script('foo.py', installer) +``` diff --git a/docs/markdown/snippets/can_run_host_binaries.md b/docs/markdown/snippets/can_run_host_binaries.md new file mode 100644 index 000000000..010818470 --- /dev/null +++ b/docs/markdown/snippets/can_run_host_binaries.md @@ -0,0 +1,5 @@ +## Rename has_exe_wrapper -> can_run_host_binaries + +The old name was confusing as it didn't really match the behavior of the +function. The old name remains as an alias (the behavior hasn't changed), but +is now deprecated. diff --git a/docs/markdown/snippets/config_tool_no_cross_path.md b/docs/markdown/snippets/config_tool_no_cross_path.md new file mode 100644 index 000000000..cec22e482 --- /dev/null +++ b/docs/markdown/snippets/config_tool_no_cross_path.md @@ -0,0 +1,7 @@ +## Config tool based dependencies no longer search PATH for cross compiling + +Before 0.55.0 config tool based dependencies (llvm-config, cups-config, etc), +would search system $PATH if they weren't defined in the cross file. This has +been a source of bugs and has been deprecated. It is now removed, config tool +binaries must be specified in the cross file now or the dependency will not +be found. diff --git a/docs/markdown/snippets/d-lang_n_debug.md b/docs/markdown/snippets/d-lang_n_debug.md new file mode 100644 index 000000000..59f09e41b --- /dev/null +++ b/docs/markdown/snippets/d-lang_n_debug.md @@ -0,0 +1,4 @@ +## b_ndebug support for D language compilers + +D Language compilers will now set -release/--release/-frelease (depending on +the compiler) when the b_ndebug flag is set. diff --git a/docs/markdown/snippets/exe_wrapper_for_cross_built_tests.md b/docs/markdown/snippets/exe_wrapper_for_cross_built_tests.md new file mode 100644 index 000000000..ebdd8a743 --- /dev/null +++ b/docs/markdown/snippets/exe_wrapper_for_cross_built_tests.md @@ -0,0 +1,9 @@ +## Test scripts are given the exe wrapper if needed + +Meson will now set the `MESON_EXE_WRAPPER` as the properly wrapped and joined +representation. For Unix-like OSes this means python's shelx.join, on Windows +an implementation that attempts to properly quote windows argument is used. +This allow wrapper scripts to run test binaries, instead of just skipping. + +for example, if the wrapper is `['emulator', '--script']`, it will be passed +as `MESON_EXE_WRAPPER="emulator --script"`. diff --git a/docs/markdown/snippets/find_program.md b/docs/markdown/snippets/find_program.md new file mode 100644 index 000000000..d0bb64ddb --- /dev/null +++ b/docs/markdown/snippets/find_program.md @@ -0,0 +1,20 @@ +## find_program: Fixes when the program has been overridden by executable + +When a program has been overridden by an executable, the returned object of +find_program() had some issues: + +```meson +# In a subproject: +exe = executable('foo', ...) +meson.override_find_program('foo', exe) + +# In main project: +# The version check was crashing meson. +prog = find_program('foo', version : '>=1.0') + +# This was crashing meson. +message(prog.path()) + +# New method to be consistent with built objects. +message(prog.full_path()) +``` diff --git a/docs/markdown/snippets/gtest_protocol.md b/docs/markdown/snippets/gtest_protocol.md new file mode 100644 index 000000000..14f3af915 --- /dev/null +++ b/docs/markdown/snippets/gtest_protocol.md @@ -0,0 +1,6 @@ +## Test protocol for gtest + +Due to the popularity of Gtest (google test) among C and C++ developers meson +now supports a special protocol for gtest. With this protocol meson injects +arguments to gtests to output JUnit, reads that JUnit, and adds the output to +the JUnit it generates. diff --git a/docs/markdown/snippets/introspect.md b/docs/markdown/snippets/introspect.md new file mode 100644 index 000000000..8eab48624 --- /dev/null +++ b/docs/markdown/snippets/introspect.md @@ -0,0 +1,4 @@ +## Introspection API changes + +dumping the AST (--ast): **new in 0.55.0** +- prints the AST of a meson.build as JSON diff --git a/docs/markdown/snippets/junit_result_generation.md b/docs/markdown/snippets/junit_result_generation.md new file mode 100644 index 000000000..fbe910bb8 --- /dev/null +++ b/docs/markdown/snippets/junit_result_generation.md @@ -0,0 +1,4 @@ +## Meson test now produces JUnit xml from results + +Meson will now generate a JUnit compatible XML file from test results. it +will be in the meson-logs directory and is called testlog.junit.xml. diff --git a/docs/markdown/snippets/keyval_kobject.md b/docs/markdown/snippets/keyval_kobject.md new file mode 100644 index 000000000..4add23c4f --- /dev/null +++ b/docs/markdown/snippets/keyval_kobject.md @@ -0,0 +1,6 @@ +## `unstable-kconfig` module renamed to `unstable-keyval` + +The `unstable-kconfig` module is now renamed to `unstable-keyval`. +We expect this module to become stable once it has some usage experience, +specifically in the next or the following release + diff --git a/docs/markdown/snippets/link_language_all_targets.md b/docs/markdown/snippets/link_language_all_targets.md new file mode 100644 index 000000000..9019d502d --- /dev/null +++ b/docs/markdown/snippets/link_language_all_targets.md @@ -0,0 +1,8 @@ +## link_language argument added to all targets + +Previously the `link_language` argument was only supposed to be allowed in +executables, because the linker used needs to be the linker for the language +that implements the main function. Unfortunately it didn't work in that case, +and, even worse, if it had been implemented properly it would have worked for +*all* targets. In 0.55.0 this restriction has been removed, and the bug fixed. +It now is valid for `executable` and all derivative of `library`. diff --git a/docs/markdown/snippets/options_string_concat.md b/docs/markdown/snippets/options_string_concat.md new file mode 100644 index 000000000..0fbf0f4b9 --- /dev/null +++ b/docs/markdown/snippets/options_string_concat.md @@ -0,0 +1,14 @@ +## String concatenation in meson_options.txt + +It is now possible to use string concatenation (with the `+` opperator) in the +meson_options.txt file. This allows splitting long option descriptions. + +```meson +option( + 'testoption', + type : 'string', + value : 'optval', + description : 'An option with a very long description' + + 'that does something in a specific context' +) +``` diff --git a/docs/markdown/snippets/rpath_behavior.md b/docs/markdown/snippets/rpath_behavior.md new file mode 100644 index 000000000..c46f0c2e6 --- /dev/null +++ b/docs/markdown/snippets/rpath_behavior.md @@ -0,0 +1,7 @@ +## rpath removal now more careful + +On Linux-like systems, meson adds rpath entries to allow running apps +in the build tree, and then removes those build-time-only +rpath entries when installing. Rpath entries may also come +in via LDFLAGS and via .pc files. Meson used to remove those +latter rpath entries by accident, but is now more careful. diff --git a/docs/sitemap.txt b/docs/sitemap.txt index 3ac138ef1..4029a609b 100644 --- a/docs/sitemap.txt +++ b/docs/sitemap.txt @@ -48,7 +48,7 @@ index.md SourceSet-module.md Windows-module.md Cuda-module.md - Kconfig-module.md + Keyval-module.md Java.md Vala.md D.md diff --git a/docs/theme/extra/templates/navbar_links.html b/docs/theme/extra/templates/navbar_links.html index 6980f8143..832bd2c49 100644 --- a/docs/theme/extra/templates/navbar_links.html +++ b/docs/theme/extra/templates/navbar_links.html @@ -14,7 +14,7 @@ ("Hotdoc-module.html","Hotdoc"), \ ("i18n-module.html","i18n"), \ ("Icestorm-module.html","Icestorm"), \ - ("Kconfig-module.html","kconfig"), \ + ("Keyval-module.html","Keyval"), \ ("Pkgconfig-module.html","Pkgconfig"), \ ("Python-module.html","Python"), \ ("Python-3-module.html","Python 3"), \ |