diff options
Diffstat (limited to 'docs/yaml/functions')
53 files changed, 2679 insertions, 0 deletions
diff --git a/docs/yaml/functions/_build_target_base.yaml b/docs/yaml/functions/_build_target_base.yaml new file mode 100644 index 0000000..53808d8 --- /dev/null +++ b/docs/yaml/functions/_build_target_base.yaml @@ -0,0 +1,270 @@ +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_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..bd94779 --- /dev/null +++ b/docs/yaml/functions/configure_file.yaml @@ -0,0 +1,128 @@ +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. + + 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..cf8312e --- /dev/null +++ b/docs/yaml/functions/custom_target.yaml @@ -0,0 +1,201 @@ +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 the keyword arguments are the + following. + + 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. + +posargs: + name: + type: str + description: The *unique* id of the custom target + +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. + + 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: + ``` + 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: + ``` + 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. + + 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..e0c8ad3 --- /dev/null +++ b/docs/yaml/functions/dependency.yaml @@ -0,0 +1,179 @@ +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. + + 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) + +posargs: + dependency_name: + type: str + description: Name of the dependency too look up + +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) + + 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..be5dcfe --- /dev/null +++ b/docs/yaml/functions/install_data.yaml @@ -0,0 +1,49 @@ +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`. + + 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..a57bd27 --- /dev/null +++ b/docs/yaml/functions/install_subdir.yaml @@ -0,0 +1,94 @@ +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. + + 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/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 |