Merge pull request #4748 from astavale/running-meson-docs

docs: update 'Running Meson' page to show Meson's setup command [skip…

1 files changed, 127 insertions, 130 deletions

diff --git a/docs/markdown/Running-Meson.md b/docs/markdown/Running-Meson.md
index 426e87d..910513c 100644
--- a/docs/markdown/Running-Meson.md
+++ b/docs/markdown/Running-Meson.md
@@ -4,49 +4,45 @@ 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.
 
-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).
 
-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".
 
-Configuring the source
-==
+## 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
+meson setup builddir
+```
 
-    cd /path/to/source/root
-    mkdir builddir
-    cd builddir
-    meson ..
+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/).
 
-First we create a directory to hold all files generated during the
-build. Then we go into it and invoke Meson, giving it the location of
-the source root.
+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 [options] [srcdir] [builddir]`,
-but you may omit either `srcdir` or `builddir`. Meson will deduce the
-`srcdir` by the location of `meson.build`. The other one will be your
-`pwd`.
+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.
-
-You can specify a different type of build with the `--buildtype`
-command line argument. It can have one of the following values.
+You can specify a different type of build with the `--buildtype` command line
+argument. It can have one of the following values.
 
 | value            | meaning                                                                                                                                                    |
 | ------           | --------                                                                                                                                                   |
@@ -55,122 +51,123 @@ 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`)                                                                  |
 | `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. 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.
-
-    cd /path/to/source/root
-    mkdir buildclang
-    cd buildclang
-    CC=clang CXX=clang++ meson ..
-
-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 build 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.
-
-    meson <source dir> <build dir> --backend=vs2010
-
-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 --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-envrionment-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.
-
-Building the source
-==
+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:
+
+```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.
+
+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.
+
+```sh
+meson setup <build dir> --backend=vs2010
+```
+
+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-envrionment-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.
+
+## Building from the source
 
 If you are not using an IDE, Meson uses the [Ninja build
-system](https://ninja-build.org/) to actually build the code. To start
-the build, simply type the following command.
+system](https://ninja-build.org/) to actually build the code. To start the
+build, simply type the following command.
 
-    ninja
+```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>`.
+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.
+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
-==
+## 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.
 
-    ninja test
+```sh
+ninja -C builddir test
+```
 
-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.
 
-Installing
-==
+## Installing
 
 Installing the built software is just as simple.
 
-    ninja install
+```sh
+ninja -C builddir install
+```
 
 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
-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:
 
-    DESTDIR=/path/to/staging ninja install
+```sh
+DESTDIR=/path/to/staging ninja -C builddir install
+```
 
-Command line help
-==
+## 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
-==
+## 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.