diff options
Diffstat (limited to 'docs/markdown/Using-multiple-build-directories.md')
| -rw-r--r-- | docs/markdown/Using-multiple-build-directories.md | 74 |
1 files changed, 59 insertions, 15 deletions
diff --git a/docs/markdown/Using-multiple-build-directories.md b/docs/markdown/Using-multiple-build-directories.md index ab6cf3c..557f344 100644 --- a/docs/markdown/Using-multiple-build-directories.md +++ b/docs/markdown/Using-multiple-build-directories.md @@ -1,44 +1,86 @@ # 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. +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. +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. +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. +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. +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. +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. +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. +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 @@ -46,4 +88,6 @@ Separate build directories allows easy integration for various different kinds o 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. +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. |