The Meson Build System
http://mesonbuild.com/
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
165 lines
4.7 KiB
165 lines
4.7 KiB
--- |
|
short-description: Build-time configuration options |
|
... |
|
|
|
# Configuration |
|
|
|
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. |
|
|
|
Suppose we have the following Meson snippet: |
|
|
|
```meson |
|
conf_data = configuration_data() |
|
conf_data.set('version', '1.2.3') |
|
configure_file(input : 'config.h.in', |
|
output : 'config.h', |
|
configuration : conf_data) |
|
``` |
|
|
|
and that the contents of `config.h.in` are |
|
|
|
```c |
|
#define VERSION_STR "@version@" |
|
``` |
|
|
|
Meson will then create a file called `config.h` in the corresponding |
|
build directory whose contents are the following. |
|
|
|
```c |
|
#define VERSION_STR "1.2.3" |
|
``` |
|
|
|
More specifically, Meson will find all strings of the type `@varname@` |
|
and replace them with respective values set in `conf_data`. You can |
|
use a single `configuration_data` object as many times as you like, |
|
but it becomes immutable after being passed to the `configure_file` |
|
function. That is, after it has been used once to generate output the |
|
`set` function becomes unusable and trying to call it causes an error. |
|
Copy of immutable `configuration_data` is still immutable. |
|
|
|
For more complex configuration file generation Meson provides a second |
|
form. To use it, put a line like this in your configuration file. |
|
|
|
#mesondefine TOKEN |
|
|
|
The replacement that happens depends on what the value and type of TOKEN is: |
|
|
|
```c |
|
#define TOKEN // If TOKEN is set to boolean true. |
|
#undef TOKEN // If TOKEN is set to boolean false. |
|
#define TOKEN 4 // If TOKEN is set to an integer or string value. |
|
/* undef TOKEN */ // If TOKEN has not been set to any value. |
|
``` |
|
|
|
Note that if you want to define a C string, you need to do the quoting |
|
yourself like this: |
|
|
|
```meson |
|
conf_data.set('TOKEN', '"value"') |
|
``` |
|
|
|
Since this is such a common operation, Meson provides a convenience |
|
method: |
|
|
|
```meson |
|
plain_var = 'value' |
|
conf_data.set_quoted('TOKEN', plain_var) # becomes #define TOKEN "value" |
|
``` |
|
|
|
Often you have a boolean value in Meson but need to define the C/C++ |
|
token as 0 or 1. Meson provides a convenience function for this use |
|
case. |
|
|
|
```meson |
|
conf_data.set10(token, boolean_value) |
|
# The line above is equivalent to this: |
|
if boolean_value |
|
conf_data.set(token, 1) |
|
else |
|
conf_data.set(token, 0) |
|
endif |
|
``` |
|
|
|
## Configuring without an input file |
|
|
|
If the input file is not defined then Meson will generate a header |
|
file all the entries in the configuration data object. The |
|
replacements are the same as when generating `#mesondefine` entries: |
|
|
|
```meson |
|
conf_data.set('FOO', '"string"') => #define FOO "string" |
|
conf_data.set('FOO', 'a_token') => #define FOO a_token |
|
conf_data.set('FOO', true) => #define FOO |
|
conf_data.set('FOO', false) => #undef FOO |
|
conf_data.set('FOO', 1) => #define FOO 1 |
|
conf_data.set('FOO', 0) => #define FOO 0 |
|
``` |
|
|
|
In this mode, you can also specify a comment which will be placed |
|
before the value so that your generated files are self-documenting. |
|
|
|
```meson |
|
conf_data.set('BAR', true, description : 'Set BAR if it is available') |
|
``` |
|
|
|
Will produce: |
|
|
|
```c |
|
/* Set BAR if it is available */ |
|
#define BAR |
|
``` |
|
|
|
## Dealing with file encodings |
|
|
|
The default meson file encoding to configure files is utf-8. If you need to |
|
configure a file that is not utf-8 encoded the encoding keyword will allow |
|
you to specify which file encoding to use. It is however strongly advised to |
|
convert your non utf-8 file to utf-8 whenever possible. Supported file |
|
encodings are those of python3, see [standard-encodings](https://docs.python.org/3/library/codecs.html#standard-encodings). |
|
|
|
# A full example |
|
|
|
Generating and using a configuration file requires the following steps: |
|
|
|
- generate the file |
|
- create an include directory object for the directory that holds the file |
|
- use it in a target |
|
|
|
We are going to use the traditional approach of generating a header |
|
file in the top directory. The common name is `config.h` but we're |
|
going to use an unique name. This avoids the problem of accidentally |
|
including the wrong header file when building a project with many |
|
subprojects. |
|
|
|
At the top level we generate the file: |
|
|
|
```meson |
|
conf_data = configuration_data() |
|
# Set data |
|
configure_file(input : 'projconfig.h.in', |
|
output : 'projconfig.h', |
|
configuration : conf_data) |
|
``` |
|
|
|
Immediately afterwards we generate the include object. |
|
|
|
```meson |
|
configuration_inc = include_directories('.') |
|
``` |
|
|
|
Finally we specify this in a target that can be in any subdirectory. |
|
|
|
```meson |
|
executable(..., include_directories : configuration_inc) |
|
``` |
|
|
|
Now any source file in this target can include the configuration |
|
header like this: |
|
|
|
```c |
|
#include<projconfig.h> |
|
```
|
|
|