diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/markdown/Build-options.md | 72 | ||||
| -rw-r--r-- | docs/markdown/Disabler.md | 65 | ||||
| -rw-r--r-- | docs/markdown/Reference-manual.md | 31 | ||||
| -rw-r--r-- | docs/markdown/Running-Meson.md | 102 | ||||
| -rw-r--r-- | docs/markdown/snippets/disabler.md | 33 | ||||
| -rwxr-xr-x | docs/markdown/snippets/get_unquoted.md | 4 | ||||
| -rw-r--r-- | docs/markdown/snippets/option-array-type.md | 18 | ||||
| -rw-r--r-- | docs/sitemap.txt | 1 |
8 files changed, 280 insertions, 46 deletions
diff --git a/docs/markdown/Build-options.md b/docs/markdown/Build-options.md index cb7b19e..cd7f07d 100644 --- a/docs/markdown/Build-options.md +++ b/docs/markdown/Build-options.md @@ -16,18 +16,43 @@ Here is a simple option file. option('someoption', type : 'string', value : 'optval', description : 'An option') option('other_one', type : 'boolean', value : false) option('combo_opt', type : 'combo', choices : ['one', 'two', 'three'], value : 'three') +option('free_array_opt', type : 'array', value : ['one', 'two']) +option('array_opt', type : 'array', choices : ['one', 'two', 'three'], value : ['one', 'two']) ``` -This demonstrates the three basic option types and their usage. String -option is just a free form string and a boolean option is, -unsurprisingly, true or false. The combo option can have any value -from the strings listed in argument `choices`. If `value` is not set, -it defaults to empty string for strings, `true` for booleans or the -first element in a combo. You can specify `description`, which is a -free form piece of text describing the option. It defaults to option -name. +All types allow a `description` value to be set describing the option, +if no option is set then the name of the option will be used instead. -These options are accessed in Meson code with the `get_option` function. +### Strings + +The string type is a free form string. If the default value is not set +then an empty string will be used as the default. + +### Booleans + +Booleans may have values of either `true` or `false`. If no default +value is supplied then `true` will be used as the default. + +### Combos + +A combo allows any one of the values in the `choices` parameter to be +selected. If no default value is set then the first value will be the +default. + +### Arrays + +Arrays represent an array of strings. By default the array can contain +arbitrary strings. To limit the possible values that can used set the +`choices` parameter. Meson will then only allow the value array to +contain strings that are in the given list. The array may be +empty. The `value` parameter specifies the default value of the option +and if it is unset then the values of `choices` will be used as the +default. + +This type is new in version 0.44.0 + + +## Using build options ```meson optval = get_option('opt_name') @@ -42,9 +67,9 @@ prefix = get_option('prefix') ``` It should be noted that you can not set option values in your Meson -scripts. They have to be set externally with the `meson configure` command -line tool. Running `meson configure` without arguments in a build dir shows -you all options you can set. +scripts. They have to be set externally with the `meson configure` +command line tool. Running `meson configure` without arguments in a +build dir shows you all options you can set. To change their values use the `-D` option: @@ -53,5 +78,26 @@ option: $ meson configure -Doption=newvalue ``` +Setting the value of arrays is a bit special. If you only pass a +single string, then it is considered to have all values separated by +commas. Thus invoking the following command: + +```console +$ meson configure -Darray_opt=foo,bar +``` + +would set the value to an array of two elements, `foo` and `bar`. + +If you need to have commas in your string values, then you need to +pass the value with proper shell quoting like this: + +```console +$ meson configure "-Doption=['a,b', 'c,d']" +``` + +The inner values must always be single quotes and the outer ones +double quotes. -**NOTE:** If you cannot call `meson configure` you likely have a old version of Meson. In that case you can call `mesonconf` instead, but that is deprecated in newer versions +**NOTE:** If you cannot call `meson configure` you likely have a old + version of Meson. In that case you can call `mesonconf` instead, but + that is deprecated in newer versions diff --git a/docs/markdown/Disabler.md b/docs/markdown/Disabler.md new file mode 100644 index 0000000..2d50c5c --- /dev/null +++ b/docs/markdown/Disabler.md @@ -0,0 +1,65 @@ +--- +short-description: Disabling options +... + +# Disabling parts of the build (available since 0.44.0) + +The following is a common fragment found in many projects: + +```meson +dep = dependency('foo') + +# In some different directory + +lib = shared_library('mylib', 'mylib.c', + dependencies : dep) + +# And Ãn a third directory + +exe = executable('mytest', 'mytest.c', + link_with : lib) +test('mytest', exe) +``` + +This works fine but gets a bit inflexible when you want to make this +part of the build optional. Basically it reduces to adding `if/else` +statements around all target invocations. Meson provides a simpler way +of achieving the same with a disabler object. + +A disabler object is created with the `disabler` function: + +```meson +d = disabler() +``` + +The only thing you can do to a disabler object is to ask if it has +been found: + +```meson +f = d.found() # returns false +``` + +Any other statement that uses a disabler object will immediately +return a disabler. For example assuming that `d` contains a disabler +object then + +```meson +d2 = some_func(d) # value of d2 will be disabler +d3 = true or d2 # value of d3 will be disabler +if d # neither branch is evaluated +``` + +Thus to disable every target that depends on the dependency given +above, you can do something like this: + +```meson +if use_foo_feature + d = dependency('foo') +else + d = disabler() +endif +``` + +This concentrates the handling of this option in one place and other +build definition files do not need to be sprinkled with `if` +statements.
\ No newline at end of file diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index e6aa9d3..13a2b2a 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -316,9 +316,20 @@ otherwise. This function supports the following keyword arguments: You can also specify multiple restrictions by passing a list to this keyword argument, such as: `['>=3.14.0', '<=4.1.0']`. +If dependency_name is '', the dependency is always not found. So with +`required: false`, this always returns a dependency object for which the +`found()` method returns `false`, and which can be passed like any other +dependency to the `dependencies:` keyword argument of a `build_target`. This +can be used to implement a dependency which is sometimes not required e.g. in +some branches of a conditional. + The returned object also has methods that are documented in the [object methods section](#dependency-object) below. +### disabler() + +Returns a [disabler object]((#disabler-object)). Added in 0.44.0. + ### error() ``` meson @@ -436,10 +447,7 @@ be passed to [shared and static libraries](#library). The list of `sources`, `objects`, and `dependencies` is always flattened, which means you can freely nest and add lists while -creating the final list. As a corollary, the best way to handle a -'disabled dependency' is by assigning an empty list `[]` to it and -passing it like any other dependency to the `dependencies:` keyword -argument. +creating the final list. The returned object also has methods that are documented in the [object methods section](#build-target-object) below. @@ -759,11 +767,7 @@ installed with a `.gz` suffix. Installs the entire given subdirectory and its contents from the source tree to the location specified by the keyword argument -`install_dir`. Note that due to implementation issues this command -deletes the entire target dir before copying the files, so you should -never use `install_subdir` to install into two overlapping directories -(such as `foo` and `foo/bar`) because if you do the behavior is -undefined. +`install_dir`. The following keyword arguments are supported: @@ -1627,6 +1631,15 @@ an external dependency with the following methods: - `version()` is the version number as a string, for example `1.2.8` +### `disabler` object + +A disabler object is an object that behaves in much the same way as +NaN numbers do in floating point math. That is when used in any +statement (function call, logical op, etc) they will cause the +statement evaluation to immediately short circuit to return a disabler +object. A disabler object has one method: + + - `found()`, always returns `false` ### `external program` object diff --git a/docs/markdown/Running-Meson.md b/docs/markdown/Running-Meson.md index 0e8da43..23d5e97 100644 --- a/docs/markdown/Running-Meson.md +++ b/docs/markdown/Running-Meson.md @@ -1,17 +1,26 @@ --- -short-description: Building a project with meson +short-description: Building a project with Meson ... -# Running meson +# Running Meson -There are two different ways of invoking Meson. First, you can run it directly from the source tree with the command `/path/to/source/meson.py`. Meson may also be installed in which case the command is simply `meson`. In this manual we only use the latter format for simplicity. +There are two different ways of invoking Meson. First, you can run it +directly from the source tree with the command +`/path/to/source/meson.py`. Meson may also be installed in which case +the command is simply `meson`. In this manual we only use the latter +format for simplicity. -At the time of writing only a command line version of Meson is available. This means that Meson must be invoked using the terminal. If you wish to use the MSVC compiler, you need to run Meson under "Visual Studio command prompt". +At the time of writing only a command line version of Meson is +available. This means that Meson must be invoked using the +terminal. If you wish to use the MSVC compiler, you need to run Meson +under "Visual Studio command prompt". Configuring the source == -Let us assume that we have a source tree that has a Meson build system. This means that at the topmost directory has a file called `meson.build`. We run the following commands to get the build started. +Let us assume that we have a source tree that has a Meson build +system. This means that at the topmost directory has a file called +`meson.build`. We run the following commands to get the build started. cd /path/to/source/root @@ -19,13 +28,22 @@ Let us assume that we have a source tree that has a Meson build system. This mea 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. +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. -Hint: The syntax of meson is `meson [options] [srcdir] [builddir]`, but you may omit either `srcdir` or `builddir`. Meson will deduce the `srcdir` by the location of `meson.build`. The other one will be your `pwd`. +Hint: The syntax of meson is `meson [options] [srcdir] [builddir]`, +but you may omit either `srcdir` or `builddir`. Meson will deduce the +`srcdir` by the location of `meson.build`. The other one will be your +`pwd`. -Meson then loads the build configuration file and writes the corresponding build backend in the build directory. By default Meson generates a *debug build*, which turns on basic warnings and debug information and disables compiler optimizations. +Meson then loads the build configuration file and writes the +corresponding build backend in the build directory. By default Meson +generates a *debug build*, which turns on basic warnings and debug +information and disables compiler optimizations. -You can specify a different type of build with the `--buildtype` command line argument. It can have one of the following values. +You can specify a different type of build with the `--buildtype` +command line argument. It can have one of the following values. | value | meaning | | ------ | -------- | @@ -34,42 +52,78 @@ You can specify a different type of build with the `--buildtype` command line ar | `debugoptimized` | debug info is generated and the code is optimized (on most compilers this means `-g -O2`) | | `release` | full optimization, no debug info | -The build directory is mandatory. The reason for this is that it simplifies the build process immensely. Meson will not under any circumstances write files inside the source directory (if it does, it is a bug and should be fixed). This means that the user does not need to add a bunch of files to their revision control's ignore list. It also means that you can create arbitrarily many build directories for any given source tree. If we wanted to test building the source code with the Clang compiler instead of the system default, we could just type the following commands. +The build directory is mandatory. The reason for this is that it +simplifies the build process immensely. Meson will not under any +circumstances write files inside the source directory (if it does, it +is a bug and should be fixed). This means that the user does not need +to add a bunch of files to their revision control's ignore list. It +also means that you can create arbitrarily many build directories for +any given source tree. If we wanted to test building the source code +with the Clang compiler instead of the system default, we could just +type the following commands. cd /path/to/source/root mkdir buildclang cd buildclang CC=clang CXX=clang++ meson .. -This separation is even more powerful if your code has multiple configuration options (such as multiple data backends). You can create a separate subdirectory for each of them. You can also have build directories for optimized builds, code coverage, static analysis and so on. They are all neatly separated and use the same source tree. Changing between different configurations is just a question of changing to the corresponding directory. +This separation is even more powerful if your code has multiple +configuration options (such as multiple data backends). You can create +a separate subdirectory for each of them. You can also have build +directories for optimized builds, code coverage, static analysis and +so on. They are all neatly separated and use the same source +tree. Changing between different configurations is just a question of +changing to the corresponding directory. -Unless otherwise mentioned, all following command line invocations are meant to be run in the build directory. +Unless otherwise mentioned, all following command line invocations are +meant to be run in the build directory. -By default Meson will use the Ninja backend to build your project. If you wish to use any of the other backends, you need to pass the corresponding argument during configuration time. As an example, here is how you would use Meson to generate a Visual studio solution. +By default Meson will use the Ninja backend to build your project. If +you wish to use any of the other backends, you need to pass the +corresponding argument during configuration time. As an example, here +is how you would use Meson to generate a Visual studio solution. meson <source dir> <build dir> --backend=vs2010 -You can then open the generated solution with Visual Studio and compile it in the usual way. A list of backends can be obtained with `meson --help`. +You can then open the generated solution with Visual Studio and +compile it in the usual way. A list of backends can be obtained with +`meson --help`. Building the source == -If you are not using an IDE, Meson uses the [Ninja build system](https://ninja-build.org/) to actually build the code. To start the build, simply type the following command. +If you are not using an IDE, Meson uses the [Ninja build +system](https://ninja-build.org/) to actually build the code. To start +the build, simply type the following command. ninja -The main usability difference between Ninja and Make is that Ninja will automatically detect the number of CPUs in your computer and parallelize itself accordingly. You can override the amount of parallel processes used with the command line argument `-j <num processes>`. - -It should be noted that after the initial configure step `ninja` is the only command you ever need to type to compile. No matter how you alter your source tree (short of moving it to a completely new location), Meson will detect the changes and regenerate itself accordingly. This is especially handy if you have multiple build directories. Often one of them is used for development (the "debug" build) and others only every now and then (such as a "static analysis" build). Any configuration can be built just by `cd`'ing to the corresponding directory and running Ninja. +The main usability difference between Ninja and Make is that Ninja +will automatically detect the number of CPUs in your computer and +parallelize itself accordingly. You can override the amount of +parallel processes used with the command line argument `-j <num +processes>`. + +It should be noted that after the initial configure step `ninja` is +the only command you ever need to type to compile. No matter how you +alter your source tree (short of moving it to a completely new +location), Meson will detect the changes and regenerate itself +accordingly. This is especially handy if you have multiple build +directories. Often one of them is used for development (the "debug" +build) and others only every now and then (such as a "static analysis" +build). Any configuration can be built just by `cd`'ing to the +corresponding directory and running Ninja. Running tests == -Meson provides native support for running tests. The command to do that is simple. +Meson provides native support for running tests. The command to do +that is simple. ninja test -Meson does not force the use of any particular testing framework. You are free to use GTest, Boost Test, Check or even custom executables. +Meson does not force the use of any particular testing framework. You +are free to use GTest, Boost Test, Check or even custom executables. Installing == @@ -78,13 +132,17 @@ Installing the built software is just as simple. ninja install -By default Meson installs to `/usr/local`. This can be changed by passing the command line argument `--prefix /your/prefix` to Meson during configure time. Meson also supports the `DESTDIR` variable used in e.g. building packages. It is used like this: +By default Meson installs to `/usr/local`. This can be changed by +passing the command line argument `--prefix /your/prefix` to Meson +during configure time. Meson also supports the `DESTDIR` variable used +in e.g. building packages. It is used like this: DESTDIR=/path/to/staging ninja install Command line help == -Meson has a standard command line help feature. It can be accessed with the following command. +Meson has a standard command line help feature. It can be accessed +with the following command. meson --help diff --git a/docs/markdown/snippets/disabler.md b/docs/markdown/snippets/disabler.md new file mode 100644 index 0000000..1323048 --- /dev/null +++ b/docs/markdown/snippets/disabler.md @@ -0,0 +1,33 @@ +# Added disabler object + +A disabler object is a new kind of object that has very specific +semantics. If it is used as part of any other operation such as an +argument to a function call, logical operations etc, it will cause the +operation to not be evaluated. Instead the return value of said +operation will also be the disabler object. + +For example if you have an setup like this: + +```meson +dep = dependency('foo') +lib = shared_library('mylib', 'mylib.c', + dependencies : dep) +exe = executable('mytest', 'mytest.c', + link_with : lib) +test('mytest', exe) +``` + +If you replace the dependency with a disabler object like this: + +```meson +dep = disabler() +lib = shared_library('mylib', 'mylib.c', + dependencies : dep) +exe = executable('mytest', 'mytest.c', + link_with : lib) +test('mytest', exe) +``` + +Then the shared library, executable and unit test are not +created. This is a handy mechanism to cut down on the number of `if` +statements. diff --git a/docs/markdown/snippets/get_unquoted.md b/docs/markdown/snippets/get_unquoted.md index 5f8969d..a6bfc4f 100755 --- a/docs/markdown/snippets/get_unquoted.md +++ b/docs/markdown/snippets/get_unquoted.md @@ -1,4 +1,4 @@ -# `get_unquoted()` mehod for the `configuration` data object +# `get_unquoted()` method for the `configuration` data object -New convenience method that allow reusing a variable value +New convenience method that allows reusing a variable value defined quoted. Useful in C for config.h strings for example. diff --git a/docs/markdown/snippets/option-array-type.md b/docs/markdown/snippets/option-array-type.md new file mode 100644 index 0000000..9eb1312 --- /dev/null +++ b/docs/markdown/snippets/option-array-type.md @@ -0,0 +1,18 @@ +# An array type for user options + +Previously to have an option that took more than one value a string value would +have to be created and split, but validating this was difficult. A new array type +has been added to the meson_options.txt for this case. It works like a 'combo', but +allows more than one option to be passed. The values can optionally be validated +against a list of valid values. When used on the command line (with -D), values +are passed as a comma separated list. + +```meson +option('array_opt', type : 'array', choices : ['one', 'two', 'three'], value : ['one']) +``` + +These can be overwritten on the command line, + +```meson +meson _build -Darray_opt=two,three +``` diff --git a/docs/sitemap.txt b/docs/sitemap.txt index 6b155af..9c86d60 100644 --- a/docs/sitemap.txt +++ b/docs/sitemap.txt @@ -26,6 +26,7 @@ index.md Localisation.md Build-options.md Subprojects.md + Disabler.md Modules.md Gnome-module.md i18n-module.md |