diff options
Diffstat (limited to 'docs/yaml')
93 files changed, 5043 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..2c847b5 --- /dev/null +++ b/docs/yaml/builtins/host_machine.yaml @@ -0,0 +1,15 @@ +name: host_machine +long_name: Host machine information +extends: build_machine +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..f8c4e78 --- /dev/null +++ b/docs/yaml/builtins/meson.yaml @@ -0,0 +1,432 @@ +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. + + install_tag: + type: str + since: 0.60.0 + description: | + A string used by the `meson install --tags` command + to install only a subset of the files. + By default the script has no install tag which means it is not being run when + `meson install --tags` argument is specified. + + - 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. + + static: + type: bool + since: 0.60.0 + description: | + Used to override static and/or shared dependencies separately. + If not specified it is assumed + `dep_object` follows `default_library` option value. + + - 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..c17adc7 --- /dev/null +++ b/docs/yaml/builtins/target_machine.yaml @@ -0,0 +1,18 @@ +name: target_machine +long_name: Target machine information +extends: build_machine +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. diff --git a/docs/yaml/elementary/any.yaml b/docs/yaml/elementary/any.yaml new file mode 100644 index 0000000..70fcf27 --- /dev/null +++ b/docs/yaml/elementary/any.yaml @@ -0,0 +1,5 @@ +name: any +long_name: Any +description: | + A placeholder representing all types. + This includes builtin, as well as returned objects. diff --git a/docs/yaml/elementary/bool.yml b/docs/yaml/elementary/bool.yml new file mode 100644 index 0000000..061f940 --- /dev/null +++ b/docs/yaml/elementary/bool.yml @@ -0,0 +1,28 @@ +name: bool +long_name: Boolean +description: A boolean object which is either `true` or `false` + +methods: +- name: to_int + returns: int + description: Returns `1` if `true` and `0` if `false` + +- name: to_string + returns: str + description: | + Returns the string `'true'` if the boolean is true or `'false'` otherwise. + You can also pass it two strings as positional + arguments to specify what to return for true/false. For instance, + `bool.to_string('yes', 'no')` will return `yes` if the boolean is + true and `no` if it is false. + + optargs: + true_str: + type: str + default: "'true'" + description: The string to return when the boolean is `true` + + false_str: + type: str + default: "'false'" + description: The string to return when the boolean is `false` diff --git a/docs/yaml/elementary/dict.yml b/docs/yaml/elementary/dict.yml new file mode 100644 index 0000000..5afe835 --- /dev/null +++ b/docs/yaml/elementary/dict.yml @@ -0,0 +1,45 @@ +name: dict +long_name: Dict +since: 0.47.0 +is_container: true +description: | + Stores a mapping of strings to other objects. See [dictionaries](Syntax.md#dictionaries). + + You can also iterate over dictionaries with the [`foreach` + statement](Syntax.md#foreach-statements). + + *(since 0.48.0)* Dictionaries can be added (e.g. `d1 = d2 + d3` and `d1 += d2`). + Values from the second dictionary overrides values from the first. + + +methods: +- name: has_key + returns: bool + description: Returns `true` if the dictionary contains the key given as argument, `false` otherwise. + + posargs: + key: + type: str + description: The key to query. + +- name: get + returns: any + description: | + returns the value for the key given as first + argument if it is present in the dictionary, or the optional + fallback value given as the second argument. If a single argument + was given and the key was not found, causes a fatal error + + posargs: + key: + type: str + description: The key to query. + + optargs: + fallback: + type: any + description: Fallback value that is returned if the key is not in the [[@dict]]. + +- name: keys + returns: list[str] + description: Returns an array of keys in the dictionary. diff --git a/docs/yaml/elementary/int.yml b/docs/yaml/elementary/int.yml new file mode 100644 index 0000000..65ab959 --- /dev/null +++ b/docs/yaml/elementary/int.yml @@ -0,0 +1,16 @@ +name: int +long_name: Integer +description: All integer numbers. See [Numbers](Syntax.md#numbers) for more information. + +methods: +- name: is_even + returns: bool + description: Returns true if the number is even. + +- name: is_odd + returns: bool + description: Returns true if the number is odd + +- name: to_string + returns: str + description: Returns the value of the number as a string. diff --git a/docs/yaml/elementary/list.yml b/docs/yaml/elementary/list.yml new file mode 100644 index 0000000..085b6ca --- /dev/null +++ b/docs/yaml/elementary/list.yml @@ -0,0 +1,38 @@ +name: list +long_name: List +description: An array of elements. See [arrays](Syntax.md#arrays). +is_container: true + +methods: +- name: contains + returns: bool + description: | + Returns `true` if the array contains the object + given as argument, `false` otherwise + + posargs: + item: + type: any + description: The item to check + +- name: get + returns: any + description: | + returns the object at the given index, + negative indices count from the back of the array, indexing out of + bounds returns the `fallback` value *(since 0.38.0)* or, if it is + not specified, causes a fatal error + + posargs: + index: + type: int + description: Index of the list position to query. Negative values start at the end of the list + + optargs: + fallback: + type: any + description: Fallback value that is returned if the index is out of range. + +- name: length + returns: int + description: Returns the current size of the array / list. diff --git a/docs/yaml/elementary/str.yml b/docs/yaml/elementary/str.yml new file mode 100644 index 0000000..b79577a --- /dev/null +++ b/docs/yaml/elementary/str.yml @@ -0,0 +1,269 @@ +name: str +long_name: String +description: | + All [strings](Syntax.md#strings) have the following methods. Strings + are immutable, all operations return their results as a new string. + +methods: + +# str.format(fmt, value...) +- name: format + returns: str + description: | + Strings can be built using the string formatting functionality. + + See [the Meson syntax entry](Syntax.md#string-formatting) for more + information. + example: | + ```meson + template = 'string: @0@, number: @1@, bool: @2@' + res = template.format('text', 1, true) + # res now has value 'string: text, number: 1, bool: true' + ``` + + posargs: + fmt: + description: | + The string to format. + + The formatting works by replacing placeholders of type `@number@` with + the corresponding varargs. + type: str + + varargs: + name: value + description: The values to replace the @number@ placeholders in the format string. + type: int | bool | str + +# str.replace(old, new) +- name: replace + description: Search all occurences of `old` and and replace it with `new` + returns: str + since: 0.58.0 + example: | + ```meson + # Replaces all instances of one substring with another + s = 'semicolons;as;separators' + s = s.replace('as', 'are') + # 's' now has the value of 'semicolons;are;separators' + ``` + + posargs: + old: + description: The substring to search + type: str + + new: + description: The replacement string + type: str + +# str.strip() +- name: strip + description: Removes leading/ending spaces and newlines from the string. + returns: str + example: | + ```meson + # Similar to the Python str.strip(). Removes leading/ending spaces and newlines + define = ' -Dsomedefine ' + stripped_define = define.strip() + # 'stripped_define' now has the value '-Dsomedefine' + ``` + + optargs: + strip_chars: + type: str + since: 0.43.0 + description: All characters in this string will be stripped. + +# str.to_lower() +- name: to_lower + description: Converts all characters to lower case + returns: str + example: | + ```meson + target = 'x86_FreeBSD' + lower = target.to_lower() # t now has the value 'x86_freebsd' + ``` + +# str.to_upper() +- name: to_upper + description: Converts all characters to upper case + returns: str + example: | + ```meson + target = 'x86_FreeBSD' + upper = target.to_upper() # t now has the value 'X86_FREEBSD' + ``` + +# str.to_int() +- name: to_int + description: Converts the string to an int and throws an error if it can't be + returns: int + example: | + ```meson + version = '1' + # Converts the string to an int and throws an error if it can't be + ver_int = version.to_int() + ``` + +# str.contains() +- name: contains + returns: bool + description: Returns `true` if string contains the string specified as the argument. + example: | + ```meson + target = 'x86_FreeBSD' + is_fbsd = target.to_lower().contains('freebsd') + # is_fbsd now has the boolean value 'true' + ``` + + posargs: + fragment: + type: str + description: The string fragment to check + +# str.startswith() +- name: startswith + returns: bool + description: Returns true if string starts with the string specified as the argument. + posargs_inherit: str.contains + example: | + ```meson + target = 'x86_FreeBSD' + is_x86 = target.startswith('x86') # boolean value 'true' + ``` + +# str.endswith() +- name: endswith + returns: bool + description: Returns true if string ends with the string specified as the argument. + posargs_inherit: str.contains + example: | + ```meson + target = 'x86_FreeBSD' + is_bsd = target.to_lower().endswith('bsd') # boolean value 'true' + ``` + +# str.substring() +- name: substring + returns: str + since: 0.56.0 + description: | + Returns a substring specified from `start` to `end`. + Both `start` and `end` arguments are optional, so, for example, `'foobar'.substring()` will return `'foobar'`. + + The method accepts negative values where negative `start` is relative to the end of + string `len(string) - start` as well as negative `end`. + + example: | + ```meson + # Similar to the Python str[start:end] syntax + target = 'x86_FreeBSD' + platform = target.substring(0, 3) # prefix string value 'x86' + system = target.substring(4) # suffix string value 'FreeBSD' + ``` + + Example with negative values: + + ```meson + string = 'foobar' + string.substring(-5, -3) # => 'oo' + string.substring(1, -1) # => 'ooba' + ``` + + optargs: + start: + type: int + description: The start position + + end: + type: int + description: The end position + +# str.split +- name: split + returns: list[str] + description: | + Splits the string at the specified character + (or whitespace if not set) and returns the parts in an + array. + + example: | + ```meson + # Similar to the Python str.split() + components = 'a b c d '.split() + # components now has the value ['a', 'b', 'c', 'd'] + components = 'a b c d '.split(' ') + # components now has the value ['a', 'b', '', '', 'c', 'd', ''] + ``` + + optargs: + split_string: + type: str + description: Specifies the character / substring where to split the string. + +# str.join() +- name: join + returns: str + description: | + The opposite of split, + for example `'.'.join(['a', 'b', 'c']` yields `'a.b.c'`. + + example: | + ```meson + # Similar to the Python str.join() + output = ' '.join(['foo', 'bar']) + # Output value is 'foo bar' + pathsep = ':' + path = pathsep.join(['/usr/bin', '/bin', '/usr/local/bin']) + # path now has the value '/usr/bin:/bin:/usr/local/bin' + ``` + + varargs: + name: strings + type: str + since: 0.60.0 + description: | + The strings to join with the current string. + + Before Meson *0.60.0* this function only accepts a single positional + argument of the type [[list[str]]]. + +# str.underscorify +- name: underscorify + returns: str + description: Creates a string where every non-alphabetical non-number character is replaced with `_`. + example: | + ```meson + name = 'Meson Docs.txt#Reference-manual' + # Replaces all characters other than `a-zA-Z0-9` with `_` (underscore) + # Useful for substituting into #defines, filenames, etc. + underscored = name.underscorify() + # underscored now has the value 'Meson_Docs_txt_Reference_manual' + ``` + +# str.version_compare +- name: version_compare + returns: bool + description: Does semantic version comparison. + example: | + ```meson + version = '1.2.3' + # Compare version numbers semantically + is_new = version.version_compare('>=2.0') + # is_new now has the boolean value false + # Supports the following operators: '>', '<', '>=', '<=', '!=', '==', '=' + ``` + + Meson version comparison conventions include: + + ```meson + '3.6'.version_compare('>=3.6.0') == false + ``` + + It is best to be unambiguous and specify the full revision level to compare. + + posargs: + compare_string: + type: str + description: The string to compare to. diff --git a/docs/yaml/elementary/void.yml b/docs/yaml/elementary/void.yml new file mode 100644 index 0000000..43f51af --- /dev/null +++ b/docs/yaml/elementary/void.yml @@ -0,0 +1,5 @@ +name: void +long_name: void +description: | + Indicates that the function does not return anything. + Similar to `void` in C and C++ diff --git a/docs/yaml/functions/_build_target_base.yaml b/docs/yaml/functions/_build_target_base.yaml new file mode 100644 index 0000000..62424b6 --- /dev/null +++ b/docs/yaml/functions/_build_target_base.yaml @@ -0,0 +1,278 @@ +name: _build_target_base +returns: void +description: PRIVATE + +posargs: + target_name: + description: The *unique* name of the build target + type: str + +varargs: + name: source + type: str | file | custom_tgt | custom_idx | generated_list + description: | + Input source to compile. The following types are supported: + + - Strings relative to the current source directory + - [[@file]] objects defined in any preceding build file + - The return value of configure-time generators such as [[configure_file]] + - The return value of build-time generators such as + [[custom_target]] or [[generator.process]] + + These input files can be sources, objects, libraries, or any other + file. Meson will automatically categorize them based on the extension + and use them accordingly. For instance, sources (`.c`, `.cpp`, + `.vala`, `.rs`, etc) will be compiled and objects (`.o`, `.obj`) and + libraries (`.so`, `.dll`, etc) will be linked. + + With the Ninja backend, Meson will create a build-time [order-only + dependency](https://ninja-build.org/manual.html#ref_dependencies) on + all generated input files, including unknown files. This is needed to + bootstrap the generation of the real dependencies in the + [depfile](https://ninja-build.org/manual.html#ref_headers) generated + by your compiler to determine when to rebuild sources. Ninja relies on + this dependency file for all input files, generated and non-generated. + The behavior is similar for other backends. + +warnings: + - The `link_language` kwarg was broken until 0.55.0 + +kwargs: + <lang>_pch: + type: str | file + description: precompiled header file to use for the given language + + <lang>_args: + type: list[str] + description: | + compiler flags to use for the given language; + eg: `cpp_args` for C++ + + sources: + type: str | file | custom_tgt | custom_idx | generated_list + description: Additional source files. Same as the source varargs. + + build_by_default: + type: bool + default: true + since: 0.38.0 + description: | + Causes, when set to `true`, to have this target be built by default. + This means it will be built when `meson compile` is called without any + arguments. The default value is `true` for all built target types. + + build_rpath: + type: str + description: | + A string to add to target's rpath definition in the build dir, + but which will be removed on install + + dependencies: + type: list[dep] + description: | + one or more dependency objects + created with + [[dependency]] or [[compiler.find_library]] + (for external deps) or [[declare_dependency]] + (for deps built by the project) + + extra_files: + type: str | file | custom_tgt | custom_idx + description: | + Not used for the build itself but are shown as source files in IDEs + that group files by targets (such as Visual Studio) + + gui_app: + type: bool + deprecated: 0.56.0 + default: false + description: | + When set to true flags this target as a GUI application + on platforms where this makes a differerence, **deprecated** since + 0.56.0, use `win_subsystem` instead. + + link_args: + type: list[str] + description: | + Flags to use during linking. You can use UNIX-style + flags here for all platforms. + + link_depends: + type: str | file | custom_tgt | custom_idx + description: | + Strings, files, or custom targets the link step depends on + such as a symbol visibility map. The purpose is to + automatically trigger a re-link (but not a re-compile) of the target + when this file changes. + + link_language: + type: str + since: 0.51.0 + description: | + Makes the linker for this target be for the specified language. + It is generally unnecessary to set + this, as Meson will detect the right linker to use in most cases. There are + only two cases where this is needed. One, your main function in an + executable is not in the language Meson picked, or second you want to force + a library to use only one ABI. + + *(broken until 0.55.0)* + + link_whole: + type: list[lib | custom_tgt | custom_idx] + since: 0.40.0 + description: | + Links all contents of the given static libraries + whether they are used by not, equivalent to the `-Wl,--whole-archive` argument flag of GCC. + + *(since 0.41.0)* If passed a list that list will be flattened. + + *(since 0.51.0)* This argument also accepts outputs produced by + custom targets. The user must ensure that the output is a library in + the correct format. + + link_with: + type: list[lib | custom_tgt | custom_idx] + description: | + One or more shared or static libraries + (built by this project) that this target should be linked with. *(since 0.41.0)* If passed a + list this list will be flattened. *(since 0.51.0)* The arguments can also be custom targets. + In this case Meson will assume that merely adding the output file in the linker command + line is sufficient to make linking work. If this is not sufficient, + then the build system writer must write all other steps manually. + + implicit_include_directories: + type: bool + since: 0.42.0 + default: true + description: Controlls whether Meson adds the current source and build directories to the include path + + include_directories: + type: list[inc | str] + description: | + one or more objects created with the [[include_directories]] function, + or *(since 0.50.0)* strings, which will be transparently expanded to include directory objects + + install: + type: bool + default: false + description: When set to true, this executable should be installed. + + install_dir: + type: str + description: | + override install directory for this file. The value is + relative to the `prefix` specified. F.ex, if you want to install + plugins into a subdir, you'd use something like this: `install_dir : + get_option('libdir') / 'projectname-1.0'`. + + install_mode: + type: list[str | int] + since: 0.47.0 + description: | + Specify the file mode in symbolic format + and optionally the owner/uid and group/gid for the installed files. + + See the `install_mode` kwarg of [[install_data]] for more information. + + install_tag: + type: str + since: 0.60.0 + description: | + A string used by the `meson install --tags` command + to install only a subset of the files. By default all build targets have the + tag `runtime` except for static libraries that have the `devel` tag. + + install_rpath: + type: str + description: | + A string to set the target's rpath to after install + (but *not* before that). On Windows, this argument has no effect. + + objects: + type: list[extracted_obj] + description: | + List of prebuilt object files (usually for third party + products you don't have source to) that should be linked in this + target, **never** use this for object files that you build yourself. + + name_prefix: + type: str | list[void] + description: | + The string that will be used as the prefix for the + target output filename by overriding the default (only used for + libraries). By default this is `lib` on all platforms and compilers, + except for MSVC shared libraries where it is omitted to follow + convention, and Cygwin shared libraries where it is `cyg`. + + Set this to `[]`, or omit the keyword argument for the default behaviour. + + name_suffix: + type: str | list[void] + description: | + The string that will be used as the extension for the + target by overriding the default. By default on Windows this is + `exe` for executables and on other platforms it is omitted. + + For shared libraries, the default value + is `dylib` on macOS, `dll` on Windows, and `so` everywhere else. + For static libraries, it is `a` everywhere. By convention MSVC + static libraries use the `lib` suffix, but we use `a` to avoid a + potential name clash with shared libraries which also generate + import libraries with a `lib` suffix. + + Set this to `[]`, or omit the keyword argument for the default behaviour. + + override_options: + type: list[str] + since: 0.40.0 + description: | + takes an array of strings in the same format as `project`'s `default_options` + overriding the values of these options + for this target only. + + gnu_symbol_visibility: + type: str + since: 0.48.0 + description: | + Specifies how symbols should be exported, see + e.g [the GCC Wiki](https://gcc.gnu.org/wiki/Visibility) for more + information. This value can either be an empty string or one of + `default`, `internal`, `hidden`, `protected` or `inlineshidden`, which + is the same as `hidden` but also includes things like C++ implicit + constructors as specified in the GCC manual. Ignored on compilers that + do not support GNU visibility arguments. + + d_import_dirs: + type: list[str] + description: List of directories to look in for string imports used in the D programming language. + + d_unittest: + type: bool + default: false + description: When set to true, the D modules are compiled in debug mode. + + d_module_versions: + type: list[str] + description: List of module version identifiers set when compiling D sources. + + d_debug: + type: list[str] + description: List of module debug identifiers set when compiling D sources. + + native: + type: bool + default: false + description: Controls whether the target is compiled for the build or host machines. + + win_subsystem: + type: str + default: "'console'" + since: 0.56.0 + description: | + Specifies the subsystem type to use + on the Windows platform. Typical values include `console` for text + mode programs and `windows` for gui apps. The value can also contain + version specification such as `windows,6.0`. See [MSDN + documentation](https://docs.microsoft.com/en-us/cpp/build/reference/subsystem-specify-subsystem) + for the full list. diff --git a/docs/yaml/functions/add_global_arguments.yaml b/docs/yaml/functions/add_global_arguments.yaml new file mode 100644 index 0000000..282869b --- /dev/null +++ b/docs/yaml/functions/add_global_arguments.yaml @@ -0,0 +1,38 @@ +name: add_global_arguments +returns: void +description: Adds global arguments to the compiler command line. + +notes: + - Usually you should use [[add_project_arguments]] instead, + because that works even when you project is used as a subproject. + - You must pass always arguments individually `arg1, arg2, ...` + rather than as a string `'arg1 arg2', ...` + +varargs: + type: str + name: Compiler argument + description: The commpiler arguments to add + +kwargs: + language: + type: list[str] + required: true + description: | + Specifies the language(s) that the arguments should be + applied to. If a list of languages is given, the arguments are added + to each of the corresponding compiler command lines. Note that there + is no way to remove an argument set in this way. If you have an + argument that is only used in a subset of targets, you have to specify + it in per-target flags. + + native: + type: bool + default: false + since: 0.48.0 + description: | + A boolean specifying whether the arguments should be + applied to the native or cross compilation. If `true` the arguments + will only be used for native compilations. If `false` the arguments + will only be used in cross compilations. If omitted, the flags are + added to native compilations if compiling natively and cross + compilations (only) when cross compiling. diff --git a/docs/yaml/functions/add_global_link_arguments.yaml b/docs/yaml/functions/add_global_link_arguments.yaml new file mode 100644 index 0000000..14b972a --- /dev/null +++ b/docs/yaml/functions/add_global_link_arguments.yaml @@ -0,0 +1,19 @@ +name: add_global_link_arguments +returns: void +description: | + Adds global arguments to the linker command line. + + Like [[add_global_arguments]] but the arguments are passed to the linker. + +notes: + - Usually you should use [[add_project_link_arguments]] instead, + because that works even when you project is used as a subproject. + - You must pass always arguments individually `arg1, arg2, ...` + rather than as a string `'arg1 arg2', ...` + +varargs: + type: str + name: Linker argument + description: The linker arguments to add + +kwargs_inherit: add_global_arguments diff --git a/docs/yaml/functions/add_languages.yaml b/docs/yaml/functions/add_languages.yaml new file mode 100644 index 0000000..6851c4e --- /dev/null +++ b/docs/yaml/functions/add_languages.yaml @@ -0,0 +1,51 @@ +name: add_languages +returns: bool +description: | + Add programming languages used by the project. + + This is equivalent to having + them in the `project` declaration. This function is usually used to + add languages that are only used under some conditions. + + Returns `true` if all languages specified were found and `false` otherwise. + + If `native` is omitted, the languages may be used for either build or host + machine, but are never required for the build machine. (i.e. it is equivalent + to `add_languages(*langs*, native: false, required: *required*) and + add_languages(*langs*, native: true, required: false)`. This default behaviour + may change to `native: false` in a future Meson version. + +example: | + ```meson + project('foobar', 'c') + + if compiling_for_osx + add_languages('objc') + endif + if add_languages('cpp', required : false) + executable('cpp-app', 'main.cpp') + endif + + # More code... + ``` + +varargs: + type: str + name: Language + description: The languages to add + +kwargs: + required: + type: bool + default: true + description: | + If set to `true`, Meson will halt if any of the languages + specified are not found. *(since 0.47.0)* The value of a + [`feature`](Build-options.md#features) option can also be passed. + native: + type: bool + since: 0.54.0 + description: | + If set to `true`, the language will be used to compile for the build + machine, if `false`, for the host machine. + diff --git a/docs/yaml/functions/add_project_arguments.yaml b/docs/yaml/functions/add_project_arguments.yaml new file mode 100644 index 0000000..6b90e68 --- /dev/null +++ b/docs/yaml/functions/add_project_arguments.yaml @@ -0,0 +1,19 @@ +name: add_project_arguments +returns: void +description: | + Adds project specific arguments to the compiler command line. + + This function behaves in the same way as [[add_global_arguments]] except + that the arguments are only used for the current project, they won't + be used in any other subproject. + +notes: + - You must pass always arguments individually `arg1, arg2, ...` + rather than as a string `'arg1 arg2', ...` + +varargs: + type: str + name: Compiler argument + description: The commpiler arguments to add + +kwargs_inherit: add_global_arguments diff --git a/docs/yaml/functions/add_project_link_arguments.yaml b/docs/yaml/functions/add_project_link_arguments.yaml new file mode 100644 index 0000000..8ae4763 --- /dev/null +++ b/docs/yaml/functions/add_project_link_arguments.yaml @@ -0,0 +1,17 @@ +name: add_project_link_arguments +returns: void +description: | + Adds global arguments to the linker command line. + + Like [[add_global_arguments]] but the arguments are passed to the linker. + +notes: + - You must pass always arguments individually `arg1, arg2, ...` + rather than as a string `'arg1 arg2', ...` + +varargs: + type: str + name: Linker argument + description: The linker arguments to add + +kwargs_inherit: add_global_arguments diff --git a/docs/yaml/functions/add_test_setup.yaml b/docs/yaml/functions/add_test_setup.yaml new file mode 100644 index 0000000..3d666c7 --- /dev/null +++ b/docs/yaml/functions/add_test_setup.yaml @@ -0,0 +1,60 @@ +name: add_test_setup +returns: void +description: | + Add a custom test setup. This setup can be used to run the tests with a + custom setup, for example under Valgrind. + + To use the test setup, run `meson test --setup=*name*` inside the + build dir. + + Note that all these options are also available while running the + `meson test` script for running tests instead of `ninja test` or + `msbuild RUN_TESTS.vcxproj`, etc depending on the backend. + +posargs: + name: + type: str + description: The name of the test setup + +kwargs: + env: + type: env | list[str] | dict[str] + description: | + environment variables to set + , such as `['NAME1=value1', 'NAME2=value2']`, + or an [[@env]] object which allows more sophisticated + environment juggling. *(Since 0.52.0)* A dictionary is also accepted. + + exe_wrapper: + type: list[str | external_program] + description: The command or script followed by the arguments to it + + gdb: + type: bool + default: false + description: If `true`, the tests are also run under `gdb` + + timeout_multiplier: + type: int + default: 1 + description: | + A number to multiply the test timeout with. + *Since 0.57* if timeout_multiplier is `<= 0` the test has infinite duration, + in previous versions of Meson the test would fail with a timeout immediately. + + is_default: + type: bool + since: 0.49.0 + default: false + description: | + Set whether this is the default test setup. + If `true`, the setup will be used whenever `meson test` is run + without the `--setup` option. + + exclude_suites: + type: list[str] + since: 0.57.0 + description: + A list of test suites that should be excluded when using this setup. + Suites specified in the `--suite` option + to `meson test` will always run, overriding `add_test_setup` if necessary.
\ No newline at end of file diff --git a/docs/yaml/functions/alias_target.yaml b/docs/yaml/functions/alias_target.yaml new file mode 100644 index 0000000..22ffdfd --- /dev/null +++ b/docs/yaml/functions/alias_target.yaml @@ -0,0 +1,21 @@ +name: alias_target +since: 0.52.0 +returns: alias_tgt +description: | + This function creates a new top-level target. Like all top-level + targets, this integrates with the selected backend. For instance, with + you can run it as `meson compile target_name`. This is a dummy target + that does not execute any command, but ensures that all dependencies + are built. Dependencies can be any build target (e.g. return value of + [[executable]], [[custom_target]], etc) + +posargs: + target_name: + type: str + description: The name of the alias target + +varargs: + name: Dep + type: tgt + min_varargs: 1 + description: The targets to depend on diff --git a/docs/yaml/functions/assert.yaml b/docs/yaml/functions/assert.yaml new file mode 100644 index 0000000..bd64f01 --- /dev/null +++ b/docs/yaml/functions/assert.yaml @@ -0,0 +1,17 @@ +name: assert +returns: void +description: Abort with an error message if `condition` evaluates to `false`. + +notes: + - The `message` argument is optional since 0.53.0 and defaults to print + the condition statement. + +posargs: + condition: + type: bool + description: Abort if this evaluates to `false` + +optargs: + message: + type: str + description: The error message to print. diff --git a/docs/yaml/functions/benchmark.yaml b/docs/yaml/functions/benchmark.yaml new file mode 100644 index 0000000..da465aa --- /dev/null +++ b/docs/yaml/functions/benchmark.yaml @@ -0,0 +1,106 @@ +name: benchmark +returns: void +description: | + Creates a benchmark item that will be run when the benchmark target is + run. The behavior of this function is identical to [[test]] + except for: + + * benchmark() has no `is_parallel` keyword because benchmarks are not run in parallel + * benchmark() does not automatically add the `MALLOC_PERTURB_` environment variable + + Defined tests can be run in a backend-agnostic way by calling + `meson test` inside the build dir, or by using backend-specific + commands, such as `ninja test` or `msbuild RUN_TESTS.vcxproj`. + +notes: + - Prior to 0.52.0 benchmark would warn that `depends` and + `priority` were unsupported, this is incorrect. + +posargs: + name: + type: str + description: The *unique* test id + + executable: + type: exe | jar | external_program | file + description: The program to execute + +kwargs: + args: + type: list[str | file | tgt] + description: Arguments to pass to the executable + + env: + type: env | list[str] | dict[str] + description: | + environment variables to set, such as `['NAME1=value1', + 'NAME2=value2']`, or an [[@env]] object which allows more sophisticated + environment juggling. *(Since 0.52.0)* A dictionary is also accepted. + + should_fail: + type: bool + default: false + description: | + when true the test is considered passed if the + executable returns a non-zero return value (i.e. reports an error) + + suite: + type: str | list[str] + description: | + `'label'` (or list of labels `['label1', 'label2']`) + attached to this test. The suite name is qualified by a (sub)project + name resulting in `(sub)project_name:label`. In the case of a list + of strings, the suite names will be `(sub)project_name:label1`, + `(sub)project_name:label2`, etc. + + timeout: + type: int + default: 30 + description: | + the amount of seconds the test is allowed to run, a test + that exceeds its time limit is always considered failed, defaults to + 30 seconds. *Since 0.57* if timeout is `<= 0` the test has infinite duration, + in previous versions of Meson the test would fail with a timeout immediately. + + workdir: + type: str + description: | + absolute path that will be used as the working directory + for the test + + depends: + type: list[build_tgt | custom_tgt] + since: 0.46.0 + description: | + specifies that this test depends on the specified + target(s), even though it does not take any of them as a command + line argument. This is meant for cases where test finds those + targets internally, e.g. plugins or globbing. Those targets are built + before test is executed even if they have `build_by_default : false`. + + protocol: + type: str + since: 0.50.0 + default: "'exitcode'" + description: | + specifies how the test results are parsed and can + be one of `exitcode`, `tap`, or `gtest`. For more information about test + harness protocol read [Unit Tests](Unit-tests.md). The following values are + accepted: + + - `exitcode`: the executable's exit code is used by the test harness + to record the outcome of the test). + - `tap`: [Test Anything Protocol](https://www.testanything.org/). + - `gtest` *(since 0.55.0)*: for Google Tests. + - `rust` *(since 0.56.0)*: for native rust tests + + priority: + type: int + since: 0.52.0 + default: 0 + description: | + specifies the priority of a test. Tests with a + higher priority are *started* before tests with a lower priority. + The starting order of tests with identical priorities is + implementation-defined. The default priority is 0, negative numbers are + permitted. diff --git a/docs/yaml/functions/both_libraries.yaml b/docs/yaml/functions/both_libraries.yaml new file mode 100644 index 0000000..fa799d1 --- /dev/null +++ b/docs/yaml/functions/both_libraries.yaml @@ -0,0 +1,15 @@ +name: both_libraries +returns: both_libs +since: 0.46.0 +description: | + Builds both a static and shared library with the given sources. + Positional and keyword arguments are otherwise the same as for + [[library]]. Source files will be compiled only once and + object files will be reused to build both shared and static libraries, + unless `b_staticpic` user option or `pic` argument are set to false in + which case sources will be compiled twice. + + +posargs_inherit: library +varargs_inherit: library +kwargs_inherit: library diff --git a/docs/yaml/functions/build_target.yaml b/docs/yaml/functions/build_target.yaml new file mode 100644 index 0000000..48385f2 --- /dev/null +++ b/docs/yaml/functions/build_target.yaml @@ -0,0 +1,45 @@ +name: build_target +returns: build_tgt +description: | + Creates a build target whose type can be set dynamically with the + `target_type` keyword argument. + + `target_type` may be set to one of: + + - `executable` (see [[executable]]) + - `shared_library` (see [[shared_library]]) + - `shared_module` (see [[shared_module]]) + - `static_library` (see [[static_library]]) + - `both_libraries` (see [[both_libraries]]) + - `library` (see [[library]]) + - `jar` (see [[jar]]) + + This declaration: + + ```meson + executable(<arguments and keyword arguments>) + ``` + + is equivalent to this: + + ```meson + build_target(<arguments and keyword arguments>, target_type : 'executable') + ``` + + The lists for the kwargs (such as `sources`, `objects`, and `dependencies`) are + always flattened, which means you can freely nest and add lists while + creating the final list. + + The returned object also has methods that are documented in [[@build_tgt]]. + +posargs_inherit: _build_target_base +varargs_inherit: _build_target_base +kwargs_inherit: + - executable + - library + - jar + +kwargs: + target_type: + type: str + description: The actual target to build diff --git a/docs/yaml/functions/configuration_data.yaml b/docs/yaml/functions/configuration_data.yaml new file mode 100644 index 0000000..e16a69f --- /dev/null +++ b/docs/yaml/functions/configuration_data.yaml @@ -0,0 +1,15 @@ +name: configuration_data +returns: cfg_data +description: | + Creates an empty configuration object. You should add your + configuration with the [[@cfg_data]] method calls and + finally use it in a call to [[configure_file]]. + +optargs: + data: + type: dict[str | bool | int] + since: 0.49.0 + description: | + Optional dictionary to specifiy an inital data set. If + provided, each key/value pair is added into the [[@cfg_data]] object + as if the [[cfg_data.set]] method was called for each of them. diff --git a/docs/yaml/functions/configure_file.yaml b/docs/yaml/functions/configure_file.yaml new file mode 100644 index 0000000..4bce368 --- /dev/null +++ b/docs/yaml/functions/configure_file.yaml @@ -0,0 +1,136 @@ +name: configure_file +returns: file +description: | + This function can run in three modes depending on the keyword arguments + passed to it. + + When a [[@cfg_data]] object is passed + to the `configuration:` keyword argument, it takes a template file as + the `input:` (optional) and produces the `output:` (required) by + substituting values from the configuration data as detailed in [the + configuration file documentation](Configuration.md). *(since 0.49.0)* + A dictionary can be passed instead of a + [[@cfg_data]] object. + + When a list of strings is passed to the `command:` keyword argument, + it takes any source or configured file as the `input:` and assumes + that the `output:` is produced when the specified command is run. + + *(since 0.47.0)* When the `copy:` keyword argument is set to `true`, + this function will copy the file provided in `input:` to a file in the + build directory with the name `output:` in the current directory. + +kwargs: + capture: + type: bool + since: 0.41.0 + default: false + description: | + When this argument is set to true, + Meson captures `stdout` of the `command` and writes it to the target + file specified as `output`. + + command: + type: list[str | file] + description: | + As explained above, if specified, Meson does not create + the file itself but rather runs the specified command, which allows + you to do fully custom file generation. *(since 0.52.0)* The command can contain + file objects and more than one file can be passed to the `input` keyword + argument, see [[custom_target]] for details about string + substitutions. + + copy: + type: bool + default: false + since: 0.47.0 + description: | + As explained above, if specified Meson only + copies the file from input to output. + + depfile: + type: str + since: 0.52.0 + description: | + A dependency file that the command can write listing + all the additional files this target depends on. A change + in any one of these files triggers a reconfiguration. + + format: + type: str + since: 0.46.0 + default: "'meson'" + description: | + The format of defines. It defaults to `'meson'`, and so substitutes + `#mesondefine` statements and variables surrounded by `@` characters, you can also use `'cmake'` + to replace `#cmakedefine` statements and variables with the `${variable}` syntax. Finally you can use + `'cmake@'` in which case substitutions will apply on `#cmakedefine` statements and variables with + the `@variable@` syntax. + + input: + type: str | file + description: | + The input file name. If it's not specified in configuration + mode, all the variables in the `configuration:` object (see above) + are written to the `output:` file. + + install: + type: bool + default: false + since: 0.50.0 + description: | + When true, this generated file is installed during + the install step, and `install_dir` must be set and not empty. When false, this + generated file is not installed regardless of the value of `install_dir`. + When omitted it defaults to true when `install_dir` is set and not empty, + false otherwise. + + install_dir: + type: str + description: | + The subdirectory to install the generated file to + (e.g. `share/myproject`), if omitted or given the value of empty + string, the file is not installed. + + install_mode: + type: list[str | int] + since: 0.47.0 + description: | + Specify the file mode in symbolic format + and optionally the owner/uid and group/gid for the installed files. + + See the `install_mode` kwarg of [[install_data]] for more information. + + install_tag: + type: str + since: 0.60.0 + description: | + A string used by the `meson install --tags` command + to install only a subset of the files. By default the file has no install + tag which means it is not being installed when `--tags` argument is specified. + + output: + type: str + description: | + The output file name. *(since 0.41.0)* may contain + `@PLAINNAME@` or `@BASENAME@` substitutions. In configuration mode, + the permissions of the input file (if it is specified) are copied to + the output file. + + output_format: + type: str + since: 0.47.0 + description: | + The format of the output to generate when no input + was specified. It defaults to `c`, in which case preprocessor directives + will be prefixed with `#`, you can also use `nasm`, in which case the + prefix will be `%`. + + encoding: + type: str + default: "'utf-8'" + since: 0.47.0 + description: | + Set the file encoding for the input and output file. + The supported encodings are those of python3, see + [standard-encodings](https://docs.python.org/3/library/codecs.html#standard-encodings). diff --git a/docs/yaml/functions/custom_target.yaml b/docs/yaml/functions/custom_target.yaml new file mode 100644 index 0000000..bfc7da9 --- /dev/null +++ b/docs/yaml/functions/custom_target.yaml @@ -0,0 +1,230 @@ +name: custom_target +returns: custom_tgt +description: | + Create a custom top level build target. The only positional argument + is the name of this target and cannot contain path separators (`/` or `\`). + The name of custom target might not be used by every backends, for instance with + the Ninja backend, `subdir/meson.build` containing the example below, + `ninja -C builddir foo` or `ninja -C builddir subdir/foo` won't work, + it is instead `ninja -C builddir subdir/file.txt`. Howerver, `meson compile subdir/foo` + is accepted. + ```meson + custom_target('foo', output: 'file.txt', ...) + ``` + + *Since 0.60.0* the name argument is optional and defaults to the basename of the first + output (`file.txt` in the example above). + + The list of strings passed to the `command` keyword argument accept + the following special string substitutions: + + - `@INPUT@`: the full path to the input passed to `input`. If more than + one input is specified, all of them will be substituted as separate + arguments only if the command uses `'@INPUT@'` as a + standalone-argument. For instance, this would not work: `command : + ['cp', './@INPUT@']`, but this would: `command : ['cp', '@INPUT@']`. + - `@OUTPUT@`: the full path to the output passed to `output`. If more + than one outputs are specified, the behavior is the same as + `@INPUT@`. + - `@INPUT0@` `@INPUT1@` `...`: the full path to the input with the specified array index in `input` + - `@OUTPUT0@` `@OUTPUT1@` `...`: the full path to the output with the specified array index in `output` + - `@OUTDIR@`: the full path to the directory where the output(s) must be written + - `@DEPFILE@`: the full path to the dependency file passed to `depfile` + - `@PLAINNAME@`: the input filename, without a path + - `@BASENAME@`: the input filename, with extension removed + - `@PRIVATE_DIR@` *(since 0.50.1)*: path to a directory where the custom target must store all its intermediate files. + - `@SOURCE_ROOT@`: the path to the root of the source tree. Depending on the backend, + this may be an absolute or a relative to current workdir path. + - `@BUILD_ROOT@`: the path to the root of the build tree. Depending on the backend, + this may be an absolute or a relative to current workdir path. + - `@CURRENT_SOURCE_DIR@`: this is the directory where the currently + processed meson.build is located in. Depending on the backend, + this may be an absolute or a relative to current workdir path. + + *(since 0.47.0)* The `depfile` keyword argument also accepts the + `@BASENAME@` and `@PLAINNAME@` substitutions. + + The returned object also has methods that are documented in [[@custom_tgt]]. + +notes: + - | + Assuming that `command:` is executed by a POSIX `sh` shell + is not portable, notably to Windows. Instead, consider using a + `native: true` [[executable]], or a python script. + +optargs: + name: + type: str + description: | + The *unique* id of the custom target + + This posarg is optional *since 0.60.0*. It defaults to the basename + of the first output. + +kwargs: + build_by_default: + type: bool + since: 0.38.0 + description: | + Causes, when set to true, to + have this target be built by default. This means it will be built when + `meson compile` is called without any arguments. The default value is `false`. + + *(since 0.50.0)* If `build_by_default` is explicitly set to false, `install` + will no longer override it. If `build_by_default` is not set, `install` will + still determine its default. + + build_always: + type: bool + deprecated: 0.47.0 + description: | + If `true` this target is always considered out of + date and is rebuilt every time. Equivalent to setting both + `build_always_stale` and `build_by_default` to true. + + build_always_stale: + type: bool + since: 0.47.0 + default: false + description: | + If `true` the target is always considered out of date. + Useful for things such as build timestamps or revision control tags. + The associated command is run even if the outputs are up to date. + + capture: + type: bool + default: false + description: | + There are some compilers that can't be told to write + their output to a file but instead write it to standard output. When + this argument is set to true, Meson captures `stdout` and writes it + to the target file. Note that your command argument list may not + contain `@OUTPUT@` when capture mode is active. + + console: + type: bool + since: 0.48.0 + description: | + Keyword argument conflicts with `capture`, and is meant + for commands that are resource-intensive and take a long time to + finish. With the Ninja backend, setting this will add this target + to [Ninja's `console` pool](https://ninja-build.org/manual.html#_the_literal_console_literal_pool), + which has special properties such as not buffering stdout and + serializing all targets in this pool. + + command: + type: list[str | file | exe | external_program] + description: | + Command to run to create outputs from inputs. The command + may be strings or the return value of functions that return file-like + objects such as [[find_program]], + [[executable]], [[configure_file]], + [[files]], [[custom_target]], etc. + Meson will automatically insert the appropriate dependencies on + targets and files listed in this keyword argument. + Note: always specify commands in array form `['commandname', + '-arg1', '-arg2']` rather than as a string `'commandname -arg1 + -arg2'` as the latter will *not* work. + + depend_files: + type: list[str | file] + description: | + files ([[@str]], + [[@file]], or the return value of [[configure_file]] that + this target depends on but are not listed in the `command` keyword + argument. Useful for adding regen dependencies. + + depends: + type: list[tgt] + description: | + Specifies that this target depends on the specified + target(s), even though it does not take any of them as a command + line argument. This is meant for cases where you have a tool that + e.g. does globbing internally. Usually you should just put the + generated sources as inputs and Meson will set up all dependencies + automatically. + + depfile: + type: str + description: | + A dependency file that the command can write listing + all the additional files this target depends on, for example a C + compiler would list all the header files it included, and a change + in any one of these files triggers a recompilation. + + *(since 0.47.0)* the `@BASENAME@` and `@PLAINNAME@` substitutions + are also accepted. + + input: + type: list[str | file] + description: List of source files. *(since 0.41.0)* the list is flattened. + + install: + type: bool + description: When true, this target is installed during the install step. + + install_dir: + type: str | list[str] + description: | + If only one install_dir is provided, all outputs are installed there. + *Since 0.40.0* Allows you to specify the installation directory for each + corresponding output. For example: + ```meson + custom_target('different-install-dirs', + output : ['first.file', 'second.file'], + install : true, + install_dir : ['somedir', 'otherdir]) + ``` + This would install `first.file` to `somedir` and `second.file` to `otherdir`. + + To only install some outputs, pass `false` for the outputs that you + don't want installed. For example: + ```meson + custom_target('only-install-second', + output : ['first.file', 'second.file'], + install : true, + install_dir : [false, 'otherdir]) + ``` + This would install `second.file` to `otherdir` and not install `first.file`. + + install_mode: + type: list[str | int] + since: 0.47.0 + description: | + The file mode and optionally the owner/uid and group/gid. + See the `install_mode` kwarg of [[install_data]] for more information. + + install_tag: + type: list[str] + since: 0.60.0 + description: | + A list of strings, one per output, used by the `meson install --tags` command + to install only a subset of the files. + + By default all outputs have no install tag which means they are not being + installed when `--tags` argument is specified. If only one tag is specified, + it is assumed that all outputs have the same tag. `false` can be used for + outputs that have no tag or are not installed. + + output: + type: list[str] + description: List of output files. + + env: + since: 0.57.0 + type: env | list[str] | dict[str] + description: | + environment variables to set, such as + `{'NAME1': 'value1', 'NAME2': 'value2'}` or `['NAME1=value1', 'NAME2=value2']`, + or an [[@env]] object which allows more + sophisticated environment juggling. + + feed: + type: bool + since: 0.59.0 + default: false + description: | + There are some compilers that can't be told to read + their input from a file and instead read it from standard input. When this + argument is set to `true`, Meson feeds the input file to `stdin`. Note that + your argument list may not contain `@INPUT@` when feed mode is active. diff --git a/docs/yaml/functions/declare_dependency.yaml b/docs/yaml/functions/declare_dependency.yaml new file mode 100644 index 0000000..f043d1d --- /dev/null +++ b/docs/yaml/functions/declare_dependency.yaml @@ -0,0 +1,59 @@ +name: declare_dependency +returns: dep +description: | + This function returns a [[@dep]] object that + behaves like the return value of [[dependency]] but is + internal to the current build. The main use case for this is in + subprojects. This allows a subproject to easily specify how it should + be used. This makes it interchangeable with the same dependency that + is provided externally by the system. + +kwargs: + compile_args: + type: list[str] + description: Compile arguments to use. + + dependencies: + type: list[dep] + description: Other dependencies needed to use this dependency. + + include_directories: + type: list[inc | str] + description: | + the directories to add to header search path, + must be [[@inc]] objects or *(since 0.50.0)* plain strings. + + link_args: + type: list[str] + description: Link arguments to use. + + link_with: + type: list[lib] + description: Libraries to link against. + + link_whole: + type: list[lib] + since: 0.46.0 + description: Libraries to link fully, same as [[executable]]. + + sources: + type: list[str | file] + description: | + sources to add to targets + (or generated header files + that should be built before sources including them are built) + + version: + type: str + description: | + the version of this dependency, + such as `1.2.3`. Defaults to the project version. + + variables: + type: dict[str] | list[str] + since: 0.54.0 + description: | + a dictionary of arbitrary strings, + this is meant to be used + in subprojects where special variables would be provided via cmake or + pkg-config. *since 0.56.0* it can also be a list of `'key=value'` strings. diff --git a/docs/yaml/functions/dependency.yaml b/docs/yaml/functions/dependency.yaml new file mode 100644 index 0000000..dcb696d --- /dev/null +++ b/docs/yaml/functions/dependency.yaml @@ -0,0 +1,200 @@ +name: dependency +returns: dep +description: | + Finds an external dependency (usually a library installed on your + system) with the given name with `pkg-config` and [with + CMake](Dependencies.md#cmake) if `pkg-config` fails. Additionally, + frameworks (OSX only) and [library-specific fallback detection + logic](Dependencies.md#dependencies-with-custom-lookup-functionality) + are also supported. + + *Since 0.60.0* more than one name can be provided, they will be tried in order + and the first name to be found will be used. The fallback subproject will be + used only if none of the names are found on the system. Once one of the name has + been found, all other names are added into the cache so subsequent calls for any + of those name will return the same value. This is useful in case a dependency + could have different names, such as `png` and `libpng`. + + Dependencies can also be resolved in two other ways: + + * if the same name was used in a `meson.override_dependency` prior to + the call to `dependency`, the overriding dependency will be returned + unconditionally; that is, the overriding dependency will be used + independent of whether an external dependency is installed in the system. + Typically, `meson.override_dependency` will have been used by a + subproject. + + * by a fallback subproject which, if needed, will be brought into the current + build specification as if [`subproject()`](#subproject) had been called. + The subproject can be specified with the `fallback` argument. Alternatively, + if the `fallback` argument is absent, *since 0.55.0* Meson can + automatically identify a subproject as a fallback if a wrap file + [provides](Wrap-dependency-system-manual.md#provide-section) the + dependency, or if a subproject has the same name as the dependency. + In the latter case, the subproject must use `meson.override_dependency` to + specify the replacement, or Meson will report a hard error. See the + [Wrap documentation](Wrap-dependency-system-manual.md#provide-section) + for more details. This automatic search can be controlled using the + `allow_fallback` keyword argument. + + 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, or with + a `fallback:` kwarg, can be used to declare an optional dependency + that only looks in the specified subproject, and only if that's + allowed by `--wrap-mode`. + + The returned object [[@dep]] also has additional methods. + +notes: + - This function supports additional [library-specific](Dependencies.md#dependencies-with-custom-lookup-functionality) + keyword arguments that may also be accepted (e.g. `modules` specifies submodules to use for + dependencies such as Qt5 or Boost. `components` allows the user to manually + add CMake `COMPONENTS` for the `find_package` lookup) + +varargs: + name: names + type: str + since: 0.60.0 + min_varargs: 1 + description: | + The names of the dependency too look up. The dependencies are looked up in + the order they are provided here. The first found dependency will then be + used. The fallback subproject will be used only if none of the names are + found on the system. Once one of the name has been found, all other names + are added into the cache so subsequent calls for any of those name will + return the same value. This is useful in case a dependency could have + different names, such as `png` and `libpng`. + + **NOTE:** Before *0.60.0* only a single dependency name was allowed. + +kwargs: + default_options: + type: list[str] + since: 0.37.0 + description: | + An array of default option values + that override those set in the subproject's `meson_options.txt` + (like `default_options` in [[project]], they only have + effect when Meson is run for the first time, and command line + arguments override any default options in build files) + + allow_fallback: + type: bool + since: 0.56.0 + description: | + Specifies whether Meson should automatically pick a fallback subproject + in case the dependency + is not found in the system. If `true` and the dependency is not found + on the system, Meson will fallback to a subproject that provides this + dependency. If `false`, Meson will not fallback even if a subproject + provides this dependency. By default, Meson will do so if `required` + is `true` or [`enabled`](Build-options.md#features); see the [Wrap + documentation](Wrap-dependency-system-manual.md#provide-section) + for more details. + + fallback: + type: list[str] | str + description: | + Manually specifies a subproject fallback + to use in case the dependency is not found in the system. + This is useful if the automatic search is not applicable or if you + want to support versions of Meson older than 0.55.0. If the value is an + array `['subproj_name', 'subproj_dep']`, the first value is the name + of the subproject and the second is the variable name in that + subproject that contains a dependency object such as the return + value of [[declare_dependency]] or + [[dependency]], etc. Note that this means the + fallback dependency may be a not-found dependency, in which + case the value of the `required:` kwarg will be obeyed. + *Since 0.54.0* the value can be a single string, the subproject name; + in this case the subproject must use + `meson.override_dependency('dependency_name', subproj_dep)` + to specify the dependency object used in the superproject. + If the value is an empty list, it has the same effect as + `allow_fallback: false`. + + language: + type: str + since: 0.42.0 + description: | + Defines what language-specific dependency to find + if it's available for multiple languages. + + method: + type: str + default: "'auto'" + description: | + Defines the way the dependency is detected, the default is + `auto` but can be overridden to be e.g. `qmake` for Qt development, + and [different dependencies support different values]( + Dependencies.md#dependencies-with-custom-lookup-functionality) + for this (though `auto` will work on all of them) + + native: + type: bool + default: false + description: | + If set to `true`, causes Meson to find the dependency on + the build machine system rather than the host system (i.e. where the + cross compiled binary will run on), usually only needed if you build + a tool to be used during compilation. + + not_found_message: + type: str + since: 0.50.0 + description: An optional string that will be printed as a [[message]] if the dependency was not found. + + required: + type: bool | feature + default: true + description: | + when set to false, Meson will proceed with the build + even if the dependency is not found. *(since 0.47.0)* The value of a + [`feature`](Build-options.md#features) option can also be passed. + + static: + type: bool + default: false + description: | + Tells the dependency provider to try to get static + libraries instead of dynamic ones (note that this is not supported + by all dependency backends) + + *Since 0.60.0* it also sets `default_library` option accordingly on the fallback + subproject if it was not set explicitly in `default_options` keyword argument. + + version: + type: str + since: 0.37.0 + description: | + Specifies the required version, + a string containing a + comparison operator followed by the version string, examples include + `>1.0.0`, `<=2.3.5` or `3.1.4` for exact matching. + You can also specify multiple restrictions by passing a list to this + keyword argument, such as: `['>=3.14.0', '<=4.1.0']`. + These requirements are never met if the version is unknown. + + include_type: + type: str + default: "'preserve'" + since: 0.52.0 + description: | + An enum flag, marking how the dependency + flags should be converted. Supported values are `'preserve'`, `'system'` and + `'non-system'`. System dependencies may be handled differently on some + platforms, for instance, using `-isystem` instead of `-I`, where possible. + If `include_type` is set to `'preserve'`, no additional conversion will be + performed. + + disabler: + type: bool + default: false + since: 0.49.0 + description: | + Returns a [[disabler]] object instead of a not-found dependency + if this kwarg is set to `true` and the dependency couldn't be found. diff --git a/docs/yaml/functions/disabler.yaml b/docs/yaml/functions/disabler.yaml new file mode 100644 index 0000000..267d4b1 --- /dev/null +++ b/docs/yaml/functions/disabler.yaml @@ -0,0 +1,4 @@ +name: disabler +returns: disabler +description: Returns a [[@disabler]] object. +since: 0.44.0 diff --git a/docs/yaml/functions/environment.yaml b/docs/yaml/functions/environment.yaml new file mode 100644 index 0000000..99c8a45 --- /dev/null +++ b/docs/yaml/functions/environment.yaml @@ -0,0 +1,12 @@ +name: environment +returns: env +since: 0.35.0 +description: Returns an empty [[@env]] object. + +optargs: + env: + type: dict[str] + since: 0.52.0 + description: | + If provided, each key/value pair is added into the [[@env]] object + as if [[env.set]] method was called for each of them. diff --git a/docs/yaml/functions/error.yaml b/docs/yaml/functions/error.yaml new file mode 100644 index 0000000..d54808c --- /dev/null +++ b/docs/yaml/functions/error.yaml @@ -0,0 +1,14 @@ +name: error +returns: void +description: Print the argument string and halts the build process. + +posargs: + message: + type: str + description: The message to print + +varargs: + name: msg + since: 0.58.0 + type: str + description: Additional parameters will be seperated by spaces diff --git a/docs/yaml/functions/executable.yaml b/docs/yaml/functions/executable.yaml new file mode 100644 index 0000000..2e57bd4 --- /dev/null +++ b/docs/yaml/functions/executable.yaml @@ -0,0 +1,46 @@ +name: executable +returns: exe +description: | + Creates a new executable. The first argument specifies its name and + the remaining positional arguments define the input files to use. + + The lists for the kwargs (such as `sources`, `objects`, and `dependencies`) are + always flattened, which means you can freely nest and add lists while + creating the final list. + + The returned object also has methods that are documented in [[@exe]]. + +warnings: + - The `link_language` kwarg was broken until 0.55.0 + +posargs_inherit: _build_target_base +varargs_inherit: _build_target_base +kwargs_inherit: _build_target_base + +kwargs: + export_dynamic: + type: bool + since: 0.45.0 + description: | + when set to true causes the target's symbols to be + dynamically exported, allowing modules built using the + [[shared_module]] function to refer to functions, + variables and other symbols defined in the executable itself. Implies + the `implib` argument. + + implib: + type: bool + since: 0.42.0 + description: | + When set to true, an import library is generated for the + executable (the name of the import library is based on *exe_name*). + Alternatively, when set to a string, that gives the base name for + the import library. The import library is used when the returned + build target object appears in `link_with:` elsewhere. Only has any + effect on platforms where that is meaningful (e.g. Windows). Implies + the `export_dynamic` argument. + + pie: + type: bool + since: 0.49.0 + description: Build a position-independent executable. diff --git a/docs/yaml/functions/files.yaml b/docs/yaml/functions/files.yaml new file mode 100644 index 0000000..ca72745 --- /dev/null +++ b/docs/yaml/functions/files.yaml @@ -0,0 +1,30 @@ +name: files +returns: list[file] +description: | + This command takes the strings given to it in arguments and returns + corresponding File objects that you can use as sources for build + targets. The difference is that file objects remember the subdirectory + they were defined in and can be used anywhere in the source tree. + +example: | + As an example suppose you have source file `foo.cpp` in subdirectory + `bar1` and you would like to use it in a build target that is defined + in `bar2`. To make this happen you first create the object in `bar1` + like this: + + ```meson + foofile = files('foo.cpp') + ``` + + Then you can use it in `bar2` like this: + + ```meson + executable('myprog', 'myprog.cpp', foofile, ...) + ``` + + Meson will then do the right thing. + +varargs: + name: file + type: str + description: Path to the file. diff --git a/docs/yaml/functions/find_program.yaml b/docs/yaml/functions/find_program.yaml new file mode 100644 index 0000000..5e147eb --- /dev/null +++ b/docs/yaml/functions/find_program.yaml @@ -0,0 +1,108 @@ +name: find_program +returns: external_program +description: | + `program_name` here is a string that can be an executable or script + to be searched for in `PATH` or other places inside the project. + The search order is: + + 1. Program overrides set via [[meson.override_find_program]] + 1. [`[provide]` sections](Wrap-dependency-system-manual.md#provide-section) + in subproject wrap files, if [`wrap_mode`](Builtin-options.md#core-options) is + set to `forcefallback` + 1. [`[binaries]` section](Machine-files.md#binaries) in your machine files + 1. Directories provided using the `dirs:` kwarg (see below) + 1. Project's source tree relative to the current subdir + - If you use the return value of [[configure_file]], the + current subdir inside the build tree is used instead + 1. `PATH` environment variable + 1. [`[provide]` sections](Wrap-dependency-system-manual.md#provide-section) in + subproject wrap files, if [`wrap_mode`](Builtin-options.md#core-options) is + set to anything other than `nofallback` + + Meson will also autodetect scripts with a shebang line and run them + with the executable/interpreter specified in it both on Windows + (because the command invocator will reject the command otherwise) and + Unixes (if the script file does not have the executable bit set). + Hence, you *must not* manually add the interpreter while using this + script as part of a list of commands. + + If you need to check for a program in a non-standard location, you can + just pass an absolute path to `find_program`, e.g. + + ```meson + setcap = find_program('setcap', '/usr/sbin/setcap', '/sbin/setcap', required : false) + ``` + + It is also possible to pass an array to `find_program` in case you + need to construct the set of paths to search on the fly: + + ```meson + setcap = find_program(['setcap', '/usr/sbin/setcap', '/sbin/setcap'], required : false) + ``` + + The returned [[@external_program]] object also has documented methods. + +posargs: + program_name: + type: str + description: The name of the program to search + +varargs: + name: fallback + type: str + since: 0.37.0 + description: | + These parameters are used as fallback strings to search for. + This is meant to be used for cases where the + program may have many alternative names, such as `foo` and + `foo.py`. The function will check for the arguments one by one and the + first one that is found is returned. + +kwargs: + required: + type: bool | feature + default: true + description: | + When `true`, Meson will abort if no program can be found. + If `required` is set to `false`, + Meson continue even if none of the programs can be found. You can + then use the `.found()` method on the returned [[@external_program]] to check + whether it was found or not. *(since 0.47.0)* The value of a + [`feature`](Build-options.md#features) option can also be passed to the + `required` keyword argument. + + native: + type: bool + default: false + since: 0.43.0 + description: | + Defines how this executable should be searched. By default + it is set to `false`, which causes Meson to first look for the + executable in the cross file (when cross building) and if it is not + defined there, then from the system. If set to `true`, the cross + file is ignored and the program is only searched from the system. + + disabler: + type: bool + since: 0.49.0 + default: false + description: | + If `true` and the program couldn't be found, return a [[@disabler]] object + instead of a not-found object. + + version: + type: str + since: 0.52.0 + description: | + specifies the required version, see + [[dependency]] for argument format. The version of the program + is determined by running `program_name --version` command. If stdout is empty + it fallbacks to stderr. If the output contains more text than simply a version + number, only the first occurrence of numbers separated by dots is kept. + If the output is more complicated than that, the version checking will have to + be done manually using [[run_command]]. + + dirs: + type: list[str] + since: 0.53.0 + description: extra list of absolute paths where to look for program names. diff --git a/docs/yaml/functions/generator.yaml b/docs/yaml/functions/generator.yaml new file mode 100644 index 0000000..cec0b79 --- /dev/null +++ b/docs/yaml/functions/generator.yaml @@ -0,0 +1,83 @@ +name: generator +returns: generator +description: | + See also: [[custom_target]] + + This function creates a [[@generator]] object that can + be used to run custom compilation commands. The only positional + argument is the executable to use. It can either be a self-built + executable or one returned by find_program. + + The template strings passed to all the keyword arguments accept + the following special substitutions: + + - `@PLAINNAME@`: the complete input file name, e.g: `foo.c` becomes `foo.c` (unchanged) + - `@BASENAME@`: the base of the input filename, e.g.: `foo.c.y` becomes `foo.c` (extension is removed) + + Each string passed to the `output` keyword argument *must* be + constructed using one or both of these two substitutions. + + In addition to the above substitutions, the `arguments` keyword + argument also accepts the following: + + - `@OUTPUT@`: the full path to the output file + - `@INPUT@`: the full path to the input file + - `@DEPFILE@`: the full path to the depfile + - `@SOURCE_DIR@`: the full path to the root of the source tree + - `@CURRENT_SOURCE_DIR@`: this is the directory where the currently processed meson.build is located in + - `@BUILD_DIR@`: the full path to the root of the build dir where the output will be placed + + NOTE: Generators should only be used for outputs that will ***only*** + be used as inputs for a [[build_target]] or a [[custom_target]]. + When you use the processed output of a + generator in multiple targets, the generator will be run multiple + times to create outputs for each target. Each output will be created + in a target-private directory `@BUILD_DIR@`. + + If you want to generate files for general purposes such as for + generating headers to be used by several sources, or data that will be + installed, and so on, use a [[custom_target]] instead. + +posargs: + exe: + type: exe | external_program + description: Executable for the command to run + +kwargs: + arguments: + type: list[str] + description: A list of template strings that will be the command line arguments passed to the executable. + + depends: + # Not sure why this is not just `target` + type: list[build_tgt | custom_tgt] + since: 0.51.0 + description: | + An array of build targets that must be built before + this generator can be run. This is used if you have a generator that calls + a second executable that is built in this project. + + depfile: + type: str + description: | + A template string pointing to a dependency file that a + generator can write listing all the additional files this target + depends on, for example a C compiler would list all the header files + it included, and a change in any one of these files triggers a + recompilation, + + output: + type: list[str] + description: | + Template string (or list of template strings) defining + how an output file name is (or multiple output names are) generated + from a single source file name. + + capture: + type: bool + default: false + since: 0.43.0 + description: | + When this argument is set to true, Meson captures `stdout` + of the `executable` and writes it to the target file + specified as `output`. diff --git a/docs/yaml/functions/get_option.yaml b/docs/yaml/functions/get_option.yaml new file mode 100644 index 0000000..0bf0042 --- /dev/null +++ b/docs/yaml/functions/get_option.yaml @@ -0,0 +1,28 @@ +name: get_option +returns: str | int | bool | feature | list[str | int | bool] +description: | + Obtains the value of the [project build option](Build-options.md) + specified in the positional argument. + + Note that the value returned for built-in options that end in `dir` + such as `bindir` and `libdir` is always a path relative to (and + inside) the `prefix`. + + The only exceptions are: `sysconfdir`, `localstatedir`, and + `sharedstatedir` which will return the value passed during + configuration as-is, which may be absolute, or relative to `prefix`. + [`install_dir` arguments](Installing.md) handles that as expected, but + if you need the absolute path to one of these e.g. to use in a define + etc., you should use `get_option('prefix') / + get_option('localstatedir')` + + For options of type `feature` a + [[@feature]] option object + is returned instead of a string. + See [`feature` options](Build-options.md#features) + documentation for more details. + +posargs: + option_name: + type: str + description: Name of the option to query diff --git a/docs/yaml/functions/get_variable.yaml b/docs/yaml/functions/get_variable.yaml new file mode 100644 index 0000000..f8177c1 --- /dev/null +++ b/docs/yaml/functions/get_variable.yaml @@ -0,0 +1,19 @@ +name: get_variable +returns: any +description: | + This function can be used to dynamically obtain a variable. `res = + get_variable(varname, fallback)` takes the value of `varname` (which + must be a string) and stores the variable of that name into `res`. If + the variable does not exist, the variable `fallback` is stored to + `res`instead. If a fallback is not specified, then attempting to read + a non-existing variable will cause a fatal error. + +posargs: + variable_name: + type: str + description: Name of the variable to get + +optargs: + default: + type: any + description: Fallback value to return when the variable does not exist diff --git a/docs/yaml/functions/import.yaml b/docs/yaml/functions/import.yaml new file mode 100644 index 0000000..13c0a06 --- /dev/null +++ b/docs/yaml/functions/import.yaml @@ -0,0 +1,28 @@ +name: import +returns: module +description: | + Imports the given extension module. Returns an object that can be used to call + the methods of the module. Here's an example for a hypothetical `testmod` + module. + +example: | + ```meson + tmod = import('testmod') + tmod.do_something() + ``` + +posargs: + module_name: + type: str + description: Name of the module to import. + +kwargs: + required: + type: bool | feature + since: 0.59.0 + description: Whether the mdule is required and Meson should abort if not found. + + disabler: + type: bool + since: 0.59.0 + description: Returns a [[@disabler]] object when not found. diff --git a/docs/yaml/functions/include_directories.yaml b/docs/yaml/functions/include_directories.yaml new file mode 100644 index 0000000..77faeb4 --- /dev/null +++ b/docs/yaml/functions/include_directories.yaml @@ -0,0 +1,72 @@ +name: include_directories +returns: inc +description: | + Returns an opaque object which contains the directories (relative to + the current directory) given in the positional arguments. The result + can then be passed to the `include_directories:` keyword argument when + building executables or libraries. You can use the returned object in + any subdirectory you want, Meson will make the paths work + automatically. + + Note that this function call itself does not add the directories into + the search path, since there is no global search path. For something + like that, see [`add_project_arguments()`](#add_project_arguments). + + See also `implicit_include_directories` parameter of + [[executable]], which adds current source and build + directories to include path. + + Each directory given is converted to two include paths: one that is + relative to the source root and one relative to the build root. + +example: | + For example, with the following source tree layout in + `/home/user/project.git`: + + `meson.build`: + ```meson + project(...) + + subdir('include') + subdir('src') + + ... + ``` + + `include/meson.build`: + ```meson + inc = include_directories('.') + + ... + ``` + + `src/meson.build`: + ```meson + sources = [...] + + executable('some-tool', sources, + include_directories : inc, + ...) + + ... + ``` + + If the build tree is `/tmp/build-tree`, the following include paths + will be added to the `executable()` call: `-I/tmp/build-tree/include + -I/home/user/project.git/include`. + +varargs: + name: includes + type: str + description: Include paths to add. + +kwargs: + is_system: + type: bool + default: false + description: | + If set to `true`, flags the specified directories as system directories. + This means that + they will be used with the `-isystem` compiler argument rather than + `-I` on compilers that support this flag (in practice everything + except Visual Studio). diff --git a/docs/yaml/functions/install_data.yaml b/docs/yaml/functions/install_data.yaml new file mode 100644 index 0000000..3bb9802 --- /dev/null +++ b/docs/yaml/functions/install_data.yaml @@ -0,0 +1,57 @@ +name: install_data +returns: void +description: | + Installs files from the source tree that are listed as positional arguments. + + See [Installing](Installing.md) for more examples. + +varargs: + name: file + type: file | str + description: Files to install. + +kwargs: + install_dir: + type: str + description: | + The absolute or relative path to the installation directory. + If this is a relative path, it is assumed to be relative to the prefix. + + If omitted, the directory defaults to `{datadir}/{projectname}` *(since 0.45.0)*. + + install_mode: + type: list[str | int] + since: 0.38.0 + description: | + specify the file mode in symbolic format and + optionally the owner/uid and group/gid for the installed files. For + example: + + `install_mode: 'rw-r--r--'` for just the file mode + + `install_mode: ['rw-r--r--', 'nobody', 'nogroup']` for the file mode and the user/group + + `install_mode: ['rw-r-----', 0, 0]` for the file mode and uid/gid + + To leave any of these three as the default, specify `false`. + + install_tag: + type: str + since: 0.60.0 + description: | + A string used by the `meson install --tags` command + to install only a subset of the files. By default these files have no install + tag which means they are not being installed when `--tags` argument is specified. + + rename: + type: list[str] + since: 0.46.0 + description: | + If specified renames each source file into corresponding file from `rename` list. + Nested paths are allowed and they are + joined with `install_dir`. Length of `rename` list must be equal to + the number of sources. + + sources: + type: list[file | str] + description: Additional files to install. diff --git a/docs/yaml/functions/install_headers.yaml b/docs/yaml/functions/install_headers.yaml new file mode 100644 index 0000000..8dc8205 --- /dev/null +++ b/docs/yaml/functions/install_headers.yaml @@ -0,0 +1,53 @@ +name: install_headers +returns: void +description: | + Installs the specified header files from the source tree into the + system header directory (usually `/{prefix}/include`) during the + install step. This directory can be overridden by specifying it with + the `install_dir` keyword argument. If you just want to install into a + subdirectory of the system header directory, then use the `subdir` + argument. As an example if this has the value `myproj` then the + headers would be installed to `/{prefix}/include/myproj`. + +example: | + For example, this will install `common.h` and `kola.h` into + `/{prefix}/include`: + + ```meson + install_headers('common.h', 'proj/kola.h') + ``` + + This will install `common.h` and `kola.h` into `/{prefix}/include/myproj`: + + ```meson + install_headers('common.h', 'proj/kola.h', subdir : 'myproj') + ``` + + This will install `common.h` and `kola.h` into `/{prefix}/cust/myproj`: + + ```meson + install_headers('common.h', 'proj/kola.h', install_dir : 'cust', subdir : 'myproj') + ``` + +varargs: + name: file + type: file | str + description: Header files to install. + +kwargs: + install_dir: + type: str + description: Where to install to + + subdir: + type: str + description: Use the `subdir` in the `install_dir` + + install_mode: + type: list[str | int] + since: 0.47.0 + description: | + Specify the file mode in symbolic format + and optionally the owner/uid and group/gid for the installed files. + + See the `install_mode` kwarg of [[install_data]] for more information. diff --git a/docs/yaml/functions/install_man.yaml b/docs/yaml/functions/install_man.yaml new file mode 100644 index 0000000..b695dc1 --- /dev/null +++ b/docs/yaml/functions/install_man.yaml @@ -0,0 +1,40 @@ +name: install_man +returns: void +description: | + Installs the specified man files from the source tree into system's man directory + during the install step. This directory can be + overridden by specifying it with the `install_dir` keyword argument. + + *(since 0.49.0)* [manpages are no longer compressed implicitly][install_man_49]. + + [install_man_49]: + https://mesonbuild.com/Release-notes-for-0-49-0.html#manpages-are-no-longer-compressed-implicitly + +varargs: + name: file + type: file | str + description: Man pages to install. + +kwargs: + install_mode: + type: list[str | int] + since: 0.47.0 + description: | + Specify the file mode in symbolic format + and optionally the owner/uid and group/gid for the installed files. + + See the `install_mode` kwarg of [[install_data]] for more information. + + install_dir: + type: str + description: Where to install to. + + locale: + type: str + since: 0.58.0 + description: | + Can be used to specify the locale + into which the + man page will be installed within the manual page directory tree. + An example manual might be `foo.fr.1` with a locale of `fr`, such + that `{mandir}/{locale}/man{num}/foo.1` becomes the installed file. diff --git a/docs/yaml/functions/install_subdir.yaml b/docs/yaml/functions/install_subdir.yaml new file mode 100644 index 0000000..83df782 --- /dev/null +++ b/docs/yaml/functions/install_subdir.yaml @@ -0,0 +1,102 @@ +name: install_subdir +returns: void +description: | + Installs the entire given subdirectory and its contents from the + source tree to the location specified by the keyword argument + `install_dir`. + + If the subdirectory does not exist in the source tree, an empty directory is + created in the specified location. *(since 0.45.0)* A newly created + subdirectory may only be created in the keyword argument `install_dir`. + +example: | + For a given directory `foo`: + ```text + foo/ + bar/ + file1 + file2 + ``` + `install_subdir('foo', install_dir : 'share', strip_directory : false)` creates + ```text + share/ + foo/ + bar/ + file1 + file2 + ``` + + `install_subdir('foo', install_dir : 'share', strip_directory : true)` creates + ```text + share/ + bar/ + file1 + file2 + ``` + + `install_subdir('foo/bar', install_dir : 'share', strip_directory : false)` creates + ```text + share/ + bar/ + file1 + ``` + + `install_subdir('foo/bar', install_dir : 'share', strip_directory : true)` creates + ```text + share/ + file1 + ``` + + `install_subdir('new_directory', install_dir : 'share')` creates + ```text + share/ + new_directory/ + ``` + +posargs: + subdir_name: + type: str + description: The sub-directory to install + +kwargs: + install_mode: + type: list[str | int] + since: 0.47.0 + description: | + Specify the file mode in symbolic format + and optionally the owner/uid and group/gid for the installed files. + + See the `install_mode` kwarg of [[install_data]] for more information. + + install_tag: + type: str + since: 0.60.0 + description: | + A string used by the `meson install --tags` command + to install only a subset of the files. By default these files have no install + tag which means they are not being installed when `--tags` argument is specified. + + exclude_files: + type: list[str] + description: | + A list of file names that should not be installed. + Names are interpreted as paths relative to the `subdir_name` location. + + exclude_directories: + type: list[str] + since: 0.47.0 + description: | + A list of directory names that should not be installed. + Names are interpreted as paths relative to the `subdir_name` location. + + install_dir: + type: str + description: Where to install to. + + strip_directory: + type: bool + since: 0.45.0 + default: false + description: | + Install directory contents. + If `strip_directory=true` only the last component of the source path is used. diff --git a/docs/yaml/functions/is_disabler.yaml b/docs/yaml/functions/is_disabler.yaml new file mode 100644 index 0000000..9f1dd93 --- /dev/null +++ b/docs/yaml/functions/is_disabler.yaml @@ -0,0 +1,9 @@ +name: is_disabler +returns: bool +since: 0.52.0 +description: Returns true if a variable is a disabler and false otherwise. + +posargs: + var: + type: any + description: The varaible to test diff --git a/docs/yaml/functions/is_variable.yaml b/docs/yaml/functions/is_variable.yaml new file mode 100644 index 0000000..6c338ee --- /dev/null +++ b/docs/yaml/functions/is_variable.yaml @@ -0,0 +1,9 @@ +name: is_variable +returns: bool +since: 0.52.0 +description: Returns true if a variable of the given name exists and false otherwise. + +posargs: + var: + type: str + description: The varaible to test diff --git a/docs/yaml/functions/jar.yaml b/docs/yaml/functions/jar.yaml new file mode 100644 index 0000000..6e8e5dd --- /dev/null +++ b/docs/yaml/functions/jar.yaml @@ -0,0 +1,16 @@ +name: jar +returns: jar +description: | + Build a jar from the specified Java source files. Keyword arguments + are the same as [[executable]]'s, with the addition of + `main_class` which specifies the main class to execute when running + the jar with `java -jar file.jar`. + +posargs_inherit: _build_target_base +varargs_inherit: _build_target_base +kwargs_inherit: _build_target_base + +kwargs: + main_class: + type: str + description: Main class for running the built jar diff --git a/docs/yaml/functions/join_paths.yaml b/docs/yaml/functions/join_paths.yaml new file mode 100644 index 0000000..f0cef0c --- /dev/null +++ b/docs/yaml/functions/join_paths.yaml @@ -0,0 +1,26 @@ +name: join_paths +returns: str +since: 0.36.0 +description: | + Joins the given strings into a file system path segment. For example + `join_paths('foo', 'bar')` results in `foo/bar`. If any one of the + individual segments is an absolute path, all segments before it are + dropped. That means that `join_paths('foo', '/bar')` returns `/bar`. + + *(since 0.49.0)* Using the `/` operator on strings is equivalent to calling + [[join_paths]]. + + ```meson + # res1 and res2 will have identical values + res1 = join_paths(foo, bar) + res2 = foo / bar + ``` + +warnings: + - Don't use [[join_paths]] for sources in [[library]] and [[executable]]. You should use [[files]] instead. + +varargs: + name: part + type: str + description: The path parts to join. + min_varargs: 1 diff --git a/docs/yaml/functions/library.yaml b/docs/yaml/functions/library.yaml new file mode 100644 index 0000000..f10ef8e --- /dev/null +++ b/docs/yaml/functions/library.yaml @@ -0,0 +1,23 @@ +name: library +returns: lib +description: | + Builds a library that is either static, shared or both depending on + the value of `default_library` + user [option](https://mesonbuild.com/Builtin-options.html). + You should use this instead of [[shared_library]], + [[static_library]] or + [[both_libraries]] most of the time. This allows you + to toggle your entire project (including subprojects) from shared to + static with only one option. This option applies to libraries being + built internal to the entire project. For external dependencies, the + default library type preferred is shared. This can be adapted on a per + library basis using the [[dependency]] `static` keyword. + + The keyword arguments for this are the same as for + [[build_target]] + +posargs_inherit: _build_target_base +varargs_inherit: _build_target_base +kwargs_inherit: + - shared_library + - static_library diff --git a/docs/yaml/functions/message.yaml b/docs/yaml/functions/message.yaml new file mode 100644 index 0000000..2adf819 --- /dev/null +++ b/docs/yaml/functions/message.yaml @@ -0,0 +1,14 @@ +name: message +returns: void +description: This function prints its argument to stdout. + +posargs: + text: + type: str + description: The message to print + +varargs: + name: more_text + since: 0.54.0 + type: str + description: Additional text that will be printed seperated by spaces. diff --git a/docs/yaml/functions/project.yaml b/docs/yaml/functions/project.yaml new file mode 100644 index 0000000..801ce8a --- /dev/null +++ b/docs/yaml/functions/project.yaml @@ -0,0 +1,90 @@ +name: project +returns: void +description: | + The first function called in each project, to initialize Meson. + + The first argument to this function must be a string defining the name + of this project. + + The project name can be any string you want, it's not used for + anything except descriptive purposes. However since it is written to + e.g. the dependency manifest is usually makes sense to have it be the + same as the project tarball or pkg-config name. So for example you + would probably want to use the name _libfoobar_ instead of _The Foobar + Library_. + + It may be followed by the list of programming languages that the project uses. + + *(since 0.40.0)* The list of languages is optional. + + These languages may be used both for `native: false` (the default) + (host machine) targets and for `native: true` (build machine) targets. + *(since 0.56.0)* The build machine compilers for the specified + languages are not required. + + Supported values for languages are `c`, `cpp` (for `C++`), `cuda`, `d`, + `objc`, `objcpp`, `fortran`, `java`, `cs` (for `C#`), `vala` and `rust`. + +posargs: + project_name: + type: str + description: The name of the project. + +varargs: + name: language + type: str + description: The languages that Meson should initialize. + +kwargs: + default_options: + type: list[str] + description: | + Accecpts strings in the form `key=value` + which have the same format as options to `meson configure`. + For example to set the default project type you would + set this: `default_options : ['buildtype=debugoptimized']`. Note + that these settings are only used when running Meson for the first + time. Global options such as `buildtype` can only be specified in + the master project, settings in subprojects are ignored. Project + specific options are used normally even in subprojects. + + version: + type: str | file + description: | + A free form string describing the version of this project. + You can access the value in your Meson build files + with [[meson.project_version]]. *(Since 0.57.0)* this can also be a + [[@file]] object pointing to a file that contains exactly one line of + text. + + meson_version: + type: str + description: | + Takes a string describing which Meson version the project requires. + Usually something like `>=0.28.0`. + + license: + type: str | list[str] + description: | + Takes a string or array of strings describing the license(s) the code is under. + To avoid ambiguity it is recommended to use a standardized + license identifier from the [SPDX license list](https://spdx.org/licenses/). + Usually this would be something like `license : 'GPL-2.0-or-later'`, but if + the code has multiple licenses you can specify them as an array like this: + `license : ['proprietary', 'GPL-3.0-only']`. Note that the text is informal + and is only written to the dependency manifest. Meson does not do any license + validation, you are responsible for verifying that you abide by all licensing + terms. You can access the value in your Meson build files with + `meson.project_license()`. + + subproject_dir: + type: str + default: "'subprojects'" + description: | + Specifies the top level directory name that holds Meson subprojects. + This is only meant as a compatibility option + for existing code bases that house their embedded source code in a + custom directory. All new projects should not set this but instead + use the default value. It should be noted that this keyword + argument is ignored inside subprojects. There can be only one + subproject dir and it is set in the top level Meson file. diff --git a/docs/yaml/functions/range.yaml b/docs/yaml/functions/range.yaml new file mode 100644 index 0000000..4d9a19a --- /dev/null +++ b/docs/yaml/functions/range.yaml @@ -0,0 +1,44 @@ +name: range +returns: range +since: 0.58.0 +description: | + Return an opaque object that can be only be used in `foreach` statements. + + <pre><code class="language-meson">[[@range]] range([[@int]] <b>stop</b>) + [[@range]] range([[@int]] <b>start</b>, [[@int]] <b>stop</b>[, [[@int]] <b>step</b>])</code></pre> + + - `start` must be integer greater or equal to 0. Defaults to 0. + - `stop` must be integer greater or equal to `start`. + - `step` must be integer greater or equal to 1. Defaults to 1. + + It cause the `foreach` loop to be called with the value from `start` included + to `stop` excluded with an increment of `step` after each loop. + +example: | + ```meson + # Loop 15 times with i from 0 to 14 included. + foreach i : range(15) + ... + endforeach + ``` + + The range object can also be assigned to a variable and indexed. + ```meson + r = range(5, 10, 2) + assert(r[2] == 9) + ``` + +optargs: + start: + type: int + default: 0 + description: The start of the range + + stop: + type: int + description: The end of the range + + step: + type: int + default: 1 + description: The loop increment diff --git a/docs/yaml/functions/run_command.yaml b/docs/yaml/functions/run_command.yaml new file mode 100644 index 0000000..091c030 --- /dev/null +++ b/docs/yaml/functions/run_command.yaml @@ -0,0 +1,39 @@ +name: run_command +returns: runresult +description: | + Runs the command specified in positional arguments. `command` can be a + string, or the output of [[find_program]], + [[files]] or [[configure_file]], or [a + compiler object](#compiler-object). + + Returns a [[@runresult]] object containing the result + of the invocation. The command is run from an *unspecified* directory, + and Meson will set three environment variables `MESON_SOURCE_ROOT`, + `MESON_BUILD_ROOT` and `MESON_SUBDIR` that specify the source + directory, build directory and subdirectory the target was defined in, + respectively. + + See also [External commands](External-commands.md). + +varargs: + name: command + type: str | file | external_program + description: The command to execute during the setup process. + +kwargs: + check: + type: bool + since: 0.47.0 + default: false + description: | + If `true`, the exit status code of the command will be checked, + and the configuration will fail if it is non-zero. + + env: + type: env | list[str] | dict[str] + since: 0.50.0 + description: | + environment variables to set, + such as `['NAME1=value1', 'NAME2=value2']`, + or an [[@env]] object which allows more sophisticated + environment juggling. *(Since 0.52.0)* A dictionary is also accepted. diff --git a/docs/yaml/functions/run_target.yaml b/docs/yaml/functions/run_target.yaml new file mode 100644 index 0000000..9aecc31 --- /dev/null +++ b/docs/yaml/functions/run_target.yaml @@ -0,0 +1,55 @@ +name: run_target +returns: run_tgt +description: | + This function creates a new top-level target that runs a specified + command with the specified arguments. Like all top-level targets, this + integrates with the selected backend. For instance, you can run it as + `meson compile target_name`. Note that a run target produces no output + as far as Meson is concerned. It is only meant for tasks such as + running a code formatter or flashing an external device's firmware + with a built file. + + The command is run from an *unspecified* directory, and Meson will set + three environment variables `MESON_SOURCE_ROOT`, `MESON_BUILD_ROOT` + and `MESON_SUBDIR` that specify the source directory, build directory + and subdirectory the target was defined in, respectively. + + *Since 0.57.0* The template strings passed to `command` keyword arguments accept + the following special substitutions: + - `@SOURCE_ROOT@`: the path to the root of the source tree. Depending on the backend, + this may be an absolute or a relative to current workdir path. + - `@BUILD_ROOT@`: the path to the root of the build tree. Depending on the backend, + this may be an absolute or a relative to current workdir path. + - `@CURRENT_SOURCE_DIR@` *Since 0.57.1*: this is the directory where the currently + processed meson.build is located in. Depending on the backend, + this may be an absolute or a relative to current workdir path. + +posargs: + target_name: + type: str + description: The name of the run target + +kwargs: + command: + type: list[exe| external_program | custom_tgt | file | str] + description: | + A list containing the command to run and the arguments + to pass to it. Each list item may be a string or a target. For + instance, passing the return value of [[executable]] + as the first item will run that executable, or passing a string as + the first item will find that command in `PATH` and run it. + + depends: + type: list[tgt] + description: | + A list of targets that this target depends on but which + are not listed in the command array (because, for example, the + script does file globbing internally) + + env: + since: 0.57.0 + type: env | list[str] | dict[str] + description: | + environment variables to set, such as + `{'NAME1': 'value1', 'NAME2': 'value2'}` or `['NAME1=value1', 'NAME2=value2']`, + or an [[@env]] object which allows more sophisticated environment juggling. diff --git a/docs/yaml/functions/set_variable.yaml b/docs/yaml/functions/set_variable.yaml new file mode 100644 index 0000000..19dc2e1 --- /dev/null +++ b/docs/yaml/functions/set_variable.yaml @@ -0,0 +1,16 @@ +name: set_variable +returns: void +description: | + Assigns a value to the given variable name. Calling + `set_variable('foo', bar)` is equivalent to `foo = bar`. + + *(since 0.46.1)* The `value` parameter can be an array type. + +posargs: + variable_name: + type: str + description: The name of the variable to set + + value: + type: any + description: The value to set the variable to diff --git a/docs/yaml/functions/shared_library.yaml b/docs/yaml/functions/shared_library.yaml new file mode 100644 index 0000000..46e5a1c --- /dev/null +++ b/docs/yaml/functions/shared_library.yaml @@ -0,0 +1,53 @@ +name: shared_library +returns: lib +description: Builds a shared library with the given sources. + +notes: + - | + Linking to a shared module is not supported on some + platforms, notably OSX. Consider using a + [[shared_library]] instead, if you need to both + `dlopen()` and link with a library. + +posargs_inherit: _build_target_base +varargs_inherit: _build_target_base +kwargs_inherit: _build_target_base + +kwargs: + version: + type: str + description: | + A string specifying the version of this shared library, + such as `1.1.0`. On Linux and OS X, this is used to set the shared + library version in the filename, such as `libfoo.so.1.1.0` and + `libfoo.1.1.0.dylib`. If this is not specified, `soversion` is used + instead (see above). + + soversion: + type: str + description: | + A string specifying the soversion of this shared library, + such as `0`. On Linux and Windows this is used to set the + soversion (or equivalent) in the filename. For example, if + `soversion` is `4`, a Windows DLL will be called `foo-4.dll` and one + of the aliases of the Linux shared library would be + `libfoo.so.4`. If this is not specified, the first part of `version` + is used instead (see below). For example, if `version` is `3.6.0` and + `soversion` is not defined, it is set to `3`. + + darwin_versions: + type: str | int | list[str] + since: 0.48.0 + description: | + Defines the `compatibility version` and `current version` for the dylib on macOS. + If a list is specified, it must be + either zero, one, or two elements. If only one element is specified + or if it's not a list, the specified value will be used for setting + both compatibility version and current version. If unspecified, the + `soversion` will be used as per the aforementioned rules. + + vs_module_defs: + type: str | file | custom_tgt | custom_idx + description: | + Specify a Microsoft module definition file for controlling symbol exports, + etc., on platforms where that is possible (e.g. Windows). diff --git a/docs/yaml/functions/shared_module.yaml b/docs/yaml/functions/shared_module.yaml new file mode 100644 index 0000000..8909c2f --- /dev/null +++ b/docs/yaml/functions/shared_module.yaml @@ -0,0 +1,26 @@ +name: shared_module +returns: build_tgt +since: 0.37.0 +description: | + Builds a shared module with the given sources. + + This is useful for building modules that will be `dlopen()`ed and + hence may contain undefined symbols that will be provided by the + library that is loading it. + + If you want the shared module to be able to refer to functions and + variables defined in the [[executable]] it is loaded by, + you will need to set the `export_dynamic` argument of the executable to + `true`. + +posargs_inherit: _build_target_base +varargs_inherit: _build_target_base +kwargs_inherit: _build_target_base + +kwargs: + vs_module_defs: + type: str | file | custom_tgt | custom_idx + since: 0.52.0 + description: | + Specify a Microsoft module definition file for controlling symbol exports, + etc., on platforms where that is possible (e.g. Windows). diff --git a/docs/yaml/functions/static_library.yaml b/docs/yaml/functions/static_library.yaml new file mode 100644 index 0000000..1d42d60 --- /dev/null +++ b/docs/yaml/functions/static_library.yaml @@ -0,0 +1,25 @@ +name: static_library +returns: lib +description: Builds a static library with the given sources. + +posargs_inherit: _build_target_base +varargs_inherit: _build_target_base +kwargs_inherit: _build_target_base + +kwargs: + pic: + type: bool + since: 0.36.0 + description: | + Builds the library as positional independent code + (so it can be linked into a shared library). This + option has no effect on Windows and OS X since it doesn't make + sense on Windows and PIC cannot be disabled on OS X. + + prelink: + type: bool + since: 0.57.0 + description: | + If `true` the object files in the target will be prelinked, + meaning that it will contain only one prelinked + object file rather than the individual object files. diff --git a/docs/yaml/functions/subdir.yaml b/docs/yaml/functions/subdir.yaml new file mode 100644 index 0000000..694fa51 --- /dev/null +++ b/docs/yaml/functions/subdir.yaml @@ -0,0 +1,23 @@ +name: subdir +returns: void +description: | + Enters the specified subdirectory and executes the `meson.build` file in it. + Once that is done, it returns and execution continues on the + line following this `subdir()` command. Variables defined in that + `meson.build` file are then available for use in later parts of the + current build file and in all subsequent build files executed with + `subdir()`. + + Note that this means that each `meson.build` file in a source tree can + and must only be executed once. + +posargs: + dir_name: + type: str + description: Directory relative to the current `meson.build` to enter. + +kwargs: + if_found: + type: list[dep] + since: 0.44.0 + description: Only enter the subdir if all [[dep.found]] methods return `true`. diff --git a/docs/yaml/functions/subdir_done.yaml b/docs/yaml/functions/subdir_done.yaml new file mode 100644 index 0000000..ef878cc --- /dev/null +++ b/docs/yaml/functions/subdir_done.yaml @@ -0,0 +1,23 @@ +name: subdir_done +returns: void +description: | + Stops further interpretation of the Meson script file from the point + of the invocation. All steps executed up to this point are valid and + will be executed by Meson. This means that all targets defined before + the call of [[subdir_done]] will be build. + + If the current script was called by `subdir` the execution returns to + the calling directory and continues as if the script had reached the + end. If the current script is the top level script Meson configures + the project as defined up to this point. + +example: | + ```meson + project('example exit', 'cpp') + executable('exe1', 'exe1.cpp') + subdir_done() + executable('exe2', 'exe2.cpp') + ``` + + The executable `exe1` will be build, while the executable `exe2` is not + build. diff --git a/docs/yaml/functions/subproject.yaml b/docs/yaml/functions/subproject.yaml new file mode 100644 index 0000000..e5d732b --- /dev/null +++ b/docs/yaml/functions/subproject.yaml @@ -0,0 +1,68 @@ +name: subproject +returns: subproject +description: | + Takes the project specified in the positional argument and brings that + in the current build specification by returning a [[@subproject]] object. + Subprojects must always be placed inside + the `subprojects` directory at the top source directory. So for + example a subproject called `foo` must be located in + `${MESON_SOURCE_ROOT}/subprojects/foo`. + + - `default_options` *(since 0.37.0)*: an array of default option values + that override those set in the subproject's `meson_options.txt` + (like `default_options` in `project`, they only have effect when + Meson is run for the first time, and command line arguments override + any default options in build files). *(since 0.54.0)*: `default_library` + built-in option can also be overridden. + - `version`: works just like the same as in `dependency`. + It specifies what version the subproject should be, as an example `>=1.0.1` + - `required` *(since 0.48.0)*: By default, `required` is `true` and + Meson will abort if the subproject could not be setup. You can set + this to `false` and then use the `.found()` method on the [[@subproject]] + object. You may also pass the value of a + [`feature`](Build-options.md#features) option, same as + [[dependency]]. + + Note that you can use the returned [[@subproject]] object + to access any variable in the + subproject. However, if you want to use a dependency object from + inside a subproject, an easier way is to use the `fallback:` keyword + argument to [[dependency]]. + + [See additional documentation](Subprojects.md). + +posargs: + subproject_name: + type: str + description: | + Name of the subproject. The subproject must exist in the `subprojects` + directory (or the directory specified in the `subproject_dir` of + [[project]]) as a directory or wrap file. + +kwargs: + default_options: + type: list[str] + since: 0.37.0 + description: | + An array of default option values + that override those set in the subproject's `meson_options.txt` + (like `default_options` in [[project]], they only have effect when + Meson is run for the first time, and command line arguments override + any default options in build files). *(since 0.54.0)*: `default_library` + built-in option can also be overridden. + + version: + type: str + description: | + Works just like the same as in [[dependency]]. + It specifies what version the subproject should be, as an example `>=1.0.1`. + + required: + type: bool | feature + since: 0.48.0 + default: true + description: | + If `true`, Meson will abort if the subproject could not be setup. You can set + this to `false` and then use the `.found()` method on the [[@subproject]] object. + You may also pass the value of a + [`feature`](Build-options.md#features) option, same as [[dependency]]. diff --git a/docs/yaml/functions/summary.yaml b/docs/yaml/functions/summary.yaml new file mode 100644 index 0000000..3e7d463 --- /dev/null +++ b/docs/yaml/functions/summary.yaml @@ -0,0 +1,71 @@ +name: summary +returns: void +since: 0.53.0 +description: | + This function is used to summarize build configuration at the end of the build + process. This function provides a way for projects (and subprojects) to report + this information in a clear way. + + The content is a series of key/value pairs grouped into sections. If + the section keyword argument is omitted, those key/value pairs are + implicitly grouped into a section with no title. key/value pairs can + optionally be grouped into a dictionary, but keep in mind that + dictionaries does not guarantee ordering. `key` must be string, + `value` can be: + + - an integer, boolean or string + - *since 0.57.0* an external program or a dependency + - *since 0.58.0* a feature option + - a list of those. + + Instead of calling summary as `summary(key, value)`, it is also possible to + directly pass a dictionary to the [[summary]] function, as seen in the example + below. + + `summary()` can be called multiple times as long as the same + section/key pair doesn't appear twice. All sections will be collected + and printed at the end of the configuration in the same order as they + have been called. + +example: | + Example `meson.build`: + ```meson + project('My Project', version : '1.0') + summary({'bindir': get_option('bindir'), + 'libdir': get_option('libdir'), + 'datadir': get_option('datadir'), + }, section: 'Directories') + summary({'Some boolean': false, + 'Another boolean': true, + 'Some string': 'Hello World', + 'A list': ['string', 1, true], + }, section: 'Configuration') + ``` + + Output: + ``` + My Project 1.0 + + Directories + prefix : /opt/gnome + bindir : bin + libdir : lib/x86_64-linux-gnu + datadir : share + + Configuration + Some boolean : False + Another boolean: True + Some string : Hello World + A list : string + 1 + True + ``` + +posargs: + key: + type: str + description: The name of the new entry + + value: + type: str | bool | int | dep | external_program | list[str | bool | int | dep | external_program] + description: The value to print for the `key` diff --git a/docs/yaml/functions/test.yaml b/docs/yaml/functions/test.yaml new file mode 100644 index 0000000..96a2b28 --- /dev/null +++ b/docs/yaml/functions/test.yaml @@ -0,0 +1,49 @@ +name: test +returns: void +description: | + Defines a test to run with the test harness. Takes two positional + arguments, the first is the name of the test and the second is the + executable to run. The executable can be an [[@exe]] object returned by + [[executable]] or an [[@external_program]] object] returned by + [[find_program]]. + + *(since 0.55.0)* When cross compiling, if an exe_wrapper is needed and + defined the environment variable `MESON_EXE_WRAPPER` will be set to + the string value of that wrapper (implementation detail: using + `mesonlib.join_args`). Test scripts may use this to run cross built + binaries. If your test needs `MESON_EXE_WRAPPER` in cross build + situations it is your responsibility to return code 77 to tell the + harness to report "skip". + + By default, environment variable + [`MALLOC_PERTURB_`](http://man7.org/linux/man-pages/man3/mallopt.3.html) + is automatically set by `meson test` to a random value between 1..255. + This can help find memory leaks on configurations using glibc, + including with non-GCC compilers. However, this can have a performance + impact, and may fail a test due to external libraries whose internals + are out of the user's control. To check if this feature is causing an + expected runtime crash, disable the feature by temporarily setting + environment variable `MALLOC_PERTURB_=0`. While it's preferable to + only temporarily disable this check, if a project requires permanent + disabling of this check in meson.build do like: + + ```meson + nomalloc = environment({'MALLOC_PERTURB_': '0'}) + + test(..., env: nomalloc, ...) + ``` + + Defined tests can be run in a backend-agnostic way by calling + `meson test` inside the build dir, or by using backend-specific + commands, such as `ninja test` or `msbuild RUN_TESTS.vcxproj`. + +posargs_inherit: benchmark +kwargs_inherit: benchmark + +kwargs: + is_parallel: + type: bool + default: false + description: | + when false, specifies that no other test must be + running at the same time as this test diff --git a/docs/yaml/functions/unset_variable.yaml b/docs/yaml/functions/unset_variable.yaml new file mode 100644 index 0000000..6231afe --- /dev/null +++ b/docs/yaml/functions/unset_variable.yaml @@ -0,0 +1,11 @@ +name: unset_variable +returns: void +since: 0.60.0 +description: | + Unsets a variable. + Referencing a variable which has been unset is an error until it has been set again. + +posargs: + varname: + type: str + description: The variable to unset. diff --git a/docs/yaml/functions/vcs_tag.yaml b/docs/yaml/functions/vcs_tag.yaml new file mode 100644 index 0000000..3d4a1c4 --- /dev/null +++ b/docs/yaml/functions/vcs_tag.yaml @@ -0,0 +1,53 @@ +name: vcs_tag +returns: custom_tgt +description: | + This command detects revision control commit information at build time + and places it in the specified output file. This file is guaranteed to + be up to date on every build. Keywords are similar to [[custom_target]]. + + Meson will read the contents of `input`, substitute the + `replace_string` with the detected revision number, and write the + result to `output`. This method returns a + [[@custom_tgt]] object that (as usual) should be + used to signal dependencies if other targets use the file outputted + by this. + + For example, if you generate a header with this and want to use that + in a build target, you must add the return value to the sources of + that build target. Without that, Meson will not know the order in + which to build the targets. + + If you desire more specific behavior than what this command provides, + you should use [[custom_target]]. + +kwargs: + command: + type: list[str] + description: | + The command to execute, see [[custom_target]] for details + on how this command must be specified. + + This parameter is optional. If it is absent, Meson will try + its best to find a suitable default command. + + input: + type: str + required: true + description: File to modify (e.g. `version.c.in`). + + output: + type: str + required: true + description: File to write the results to (e.g. `version.c`). + + fallback: + type: str + default: "[[meson.project_version]]" + description: | + Version number to use when no revision control information is present, + such as when building from a release tarball. + + replace_string: + type: str + default: "'@VCS_TAG@'" + description: String in the input file to substitute with the commit information. diff --git a/docs/yaml/functions/warning.yaml b/docs/yaml/functions/warning.yaml new file mode 100644 index 0000000..f4bb0ec --- /dev/null +++ b/docs/yaml/functions/warning.yaml @@ -0,0 +1,7 @@ +name: warning +returns: void +since: 0.44.0 +description: This function prints its argument to stdout prefixed with WARNING:. + +posargs_inherit: message +varargs_inherit: message diff --git a/docs/yaml/modules/cmake/module.yaml b/docs/yaml/modules/cmake/module.yaml new file mode 100644 index 0000000..1fa5064 --- /dev/null +++ b/docs/yaml/modules/cmake/module.yaml @@ -0,0 +1,8 @@ +name: cmake +long_name: CMake module +description: The CMake module + +methods: +- name: subproject_options + description: Returns an empty `cmake_options` object. + returns: cmake_options diff --git a/docs/yaml/modules/cmake/options.yaml b/docs/yaml/modules/cmake/options.yaml new file mode 100644 index 0000000..d39132c --- /dev/null +++ b/docs/yaml/modules/cmake/options.yaml @@ -0,0 +1,14 @@ +name: cmake_options +long_name: CMake subproject options +description: Central configuration object for CMake subprojects +since: 0.55.0 + +methods: +- name: add_cmake_defines + returns: void + description: Add CMake defines (`-D<VAR>=<VAL>`) to the CMake commandline + + varargs: + name: defines + description: A `key` `value` map of CMake defines to add (`-D<key>=<val>`) + type: dict[str] diff --git a/docs/yaml/objects/alias_tgt.yaml b/docs/yaml/objects/alias_tgt.yaml new file mode 100644 index 0000000..bd36502 --- /dev/null +++ b/docs/yaml/objects/alias_tgt.yaml @@ -0,0 +1,4 @@ +name: alias_tgt +long_name: Alias target +description: Opaque object returned by [[alias_target]]. +extends: tgt diff --git a/docs/yaml/objects/both_libs.yaml b/docs/yaml/objects/both_libs.yaml new file mode 100644 index 0000000..36e5baa --- /dev/null +++ b/docs/yaml/objects/both_libs.yaml @@ -0,0 +1,14 @@ +name: both_libs +long_name: Both libraries object +extends: lib +description: Container for both a static and shared library. +since: 0.46.0 + +methods: + - name: get_shared_lib + returns: lib + description: Returns the stored shared library + + - name: get_static_lib + returns: lib + description: Returns the stored static library diff --git a/docs/yaml/objects/build_tgt.yaml b/docs/yaml/objects/build_tgt.yaml new file mode 100644 index 0000000..97c0c5d --- /dev/null +++ b/docs/yaml/objects/build_tgt.yaml @@ -0,0 +1,39 @@ +name: build_tgt +long_name: Build target +extends: tgt +description: | + A build target is either an executable, shared library, static library, + both shared and static library or shared module. + +methods: +- name: full_path + returns: str + description: | + Returns a full path pointing to the result target file. + **NOTE:** In most cases using the object itself will do the same job + as this and will also allow Meson to setup inter-target dependencies + correctly. Please file a bug if that doesn't work for you. + +- name: path + returns: str + since: 0.59.0 + deprecated: 0.59.0 + description: | + Does the exact same as [[build_tgt.full_path]]. **NOTE**: This + function is solely kept for compatebility with [[@external_program]] objects. + It will be removed once the, also deprecated, corresponding `path()` + function in the [[@external_program]] object is removed. + +- name: name + returns: str + since: 0.54.0 + description: Returns the name of the target. + +- name: found + returns: bool + since: 0.59.0 + description: | + Always returns `true`. This function is meant to make executables + objects feature compatible with [[@external_program]] objects. This + simplifies use-cases where an executable is used instead of + an [[@external_program]]. diff --git a/docs/yaml/objects/cfg_data.yaml b/docs/yaml/objects/cfg_data.yaml new file mode 100644 index 0000000..9a66b73 --- /dev/null +++ b/docs/yaml/objects/cfg_data.yaml @@ -0,0 +1,128 @@ +name: cfg_data +long_name: Configuration data object +description: | + This object encapsulates + configuration values to be used for generating configuration files. A + more in-depth description can be found in the [the configuration wiki + page](Configuration.md). + +methods: +- name: set + returns: void + description: Sets a variable to a given value + + posargs: + varname: + type: str + description: The name of the variable to set + value: + type: str | int | bool + description: The value to set + + kwargs: + description: + type: str + description: | + Message / Comment that will be written in the + result file. The replacement assumes a file with C syntax. If your + generated file is source code in some other language, you probably + don't want to add a description field because it most likely will + cause a syntax error. + +- name: set10 + returns: void + description: | + Is the same as [[cfg_data.set]] but the value + is either `true` or `false` and will be written as 1 or 0, + respectively + + posargs: + varname: + type: str + description: The name of the variable to set + value: + type: bool + description: The value to set as either `1` or `0` + + kwargs_inherit: cfg_data.set + +- name: set_quoted + returns: void + description: Is same as [[cfg_data.set]] but quotes the value in double quotes (`"`) + + posargs: + varname: + type: str + description: The name of the variable to set + value: + type: str | int | bool + description: The value to set + + kwargs_inherit: cfg_data.set + +- name: get + returns: str | int | bool + since: 0.38.0 + description: | + Returns the value of `varname`, if the + value has not been set returns `default_value` if it is defined + *(since 0.38.0)* and errors out if not + + posargs: + varname: + type: str + description: The name of the variable to query + + optargs: + default_value: + type: str | int | bool + description: The default value to return when `varname` does not exist + +- name: get_unquoted + returns: str | int | bool + since: 0.44.0 + description: | + Returns the value + of `varname` but without surrounding double quotes (`"`). If the value has + not been set returns `default_value` if it is defined and errors out if not. + + posargs: + varname: + type: str + description: The name of the variable to query + + optargs: + default_value: + type: str | int | bool + description: The default value to return when `varname` does not exist + +- name: has + returns: bool + description: returns `true` if the specified variable is set + posargs: + varname: + type: str + description: The name of the variable to query + +- name: keys + returns: list[str] + since: 0.57.0 + description: | + Returns an array of keys of + the configuration data object. + + You can iterate over this array with the [`foreach` + statement](Syntax.md#foreach-statements). + +- name: merge_from + returns: void + since: 0.42.0 + description: | + Takes as argument a different + configuration data object and copies all entries from that object to + the current. + + posargs: + other: + type: cfg_data + description: The other [[@cfg_data]] object to merge into this one. diff --git a/docs/yaml/objects/compiler.yaml b/docs/yaml/objects/compiler.yaml new file mode 100644 index 0000000..78e8ce1 --- /dev/null +++ b/docs/yaml/objects/compiler.yaml @@ -0,0 +1,548 @@ +name: compiler +long_name: Compiler object +description: | + This object is returned by [[meson.get_compiler]]. + It represents a compiler for a given language and allows you to query its properties. + +notes: +- | + These compiler checks do not use compiler arguments added + with `add_*_arguments()`, via `-Dlang_args` on the command-line, or + through `CFLAGS`/`LDFLAGS`, etc in the environment. Hence, you can + trust that the tests will be fully self-contained, and won't fail + because of custom flags added by other parts of the build file or by + users. + +- | + Note that if you have a single prefix with all your dependencies, you + might find it easier to append to the environment variables + `C_INCLUDE_PATH` with GCC/Clang and `INCLUDE` with MSVC to expand the + default include path, and `LIBRARY_PATH` with GCC/Clang and `LIB` with + MSVC to expand the default library search path. + + However, with GCC, these variables will be ignored when + cross-compiling. In that case you need to use a specs file. See: + http://www.mingw.org/wiki/SpecsFileHOWTO + +methods: + +# Helper methods to pre-define common posargs +- name: _code + returns: void + description: You have found a bug if you can see this! + posargs: + code: + type: str | file + description: | + The source code to check. + + If a string is passed, the code is used directly. If a [[@file]] object + is passed, it's content is used for the compiler check. + +# Helper methods to pre-define common kwargs +- name: _args + returns: void + description: You have found a bug if you can see this! + kwargs: + args: + type: list[str] + description: | + Used to pass a list of compiler arguments. + Defining include paths for headers not in the default include path + via `-Isome/path/to/header` is generally supported, however, usually not + recommended. + + This is because include directories can also be specified via the + `include_directories` or the `dependency` kwarg (if present). + The same is also true for passing libraries to link with `-lfoo`. + +- name: _include_directories + returns: void + description: You have found a bug if you can see this! + kwargs: + include_directories: + type: inc | list[inc] + since: 0.38.0 + description: Extra directories for header searches. + +- name: _dependencies + returns: void + description: You have found a bug if you can see this! + kwargs: + dependencies: + type: dep | list[dep] + description: Additionally dependencies required for compiling and / or linking. + +- name: _prefix + returns: void + description: You have found a bug if you can see this! + kwargs: + prefix: + type: str + description: | + Used to add `#include`s and other things that are required + for the symbol to be declared. System definitions should be + passed via compiler args (eg: `_GNU_SOURCE` is often required for + some symbols to be exposed on Linux, and it should be passed via + `args` keyword argument). + +- name: _no_builtin_args + returns: void + description: You have found a bug if you can see this! + kwargs: + no_builtin_args: + type: bool + default: false + description: When set to `true`, the compiler arguments controlled by built-in configuration options are not added. + +- name: _name + returns: void + description: You have found a bug if you can see this! + kwargs: + name: + type: str + description: | + The name to use for printing a message about the compiler check. + If this keyword argument is not passed, no message will be printed about the check. + +# Even more convinient +- name: _common + returns: void + description: You have found a bug if you can see this! + kwargs_inherit: + - compiler._args + - compiler._include_directories + - compiler._dependencies + - compiler._no_builtin_args + - compiler._prefix + +- name: _compiles + returns: void + description: You have found a bug if you can see this! + kwargs_inherit: + - compiler._args + - compiler._include_directories + - compiler._dependencies + - compiler._no_builtin_args + - compiler._name + +- name: _header + returns: void + description: You have found a bug if you can see this! + kwargs_inherit: compiler._common + kwargs: + required: + type: bool | feature + default: false + since: 0.50.0 + description: If set to `true`, Meson will halt if the header check fails. + + +# Star of the actual functions +- name: version + returns: str + description: Returns the compiler's version number as a string. + +- name: cmd_array + returns: list[str] + description: Returns an array containing the command(s) for the compiler. + + +- name: alignment + returns: int + description: Returns the alignment of the specified type. + + posargs: + typename: + type: str + description: The name of the type to check. + + kwargs_inherit: + - compiler._args + - compiler._prefix + - compiler._dependencies + # TODO: why not also allow passing `include_directories`? + +- name: run + returns: runresult + description: Attempts to compile and execute the given code fragment. + posargs_inherit: compiler._code + kwargs_inherit: compiler._compiles + +- name: get_id + returns: str + description: | + Returns a string identifying the compiler. + For example, `gcc`, `msvc`, [and more](Reference-tables.md#compiler-ids). + +- name: get_linker_id + returns: str + since: 0.53.0 + description: | + Returns a string identifying the linker. + For example, `ld.bfd`, `link`, [and more](Reference-tables.md#linker-ids). + +- name: symbols_have_underscore_prefix + returns: bool + since: 0.37.0 + description: Returns `true` if the C symbol mangling is one underscore (`_`) prefixed to the symbol. + +- name: has_member + returns: bool + description: Returns true if the type has the specified member. + kwargs_inherit: compiler._common + posargs: + typename: + type: str + description: The type to check. + membername: + type: str + description: The member to check. + +- name: has_members + returns: bool + description: Returns `true` if the type has *all* the specified members. + kwargs_inherit: compiler._common + posargs: + typename: + type: str + description: The type to check. + varargs: + name: member + type: str + min_varargs: 1 + description: The members to check + +- name: has_function + returns: bool + description: | + Returns true if the given function is provided + by the standard library or a library passed in with the `args` keyword. + + kwargs_inherit: compiler._common + posargs: + funcname: + type: str + description: The function to check. + +- name: has_type + returns: bool + description: Returns `true` if the specified token is a type. + kwargs_inherit: compiler._common + posargs: + typename: + type: str + description: The type to check. + +- name: compute_int + returns: int + since: 0.40.0 + kwargs_inherit: compiler._common + description: | + Computes the value of the given expression + (as an example `1 + 2`). When cross compiling this is evaluated with + an iterative algorithm, you can specify keyword arguments `low` + (defaults to -1024), `high` (defaults to 1024) and `guess` to + specify max and min values for the search and the value to try + first. + + posargs: + expr: + type: str + description: The expression to compute. + + kwargs: + low: + type: int + default: -1024 + description: The min value. + high: + type: int + default: 1024 + description: The max value. + guess: + type: int + description: The value to try first. + +- name: sizeof + returns: int + description: returns the size of the given type (e.g. `'int'`) or -1 if the type is unknown. + kwargs_inherit: compiler._common + posargs: + typename: + type: str + description: The type to compute. + +- name: get_define + returns: str + since: 0.40.0 + description: | + Returns the given preprocessor symbol's value + as a string or empty string if it is not defined. + + *(since 0.47.0)* This method will concatenate string literals as + the compiler would. E.g. `"a" "b"` will become `"ab"`. + + kwargs_inherit: compiler._common + posargs: + definename: + type: str + description: The define to check. + +- name: compiles + returns: bool + description: Returns true if the code compiles. + posargs_inherit: compiler._code + kwargs_inherit: compiler._compiles + +- name: links + returns: bool + description: | + Returns true if the code compiles and links. + + *Since 0.60.0*, if the `file` object's + suffix does not match the compiler object's language, the compiler + corresponding to the suffix is used to compile the source, while the + target of the `links` method is used to link the resulting object file. + posargs_inherit: compiler._code + kwargs_inherit: compiler._compiles + +- name: check_header + returns: bool + since: 0.47.0 + description: | + Returns true if the specified header is *usable* + with the specified prefix, dependencies, and arguments. + + kwargs_inherit: compiler._header + posargs: + header_name: + type: str + description: The header to check. + +- name: has_header + returns: bool + description: | + Returns true if the specified header is *exists* + with the specified prefix, dependencies, and arguments. + + This method is faster than [[compiler.check_header]] since it only does a + pre-processor check. + + kwargs_inherit: compiler._header + posargs_inherit: compiler.check_header + +- name: has_header_symbol + returns: bool + description: | + Detects whether a particular symbol is declared in the specified header. + + Symbols here include function, variable, `#define`, type definition, etc. + + kwargs_inherit: compiler._header + posargs: + heade: + type: str + description: The header to check. + symbol: + type: str + description: The symbol to check. + +- name: find_library + returns: dep + description: Tries to find the library specified in the positional argument. + + kwargs_inherit: compiler._common + kwargs: + required: + type: bool | feature + default: true + description: | + If set `true`, Meson will abort with an error if the library could not + be found. Otherwise, Meson will continue and the found method of the + returned object will return `false`. + + *(since 0.47.0)* The value of a [`feature`](Build-options.md#features) + option can also be passed here. + + has_headers: + type: list[str] + since: 0.50.0 + description: | + List of headers that must be found as well. + This is check is equivalent to checking each herader with an + [[compiler.has_header]] call. + + static: + type: bool + default: false + since: 0.51.0 + description: | + If `true`, the search is limited to static libraries only. + Setting this value to `false` (the default) will search for both shared + *and* static libraries. + + disabler: + type: bool + default: false + since: 0.49.0 + description: If `true`, this method will return a [[@disabler]] on a failed check. + + dirs: + type: list[str] + description: | + Additional directories to search in. + + By default the library is searched for in the system library directory + (e.g. /usr/lib). Specifying more directories here, causes Meson to search + in those directories as well as the system directories. + + +# Compiler arguments +- name: has_argument + returns: bool + description: | + Returns `true` if the compiler accepts the specified command line argument, + that is, can compile code without erroring out or printing a warning about + an unknown flag. + + posargs: + argument: + type: str + description: The argument to check. + +- name: has_multi_arguments + since: 0.37.0 + returns: bool + description: | + the same as [[compiler.has_argument]] but takes multiple arguments + and uses them all in a single compiler invocation. + + varargs: + name: arg + type: str + description: The arguments to check. + +- name: get_supported_arguments + returns: list[str] + since: 0.43.0 + varargs_inherit: compiler.has_multi_arguments + description: | + Returns an array containing only the arguments supported by the compiler, + as if [[compiler.has_argument]] were called on them individually. + + kwargs: + checked: + type: str + since: 0.59.0 + default: "'off'" + description: | + Supported values: + - `'off'`: Quietely ignore unsupported arguments + - `'warn'`: Print a warning for unsupported arguments + - `'require'`: Abort if at least one argument is not supported + +- name: first_supported_argument + returns: list[str] + since: 0.43.0 + varargs_inherit: compiler.has_multi_arguments + description: | + Given a list of strings, returns the first argument that passes the + [[compiler.has_argument]] test or an empty array if none pass. + + +# Linker arguments +- name: has_link_argument + since: 0.46.0 + returns: bool + description: | + Returns `true` if the linker accepts the specified command line argument, + that is, can + compile and link code without erroring out or printing a warning + about an unknown flag. Link arguments will be passed to the + compiler, so should usually have the `-Wl,` prefix. On VisualStudio + a `/link` argument will be prepended. + + posargs: + argument: + type: str + description: The argument to check. + +- name: has_multi_link_arguments + since: 0.46.0 + returns: bool + description: | + the same as [[compiler.has_link_argument]] but takes multiple arguments + and uses them all in a single compiler invocation. + + varargs: + name: arg + type: str + description: The link arguments to check. + +- name: get_supported_link_arguments + returns: list[str] + since: 0.46.0 + varargs_inherit: compiler.has_multi_link_arguments + description: | + Returns an array containing only the arguments supported by the compiler, + as if [[compiler.has_link_argument]] were called on them individually. + + # TODO: why is this not present here? + # kwargs: + # checked: + # type: str + # sinec: 0.59.0 + # default: "'off'" + # description: | + # Supported values: + # - `'off'`: Quietely ignore unsupported arguments + # - `'warn'`: Print a warning for unsupported arguments + # - `'require'`: Abort if at least one argument is not supported + +- name: first_supported_link_argument + returns: list[str] + since: 0.46.0 + varargs_inherit: compiler.has_multi_link_arguments + description: | + Given a list of strings, returns the first argument that passes the + [[compiler.has_link_argument]] test or an empty array if none pass. + + + + + +- name: has_function_attribute + returns: bool + since: 0.48.0 + description: | + Returns `true` if the compiler supports the GNU style (`__attribute__(...)`) `name`. + This is preferable to manual compile checks as it may be optimized for compilers that + do not support such attributes. + [This table](Reference-tables.md#gcc-__attribute__) lists all of the supported attributes. + + posargs: + name: + type: str + description: The attribute nane to check. + +- name: get_supported_function_attributes + returns: list[str] + since: 0.48.0 + description: | + Returns an array containing any names that are supported GCC style attributes. + Equivalent to [[compiler.has_function_attribute]] was called on each of + them individually. + + # TODO: Again why doesn't this function have the checked kwarg? + +- name: get_argument_syntax + returns: str + since: 0.49.0 + description: | + returns a string identifying the type of arguments the compiler takes. + Can be one of `gcc`, `msvc`, or an undefined + string value. This method is useful for identifying compilers that are not + gcc or msvc, but use the same argument syntax as one of those two compilers + such as clang or icc, especially when they use different syntax on different + operating systems. diff --git a/docs/yaml/objects/custom_idx.yaml b/docs/yaml/objects/custom_idx.yaml new file mode 100644 index 0000000..68440ba --- /dev/null +++ b/docs/yaml/objects/custom_idx.yaml @@ -0,0 +1,15 @@ +name: custom_idx +long_name: Custom target index +description: References a specific output file of a [[@custom_tgt]] object. + +methods: + - name: full_path + returns: str + since: 0.54.0 + description: | + Returns a full path pointing to the result target file + NOTE: In most cases using the object itself will do the same job as + this and will also allow Meson to setup inter-target dependencies + correctly. Please file a bug if that doesn't work for you. + + See [[custom_tgt.full_path]] diff --git a/docs/yaml/objects/custom_tgt.yaml b/docs/yaml/objects/custom_tgt.yaml new file mode 100644 index 0000000..5102ab9 --- /dev/null +++ b/docs/yaml/objects/custom_tgt.yaml @@ -0,0 +1,33 @@ +name: custom_tgt +long_name: Custom target +extends: tgt +description: | + This object is returned by [[custom_target]] and contains a target with the following methods: + +methods: + - name: full_path + returns: str + description: | + Returns a full path pointing to the result target file + NOTE: In most cases using the object itself will do the same job as + this and will also allow Meson to setup inter-target dependencies + correctly. Please file a bug if that doesn't work for you. + *(since 0.54.0)* It can be also called on indexes objects: + `custom_targets[i].full_path()`. + + - name: "[index]" + returns: custom_idx + description: | + Returns an opaque object that references this target, and + can be used as a source in other targets. When it is used as such it + will make that target depend on this custom target, but the only + source added will be the one that corresponds to the index of the + custom target's output argument. + + - name: to_list + returns: list[custom_idx] + since: 0.54.0 + description: | + Returns a list of opaque objects that references this target, + and can be used as a source in other targets. This can be used to + iterate outputs with `foreach` loop. diff --git a/docs/yaml/objects/dep.yaml b/docs/yaml/objects/dep.yaml new file mode 100644 index 0000000..23092c2 --- /dev/null +++ b/docs/yaml/objects/dep.yaml @@ -0,0 +1,212 @@ +name: dep +long_name: Dependency object +description: Abstract representation of a dependency + +methods: + - name: found + returns: bool + description: Returns whether the dependency was found. + + - name: name + since: 0.48.0 + returns: str + description: | + Returns the name of the dependency that was searched. + Returns `'internal'` for dependencies created with + [[declare_dependency]]. + + - name: get_pkgconfig_variable + since: 0.36.0 + deprecated: 0.56.0 + returns: str + description: | + Gets the pkg-config variable specified, + or, if invoked on a non pkg-config + dependency, error out. + + posargs: + var_name: + type: str + description: Name of the variable to query + + kwargs: + define_variable: + type: list[str] + since: 0.44.0 + description: | + You can also redefine a + variable by passing a list to this kwarg + that can affect the retrieved variable: `['prefix', '/'])`. + + default: + type: str + since: 0.45.0 + description: | + The value to return if the variable was not found. + A warning is issued if the variable is not defined and this kwarg is not set. + + - name: get_configtool_variable + since: 0.44.0 + deprecated: 0.56.0 + returns: str + description: | + Gets the command line argument from the config tool (with `--` prepended), or, + if invoked on a non config-tool dependency, error out. + + posargs: + var_name: + type: str + description: Name of the variable to query + + - name: type_name + returns: str + description: | + Returns a string describing the type of the + dependency, the most common values are `internal` for deps created + with [[declare_dependency]] and `pkgconfig` for system dependencies + obtained with Pkg-config. + + - name: version + returns: str + description: | + the version number as a string, + for example `1.2.8`. + `unknown` if the dependency provider doesn't support determining the + version. + + - name: include_type + returns: str + since: 0.52.0 + description: Returns the value set by the `include_type` kwarg. + + - name: as_system + returns: dep + since: 0.52.0 + description: | + Returns a copy of the dependency object, which has changed the value of `include_type` + to `value`. The `value` argument is optional and + defaults to `'preserve'`. + + optargs: + value: + type: str + description: The new value. See [[dependency]] for supported values. + + - name: as_link_whole + returns: dep + since: 0.56.0 + description: | + Only dependencies created with [[declare_dependency]], + returns a copy of the dependency object with all + link_with arguments changed to link_whole. This is useful for example for + fallback dependency from a subproject built with `default_library=static`. + Note that all `link_with` objects must be static libraries otherwise an error + will be raised when trying to `link_whole` a shared library. + + - name: partial_dependency + returns: dep + since: 0.46.0 + description: | + Returns a new dependency object with the same name, version, found status, + type name, and methods as the object that called it. This new + object will only inherit other attributes from its parent as + controlled by keyword arguments. + + If the parent has any dependencies, those will be applied to the new + partial dependency with the same rules. So, given: + + ```meson + dep1 = declare_dependency(compile_args : '-Werror=foo', link_with : 'libfoo') + dep2 = declare_dependency(compile_args : '-Werror=bar', dependencies : dep1) + dep3 = dep2.partial_dependency(compile_args : true) + ``` + + dep3 will add `['-Werror=foo', '-Werror=bar']` to the compiler args + of any target it is added to, but libfoo will not be added to the + link_args. + + The following arguments will add the following attributes: + + - compile_args: any arguments passed to the compiler + - link_args: any arguments passed to the linker + - links: anything passed via link_with or link_whole + - includes: any include_directories + - sources: any compiled or static sources the dependency has + + warnings: + - A bug present until 0.50.1 results in the above behavior + not working correctly. + + kwargs: + compile_args: + type: bool + default: false + description: Whether to include compile_args + + link_args: + type: bool + default: false + description: Whether to include link_args + + links: + type: bool + default: false + description: Whether to include links + + includes: + type: bool + default: false + description: Whether to include includes + + sources: + type: bool + default: false + description: Whether to include sources + + - name: get_variable + returns: str + since: 0.51.0 + description: | + A generic variable getter method, which replaces the + `get_*type*_variable` methods. This allows one to get the variable + from a dependency without knowing specifically how that dependency + was found. If `default_value` is set and the value cannot be gotten + from the object then `default_value` is returned, if it is not set + then an error is raised. + + optargs: + varname: + type: str + since: 0.58.0 + description: | + This argument is used as a default value + for `cmake`, `pkgconfig`, `configtool` and `internal` keyword + arguments. It is useful in the common case where `pkgconfig` and `internal` + use the same variable name, in which case it's easier to write `dep.get_variable('foo')` + instead of `dep.get_variable(pkgconfig: 'foo', internal: 'foo')`. + + kwargs: + cmake: + type: str + description: The CMake variable name + + pkgconfig: + type: str + description: The pkgconfig variable name + + configtool: + type: str + description: The configtool variable name + + internal: + type: str + since: 0.54.0 + description: The internal variable name + + default_value: + type: str + description: The davault value to return when the variable does not exist + + pkgconfig_define: + type: list[str] + description: See [[dep.get_pkgconfig_variable]] diff --git a/docs/yaml/objects/disabler.yaml b/docs/yaml/objects/disabler.yaml new file mode 100644 index 0000000..bd785bb --- /dev/null +++ b/docs/yaml/objects/disabler.yaml @@ -0,0 +1,13 @@ +name: disabler +long_name: Disabler +description: | + 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: + +methods: +- name: found + returns: bool + description: Always returns `false` diff --git a/docs/yaml/objects/env.yaml b/docs/yaml/objects/env.yaml new file mode 100644 index 0000000..fea11d5 --- /dev/null +++ b/docs/yaml/objects/env.yaml @@ -0,0 +1,85 @@ +name: env +long_name: Environment +description: | + This object is returned by [[environment]] and stores + detailed information about how environment variables should be set + during tests. It should be passed as the `env` keyword argument to + tests and other functions. + + *Since 0.58.0* [[env.append]] and [[env.prepend]] can be called multiple times + on the same `varname`. Earlier Meson versions would warn and only the last + operation took effect. + +example: | + ```meson + env = environment() + + # MY_PATH will be '0:1:2:3' + env.set('MY_PATH', '1') + env.append('MY_PATH', '2') + env.append('MY_PATH', '3') + env.prepend('MY_PATH', '0') + ``` + +methods: +- name: append + returns: void + description: | + appends the given values to + the old value of the environment variable, e.g. `env.append('FOO', + 'BAR', 'BAZ', separator : ';')` produces `BOB;BAR;BAZ` if `FOO` had + the value `BOB` and plain `BAR;BAZ` if the value was not defined. + + posargs: + variable: + type: str + description: The variable to modify + + varargs: + type: str + name: Value + description: The values to append + + kwargs: + separator: + type: str + description: | + The seperator to use. If not explicitly specified, the default path + separator for the host operating system will be used, i.e. ';' for + Windows and ':' for UNIX/POSIX systems. + +- name: prepend + returns: void + description: Same as `append` except that it writes to the beginning of the variable. + + posargs: + variable: + type: str + description: The variable to modify + + varargs: + type: str + name: Value + description: The values to prepend + + kwargs_inherit: env.append + +- name: set + returns: void + description: | + Sets the environment variable + specified in the first argument to the values in the varargs + joined by the separator. For instance, `env.set('FOO', 'BAR'),` sets envvar + `FOO` to value `BAR`. + + posargs: + variable: + type: str + description: The variable to modify + + varargs: + type: str + name: Value + description: The values to set + + kwargs_inherit: env.append diff --git a/docs/yaml/objects/exe.yaml b/docs/yaml/objects/exe.yaml new file mode 100644 index 0000000..c7be05b --- /dev/null +++ b/docs/yaml/objects/exe.yaml @@ -0,0 +1,4 @@ +name: exe +long_name: Executable target +description: An executable +extends: build_tgt diff --git a/docs/yaml/objects/external_program.yaml b/docs/yaml/objects/external_program.yaml new file mode 100644 index 0000000..02bf48f --- /dev/null +++ b/docs/yaml/objects/external_program.yaml @@ -0,0 +1,40 @@ +name: external_program +long_name: External program +description: Opaque object representing an external program + +methods: +- name: found + returns: bool + description: Returns whether the executable was found. + +- name: path + returns: str + deprecated: 0.55.0 + description: | + *Deprecated:* Use [[external_program.full_path]] instead. + + Returns a string pointing to the script or executable. + + **NOTE:** You should not need to use this method. Passing the object itself + should work in all cases. + + For example: + + ```meson + run_command(find_program('foo'), 'arg1', 'arg2') + ``` + +- name: full_path + returns: str + since: 0.55.0 + description: | + Returns a string pointing to the script or executable. + + **NOTE:** You should not need to use this method. Passing the object itself + should work in all cases. + + For example: + + ```meson + run_command(find_program('foo'), 'arg1', 'arg2') + ``` diff --git a/docs/yaml/objects/extracted_obj.yaml b/docs/yaml/objects/extracted_obj.yaml new file mode 100644 index 0000000..c418faf --- /dev/null +++ b/docs/yaml/objects/extracted_obj.yaml @@ -0,0 +1,3 @@ +name: extracted_obj +long_name: Extracted object file +description: Opaque object representing extracted object files from build targets diff --git a/docs/yaml/objects/feature.yaml b/docs/yaml/objects/feature.yaml new file mode 100644 index 0000000..5b451e5 --- /dev/null +++ b/docs/yaml/objects/feature.yaml @@ -0,0 +1,70 @@ +name: feature +long_name: Feature option object +since: 0.47.0 +description: Meson object representing a [`feature` options](Build-options.md#features) + +methods: +- name: enabled + returns: bool + description: Returns whether the feature was set to `'enabled'` + +- name: disabled + returns: bool + description: Returns whether the feature was set to `'disabled'` + +- name: auto + returns: bool + description: Returns whether the feature was set to `'auto'` + +- name: allowed + since: 0.59.0 + returns: bool + description: Returns whether the feature was set to `'enabled'` or `'auto'` + +- name: disable_auto_if + since: 0.59.0 + returns: feature + description: | + Returns the feature, with `'auto'` converted to `'disabled'` if value is true. + + | Feature / Condition | `value = true` | `value = false` | + | ------------------- | -------------- | --------------- | + | Enabled | Enabled | Enabled | + | Disabled | Disabled | Disabled | + | Auto | Disabled | Auto | + + posargs: + value: + type: bool + description: See the table above + +- name: require + returns: feature + since: 0.59.0 + description: | + Returns the object itself if the value is true; an error if the object is + `'enabled'` and the value is false; a disabled feature if the object + is `'auto'` or `'disabled'` and the value is false. + + example: | + `require` is useful to restrict the applicability of `'auto'` features, + for example based on other features or on properties of the host machine: + + ``` + if get_option('directx').require(host_machine.system() == 'windows', + error_message: 'DirectX only available on Windows').allowed() then + src += ['directx.c'] + config.set10('HAVE_DIRECTX', 1) + endif + ``` + + posargs: + value: + type: bool + description: The value to check + + kwargs: + error_message: + type: str + default: "''" + description: The error Message to print if the check fails diff --git a/docs/yaml/objects/file.yaml b/docs/yaml/objects/file.yaml new file mode 100644 index 0000000..6aa0b85 --- /dev/null +++ b/docs/yaml/objects/file.yaml @@ -0,0 +1,3 @@ +name: file +long_name: File +description: Opaque object that stores the path to an existing file diff --git a/docs/yaml/objects/generated_list.yaml b/docs/yaml/objects/generated_list.yaml new file mode 100644 index 0000000..7d1fe61 --- /dev/null +++ b/docs/yaml/objects/generated_list.yaml @@ -0,0 +1,3 @@ +name: generated_list +long_name: Generated list object +description: Opaque object representing the result of a [[generator.process]] call. diff --git a/docs/yaml/objects/generator.yaml b/docs/yaml/objects/generator.yaml new file mode 100644 index 0000000..e7b866a --- /dev/null +++ b/docs/yaml/objects/generator.yaml @@ -0,0 +1,36 @@ +name: generator +long_name: Generator object +description: | + This object is returned by [[generator]] and contains a + generator that is used to transform files from one type to another by + an executable (e.g. `idl` files into source code and headers). + +methods: + - name: process + returns: generated_list + description: | + Takes a list of files, causes them to be processed and returns an object containing the result + which can then, for example, be passed into a build target definition. + + varargs: + name: source + min_varargs: 1 + type: str | file | custom_tgt | custom_idx | generated_list + description: List of sources to process. + + kwargs: + extra_args: + type: list[str] + description: | + If present, will be used to replace an entry `@EXTRA_ARGS@` in the argument list. + + preserve_path_from: + type: str + since: 0.45.0 + description: | + If given, specifies that the output files need to maintain their directory structure + inside the target temporary directory. The most common value for this is + `meson.current_source_dir()`. With this value when a file called + `subdir/one.input` is processed it generates a file `{target private + directory}/subdir/one.out` as opposed to `{target private + directory}/one.out`. diff --git a/docs/yaml/objects/inc.yaml b/docs/yaml/objects/inc.yaml new file mode 100644 index 0000000..9f5e684 --- /dev/null +++ b/docs/yaml/objects/inc.yaml @@ -0,0 +1,3 @@ +name: inc +long_name: Include directories +description: Opaque wrapper for storing include directories diff --git a/docs/yaml/objects/jar.yaml b/docs/yaml/objects/jar.yaml new file mode 100644 index 0000000..14e79ae --- /dev/null +++ b/docs/yaml/objects/jar.yaml @@ -0,0 +1,4 @@ +name: jar +long_name: JAR build target +description: A Java JAR build target +extends: build_tgt diff --git a/docs/yaml/objects/lib.yaml b/docs/yaml/objects/lib.yaml new file mode 100644 index 0000000..da28489 --- /dev/null +++ b/docs/yaml/objects/lib.yaml @@ -0,0 +1,4 @@ +name: lib +long_name: Library target +extends: build_tgt +description: Represents either a shared or static library diff --git a/docs/yaml/objects/module.yaml b/docs/yaml/objects/module.yaml new file mode 100644 index 0000000..cd98faa --- /dev/null +++ b/docs/yaml/objects/module.yaml @@ -0,0 +1,13 @@ +name: module +long_name: Imported module object +description: | + Base type for all modules. + + Modules provide their own specific implementation methods, but all modules + proivide the following methods: + +methods: +- name: found + returns: bool + since: 0.59.0 + description: Returns `true` if the module was successfully imported, otherwise `false`. diff --git a/docs/yaml/objects/range.yaml b/docs/yaml/objects/range.yaml new file mode 100644 index 0000000..bc9e981 --- /dev/null +++ b/docs/yaml/objects/range.yaml @@ -0,0 +1,4 @@ +name: range +long_name: Range object +since: 0.58.0 +description: Opaque object that can be used in a loop and accessed via `[num]`. diff --git a/docs/yaml/objects/run_tgt.yaml b/docs/yaml/objects/run_tgt.yaml new file mode 100644 index 0000000..7805878 --- /dev/null +++ b/docs/yaml/objects/run_tgt.yaml @@ -0,0 +1,4 @@ +name: run_tgt +long_name: Run target +description: Opaque object returned by [[run_target]]. +extends: tgt diff --git a/docs/yaml/objects/runresult.yaml b/docs/yaml/objects/runresult.yaml new file mode 100644 index 0000000..36079a3 --- /dev/null +++ b/docs/yaml/objects/runresult.yaml @@ -0,0 +1,26 @@ +name: runresult +long_name: Run result object +description: | + This object encapsulates the result of trying to compile and run a + sample piece of code with [[compiler.run]] or + [[run_command]]. + +methods: +- name: compiled + returns: bool + description: | + If `true`, the compilation succeeded, if `false` it did not + and the other methods return unspecified data. This is only available + for `compiler.run()` results. + +- name: returncode + returns: int + description: The return code of executing the compiled binary + +- name: stderr + returns: str + description: The standard error produced when the command was run. + +- name: stdout + returns: str + description: The standard out produced when the command was run. diff --git a/docs/yaml/objects/subproject.yaml b/docs/yaml/objects/subproject.yaml new file mode 100644 index 0000000..d84e3f0 --- /dev/null +++ b/docs/yaml/objects/subproject.yaml @@ -0,0 +1,30 @@ +name: subproject +long_name: Subproject object +description: This object is returned by [[subproject]] and is an opaque object representing it. + +methods: +- name: found + returns: bool + since: 0.48.0 + description: Returns whether the subproject was successfully setup. + +- name: get_variable + returns: any + description: | + fetches the specified variable from inside the subproject. + This is useful to, for instance, get a + [[declare_dependency]] from the [subproject](Subprojects.md). + + If the variable does not exist, the variable `fallback` is returned. + If a fallback is not specified, then attempting to read a non-existing + variable will cause a fatal error. + + posargs: + var_name: + type: str + description: The name of the variable to query + + optargs: + fallback: + type: any + description: The fallback value to return if `var_name` does not exist. diff --git a/docs/yaml/objects/tgt.yaml b/docs/yaml/objects/tgt.yaml new file mode 100644 index 0000000..c0d0285 --- /dev/null +++ b/docs/yaml/objects/tgt.yaml @@ -0,0 +1,3 @@ +name: tgt +long_name: Meson Target +description: Opaque base object for all Meson targets |