short-description: Build options to configure project properties
...
# Build options
Most non-trivial builds require user-settable options. As an example a program may have two different data backends that are selectable at build time. Meson provides for this by having a option definition file. Its name is `meson_options.txt` and it is placed at the root of your source tree.
short-description: Converting other build systems to Meson
...
# Build system converters
Moving from one build system into another includes a fair bit of work. To make things easier, Meson provides scripts to convert other build systems into Meson. At the time of writing, scripts for CMake and autotools exist. It can be found in the `tools` subdirectory in Meson's source tree.
If there are multiple configuration options, passing them through compiler flags becomes very burdensome. It also makes the configuration settings hard to inspect. To make things easier, Meson supports the generation of configure files. This feature is similar to one found in other build systems such as CMake.
short-description: Configuring a pre-generated build directory
...
# Configuring a build directory
Often you want to change the settings of your build after it has been generated. For example you might want to change from a debug build into a release build, set custom compiler flags, change the build options provided in your `meson_options.txt` file and so on.
short-description: Creating universal Linux binaries
...
# Creating Linux binaries
Creating Linux binaries that can be downloaded and run on any distro (like .dmg packages for OSX or .exe installers for Windows) has traditionally been difficult. This is even more tricky if you want to use modern compilers and features, which is especially desired in game development. There is still no simple turn key solution for this problem but with a bit of setup it can be relatively straightforward.
Meson does not have native support for building OSX packages but it does provide all the tools you need to create one yourself. The reason for this is that it is a very hard task to write a system that provides for all the different ways to do that but it is very easy to write simple scripts for each application.
short-description: Build targets for custom languages or corner-cases
...
# Custom build targets
While Meson tries to support as many languages and tools as possible, there is no possible way for it to cover all corner cases. For these cases it permits you to define custom build targets. Here is how one would use it.
short-description: Dependencies for external libraries and frameworks
...
# Dependencies
Very few applications are fully self-contained, but rather they use external libraries and frameworks to do their work. Meson makes it very easy to find and use external dependencies. Here is how one would use the Zlib compression library.
short-description: Generation of source files before compilation
...
# Generating sources
Sometimes source files need to be preprocessed before they are passed to the actual compiler. As an example you might want build an IDL compiler and then run some files through that to generate actual source files. In Meson this is done with [`generator()`](https://github.com/mesonbuild/meson/wiki/Reference-manual#generator) or [`custom_target()`](https://github.com/mesonbuild/meson/wiki/Reference-manual#custom_target).
short-description: Meson's API to integrate Meson support into an IDE
...
# IDE integration
Meson has exporters for Visual Studio and XCode, but writing a custom backend for every IDE out there is not a scalable approach. To solve this problem, Meson provides an API that makes it easy for any IDE or build tool to integrate Meson builds and provide an experience comparable to a solution native to the IDE.
@ -6,7 +10,7 @@ The basic tool for this is a script called `mesonintrospect.py`. Some distro pac
The first thing to do when setting up a Meson project in an IDE is to select the source and build directories. For this example we assume that the source resides in an Eclipse-like directory called `workspace/project` and the build tree is nested inside it as `workspace/project/build`. First we initialise Meson by running the following command in the source directory.
meson build
meson builddir
For the remainder of the document we assume that all commands are executed inside the build directory unless otherwise specified.
@ -32,7 +36,7 @@ The next thing to display is the list of options that can be set. These include
To set the options, use the `mesonconf.py` binary.
Compilation and unit tests are done as usual by running the `ninja` and `ninja test` commands. A JSON formatted result log can be found in `workspace/project/build/meson-logs/testlog.json`.
Compilation and unit tests are done as usual by running the `ninja` and `ninja test` commands. A JSON formatted result log can be found in `workspace/project/builddir/meson-logs/testlog.json`.
When these tests fail, the user probably wants to run the failing test in a debugger. To make this as integrated as possible, extract the test test setups with this command.
short-description: Instructions on handling include directories
...
# Include directories
Most `C`/`C++` projects have headers in different directories than sources. Thus you need to specify include directories. Let's assume that we are at some subdirectory and wish to add its `include` subdirectory to some target's search path. To create a include directory object we do this:
@ -78,7 +78,7 @@ At this point we can return to the pkg-config generator line. All shared librari
With these four files we are done. To configure, build and run the test suite, we just need to execute the following commands (starting at source tree root directory).
Localising your application with GNU Gettext takes a little effort but is quite straightforward. This documentation assumes that you have a `po` subdirectory at your project root directory that contains all the localisation info.
short-description: Meson modules for common build operations
...
# Modules
In addition to core language features, Meson also provides a module system aimed at providing helper methods for common build operations. Using modules is simple, first you import them:
short-description: Using precompiled headers to reduce compilation time
...
# Precompiled headers
Parsing header files of system libraries is surprisingly expensive. A typical source file has less than one thousand lines of code. In contrast the headers of large libraries can be tens of thousands of lines. This is especially problematic with C++, where header-only libraries are common and they may contain extremely complex code. This makes them slow to compile.
The command line switch `--buildtype=plain` tells Meson not to add its own flags to the command line. This gives the packager total control on used flags.
@ -696,7 +696,7 @@ Provides information about the build machine — the machine that is doing the a
- `system()` returns the operating system name, such as `windows` (all versions of Windows), `linux` (all Linux distros), `darwin` (all versions of OS X), etc.
- `endian()` returns `big` on big-endian systems and `little` on little-endian systems.
Currently, these values are populated using the [`platform.system()`](https://docs.python.org/3.4/library/platform.html#platform.system) and [`platform.machine()`](https://docs.python.org/3.4/library/platform.html#platform.machine). If you think the returned values for any of these are incorrect for your system or CPU, please file [a bug report](/mesonbuild/meson/issues/new).
Currently, these values are populated using the [`platform.system()`](https://docs.python.org/3.4/library/platform.html#platform.system) and [`platform.machine()`](https://docs.python.org/3.4/library/platform.html#platform.machine). If you think the returned values for any of these are incorrect for your system or CPU, please file [a bug report](https://github.com/mesonbuild/meson/issues/new).
short-description: Targets to run external commands
...
# Run targets
Sometimes you need to have a target that just runs an external command. As an example you might have a build target that reformats your source code, runs `cppcheck` or something similar. In Meson this is accomplished with a so called *run target*.
@ -15,8 +15,8 @@ Let us assume that we have a source tree that has a Meson build system. This mea
cd /path/to/source/root
mkdir build
cd build
mkdir builddir
cd builddir
meson ..
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.
short-description: Using meson projects as subprojects within other meson projects
...
# Subprojects
Some platforms do not provide a native packaging system. In these cases it is common to bundle all third party libraries in your source tree. This is usually frowned upon because it makes it hard to add these kinds of projects into e.g. those Linux distributions that forbid bundled libraries.
Meson has a very simple notational shorthand for enabling thread support on your build targets. First you obtain the thread dependency object like this:
That is all. We are now ready to build our application. First we need to initialise the build by going into the source directory and issuing the following commands.
```console
$ meson build
$ meson builddir
```
We create a separate build directory to hold all of the compiler output. Meson is different from some other build systems in that it does not permit in-source builds. You must always create a separate build directory. Common convention is to put the default build directory in a subdirectory of your toplevel source directory.
@ -40,7 +40,7 @@ When Meson is run it prints the following output.
The Meson build system
version: 0.13.0-research
Source dir: /home/jpakkane/mesontutorial
Build dir: /home/jpakkane/mesontutorial/build
Build dir: /home/jpakkane/mesontutorial/builddir
Build type: native build
Project name is "tutorial".
Using native c compiler "ccache cc". (gcc 4.8.2)
@ -49,7 +49,7 @@ When Meson is run it prints the following output.
Now we are ready to build our code.
```
$ cd build
$ cd builddir
$ ninja
```
@ -102,7 +102,7 @@ Once you have set up your build directory the first time, you don't ever need to
short-description: Unity builds are a technique for reducing build times
...
# Unity builds
Unity builds are a technique for cutting down build times. The way it works is relatively straightforward. Suppose we have source files `src1.c`, `src2.c` and `src3.c`. Normally we would run the compiler three times, once for each file. In a unity build we instead compile all these sources in a single unit. The simplest approach is to create a new source file that looks like this.
@ -14,13 +14,13 @@ Since a build directory is fully self contained and treats the source tree as a
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 build
meson build
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
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.
If you wish to use the Ninja backend instead of vs2015, pass `--backend ninja`. At the time of writing the Ninja backend is more mature than the VS backend so you might want to use it for serious work.
Jussi Pakkanen
8 years ago
committed by
GitHub