Add submodule dependency filesHEADmaster

Change-Id: Iaf8d18082d3991dec7c0ebbea540f092188eb4ec

1 files changed, 210 insertions, 0 deletions

diff --git a/meson/docs/markdown/Running-Meson.md b/meson/docs/markdown/Running-Meson.md
new file mode 100644
index 000000000..2873cbc1b
--- /dev/null
+++ b/meson/docs/markdown/Running-Meson.md
@@ -0,0 +1,210 @@
+---
+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`. Second, 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".
+
+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.
+
+```sh
+cd /path/to/source/root
+meson setup builddir
+```
+
+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`.
+
+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).
+
+You can specify a different type of build with the `--buildtype` command line
+argument. It can have one of the following values.
+
+| value            | meaning                                                                                                                                                    |
+| ------           | --------                                                                                                                                                   |
+| `plain`          | no extra build flags are used, even for compiler warnings, useful for distro packagers and other cases where you need to specify all arguments by yourself |
+| `debug`          | debug info is generated but the result is not optimized, this is the default                                                                               |
+| `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.
+
+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=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`.
+
+## 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.
+
+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
+
+To start the build, simply type the following command.
+
+```sh
+meson compile -C builddir
+```
+
+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.
+
+```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.
+
+## Running tests
+
+Meson provides native support for running tests. The command to do
+that is simple.
+
+```sh
+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.
+
+Note: it can be also invoked directly with ninja with the following command:
+```sh
+ninja -C builddir test
+```
+
+## Installing
+
+Installing the built software is just as simple.
+
+```sh
+meson install -C builddir
+```
+
+See [`meson install` description](Commands.md#install) for more info.
+
+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:
+
+```sh
+DESTDIR=/path/to/staging meson install -C builddir
+```
+
+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 --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.