1 files changed, 93 insertions, 0 deletions
diff --git a/meson/docs/markdown/Using-multiple-build-directories.md b/meson/docs/markdown/Using-multiple-build-directories.md
new file mode 100644
index 000000000..557f3444d
--- /dev/null
+++ b/meson/docs/markdown/Using-multiple-build-directories.md
@@ -0,0 +1,93 @@
+# Using multiple build directories
+
+One of the main design goals of Meson has been to build all projects
+out-of-source. This means that *all* files generated during the build
+are placed in a separate subdirectory. This goes against common Unix
+tradition where you build your projects in-source. Building out of
+source gives two major advantages.
+
+First of all this makes for very simple `.gitignore` files. In
+classical build systems you may need to have tens of lines of
+definitions, most of which contain wildcards. When doing out of source
+builds all of this busywork goes away. A common ignore file for a
+Meson project only contains a few lines that are the build directory
+and IDE project files.
+
+Secondly this makes it very easy to clean your projects: just delete
+the build subdirectory and you are done. There is no need to guess
+whether you need to run `make clean`, `make distclean`, `make
+mrproper` or something else. When you delete a build subdirectory
+there is no possible way to have any lingering state from your old
+builds.
+
+The true benefit comes from somewhere else, though.
+
+## Multiple build directories for the same source tree
+
+Since a build directory is fully self contained and treats the source
+tree as a read-only piece of data, it follows that you can have
+arbitrarily many build trees for any source tree at the same time.
+Since all build trees can have different configuration, this is
+extremely powerful. Now you might be wondering why one would want to
+have multiple build setups at the same time. Let's examine this by
+setting up a hypothetical project.
+
+The first thing to do is to set up the default build, that is, the one
+we are going to use over 90% of the time. In this we use the system
+compiler and build with debug enabled and no optimizations so it
+builds as fast as possible. This is the default project type for
+Meson, so setting it up is simple.
+
+    mkdir builddir
+    meson builddir
+
+Another common setup is to build with debug and optimizations to, for
+example, run performance tests. Setting this up is just as simple.
+
+    mkdir buildopt
+    meson --buildtype=debugoptimized buildopt
+
+For systems where the default compiler is GCC, we would like to
+compile with Clang, too. So let's do that.
+
+    mkdir buildclang
+    CC=clang CXX=clang++ meson buildclang
+
+You can add cross builds, too. As an example, let's set up a Linux ->
+Windows cross compilation build using MinGW.
+
+    mkdir buildwine
+    meson --cross-file=mingw-cross.txt buildwine
+
+The cross compilation file sets up Wine so that not only can you
+compile your application, you can also run the unit test suite just by
+issuing the command `meson test`.
+
+To compile any of these build types, just cd into the corresponding
+build directory and run `meson compile` or instruct your IDE to do the
+same. Note that once you have set up your build directory once, you
+can just run Ninja and Meson will ensure that the resulting build is
+fully up to date according to the source. Even if you have not touched
+one of the directories in weeks and have done major changes to your
+build configuration, Meson will detect this and bring the build
+directory up to date (or print an error if it can't do that). This
+allows you to do most of your work in the default directory and use
+the others every now and then without having to babysit your build
+directories.
+
+## Specialized uses
+
+Separate build directories allows easy integration for various
+different kinds of tools. As an example, Clang comes with a static
+analyzer. It is meant to be run from scratch on a given source tree.
+The steps to run it with Meson are very simple.
+
+    rm -rf buildscan
+    mkdir buildscan
+    scan-build meson buildscan
+    cd buildscan
+    scan-build ninja
+
+These commands are the same for every single Meson project, so they
+could even be put in a script turning static analysis into a single
+command.