Compiling QML to C++: Import paths
This is the seventh installment in the series of blog posts on how to adjust your QML application to take the maximum advantage of qmlsc. In the first post we've set up the environment. You should read that post first in order to understand the others. We're going to look at import paths this time around.
QmlProfilerFlameGraphView.qml contains the following code:
import "../Tracing" // TODO: Turn into module import when possible
The TODO already tells us what is wrong here. We're importing the "Tracing" module by path, not by module name. This is bad because, at compile time, we don't really know what the QML engine will find at that path later. And indeed, qmlsc produces a number of warnings when compiling this file.
It's better to clearly state the intention here, and import the module by URI:
import QtCreator.Tracing 1.0
This should work, right? "Tracing" is a module after all. If you compile this, then open Qt Creator and navigate to the flame graph view in the QML profiler, you will see it doesn't work.
qrc:/QtCreator/QmlProfiler/QmlProfilerFlameGraphView.qml:29:1: FlameGraphView is not a type
In addition a whole number of bindings cannot be compiled in that file. For example:
Error: QmlProfilerFlameGraphView.qml:34:5: Could not compile binding for typeIdRole: Cannot resolve property type for binding on typeIdRole
Maybe there was some deeper reason to import by path rather than by URI after all? Let's take a closer look. If we import by URI, the QML engine has to locate the module in its import path. The default import path consists of
- The directory where Qt's own modules are stored, typically a directory called "qml" in your Qt installation.
- The directory where the application binary resides.
- :/qt/qml in the resource file system.
- :/qt-project.org/imports/ in the resource file system.
There are some platform-specific quirks in addition to this, but those don't really matter here. Now, where does Qt Creator's build system put the "Tracing" module? One place we can see already in the error message above is the resource root path. QmlProfilerFlameGraphView.qml of module QtCreator.QmlProfiler seems to reside at :/QtCreator/QmlProfiler/ . When the QML engine looks for a module, the module URI gets translated to a subdirectory of the import path by replacing the dots with slashes. So, adding ":/" to the import path would make this module detectable. We can do this. In the constructor of FlameGraphView in src/plugins/qmlprofiler/flamegraphview.cpp a QQuickWidget m_content gets created. QQuickWidget in turn contains a QQmlEngine, and we can add an import path to that, before we setSource() on it:
That works, indeed. However, is it a good idea? It depends. If your application uses the resource file system predominantly for QML, you may want to dedicate the whole resource file system to QML. In that case ":/" may be the right choice here. However, if you want to store further data in the resource file system without creating name conflicts with your QML modules, you may want to move your QML modules to a different place. Indeed the build system tells you to be specific here:
CMake Warning at .../cmake/Qt6Qml/Qt6QmlMacros.cmake:460 (message): Neither RESOURCE_PREFIX nor AUTO_RESOURCE_PREFIX are specified for QmlProfiler. The resource root directory, ':/', is used as prefix. If this is what you want, specify '/' as RESOURCE_PREFIX. The recommended resource directory to be used as prefix is ':/qt/qml/'. Specify AUTO_RESOURCE_PREFIX to use it.
Let's say we want all our modules to live at ":/qt/qml" in the resource file system. This is what the AUTO_RESOURCE_PREFIX parameter to the qt_add_qml_module CMake function is for. ":/qt/qml" is the new standard location for user QML modules in the resource file system. It is automatically included in the QML Import Path.
Mind that you have to add AUTO_RESOURCE_PREFIX to all your QML modules for it to make sense. Having half of your QML modules at ":/" and the other ones at ":/qt/qml" gives you the worst of both options.
You also need to adapt the entry points to load their QML documents from the new locations. For example, for a QQuickWidget called m_content:
Finally, if you rely on extra resources, like shaders, to be positioned relative to your QML modules, you need to also adapt their paths. Mind that qt_add_qml_module() offers an argument RESOURCES. The files given that way are automatically put in the right places. Use it where possible.
addImportPath exists since Qt 5.0. However, writing QML modules is a lot more complicated in Qt 5 than in Qt 6. This is why directory imports are relatively common in existing code. ":/qt/qml" is a recent addition to the default QML import path, as is AUTO_RESOURCE_PREFIX. They will be released ith Qt 6.5. Until then, you can manually add ":/qt/qml" to your import path:
And you can use RESOURCE_PREFIX instead of AUTO_RESOURCE_PREFIX in CMake for now:
Subscribe to our newsletter
Try Qt 6.6 Now!
Download the latest release here: www.qt.io/download.
Qt 6.6. is a feature release with focus on improving UX capabilities including responsive UI technology and the Qt Graph module.
Check out all our open positions here and follow us on Instagram to see what it's like to be #QtPeople.