Chiebot-Mirror
/
meson
mirror of https://github.com/mesonbuild/meson.git
8
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: Re-wrap Running-Meson.md from 70 to 80 columns [skip ci]

Browse Source
pull/4748/head
Alistair Thomas 6 years ago
parent 8f24d34e31
commit 55e6d3c35e
1 changed files with 84 additions and 93 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 177
      docs/markdown/Running-Meson.md

177
docs/markdown/Running-Meson.md
Unescape View File

@ -4,26 +4,24 @@ short-description: Building a project with Meson
# Running Meson # Running Meson
There are two different ways of invoking Meson. First, you can run it There are two different ways of invoking Meson. First, you can run it directly
directly from the source tree with the command from the source tree with the command `/path/to/source/meson.py`. Meson may
`/path/to/source/meson.py`. Meson may also be installed in which case also be installed in which case the command is simply `meson`. In this manual
the command is simply `meson`. In this manual we only use the latter we only use the latter format for simplicity.
format for simplicity.
Additionally, the invocation can pass options to meson. Additionally, the invocation can pass options to meson. The list of options is
The list of options is documented [here](Builtin-options.md). documented [here](Builtin-options.md).
At the time of writing only a command line version of Meson is At the time of writing only a command line version of Meson is available. This
available. This means that Meson must be invoked using the means that Meson must be invoked using the terminal. If you wish to use the
terminal. If you wish to use the MSVC compiler, you need to run Meson MSVC compiler, you need to run Meson under "Visual Studio command prompt".
under "Visual Studio command prompt".
Configuring the source Configuring the source
== ==
Let us assume that we have a source tree that has a Meson build Let us assume that we have a source tree that has a Meson build system. This
system. This means that at the topmost directory has a file called means that at the topmost directory has a file called `meson.build`. We run the
`meson.build`. We run the following commands to get the build started. following commands to get the build started.
cd /path/to/source/root cd /path/to/source/root
@ -31,22 +29,20 @@ system. This means that at the topmost directory has a file called
cd builddir cd builddir
meson .. meson ..
First we create a directory to hold all files generated during the First we create a directory to hold all files generated during the build. Then
build. Then we go into it and invoke Meson, giving it the location of we go into it and invoke Meson, giving it the location of the source root.
the source root.
Hint: The syntax of meson is `meson [options] [srcdir] [builddir]`, Hint: The syntax of meson is `meson [options] [srcdir] [builddir]`, but you may
but you may omit either `srcdir` or `builddir`. Meson will deduce the omit either `srcdir` or `builddir`. Meson will deduce the `srcdir` by the
`srcdir` by the location of `meson.build`. The other one will be your location of `meson.build`. The other one will be your `pwd`.
`pwd`.
Meson then loads the build configuration file and writes the Meson then loads the build configuration file and writes the corresponding
corresponding build backend in the build directory. By default Meson build backend in the build directory. By default Meson generates a *debug
generates a *debug build*, which turns on basic warnings and debug build*, which turns on basic warnings and debug information and disables
information and disables compiler optimizations. compiler optimizations.
You can specify a different type of build with the `--buildtype` You can specify a different type of build with the `--buildtype` command line
command line argument. It can have one of the following values. argument. It can have one of the following values.
| value | meaning | | value | meaning |
| ------ | -------- | | ------ | -------- |
@ -55,94 +51,88 @@ command line argument. It can have one of the following values.
| `debugoptimized` | debug info is generated and the code is optimized (on most compilers this means `-g -O2`) | | `debugoptimized` | debug info is generated and the code is optimized (on most compilers this means `-g -O2`) |
| `release` | full optimization, no debug info | | `release` | full optimization, no debug info |
The build directory is mandatory. The reason for this is that it The build directory is mandatory. The reason for this is that it simplifies the
simplifies the build process immensely. Meson will not under any build process immensely. Meson will not under any circumstances write files
circumstances write files inside the source directory (if it does, it inside the source directory (if it does, it is a bug and should be fixed). This
is a bug and should be fixed). This means that the user does not need means that the user does not need to add a bunch of files to their revision
to add a bunch of files to their revision control's ignore list. It control's ignore list. It also means that you can create arbitrarily many build
also means that you can create arbitrarily many build directories for directories for any given source tree. If we wanted to test building the source
any given source tree. If we wanted to test building the source code code with the Clang compiler instead of the system default, we could just type
with the Clang compiler instead of the system default, we could just the following commands.
type the following commands.
cd /path/to/source/root cd /path/to/source/root
mkdir buildclang mkdir buildclang
cd buildclang cd buildclang
CC=clang CXX=clang++ meson .. CC=clang CXX=clang++ meson ..
This separation is even more powerful if your code has multiple This separation is even more powerful if your code has multiple configuration
configuration options (such as multiple data backends). You can create options (such as multiple data backends). You can create a separate
a separate subdirectory for each of them. You can also have build subdirectory for each of them. You can also have build directories for
directories for optimized builds, code coverage, static analysis and optimized builds, code coverage, static analysis and so on. They are all neatly
so on. They are all neatly separated and use the same source separated and use the same source tree. Changing between different
tree. Changing between different configurations is just a question of configurations is just a question of changing to the corresponding directory.
changing to the corresponding directory.
Unless otherwise mentioned, all following command line invocations are Unless otherwise mentioned, all following command line invocations are meant to
meant to be run in the build directory. be run in the build directory.
By default Meson will use the Ninja backend to build your project. If By default Meson will use the Ninja backend to build your project. If you wish
you wish to use any of the other backends, you need to pass the to use any of the other backends, you need to pass the corresponding argument
corresponding argument during configuration time. As an example, here during configuration time. As an example, here is how you would use Meson to
is how you would use Meson to generate a Visual studio solution. generate a Visual studio solution.
meson <source dir> <build dir> --backend=vs2010 meson <source dir> <build dir> --backend=vs2010
You can then open the generated solution with Visual Studio and You can then open the generated solution with Visual Studio and compile it in
compile it in the usual way. A list of backends can be obtained with the usual way. A list of backends can be obtained with `meson --help`.
`meson --help`.
Environment Variables Environment Variables
-- --
Sometimes you want to add extra compiler flags, this can be done by Sometimes you want to add extra compiler flags, this can be done by passing
passing them in environment variables when calling meson. See [the them in environment variables when calling meson. See [the reference
reference tables](Reference-tables.md#compiler-and-linker-flag-envrionment-variables) for
tables](Reference-tables.md#compiler-and-linker-flag-envrionment-variables) a list of all the environment variables. Be aware however these environment
for a list of all the environment variables. Be aware however these variables are only used for the native compiler and will not affect the
environment variables are only used for the native compiler and will compiler used for cross-compiling, where the flags specified in the cross file
not affect the compiler used for cross-compiling, where the flags will be used.
specified in the cross file will be used.
Furthermore it is possible to stop meson from adding flags itself by Furthermore it is possible to stop meson from adding flags itself by using the
using the `--buildtype=plain` option, in this case you must provide `--buildtype=plain` option, in this case you must provide the full compiler and
the full compiler and linker arguments needed. linker arguments needed.
Building the source Building the source
== ==
If you are not using an IDE, Meson uses the [Ninja build If you are not using an IDE, Meson uses the [Ninja build
system](https://ninja-build.org/) to actually build the code. To start system](https://ninja-build.org/) to actually build the code. To start the
the build, simply type the following command. build, simply type the following command.
ninja ninja
The main usability difference between Ninja and Make is that Ninja The main usability difference between Ninja and Make is that Ninja will
will automatically detect the number of CPUs in your computer and automatically detect the number of CPUs in your computer and parallelize itself
parallelize itself accordingly. You can override the amount of accordingly. You can override the amount of parallel processes used with the
parallel processes used with the command line argument `-j <num command line argument `-j <num processes>`.
processes>`.
It should be noted that after the initial configure step `ninja` is the only
It should be noted that after the initial configure step `ninja` is command you ever need to type to compile. No matter how you alter your source
the only command you ever need to type to compile. No matter how you tree (short of moving it to a completely new location), Meson will detect the
alter your source tree (short of moving it to a completely new changes and regenerate itself accordingly. This is especially handy if you have
location), Meson will detect the changes and regenerate itself multiple build directories. Often one of them is used for development (the
accordingly. This is especially handy if you have multiple build "debug" build) and others only every now and then (such as a "static analysis"
directories. Often one of them is used for development (the "debug" build). Any configuration can be built just by `cd`'ing to the corresponding
build) and others only every now and then (such as a "static analysis" directory and running Ninja.
build). Any configuration can be built just by `cd`'ing to the
corresponding directory and running Ninja.
Running tests Running tests
== ==
Meson provides native support for running tests. The command to do Meson provides native support for running tests. The command to do that is
that is simple. simple.
ninja test ninja test
Meson does not force the use of any particular testing framework. You Meson does not force the use of any particular testing framework. You are free
are free to use GTest, Boost Test, Check or even custom executables. to use GTest, Boost Test, Check or even custom executables.
Installing Installing
== ==
@ -152,25 +142,26 @@ Installing the built software is just as simple.
ninja install ninja install
Note that Meson will only install build targets explicitly tagged as Note that Meson will only install build targets explicitly tagged as
installable, as detailed in the [installing targets documentation](Installing.md). installable, as detailed in the [installing targets
documentation](Installing.md).
By default Meson installs to `/usr/local`. This can be changed by By default Meson installs to `/usr/local`. This can be changed by passing the
passing the command line argument `--prefix /your/prefix` to Meson command line argument `--prefix /your/prefix` to Meson during configure time.
during configure time. Meson also supports the `DESTDIR` variable used Meson also supports the `DESTDIR` variable used in e.g. building packages. It
in e.g. building packages. It is used like this: is used like this:
DESTDIR=/path/to/staging ninja install DESTDIR=/path/to/staging ninja install
Command line help Command line help
== ==
Meson has a standard command line help feature. It can be accessed Meson has a standard command line help feature. It can be accessed with the
with the following command. following command.
meson --help meson --help
Exit status Exit status
== ==
Meson exits with status 0 if successful, 1 for problems with the command line or Meson exits with status 0 if successful, 1 for problems with the command line
meson.build file, and 2 for internal errors. or meson.build file, and 2 for internal errors.

Write Preview
Loading…
Cancel
Save