diff options
Diffstat (limited to 'docs/yaml/builtins')
| -rw-r--r-- | docs/yaml/builtins/build_machine.yaml | 37 | ||||
| -rw-r--r-- | docs/yaml/builtins/host_machine.yaml | 14 | ||||
| -rw-r--r-- | docs/yaml/builtins/meson.yaml | 415 | ||||
| -rw-r--r-- | docs/yaml/builtins/target_machine.yaml | 17 |
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. |