| 1 |
name: project |
| 2 |
returns: void |
| 3 |
description: | |
| 4 |
The first function called in each project, to initialize Meson. |
| 5 |
|
| 6 |
The first argument to this function must be a string defining the name |
| 7 |
of this project. |
| 8 |
|
| 9 |
The project name can be any string you want, it's not used for |
| 10 |
anything except descriptive purposes. However since it is written to |
| 11 |
e.g. the dependency manifest is usually makes sense to have it be the |
| 12 |
same as the project tarball or pkg-config name. So for example you |
| 13 |
would probably want to use the name _libfoobar_ instead of _The Foobar |
| 14 |
Library_. |
| 15 |
|
| 16 |
It may be followed by the list of programming languages that the project uses. |
| 17 |
|
| 18 |
*(since 0.40.0)* The list of languages is optional. |
| 19 |
|
| 20 |
These languages may be used both for `native: false` (the default) |
| 21 |
(host machine) targets and for `native: true` (build machine) targets. |
| 22 |
*(since 0.56.0)* The build machine compilers for the specified |
| 23 |
languages are not required. |
| 24 |
|
| 25 |
Supported values for languages are `c`, `cpp` (for `C++`), `cuda`, |
| 26 |
`cython`, `d`, `objc`, `objcpp`, `fortran`, `java`, `cs` (for `C#`), |
| 27 |
`vala` and `rust`. |
| 28 |
|
| 29 |
posargs: |
| 30 |
project_name: |
| 31 |
type: str |
| 32 |
description: The name of the project. |
| 33 |
|
| 34 |
varargs: |
| 35 |
name: language |
| 36 |
type: str |
| 37 |
description: The languages that Meson should initialize. |
| 38 |
|
| 39 |
kwargs: |
| 40 |
default_options: |
| 41 |
type: list[str] | dict[str | bool | int | list[str]] |
| 42 |
description: | |
| 43 |
Accepts strings in the form `key=value` |
| 44 |
which have the same format as options to `meson configure`. |
| 45 |
For example to set the default project type you would |
| 46 |
set this: `default_options : ['buildtype=debugoptimized']`. Note |
| 47 |
that these settings are only used when running Meson for the first |
| 48 |
time. Global options such as `buildtype` can only be specified in |
| 49 |
the master project, settings in subprojects are ignored. Project |
| 50 |
specific options are used normally even in subprojects. |
| 51 |
|
| 52 |
Note that some options can override the default behavior; |
| 53 |
for example, using `c_args` here means that the `CFLAGS` |
| 54 |
environment variable is not used. Consider using |
| 55 |
[[add_project_arguments()]] instead. |
| 56 |
|
| 57 |
*(since 1.2.0)*: A dictionary may now be passed. |
| 58 |
|
| 59 |
version: |
| 60 |
type: str | file |
| 61 |
description: | |
| 62 |
A free form string describing the version of this project. |
| 63 |
You can access the value in your Meson build files |
| 64 |
with [[meson.project_version]]. *(Since 0.57.0)* this can also be a |
| 65 |
[[@file]] object pointing to a file that contains exactly one line of |
| 66 |
text. |
| 67 |
|
| 68 |
meson_version: |
| 69 |
type: str |
| 70 |
description: | |
| 71 |
Takes a string describing which Meson version the project requires. |
| 72 |
Usually something like `>=0.28.0`. |
| 73 |
|
| 74 |
license: |
| 75 |
type: str | list[str] |
| 76 |
description: | |
| 77 |
Takes a string or array of strings describing the license(s) the code is under. |
| 78 |
|
| 79 |
This *should* be an [SPDX license expression](https://spdx.dev/ids/), |
| 80 |
using the standardized license identifier from the [SPDX license |
| 81 |
list](https://spdx.org/licenses/). Usually this would be something like |
| 82 |
`license : 'GPL-2.0-or-later'`. If there are multiple licenses you can use the |
| 83 |
`AND` and `OR` operators to join them: `license : 'Apache-2.0 OR GPL-2.0'`. |
| 84 |
|
| 85 |
For backwards compatibility reasons you can also pass an array of |
| 86 |
licenses here. This is not recommended, as it is ambiguous: `license : |
| 87 |
['Apache-2.0', 'GPL-2.0-only']` instead use an SPDX expression: `license |
| 88 |
: 'Apache-2.0 OR GPL-2.0-only'`, which makes it clear that the license |
| 89 |
mean OR, not AND. |
| 90 |
|
| 91 |
Note that the text is informal and is only written to the dependency |
| 92 |
manifest. Meson does not do any license validation, you are responsible |
| 93 |
for verifying that you abide by all licensing terms. You can access the |
| 94 |
value in your Meson build files with `meson.project_license()`. |
| 95 |
|
| 96 |
license_files: |
| 97 |
type: str | list[str] |
| 98 |
since: 1.1.0 |
| 99 |
description: | |
| 100 |
Takes a string or array of strings with the paths to the license file(s) |
| 101 |
the code is under. |
| 102 |
|
| 103 |
This enhances the value of the `license` kwarg by allowing to specify both |
| 104 |
the short license name and the full license text. Usually this would be |
| 105 |
something like `license_files: ['COPYING']`. |
| 106 |
|
| 107 |
Note that the files are informal and are only installed with the dependency |
| 108 |
manifest. Meson does not do any license validation, you are responsible |
| 109 |
for verifying that you abide by all licensing terms. You can access the |
| 110 |
value in your Meson build files with [[meson.project_license_files]]. |
| 111 |
|
| 112 |
subproject_dir: |
| 113 |
type: str |
| 114 |
default: "'subprojects'" |
| 115 |
description: | |
| 116 |
Specifies the top level directory name that holds Meson subprojects. |
| 117 |
This is only meant as a compatibility option |
| 118 |
for existing code bases that house their embedded source code in a |
| 119 |
custom directory. All new projects should not set this but instead |
| 120 |
use the default value. It should be noted that this keyword |
| 121 |
argument is ignored inside subprojects. There can be only one |
| 122 |
subproject dir and it is set in the top level Meson file. |