Adding Glean to your Qt/QML project
This page provides a step-by-step guide on how to integrate the Glean.js library into a Qt/QML project.
Nevertheless this is just one of the required steps for integrating Glean successfully into a project. Check you the full Glean integration checklist for a comprehensive list of all the steps involved in doing so.
- Python >= 3.6
- Qt >= 5.15.2
Setting up the dependency
Glean.js' Qt/QML build is distributed as an asset with every Glean.js release. In order to download the latest version visit https://github.com/mozilla/glean.js/releases/latest.
Glean.js is a QML module, so extract the contents of the downloaded file wherever you keep your other modules. Make sure that whichever directory that module is placed in, is part of the QML Import Path.
After doing that, import Glean like so:
import org.mozilla.Glean <version>
Picking the correct version
<version>number is the version of the release you downloaded minus its patch version. For example, if you downloaded Glean.js version
0.15.0your import statement will be:
import org.mozilla.Glean 0.15
Consuming YAML registry files
Qt/QML projects need to setup metrics and pings code generation manually.
First install the
glean_parser CLI tool.
pip install glean_parser
Make sure you have the correct
Qt/QML support was added to
glean_parserin version 3.5.0.
glean_parser from the command line:
translate command will takes a list of YAML registry file paths and an output path and parse
The generated folder will be a QML module. Make sure wherever the generated module is placed is also part of the QML Import Path.
Notice that when building for Qt/QML it is mandatory to give the
translate command two extra options.
The version passed to this option will be the version of the generated QML module.
Prefer using the Glean Dictionary
While it is still possible to generate Markdown documentation, if working on a public Mozilla project rely on the Glean Dictionary for documentation. Your product will be automatically indexed by the Glean Dictionary after it gets enabled in the pipeline.
One of the commands provided by
glean_parser allows users to generate Markdown documentation based
on the contents of their YAML registry files. To perform that translation, use the
with a different output format, as shown below.
glean_parser translate path/to/metrics.yaml path/to/pings.yaml \ -f markdown \ -o path/to/docs
YAML registry files linting
glean_parser includes a "linter" for the YAML registry files called the
glinter that catches a
number of common mistakes in these files. To run the linter use the
glean_parser glinter path/to/metrics.yaml path/to/pings.yaml
By default, the Glean.js QML module uses a minified version of the Glean.js library. It may be useful to use the unminified version of the library in order to get proper line numbers and function names when debugging crashes.
The bundle provided contains the unminified version of the library.
In order to use it, open the
glean.js file inside the included module and change the line:
.import "glean.lib.js" as Glean
.import "glean.dev.js" as Glean
submitPing may cause crashes when debugging iOS devices
submitPing function hits a
This bug is only reproduced in iOS devices, it does not happen in emulators. It also only happens when using the Qt debug library for iOS.
There is no way around this bug other than avoiding the Qt debug library for iOS altogether until it is fixed. Refer to the the Qt debugging documentation on how to do that.