Debian Codegraph @

subprojects/meson-docs/docs/yaml/functions/project.yaml

raw
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.