| 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 |
``` |