docs/machine-files: Add a section on data types

This attempts to clarify the usage of strings and arrays, as well as
document the boolean type that has been exposed via the project and
built-in options
pull/6597/head
Dylan Baker 4 years ago
parent 17c8193615
commit 1ca17dc853
  1. 48
      docs/markdown/Machine-files.md

@ -5,6 +5,37 @@ documentation on the common values used by both, for the specific values of
one or the other see the [cross compilation](Cross-compilation.md) and [native one or the other see the [cross compilation](Cross-compilation.md) and [native
environments](Native-environments.md). environments](Native-environments.md).
## Data Types
There are four basic data types in a machine file:
- strings
- arrays
- booleans
- integers
A string is specified single quoted:
```ini
[section]
option1 = 'false'
option2 = '2'
```
An array is enclosed in square brackets, and must consist of strings or booleans
```ini
[section]
option = ['value']
```
A boolean must be either `true` or `false`, and unquoted.
```ini
option = false
```
An integer must be either an unquoted numeric constant;
```ini
option = 42
```
## Sections ## Sections
The following sections are allowed: The following sections are allowed:
@ -90,14 +121,16 @@ a = 'Hello'
### Binaries ### Binaries
The binaries section contains a list of binaries. These can be used The binaries section contains a list of binaries. These can be used
internally by meson, or by the `find_program` function: internally by meson, or by the `find_program` function.
These values must be either strings or an array of strings
Compilers and linkers are defined here using `<lang>` and `<lang>_ld`. Compilers and linkers are defined here using `<lang>` and `<lang>_ld`.
`<lang>_ld` is special because it is compiler specific. For compilers like `<lang>_ld` is special because it is compiler specific. For compilers like
gcc and clang which are used to invoke the linker this is a value to pass to gcc and clang which are used to invoke the linker this is a value to pass to
their "choose the linker" argument (-fuse-ld= in this case). For compilers their "choose the linker" argument (-fuse-ld= in this case). For compilers
like MSVC and Clang-Cl, this is the path to a linker for meson to invoke, like MSVC and Clang-Cl, this is the path to a linker for meson to invoke,
such as `link.exe` or `lld-link.exe`. Support for ls is *new in 0.53.0* such as `link.exe` or `lld-link.exe`. Support for `ld` is *new in 0.53.0*
*changed in 0.53.1* the `ld` variable was replaced by `<lang>_ld`, because it *changed in 0.53.1* the `ld` variable was replaced by `<lang>_ld`, because it
*regressed a large number of projects. in 0.53.0 the `ld` variable was used *regressed a large number of projects. in 0.53.0 the `ld` variable was used
@ -115,8 +148,8 @@ llvm-config = '/usr/lib/llvm8/bin/llvm-config'
Cross example: Cross example:
```ini ```ini
c = '/usr/bin/i586-mingw32msvc-gcc' c = ['ccache', '/usr/bin/i586-mingw32msvc-gcc']
cpp = '/usr/bin/i586-mingw32msvc-g++' cpp = ['ccache', '/usr/bin/i586-mingw32msvc-g++']
c_ld = 'gold' c_ld = 'gold'
cpp_ld = 'gold' cpp_ld = 'gold'
ar = '/usr/i586-mingw32msvc/bin/ar' ar = '/usr/i586-mingw32msvc/bin/ar'
@ -140,7 +173,7 @@ An incomplete list of internally used programs that can be overridden here is:
### Paths and Directories ### Paths and Directories
As of 0.50.0 paths and directories such as libdir can be defined in the native As of 0.50.0 paths and directories such as libdir can be defined in the native
file in a paths section and cross files in a paths section. These should be strings
```ini ```ini
[paths] [paths]
@ -186,7 +219,6 @@ build-tests = true
build-tests = false build-tests = false
``` ```
### Meson built-in options ### Meson built-in options
Meson built-in options can be set the same way: Meson built-in options can be set the same way:
@ -230,9 +262,9 @@ An incomplete list of options is:
## Loading multiple machine files ## Loading multiple machine files
Native files allow layering (cross files can be layered since meson 0.52.0). Native files allow layering (cross files can be layered since meson 0.52.0).
More than one native file can be loaded, with values from a previous file being More than one file can be loaded, with values from a previous file being
overridden by the next. The intention of this is not overriding, but to allow overridden by the next. The intention of this is not overriding, but to allow
composing native files. This composition is done by passing the command line composing files. This composition is done by passing the command line
argument multiple times: argument multiple times:
```console ```console

Loading…
Cancel
Save