diff options
Diffstat (limited to 'docs/yaml/objects')
26 files changed, 1300 insertions, 0 deletions
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..e1c8a80 --- /dev/null +++ b/docs/yaml/objects/build_tgt.yaml @@ -0,0 +1,41 @@ +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. + + TODO: Missing methods, links + +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..d4f0715 --- /dev/null +++ b/docs/yaml/objects/compiler.yaml @@ -0,0 +1,542 @@ +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. + 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..d0e476f --- /dev/null +++ b/docs/yaml/objects/external_program.yaml @@ -0,0 +1,3 @@ +name: external_program +long_name: External program +description: TODO 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 |