<!-- from https://svn.jenkins-ci.org/trunk/hudson/dtkit/dtkit-format/dtkit-junit-model/src/main/resources/com/thalesgroup/dtkit/junit/model/xsd/junit-4.xsd -->
Each wrap repository has a master branch with only one initial commit and *no* wrap files.
And that is the only commit ever made on that branch.
For every release of a project a new branch is created. The new branch is named after the
the upstream release number (e.g. `1.0.0`). This branch holds a wrap file for
For every release of a project a new branch is created. The new branch is named after the
the upstream release number (e.g. `1.0.0`). This branch holds a wrap file for
this particular release.
There are two types of wraps on WrapDB - regular wraps and wraps with Meson build
definition patches. A wrap file in a repository on WrapDB must have a name `upstream.wrap`.
Wraps with Meson build definition patches work in much the same way as Debian: we take the unaltered upstream source package and add a new build system to it as a patch. These build systems are stored as Git repositories on GitHub. They only contain build definition files. You may also think of them as an overlay to upstream source.
Wraps with Meson build definition patches work in much the same way as Debian:
we take the unaltered upstream source package and add a new build system to it as a patch.
These build systems are stored as Git repositories on GitHub. They only contain build definition files.
You may also think of them as an overlay to upstream source.
Whenever a new commit is pushed into GitHub's project branch, a new wrap is generated
with an incremented version number. All the old releases remain unaltered.
@ -21,13 +24,15 @@ New commits are always done via GitHub merge requests and must be reviewed by
someone other than the submitter.
Note that your Git repo with wrap must not contain the subdirectory of the source
release. That gets added automatically by the service. You also must not commit
release. That gets added automatically by the service. You also must not commit
any source code from the original tarball into the wrap repository.
## Choosing the repository name
Wrapped subprojects are used much like external dependencies. Thus
they should have the same name as the upstream projects.
they should have the same name as the upstream projects.
NOTE: Repo names must fully match this regexp: `[a-z0-9._]+`.
If the project provides a pkg-config file, then the repository name should be
the same as the pkg-config name. Usually this is the name of the
@ -36,16 +41,19 @@ however. As an example the libogg project's chosen pkg-config name is
`ogg` instead of `libogg`, which is the reason why the repository is
named plain `ogg`.
If there is no a pkg-config file, the name the project uses/promotes should be used,
If there is no a pkg-config file, the name the project uses/promotes should be used,
lowercase only (Catch2 -> catch2).
If the project name is too generic or ambiguous (e.g. `benchmark`),
consider using `organization-project` naming format (e.g. `google-benchmark`).
## How to contribute a new wrap
If the project already uses Meson build system, then only a wrap file - `upstream.wrap`
should be provided. In other case a Meson build definition patch - a set of `meson.build`
should be provided. In other case a Meson build definition patch - a set of `meson.build`
files - should be also provided.
### Request a new repository or branch
### Request a new repository
Create an issue on the [wrapdb bug tracker](https://github.com/mesonbuild/wrapdb/issues)
using *Title* and *Description* below as a template.
@ -48,7 +48,7 @@ Then we need to generate the main pot file. The potfile can have any name but is
Run the following command from your build folder to generate the pot file. It is recommended to inspect it manually afterwards and fill in e.g. proper copyright and contact information.
```console
$ ninja intltest-pot
$ meson compile intltest-pot
```
### generate .po files
@ -56,5 +56,5 @@ $ ninja intltest-pot
For each language listed in the array above we need a corresponding `.po` file. Those can be generated by running the following command from your build folder.
Here we create a unit test called *simple test*, and which uses the built executable. When the tests are run with the `ninja test` command, the built executable is run. If it returns zero, the test passes. A non-zero return value indicates an error, which Meson will then report to the user.
Here we create a unit test called *simple test*, and which uses the built executable. When the tests are run with the `meson test` command, the built executable is run. If it returns zero, the test passes. A non-zero return value indicates an error, which Meson will then report to the user.
@ -21,7 +21,7 @@ This method generates the necessary targets to build translation files with lrel
- `ts_files`, the list of input translation files produced by Qt's lupdate tool.
- `install` when true, this target is installed during the install step (optional).
- `install_dir` directory to install to (optional).
- `build_by_default` when set to true, to have this target be built by default, that is, when invoking plain ninja; the default value is false (optional).
- `build_by_default` when set to true, to have this target be built by default, that is, when invoking `meson compile`; the default value is false (optional).
# Supports the following operators: '>', '<', '>=', '<=', '!=', '==', '='
```
Arrays
--
Meson version comparison conventions include:
```meson
'3.6'.version_compare('>=3.6.0') == false
```
It is best to be unambiguous and specify the full revision level to compare.
## Arrays
Arrays are delimited by brackets. An array can contain an arbitrary number of objects of any type.
@ -302,6 +344,7 @@ assign it to `my_array` instead of modifying the original since all
objects in Meson are immutable.
Since 0.49.0, you can check if an array contains an element like this:
```meson
my_array = [1, 2]
if 1 in my_array
@ -312,7 +355,7 @@ if 1 not in my_array
endif
```
#### Array methods
### Array methods
The following methods are defined for all arrays:
@ -320,8 +363,7 @@ The following methods are defined for all arrays:
- `contains`, returns `true` if the array contains the object given as argument, `false` otherwise
- `get`, returns the object at the given index, negative indices count from the back of the array, indexing out of bounds is a fatal error. Provided for backwards-compatibility, it is identical to array indexing.
Dictionaries
--
## Dictionaries
Dictionaries are delimited by curly braces. A dictionary can contain an
arbitrary number of key value pairs. Keys are required to be strings, values can
@ -346,6 +388,7 @@ Visit the [Reference Manual](Reference-manual.md#dictionary-object) to read
about the methods exposed by dictionaries.
Since 0.49.0, you can check if a dictionary contains a key like this:
```meson
my_dict = {'foo': 42, 'bar': 43}
if 'foo' in my_dict
@ -361,14 +404,14 @@ endif
*Since 0.53.0* Keys can be any expression evaluating to a string value, not limited
to string literals any more.
```meson
d = {'a' + 'b' : 42}
k = 'cd'
d += {k : 43}
```
Function calls
--
## Function calls
Meson provides a set of usable functions. The most common use case is
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
$ MESON_TESTTHREADS=5 meson test
```
## Priorities
*(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
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.
```console
$ meson test
@ -107,7 +135,7 @@ For clarity, consider the meson.build containing:
```meson
test('A', ..., suite: 'foo')
test('B', ..., suite: 'foo')
test('B', ..., suite: ['foo', 'bar'])
test('C', ..., suite: 'bar')
test('D', ..., suite: 'baz')
@ -125,7 +153,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 +174,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 +193,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
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
- [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
- [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
@ -115,6 +118,7 @@ format files
- [RxDock](https://gitlab.com/rxdock/rxdock), a protein-ligand docking software designed for high throughput virtual screening (fork of rDock)
- [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
- [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
@ -124,6 +128,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
@ -32,9 +32,9 @@ You can add cross builds, too. As an example, let's set up a Linux -> Windows cr
mkdir buildwine
meson --cross-file=mingw-cross.txt buildwine
The cross compilation file sets up Wine so that not only can you compile your application, you can also run the unit test suite just by issuing the command `ninja test`.
The cross compilation file sets up Wine so that not only can you compile your application, you can also run the unit test suite just by issuing the command `meson test`.
To compile any of these build types, just cd into the corresponding build directory and run `ninja` or instruct your IDE to do the same. Note that once you have set up your build directory once, you can just run Ninja and Meson will ensure that the resulting build is fully up to date according to the source. Even if you have not touched one of the directories in weeks and have done major changes to your build configuration, Meson will detect this and bring the build directory up to date (or print an error if it can't do that). This allows you to do most of your work in the default directory and use the others every now and then without having to babysit your build directories.
To compile any of these build types, just cd into the corresponding build directory and run `meson compile` or instruct your IDE to do the same. Note that once you have set up your build directory once, you can just run Ninja and Meson will ensure that the resulting build is fully up to date according to the source. Even if you have not touched one of the directories in weeks and have done major changes to your build configuration, Meson will detect this and bring the build directory up to date (or print an error if it can't do that). This allows you to do most of your work in the default directory and use the others every now and then without having to babysit your build directories.
John Ericson
5 years ago