Debian Codegraph @

subprojects/meson-docs/docs/markdown/Qt6-module.md

raw
1 # Qt6 module
2
3 *New in Meson 0.57.0*
4
5 The Qt6 module provides methods to automatically deal with the various
6 tools and steps required for Qt.
7
8 <div class="alert alert-warning">
9 <strong>Warning:</strong> before version 0.63.0 Meson would fail to find
10 Qt 6.1 or later due to the Qt tools having moved to the libexec subdirectory,
11 and tool names being suffixed with only the Qt major version number e.g. qmake6.
12 </div>
13
14 ## compile_resources
15
16 *New in 0.59.0*
17
18 Compiles Qt's resources collection files (.qrc) into c++ files for compilation.
19
20 It takes no positional arguments, and the following keyword arguments:
21 - `name` (string | empty): if provided a single .cpp file will be generated,
22 and the output of all qrc files will be combined in this file, otherwise
23 each qrc file be written to its own cpp file.
24 - `sources` (File | string | custom_target | custom_target index | generator_output)[]:
25 A list of sources to be transpiled. Required, must have at least one source<br/>
26 *New in 0.60.0*: support for custom_target, custom_target_index, and generator_output.
27 - `extra_args` string[]: Extra arguments to pass directly to `qt-rcc`
28 - `method` string: The method to use to detect Qt, see [[dependency]]
29
30 ## compile_ui
31
32 *New in 0.59.0*
33
34 Compiles Qt's ui files (.ui) into header files.
35
36 It takes no positional arguments, and the following keyword arguments:
37 - `sources` (File | string | custom_target | custom_target index | generator_output)[]:
38 A list of sources to be transpiled. Required, must have at least one source<br/>
39 *New in 0.60.0*: support for custom_target, custom_target_index, and generator_output.
40 - `extra_args` string[]: Extra arguments to pass directly to `qt-uic`
41 - `method` string: The method to use to detect Qt, see [[dependency]]
42 - `preserve_paths` bool: *New in 1.4.0*. If `true`, specifies that the output
43 files need to maintain their directory structure inside the target temporary
44 directory. For instance, when a file called `subdir/one.input` is processed
45 it generates a file `{target private directory}/subdir/one.out` when `true`,
46 and `{target private directory}/one.out` when `false` (default).
47
48 ## compile_moc
49
50 *New in 0.59.0*
51
52 Compiles Qt's moc files (.moc) into header and/or source files. At least one of
53 the keyword arguments `headers` and `sources` must be provided.
54
55 It takes no positional arguments, and the following keyword arguments:
56 - `sources` (File | string | custom_target | custom_target index | generator_output)[]:
57 A list of sources to be transpiled into .moc files for manual inclusion.<br/>
58 *New in 0.60.0*: support for custom_target, custom_target_index, and generator_output.
59 - `headers` (File | string | custom_target | custom_target index | generator_output)[]:
60 A list of headers to be transpiled into .cpp files<br/>
61 *New in 0.60.0*: support for custom_target, custom_target_index, and generator_output.
62 - `extra_args` string[]: Extra arguments to pass directly to `qt-moc`
63 - `method` string: The method to use to detect Qt, see [[dependency]]
64 - `dependencies`: dependency objects whose include directories are used by moc.
65 - `include_directories` (string | IncludeDirectory)[]: A list of `include_directory()`
66 objects used when transpiling the .moc files
67 - `preserve_paths` bool: *New in 1.4.0*. If `true`, specifies that the output
68 files need to maintain their directory structure inside the target temporary
69 directory. For instance, when a file called `subdir/one.input` is processed
70 it generates a file `{target private directory}/subdir/one.out` when `true`,
71 and `{target private directory}/one.out` when `false` (default).
72 - `output_json` bool: *New in 1.7.0*. If `true`, generates additionnaly a
73 JSON representation which may be used by external tools such as qmltyperegistrar
74
75 ## preprocess
76
77 Consider using `compile_resources`, `compile_ui`, and `compile_moc` instead.
78
79 Takes sources for moc, uic, and rcc, and converts them into c++ files for
80 compilation.
81
82 Has the following signature: `qt.preprocess(name: str | None, *sources: str)`
83
84 If the `name` parameter is passed then all of the rcc files will be written to
85 a single output file
86
87 *Deprecated in 0.59.0*: Files given in the variadic `sources` arguments as well
88 as the `sources` keyword argument, were passed unmodified through the preprocessor
89 programs. Don't do this - just add the output of `preprocess()` to another sources
90 list:
91 ```meson
92 sources = files('a.cpp', 'main.cpp', 'bar.c')
93 sources += qt.preprocess(qresources : ['resources'])
94 ```
95
96 This method takes the following keyword arguments:
97 - `qresources` (string | File)[]: Passed to the RCC compiler
98 - `ui_files`: (string | File | CustomTarget)[]: Passed the `uic` compiler
99 - `moc_sources`: (string | File | CustomTarget)[]: Passed the `moc` compiler.
100 These are converted into .moc files meant to be `#include`ed
101 - `moc_headers`: (string | File | CustomTarget)[]: Passed the `moc` compiler.
102 These will be converted into .cpp files
103 - `include_directories` (IncludeDirectories | string)[], the directories to add
104 to header search path for `moc`
105 - `moc_extra_arguments` string[]: any additional arguments to `moc`.
106 - `uic_extra_arguments` string[]: any additional arguments to `uic`.
107 - `rcc_extra_arguments` string[]: any additional arguments to `rcc`.
108 - `dependencies` Dependency[]: dependency objects needed by moc.
109 - *Deprecated in 0.59.0.*: `sources`: a list of extra sources, which are added
110 to the output unchanged.
111 - `preserve_paths` bool: *Since 1.4.0*. If `true`, specifies that the output
112 files need to maintain their directory structure inside the target temporary
113 directory. For instance, when a file called `subdir/one.input` is processed
114 it generates a file `{target private directory}/subdir/one.out` when `true`,
115 and `{target private directory}/one.out` when `false` (default).
116 - `moc_output_json` bool: *New in 1.7.0*. If `true`, generates additionally a
117 JSON representation which may be used by external tools such as qmltyperegistrar
118
119 It returns an array of targets and sources to pass to a compilation target.
120
121 ## compile_translations
122
123 This method generates the necessary targets to build translation files with
124 lrelease, it takes no positional arguments, and the following keyword arguments:
125
126 - `ts_files` (File | string | custom_target | custom_target index | generator_output)[]:
127 the list of input translation files produced by Qt's lupdate tool.<br/>
128 *New in 0.60.0*: support for custom_target, custom_target_index, and generator_output.
129 - `install` bool: when true, this target is installed during the install step (optional).
130 - `install_dir` string: directory to install to (optional).
131 - `build_by_default` bool: when set to true, to have this target be built by
132 default, that is, when invoking `meson compile`; the default value is false
133 (optional).
134 - `qresource` string: rcc source file to extract ts_files from; cannot be used
135 with ts_files kwarg.
136 - `rcc_extra_arguments` string[]: any additional arguments to `rcc` (optional),
137 when used with `qresource.
138
139 Returns either: a list of custom targets for the compiled
140 translations, or, if using a `qresource` file, a single custom target
141 containing the processed source file, which should be passed to a main
142 build target.
143
144 ## has_tools
145
146 This method returns `true` if all tools used by this module are found,
147 `false` otherwise.
148
149 It should be used to compile optional Qt code:
150 ```meson
151 qt6 = import('qt6')
152 if qt6.has_tools(required: get_option('qt_feature'))
153 moc_files = qt6.preprocess(...)
154 ...
155 endif
156 ```
157
158 This method takes the following keyword arguments:
159 - `required` bool | FeatureOption: by default, `required` is set to `false`. If `required` is set to
160 `true` or an enabled [`feature`](Build-options.md#features) and some tools are
161 missing Meson will abort.
162 - `method` string: The method to use to detect Qt, see [[dependency]]
163 - `tools`: string[]: *Since 1.6.0*. List of tools to check. Testable tools
164 are `moc`, `uic`, `rcc` and `lrelease`. By default `tools` is set to `['moc',
165 'uic', 'rcc', 'lrelease']`
166
167 ## qml_module
168
169 *New in 1.7.0*
170
171 This function requires one positional argument: the URI of the module as dotted
172 identifier string. For instance `Foo.Bar`
173
174 This method takes the following keyword arguments:
175
176 - `version`: string: the module version in the form `Major.Minor` with an
177 optional `.Patch`. For instance `1.0`
178 - `qml_sources` (File | string | custom_target | custom_target index | generator_output)[]:
179 A list of qml to be embedded in the module
180 - `qml_singletons` (File | string | custom_target | custom_target index | generator_output)[]:
181 A list of qml to be embedded in the module and marked as singletons
182 - `qml_internals` (File | string | custom_target | custom_target index | generator_output)[]:
183 A list of qml to be embedded in the module and marked as internal files
184 - `resources_prefix` string: By default `resources_prefix` is set to
185 `qt/qml`. Prefix resources in the generated QRC with the given prefix
186 - `imports`: string[]: List of other QML modules imported by this module. Version
187 can be specified as `Module/1.0` or `Module/auto`. See qmldir documentation
188 - `optional_imports`: string[]: List of other QML modules that may be imported by this
189 module. See `imports` for expected format and qmldir documentation
190 - `default_imports`: string[]: List QML modules that may be loaded by
191 tooling. See `imports` for expected format and qmldir documentation
192 - `depends_imports`: string[]: List of QML extra dependencies that may not be
193 imported by QML, such as dependencies existing in C++ code. See `imports` for
194 expected format and qmldir documentation
195 - `designer_supported` bool: If `true` specifies that the module supports Qt
196 Quick Designer
197 - `moc_headers` (File | string | custom_target | custom_target index | generator_output)[]:
198 A list of headers to be transpiled into .cpp files. See [Qt
199 documentation](https://doc.qt.io/qt-6/qtqml-cppintegration-definetypes.html)
200 regarding how to register C++ class as Qml elements. Note: due to some
201 limitations of qmltyperegistrar, all headers that declare QML types need to
202 be accessible in the project's include path.
203 - `namespace`: str: optional C++ namespace for plugin and generation code
204 - `typeinfo`: str: optional name for the generated qmltype file, by default it
205 will be generated as `{target_name}.qmltype`
206 - `rcc_extra_arguments`: string[]: Extra arguments to pass directly to `qt-rcc`
207 - `moc_extra_arguments`: string[]: Extra arguments to pass directly to `qt-moc`
208 - `qmlcachegen_extra_arguments`: string[]: Extra arguments to pass directly to
209 `qmlcachegen`
210 - `qmltyperegistrar_extra_arguments`: string[]: Extra arguments to pass directly to
211 `qmltyperegistrar`
212 - `generate_qmldir`: bool: If `true` (default) auto generate the `qmldir` file
213 - `generate_qmltype`: bool: If `true` (default) auto generate `qmltype` file
214 - `cachegen`: bool: If `true` (default) preprocess QML and JS files with
215 qmlcachegen
216 - `method` string: The method to use to detect Qt, see [[dependency]]
217 - `preserve_paths` bool: If `true`, specifies that the output
218 files need to maintain their directory structure inside the target temporary
219 directory. For instance, when a file called `subdir/one.input` is processed
220 it generates a file `{target private directory}/subdir/one.out` when `true`,
221 and `{target private directory}/one.out` when `false` (default).
222 - `dependencies`: dependency objects whose include directories are used by
223 moc.
224 - `include_directories` (string | IncludeDirectory)[]: A list of `include_directory()`
225 objects used when transpiling the .moc files
226 - `install` bool: when true, this target is installed during the install step (optional).
227 - `install_dir` string: directory to install to (optional).
228
229
230 Note: Qt uses static initialization to register its resources, if you're
231 building a static library you may need to call these entry points
232 explicitly. For a module `Foo.Bar42` the generated resources are `Foo_Bar42`
233 and `qmlcache_Foo_Bar42` when qmlcache is used, they can be imported using
234 `Q_INIT_RESOURCE`. All non-alphanumeric characters from the module name are
235 replaced with `_`. Type registration may be invoked explicitly using
236 `extern void qml_register_types_Foo_Bar42()`.
237
238 See [Qt documentation](https://doc.qt.io/qt-6/resources.html#explicit-loading-and-unloading-of-embedded-resources)
239 for more information
240
241
242 ## Dependencies
243
244 See [Qt dependencies](Dependencies.md#qt)
245
246 The 'modules' argument is used to include Qt modules in the project.
247 See the Qt documentation for the [list of
248 modules](https://doc.qt.io/qt-6/qtmodules.html).
249
250 The 'private_headers' argument allows usage of Qt's modules private
251 headers.
252
253 ## Example
254 A simple example would look like this:
255
256 ```meson
257 qt6 = import('qt6')
258 qt6_dep = dependency('qt6', modules: ['Core', 'Gui'])
259 inc = include_directories('includes')
260 moc_files = qt6.compile_moc(headers : 'myclass.h',
261 extra_arguments: ['-DMAKES_MY_MOC_HEADER_COMPILE'],
262 include_directories: inc,
263 dependencies: qt6_dep)
264 translations = qt6.compile_translations(ts_files : 'myTranslation_fr.ts', build_by_default : true)
265 executable('myprog', 'main.cpp', 'myclass.cpp', moc_files,
266 include_directories: inc,
267 dependencies : qt6_dep)
268 ```
269
270 Sometimes, translations are embedded inside the binary using qresource
271 files. In this case the ts files do not need to be explicitly listed,
272 but will be inferred from the built qm files listed in the qresource
273 file. For example:
274
275 ```meson
276 qt6 = import('qt6')
277 qt6_dep = dependency('qt6', modules: ['Core', 'Gui'])
278 lang_cpp = qt6.compile_translations(qresource: 'lang.qrc')
279 executable('myprog', 'main.cpp', lang_cpp,
280 dependencies: qt6_dep)
281 ```