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