Add submodule dependency filesHEADmaster

Change-Id: Iaf8d18082d3991dec7c0ebbea540f092188eb4ec

1 files changed, 229 insertions, 0 deletions

diff --git a/meson/docs/markdown/Build-options.md b/meson/docs/markdown/Build-options.md
new file mode 100644
index 000000000..4a0b17800
--- /dev/null
+++ b/meson/docs/markdown/Build-options.md
@@ -0,0 +1,229 @@
+---
+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.
+
+Here is a simple option file.
+
+```meson
+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('integer_opt', type : 'integer', min : 0, max : 5, value : 3) # Since 0.45.0
+option('free_array_opt', type : 'array', value : ['one', 'two'])  # Since 0.44.0
+option('array_opt', type : 'array', choices : ['one', 'two', 'three'], value : ['one', 'two'])
+option('some_feature', type : 'feature', value : 'enabled')  # Since 0.47.0
+option('long_desc', type : 'string', value : 'optval',
+       description : 'An option with a very long description' +
+                     'that does something in a specific context') # Since 0.55.0
+```
+
+For built-in options, see [Built-in options][builtin_opts].
+
+## Build option types
+
+All types allow a `description` value to be set describing the option,
+if no description is set then the name of the option will be used instead.
+
+### 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.
+
+### Integers
+
+An integer option contains a single integer with optional upper and
+lower values that are specified with the `min` and `max` keyword
+arguments.
+
+This type is available since Meson version 0.45.0.
+
+### 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.
+
+As of 0.47.0 -Dopt= and -Dopt=[] both pass an empty list, before this
+-Dopt= would pass a list with an empty string.
+
+This type is available since version 0.44.0
+
+### Features
+
+A `feature` option has three states: `enabled`, `disabled` or `auto`.
+It is intended to be passed as value for the `required` keyword
+argument of most functions. Currently supported in
+[`dependency()`](Reference-manual.md#dependency),
+[`find_library()`](Reference-manual.md#compiler-object),
+[`find_program()`](Reference-manual.md#find_program) and
+[`add_languages()`](Reference-manual.md#add_languages) functions.
+
+- `enabled` is the same as passing `required : true`.
+- `auto` is the same as passing `required : false`.
+- `disabled` do not look for the dependency and always return 'not-found'.
+
+When getting the value of this type of option using `get_option()`, a
+special [feature option
+object](Reference-manual.md#feature-option-object) is returned instead
+of the string representation of the option's value. This object can be
+passed to `required`:
+
+```meson
+d = dependency('foo', required : get_option('myfeature'))
+if d.found()
+  app = executable('myapp', 'main.c', dependencies : [d])
+endif
+```
+
+To check the value of the feature, the object has three methods
+returning a boolean and taking no argument:
+
+- `.enabled()`
+- `.disabled()`
+- `.auto()`
+
+This is useful for custom code depending on the feature:
+
+```meson
+if get_option('myfeature').enabled()
+  # ...
+endif
+```
+
+If the value of a `feature` option is set to `auto`, that value is
+overridden by the global `auto_features` option (which defaults to
+`auto`). This is intended to be used by packagers who want to have
+full control on which dependencies are required and which are
+disabled, and not rely on build-deps being installed (at the right
+version) to get a feature enabled. They could set
+`auto_features=enabled` to enable all features and disable explicitly
+only the few they don't want, if any.
+
+This type is available since version 0.47.0
+
+## Using build options
+
+```meson
+optval = get_option('opt_name')
+```
+
+This function also allows you to query the value of Meson's built-in
+project options. For example, to get the installation prefix you would
+issue the following command:
+
+```meson
+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.
+
+To change their values use the `-D`
+option:
+
+```console
+$ 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.
+
+To change values in subprojects prepend the name of the subproject and
+a colon:
+
+```console
+$ meson configure -Dsubproject:option=newvalue
+```
+
+**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
+
+## Yielding to superproject option
+
+Suppose you have a master project and a subproject. In some cases it
+might be useful to have an option that has the same value in both of
+them. This can be achieved with the `yield` keyword. Suppose you have
+an option definition like this:
+
+```meson
+option('some_option', type : 'string', value : 'value', yield : true)
+```
+
+If you build this project on its own, this option behaves like
+usual. However if you build this project as a subproject of another
+project which also has an option called `some_option`, then calling
+`get_option` returns the value of the superproject. If the value of
+`yield` is `false`, `get_option` returns the value of the subproject's
+option.
+
+
+## Built-in build options
+
+There are a number of [built-in options][builtin_opts]. To get the
+current list execute `meson configure` in the build directory.
+
+[builtin_opts]: https://mesonbuild.com/Builtin-options.html
+
+### Visual Studio
+
+#### Startup project
+
+The `backend_startup_project` option can be set to define the default
+project that will be executed with the "Start debugging F5" action in
+visual studio. It should be the same name as an executable target
+name.
+
+```meson
+project('my_project', 'c', default_options: ['backend_startup_project=my_exe'])
+executable('my_exe', ...)
+```
+
+### Ninja
+
+#### Max links
+
+The `backend_max_links` can be set to limit the number of processes
+that ninja will use to link.