The Meson Build System
http://mesonbuild.com/
238 lines
5.2 KiB
238 lines
5.2 KiB
.TH MESON "1" "July 2021" "meson 0.59.0" "User Commands" |
|
.SH NAME |
|
meson - a high productivity build system |
|
.SH DESCRIPTION |
|
|
|
Meson is a build system designed to optimize programmer |
|
productivity. It aims to do this by providing simple, out-of-the-box |
|
support for modern software development tools and practices, such as |
|
unit tests, coverage reports, Valgrind, Ccache and the like. |
|
|
|
The main Meson executable provides many subcommands to access all |
|
the functionality. |
|
|
|
.SH The setup command |
|
|
|
Using Meson is simple and follows the common two-phase |
|
process of most build systems. First you run Meson to |
|
configure your build: |
|
|
|
.B meson setup [ |
|
.I options |
|
.B ] [ |
|
.I build directory |
|
.B ] [ |
|
.I source directory |
|
.B ] |
|
|
|
Note that the build directory must be different from the source |
|
directory. Meson does not support building inside the source directory |
|
and attempting to do that leads to an error. |
|
|
|
After a successful configuration step you can build the source by |
|
running the actual build command in the build directory. The default |
|
backend of Meson is Ninja, which can be invoked like this. |
|
|
|
\fBninja [\fR \fItarget\fR \fB]\fR |
|
|
|
You only need to run the Meson command once: when you first configure |
|
your build dir. After that you just run the build command. Meson will |
|
autodetect changes in your source tree and regenerate all files |
|
needed to build the project. |
|
|
|
The setup command is the default operation. If no actual command is |
|
specified, Meson will assume you meant to do a setup. That means |
|
that you can set up a build directory without the setup command |
|
like this: |
|
|
|
.B meson [ |
|
.I options |
|
.B ] [ |
|
.I build directory |
|
.B ] [ |
|
.I source directory |
|
.B ] |
|
|
|
.SS "options:" |
|
.TP |
|
\fB\-\-version\fR |
|
print version number |
|
.TP |
|
\fB\-\-help\fR |
|
print command line help |
|
|
|
.SH The configure command |
|
|
|
.B meson configure |
|
provides a way to configure a Meson project from the command line. |
|
Its usage is simple: |
|
|
|
.B meson configure [ |
|
.I build directory |
|
.B ] [ |
|
.I options to set |
|
.B ] |
|
|
|
If build directory is omitted, the current directory is used instead. |
|
|
|
If no parameters are set, |
|
.B meson configure |
|
will print the value of all build options to the console. |
|
|
|
To set values, use the \-D command line argument like this. |
|
|
|
.B meson configure \-Dopt1=value1 \-Dopt2=value2 |
|
|
|
.SH The introspect command |
|
|
|
Meson introspect is a command designed to make it simple to integrate with |
|
other tools, such as IDEs. The output of this command is in JSON. |
|
|
|
.B meson introspect [ |
|
.I build directory |
|
.B ] [ |
|
.I option |
|
.B ] |
|
|
|
If build directory is omitted, the current directory is used instead. |
|
|
|
.SS "options:" |
|
.TP |
|
\fB\-\-targets\fR |
|
print all top level targets (executables, libraries, etc) |
|
.TP |
|
\fB\-\-target\-files\fR |
|
print the source files of the given target |
|
.TP |
|
\fB\-\-buildsystem\-files\fR |
|
print all files that make up the build system (meson.build, meson_options.txt etc) |
|
.TP |
|
\fB\-\-tests\fR |
|
print all unit tests |
|
.TP |
|
\fB\-\-help\fR |
|
print command line help |
|
|
|
.SH The test command |
|
|
|
.B meson test |
|
is a helper tool for running test suites of projects using Meson. |
|
The default way of running tests is to invoke the default build command: |
|
|
|
\fBninja [\fR \fItest\fR \fB]\fR |
|
|
|
.B meson test |
|
provides a richer set of tools for invoking tests. |
|
|
|
.B meson test |
|
automatically rebuilds the necessary targets to run tests when used with the Ninja backend. |
|
Upon build failure, |
|
.B meson test |
|
will return an exit code of 125. |
|
This return code tells |
|
.B git bisect run |
|
to skip the current commit. |
|
Thus bisecting using git can be done conveniently like this. |
|
|
|
.B git bisect run meson test -C build_dir |
|
|
|
.SS "options:" |
|
.TP |
|
\fB\-\-repeat\fR |
|
run tests as many times as specified |
|
.TP |
|
\fB\-\-gdb\fR |
|
run tests under gdb |
|
.TP |
|
\fB\-\-list\fR |
|
list all available tests |
|
.TP |
|
\fB\-\-wrapper\fR |
|
invoke all tests via the given wrapper (e.g. valgrind) |
|
.TP |
|
\fB\-C\fR |
|
Change into the given directory before running tests (must be root of build directory). |
|
.TP |
|
\fB\-\-suite\fR |
|
run tests in this suite |
|
.TP |
|
\fB\-\-no\-suite\fR |
|
do not run tests in this suite |
|
.TP |
|
\fB\-\-no\-stdsplit\fR |
|
do not split stderr and stdout in test logs |
|
.TP |
|
\fB\-\-benchmark\fR |
|
run benchmarks instead of tests |
|
.TP |
|
\fB\-\-logbase\fR |
|
base of file name to use for writing test logs |
|
.TP |
|
\fB\-\-num-processes\fR |
|
how many parallel processes to use to run tests |
|
.TP |
|
\fB\-\-verbose\fR |
|
do not redirect stdout and stderr |
|
.TP |
|
\fB\-t\fR |
|
a multiplier to use for test timeout values (usually something like 100 for Valgrind) |
|
.TP |
|
\fB\-\-setup\fR |
|
use the specified test setup |
|
|
|
.SH The wrap command |
|
|
|
Wraptool is a helper utility to manage source dependencies |
|
using the online wrapdb service. |
|
|
|
.B meson wrap < |
|
.I command |
|
.B > [ |
|
.I options |
|
.B ] |
|
|
|
You should run this command in the top level source directory |
|
of your project. |
|
|
|
.SS "Commands:" |
|
.TP |
|
\fBlist\fR |
|
list all available projects |
|
.TP |
|
\fBsearch\fR |
|
search projects by name |
|
.TP |
|
\fBinstall\fR |
|
install a project with the given name |
|
.TP |
|
\fBupdate\fR |
|
update the specified project to latest available version |
|
.TP |
|
\fBinfo\fR |
|
show available versions of the specified project |
|
.TP |
|
\fBstatus\fR |
|
show installed and available versions of currently used subprojects |
|
|
|
.SH EXIT STATUS |
|
|
|
.TP |
|
.B 0 |
|
Successful. |
|
.TP |
|
.B 1 |
|
Usage error, or an error parsing or executing meson.build. |
|
.TP |
|
.B 2 |
|
Internal error. |
|
.TP |
|
.B 125 |
|
.B meson test |
|
could not rebuild the required targets. |
|
.TP |
|
|
|
.SH SEE ALSO |
|
|
|
http://mesonbuild.com/ |
|
|
|
https://wrapdb.mesonbuild.com/
|
|
|