manual/meson/original/man1/meson.1

   1 .TH MESON "1" "November 2021" "meson 0.60.2" "User Commands"
   2 .SH NAME
   3 meson - a high productivity build system
   4 .SH DESCRIPTION
   5
   6 Meson is a build system designed to optimize programmer
   7 productivity. It aims to do this by providing simple, out-of-the-box
   8 support for modern software development tools and practices, such as
   9 unit tests, coverage reports, Valgrind, Ccache and the like.
  10
  11 The main Meson executable provides many subcommands to access all
  12 the functionality.
  13
  14 .SH The setup command
  15
  16 Using Meson is simple and follows the common two-phase
  17 process of most build systems. First you run Meson to
  18 configure your build:
  19
  20 .B meson setup [
  21 .I options
  22 .B ] [
  23 .I build directory
  24 .B ] [
  25 .I source directory
  26 .B ]
  27
  28 Note that the build directory must be different from the source
  29 directory. Meson does not support building inside the source directory
  30 and attempting to do that leads to an error.
  31
  32 After a successful configuration step you can build the source by
  33 running the actual build command in the build directory. The default
  34 backend of Meson is Ninja, which can be invoked like this.
  35
  36 \fBninja [\fR \fItarget\fR \fB]\fR
  37
  38 You only need to run the Meson command once: when you first configure
  39 your build dir. After that you just run the build command. Meson will
  40 autodetect changes in your source tree and regenerate all files
  41 needed to build the project.
  42
  43 The setup command is the default operation. If no actual command is
  44 specified, Meson will assume you meant to do a setup. That means
  45 that you can set up a build directory without the setup command
  46 like this:
  47
  48 .B meson [
  49 .I options
  50 .B ] [
  51 .I build directory
  52 .B ] [
  53 .I source directory
  54 .B ]
  55
  56 .SS "options:"
  57 .TP
  58 \fB\-\-version\fR
  59 print version number
  60 .TP
  61 \fB\-\-help\fR
  62 print command line help
  63
  64 .SH The configure command
  65
  66 .B meson configure
  67 provides a way to configure a Meson project from the command line.
  68 Its usage is simple:
  69
  70 .B meson configure [
  71 .I build directory
  72 .B ] [
  73 .I options to set
  74 .B ]
  75
  76 If build directory is omitted, the current directory is used instead.
  77
  78 If no parameters are set,
  79 .B meson configure
  80 will print the value of all build options to the console.
  81
  82 To set values, use the \-D command line argument like this.
  83
  84 .B meson configure \-Dopt1=value1 \-Dopt2=value2
  85
  86 .SH The introspect command
  87
  88 Meson introspect is a command designed to make it simple to  integrate with
  89 other tools, such as IDEs. The output of this command is in JSON.
  90
  91 .B meson introspect [
  92 .I build directory
  93 .B ] [
  94 .I option
  95 .B ]
  96
  97 If build directory is omitted, the current directory is used instead.
  98
  99 .SS "options:"
 100 .TP
 101 \fB\-\-targets\fR
 102 print all top level targets (executables, libraries, etc)
 103 .TP
 104 \fB\-\-target\-files\fR
 105 print the source files of the given target
 106 .TP
 107 \fB\-\-buildsystem\-files\fR
 108 print all files that make up the build system (meson.build, meson_options.txt etc)
 109 .TP
 110 \fB\-\-tests\fR
 111 print all unit tests
 112 .TP
 113 \fB\-\-help\fR
 114 print command line help
 115
 116 .SH The test command
 117
 118 .B meson test
 119 is a helper tool for running test suites of projects using Meson.
 120 The default way of running tests is to invoke the default build command:
 121
 122 \fBninja [\fR \fItest\fR \fB]\fR
 123
 124 .B meson test
 125 provides a richer set of tools for invoking tests.
 126
 127 .B meson test
 128 automatically rebuilds the necessary targets to run tests when used with the Ninja backend.
 129 Upon build failure,
 130 .B meson test
 131 will return an exit code of 125.
 132 This return code tells
 133 .B git bisect run
 134 to skip the current commit.
 135 Thus bisecting using git can be done conveniently like this.
 136
 137 .B git bisect run meson test -C build_dir
 138
 139 .SS "options:"
 140 .TP
 141 \fB\-\-repeat\fR
 142 run tests as many times as specified
 143 .TP
 144 \fB\-\-gdb\fR
 145 run tests under gdb
 146 .TP
 147 \fB\-\-list\fR
 148 list all available tests
 149 .TP
 150 \fB\-\-wrapper\fR
 151 invoke all tests via the given wrapper (e.g. valgrind)
 152 .TP
 153 \fB\-C\fR
 154 Change into the given directory before running tests (must be root of build directory).
 155 .TP
 156 \fB\-\-suite\fR
 157 run tests in this suite
 158 .TP
 159 \fB\-\-no\-suite\fR
 160 do not run tests in this suite
 161 .TP
 162 \fB\-\-no\-stdsplit\fR
 163 do not split stderr and stdout in test logs
 164 .TP
 165 \fB\-\-benchmark\fR
 166 run benchmarks instead of tests
 167 .TP
 168 \fB\-\-logbase\fR
 169 base of file name to use for writing test logs
 170 .TP
 171 \fB\-\-num-processes\fR
 172 how many parallel processes to use to run tests
 173 .TP
 174 \fB\-\-verbose\fR
 175 do not redirect stdout and stderr
 176 .TP
 177 \fB\-t\fR
 178 a multiplier to use for test timeout values (usually something like 100 for Valgrind)
 179 .TP
 180 \fB\-\-setup\fR
 181 use the specified test setup
 182
 183 .SH The wrap command
 184
 185 Wraptool is a helper utility to manage source dependencies
 186 using the online wrapdb service.
 187
 188 .B meson wrap <
 189 .I command
 190 .B > [
 191 .I options
 192 .B ]
 193
 194 You should run this command in the top level source directory
 195 of your project.
 196
 197 .SS "Commands:"
 198 .TP
 199 \fBlist\fR
 200 list all available projects
 201 .TP
 202 \fBsearch\fR
 203 search projects by name
 204 .TP
 205 \fBinstall\fR
 206 install a project with the given name
 207 .TP
 208 \fBupdate\fR
 209 update the specified project to latest available version
 210 .TP
 211 \fBinfo\fR
 212 show available versions of the specified project
 213 .TP
 214 \fBstatus\fR
 215 show installed and available versions of currently used subprojects
 216
 217 .SH EXIT STATUS
 218
 219 .TP
 220 .B 0
 221 Successful.
 222 .TP
 223 .B 1
 224 Usage error, or an error parsing or executing meson.build.
 225 .TP
 226 .B 2
 227 Internal error.
 228 .TP
 229 .B 125
 230 .B meson test
 231 could not rebuild the required targets.
 232 .TP
 233
 234 .SH SEE ALSO
 235
 236 http://mesonbuild.com/
 237
 238 https://wrapdb.mesonbuild.com/