docs: Add the YAML Reference manual

4 files changed, 483 insertions, 0 deletions

diff --git a/docs/yaml/builtins/build_machine.yaml b/docs/yaml/builtins/build_machine.yaml
new file mode 100644
index 0000000..7b7fcd2
--- /dev/null
+++ b/docs/yaml/builtins/build_machine.yaml
@@ -0,0 +1,37 @@
+name: build_machine
+long_name: Build machine information
+description: |
+  Provides information about the build machine -- the machine that is doing the actual compilation.
+  See [Cross-compilation](Cross-compilation.md).
+
+  Currently, these values are populated using
+  [`platform.system()`](https://docs.python.org/3.7/library/platform.html#platform.system) and
+  [`platform.machine()`](https://docs.python.org/3.7/library/platform.html#platform.machine).
+  If you think the returned values for any of these are incorrect for
+  your system or CPU, or if your OS is not in the linked table, please
+  [file a bug](https://github.com/mesonbuild/meson/issues/new) report
+  with details and we'll look into it.
+
+methods:
+- name: cpu_family
+  returns: str
+  description: |
+    Returns the CPU family name.
+    [This table](Reference-tables.md#cpu-families) contains
+    all known CPU families. These are guaranteed to continue working.
+
+- name: cpu
+  returns: str
+  description: Returns a more specific CPU name, such as `i686`, `amd64`, etc.
+
+- name: system
+  returns: str
+  description: |
+    Returns the operating system name.
+    [This table](Reference-tables.md#operating-system-names) Lists
+    all of the currently known Operating System names, these are
+    guaranteed to continue working.
+
+- name: endian
+  returns: str
+  description: returns `'big'` on big-endian systems and `'little'` on little-endian systems.
diff --git a/docs/yaml/builtins/host_machine.yaml b/docs/yaml/builtins/host_machine.yaml
new file mode 100644
index 0000000..f130586
--- /dev/null
+++ b/docs/yaml/builtins/host_machine.yaml
@@ -0,0 +1,14 @@
+name: host_machine
+long_name: Host machine information
+description: |
+  Provides information about the host machine -- the machine on which the
+  compiled binary will run. See
+  [Cross-compilation](Cross-compilation.md).
+
+  It has the same methods as [[@build_machine]].
+
+  When not cross-compiling, all the methods return the same values as
+  [[@build_machine]] (because the build machine is the host machine)
+
+  Note that while cross-compiling, it simply returns the values defined
+  in the cross-info file.
diff --git a/docs/yaml/builtins/meson.yaml b/docs/yaml/builtins/meson.yaml
new file mode 100644
index 0000000..b217055
--- /dev/null
+++ b/docs/yaml/builtins/meson.yaml
@@ -0,0 +1,415 @@
+name: meson
+long_name: Meson object
+description: |
+  The `meson` object allows you to introspect various properties of the
+  system. This object is always mapped in the `meson` variable.
+
+methods:
+  - name: add_dist_script
+    returns: void
+    since: 0.48.0
+    description: |
+      Causes the script given as argument to run during `dist`
+      operation after the
+      distribution source has been generated but before it is
+      archived. Note that this runs the script file that is in the
+      _staging_ directory, not the one in the source directory. If the
+      script file can not be found in the staging directory, it is a hard
+      error. The `MESON_DIST_ROOT` environment variables is set when dist scripts is
+      run.
+
+      *(since 0.54.0)* The `MESON_SOURCE_ROOT` and `MESON_BUILD_ROOT`
+      environment variables are set when dist scripts are run. They are path to the
+      root source and build directory of the main project, even when the script
+      comes from a subproject.
+
+      *(since 0.58.0)* This command can be invoked from a subproject, it was a hard
+      error in earlier versions. Subproject dist scripts will only be executed
+      when running `meson dist --include-subprojects`. `MESON_PROJECT_SOURCE_ROOT`,
+      `MESON_PROJECT_BUILD_ROOT` and `MESON_PROJECT_DIST_ROOT` environment
+      variables are set when dist scripts are run. They are identical to
+      `MESON_SOURCE_ROOT`, `MESON_BUILD_ROOT` and `MESON_DIST_ROOT` for main project
+      scripts, but for subproject scripts they have the path to the root of the
+      subproject appended, usually `subprojects/<subproject-name>`.
+
+    posargs:
+      script_name:
+        type: str | file | external_program | exe | custom_tgt | custom_idx
+        description: |
+          The script to execute.
+
+          *(since 0.55.0)* The output of [[configure_file]], [[files]], and [[find_program]]
+          as well as strings are accepted.
+
+          *(since 0.57.0)* [[@file]] objects and the output of [[configure_file]] may be used.
+
+    varargs:
+      name: arg
+      type: str | file | external_program | exe | custom_tgt | custom_idx
+      since: 0.49.0
+      description: |
+        Additional arguments
+
+        *(since 0.55.0)* The output of [[configure_file]], [[files]], and [[find_program]]
+        as well as strings are accepted.
+
+        *(since 0.57.0)* [[@file]] objects and the output of [[configure_file]] may be used.
+
+  - name: add_install_script
+    returns: void
+    description: |
+      Causes the script given as an argument to be run during the install step,
+      this script  will have the environment variables `MESON_SOURCE_ROOT`,
+      `MESON_BUILD_ROOT`, `MESON_INSTALL_PREFIX`,
+      `MESON_INSTALL_DESTDIR_PREFIX`, and `MESONINTROSPECT` set.
+      All positional arguments are passed as parameters.
+
+      *(since 0.54.0)* If `meson install` is called with the `--quiet` option, the
+      environment variable `MESON_INSTALL_QUIET` will be set.
+
+      Meson uses the `DESTDIR` environment variable as set by the
+      inherited environment to determine the (temporary) installation
+      location for files. Your install script must be aware of this while
+      manipulating and installing files. The correct way to handle this is
+      with the `MESON_INSTALL_DESTDIR_PREFIX` variable which is always set
+      and contains `DESTDIR` (if set) and `prefix` joined together. This
+      is useful because both are usually absolute paths and there are
+      platform-specific edge-cases in joining two absolute paths.
+
+      In case it is needed, `MESON_INSTALL_PREFIX` is also always set and
+      has the value of the `prefix` option passed to Meson.
+
+      `MESONINTROSPECT` contains the path to the introspect command that
+      corresponds to the `meson` executable that was used to configure the
+      build. (This might be a different path than the first executable
+      found in `PATH`.) It can be used to query build configuration. Note
+      that the value will contain many parts, f.ex., it may be `python3
+      /path/to/meson.py introspect`. The user is responsible for splitting
+      the string to an array if needed by splitting lexically like a UNIX
+      shell would. If your script uses Python, `shlex.split()` is the
+      easiest correct way to do this.
+
+    posargs_inherit: meson.add_dist_script
+    varargs_inherit: meson.add_dist_script
+
+    kwargs:
+      skip_if_destdir:
+        type: bool
+        since: 0.57.0
+        default: false
+        description: |
+          If `true` the script will not be run if DESTDIR is set during installation.
+          This is useful in the case the script updates system wide
+          cache that is only needed when copying files into final destination.
+
+  - name: add_postconf_script
+    returns: void
+    description: |
+      Runs the given command after all project files have been generated.
+      This script will have the environment variables
+      `MESON_SOURCE_ROOT` and `MESON_BUILD_ROOT` set.
+
+    posargs_inherit: meson.add_dist_script
+    varargs_inherit: meson.add_dist_script
+
+  - name: backend
+    returns: str
+    since: 0.37.0
+    description: |
+      Returns a string representing the current backend:
+
+      - `ninja`
+      - `vs2010`
+      - `vs2012`
+      - `vs2013`
+      - `vs2015`
+      - `vs2017`
+      - `vs2019`
+      - `xcode`
+
+  - name: build_root
+    returns: str
+    deprecated: 0.56.0
+    description: |
+      Returns a string with the absolute path to the build root directory.
+      This function will return the
+      build root of the parent project if called from a subproject, which is usually
+      not what you want. Try using [[meson.current_build_dir]] or [[meson.project_build_root]].
+      In the rare cases where the root of the main project is needed,
+      use [[meson.global_build_root]] that has the same behaviour but with a more explicit
+      name.
+
+  - name: source_root
+    returns: str
+    deprecated: 0.56.0
+    description: |
+      Returns a string with the absolute path to the source root directory.
+
+      This function will return the source root of the
+      parent project if called from a subproject, which is usually not what you want.
+      Try using [[meson.current_source_dir]] or [[meson.project_source_root]].
+      In the rare cases where the root of the main project is needed,
+      use [[meson.global_source_root]] that has the same behaviour but with a more explicit
+      name.
+
+    notes:
+      - |
+        You should use the [[files]] function
+        to refer to files in the root source directory instead of
+        constructing paths manually with [[meson.source_root]].
+
+  - name: project_build_root
+    returns: str
+    since: 0.56.0
+    description: Returns a string with the absolute path to the build root directory of the current (sub)project.
+
+  - name: project_source_root
+    returns: str
+    since: 0.56.0
+    description: Returns a string with the absolute path to the source root directory of the current (sub)project.
+
+  - name: global_build_root
+    returns: str
+    since: 0.58.0
+    description: |
+      Returns a string with the absolute path to the build root directory.
+      This function will return the build root of the
+      main project if called from a subproject, which is usually not what you want.
+      It is usually preferable to use [[meson.current_build_dir]] or [[meson.project_build_root]].
+
+  - name: global_source_root
+    returns: str
+    since: 0.58.0
+    description: |
+      Returns a string with the absolute path to the source root directory
+      This function will return the source root of the
+      main project if called from a subproject, which is usually not what you want.
+      It is usually preferable to use [[meson.current_source_dir]] or [[meson.project_source_root]].
+
+  - name: current_build_dir
+    returns: str
+    description: Returns a string with the absolute path to the current build directory.
+
+  - name: current_source_dir
+    returns: str
+    description: Returns a string to the current source directory.
+    notes:
+      - |
+        **You do not need to use this function!**
+
+        When passing files from the current source directory to a function since
+        that is the default. Also, you can use the [[files]] function to
+        refer to files in the current or any other source directory instead
+        of constructing paths manually with [[meson.current_source_dir]].
+
+  - name: get_compiler
+    returns: compiler
+    description: Returns a [[@compiler]] object describing a compiler.
+
+    posargs:
+      language:
+        type: str
+        description: |
+          The language of the compiler to return.
+
+          See our [list of supported languages](Reference-tables.md#language-arguments-parameter-names).
+
+    kwargs:
+      native:
+        type: bool
+        default: false
+        description: |
+          When set to `true` Meson returns the compiler for the build
+          machine (the "native" compiler) and when `false` it returns the host
+          compiler (the "cross" compiler). If `native` is omitted, Meson
+          returns the "cross" compiler if we're currently cross-compiling and
+          the "native" compiler if we're not.
+
+  - name: get_cross_property
+    returns: any
+    deprecated: 0.58.0
+    description: |
+      Returns the given property from a cross file, the optional fallback_value
+      is returned if not cross compiling or the given property is not found.
+
+      This method is replaced by [[meson.get_external_property]].
+
+    posargs_inherit: meson.get_external_property
+    optargs_inherit: meson.get_external_property
+
+  - name: get_external_property
+    returns: any
+    since: 0.54.0
+    description: |
+      Returns the given property from a native or cross file.
+      The optional fallback_value is returned if the given property is not found.
+
+    posargs:
+      propname:
+        type: str
+        description: Name of the property in the cross / native file.
+
+    optargs:
+      fallback_value:
+        type: any
+        description: Value to return if `propname` is not set in the machine file.
+
+    kwargs:
+      native:
+        type: bool
+        description: |
+          Setting `native` to `true` forces retrieving a variable from the
+          native file, even when cross-compiling.
+          If `native: false` or not specified, the variable is retrieved from the
+          cross-file if cross-compiling, and from the native-file when not cross-compiling.
+
+  - name: has_external_property
+    returns: bool
+    since: 0.58.0
+    description: Checks whether the given property exist in a native or cross file.
+    posargs_inherit: meson.get_external_property
+    kwargs_inherit: meson.get_external_property
+
+  - name: can_run_host_binaries
+    returns: bool
+    since: 0.55.0
+    description: |
+      Returns true if the build machine can run binaries compiled for the host.
+      This returns `true` unless you are
+      cross compiling, need a helper to run host binaries, and don't have one.
+      For example when cross compiling from Linux to Windows, one can use `wine`
+      as the helper.
+
+  - name: has_exe_wrapper
+    returns: bool
+    deprecated: 0.55.0
+    description: Use [[meson.can_run_host_binaries]] instead.
+
+  - name: install_dependency_manifest
+    returns: void
+    description: |
+      Installs a manifest file
+      containing a list of all subprojects, their versions and license
+      files to the file name given as the argument.
+
+    posargs:
+      output_name:
+        type: str
+        description: Name of the manifest file to install
+
+  - name: override_find_program
+    returns: void
+    since: 0.46.0
+    description: |
+      specifies that whenever [[find_program]] is used to find a program
+      named `progname`, Meson should not look it up on the system but
+      instead return `program`, which may either be the result of
+      [[find_program]], [[configure_file]] or [[executable]].
+
+      *(since 0.55.0)* If a version
+      check is passed to [[find_program]] for a program that has been overridden with
+      an executable, the current project version is used.
+
+    posargs:
+      progname:
+        type: str
+        description: The name of the program to override.
+
+      program:
+        type: exe | file | external_program
+        description: The program to set as the override for `progname`.
+
+  - name: override_dependency
+    returns: void
+    since: 0.54.0
+    description: |
+      Specifies that whenever [[dependency]] with `name` is used, Meson should not
+      look it up on the system but instead return `dep_object`, which may either be
+      the result of [[dependency]] or [[declare_dependency]].
+
+      Doing this in a subproject allows the parent
+      project to retrieve the dependency without having to know the dependency
+      variable name: `dependency(name, fallback : subproject_name)`.
+
+    posargs:
+      name:
+        type: str
+        description: The name of the dependency to override.
+
+      dep_object:
+        type: dep
+        description: The dependency to set as the override for `name`.
+
+    kwargs:
+      native:
+        type: bool
+        default: false
+        description: |
+          If set to `true`, the dependency is always overwritten for the build machine.
+          Otherwise, the dependency is overwritten for the host machine, which
+          differs from the build machine when cross-compiling.
+
+  - name: is_cross_build
+    returns: bool
+    description: Returns `true` if the current build is a [cross build](Cross-compilation.md) and `false` otherwise.
+
+  - name: is_subproject
+    returns: bool
+    description: Returns `true` if the current project is being built as a subproject of some other project and `false` otherwise.
+
+  - name: is_unity
+    returns: bool
+    description: Returns `true` when doing a [unity build](Unity-builds.md) (multiple sources are combined before compilation to reduce build time) and `false` otherwise.
+
+  - name: project_version
+    returns: str
+    description: Returns the version string specified in [[project]] function call.
+
+  - name: project_license
+    returns: list[str]
+    description: Returns the array of licenses specified in [[project]] function call.
+
+  - name: project_name
+    returns: str
+    description: Returns the project name specified in the [[project]] function call.
+
+  - name: version
+    returns: str
+    description: Return a string with the version of Meson.
+
+  - name: add_devenv
+    returns: void
+    since: 0.58.0
+    description: |
+      add an [[@env]] object (returned by [[environment]])
+      to the list of environments that will be applied when using [`meson devenv`](Commands.md#devenv)
+      command line.
+
+      This is useful for developpers who wish to use the project without
+      installing it, it is often needed to set for example the path to plugins
+      directory, etc. Alternatively, a list or dictionary can be passed as first
+      argument.
+
+      ``` meson
+      devenv = environment()
+      devenv.set('PLUGINS_PATH', meson.current_build_dir())
+      ...
+      meson.add_devenv(devenv)
+      ```
+
+      After configuring and compiling that project, a terminal can be opened with
+      the environment set:
+
+      ```sh
+      $ meson devenv -C <builddir>
+      $ echo $PLUGINS_PATH
+      /path/to/source/subdir
+      ```
+
+      See [`meson devenv`](Commands.md#devenv) command documentation for a list of
+      environment variables that are set by default by Meson.
+
+    posargs:
+      env:
+        type: env
+        description: The [[@env]] object to add.
diff --git a/docs/yaml/builtins/target_machine.yaml b/docs/yaml/builtins/target_machine.yaml
new file mode 100644
index 0000000..d5c4e4d
--- /dev/null
+++ b/docs/yaml/builtins/target_machine.yaml
@@ -0,0 +1,17 @@
+name: target_machine
+long_name: Target machine information
+description: |
+  Provides information about the target machine -- the machine on which
+  the compiled binary's output will run. Hence, this object should only
+  be used while cross-compiling a compiler. See
+  [Cross-compilation](Cross-compilation.md).
+
+  It has the same methods as [[@build_machine]].
+
+  When all compilation is 'native', all the methods return the same
+  values as [[@build_machine]] (because the build machine is the host
+  machine and the target machine).
+
+  Note that while cross-compiling, it simply returns the values defined
+  in the cross-info file. If `target_machine` values are not defined in
+  the cross-info file, `host_machine` values are returned instead.