1// Copyright (C) 2017 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
4\page qtqml-modules-qmldir.html
5\title Module Definition qmldir Files
6\brief Defines a QML module
8There are two distinct types of \c qmldir files:
10\li QML document directory listing files
11\li QML module definition files
14This documentation covers only the second form of \c qmldir file, which
15lists the QML types, JavaScript files, and plugins that are available under a
16module. For more information about the first form of \c qmldir file, see
17\l{qtqml-syntax-directoryimports.html#directory-listing-qmldir-files}
18{directory listing qmldir files}.
20\section1 Contents of a Module Definition qmldir File
22A \c qmldir file is a plain-text file that contains the following commands:
25 \li \l {Module Identifier Declaration}
26 \li \l {Object Type Declaration}
27 \li \l {Internal Object Type Declaration}
28 \li \l {JavaScript Resource Declaration}
29 \li \l {Plugin Declaration}
30 \li \l {Plugin Classname Declaration}
31 \li \l {Type Description File Declaration}
32 \li \l {Module Dependencies Declaration}
33 \li \l {Module Import Declaration}
34 \li \l {Designer Support Declaration}
35 \li \l {Preferred Path Declaration}
38\note Each command in a \c qmldir file must be on a separate line.
40In addition to commands, you can also add comments, which are lines starting
43\section2 Module Identifier Declaration
46 module <ModuleIdentifier>
49Declares the module identifier of the module. The <ModuleIdentifier> is the
50(dotted URI notation) identifier for the module, which must match the module's
53The \l{Identified Modules#Semantics of Identified Modules}
54{module identifier directive} must be the first line of the file. Exactly one
55module identifier directive may exist in the \c qmldir file.
62\section2 Object Type Declaration
64 [singleton] <TypeName> <InitialVersion> <File>
67Declares a \l{qtqml-typesystem-objecttypes.html}{QML object type}
68to be made available by the module.
70 \li \c [singleton] Optional. Used to declare a singleton type.
71 \li \c <TypeName> is the type being made available
72 \li \c <InitialVersion> is the module version for which the type is to be
74 \li \c <File> is the (relative) file name of the QML file that defines
78Zero or more object type declarations may exist in the \c qmldir
79file. However, each object type must have a unique type name within
80any particular version of the module.
81\note To declare a \c singleton type, the QML file defining the
82type must include the \c {pragma Singleton} statement.
86 //Style.qml with custom singleton type definition
91 property int textSize: 20
92 property color textColor: "green"
95 // qmldir declaring the singleton type
97 singleton Style 1.0 Style.qml
99 // singleton type in use
101 import CustomStyles 1.0
104 font.pixelSize: Style.textSize
105 color: Style.textColor
110\section2 Internal Object Type Declaration
113 internal <TypeName> <File>
116Declares an object type that is in the module but should not be
117made available to users of the module.
119Zero or more internal object type declarations may exist in the
124 internal MyPrivateType MyPrivateType.qml
127This is necessary if the module is imported remotely
128(see \l{Identified Modules#Remotely Installed Identified Modules}
129{Remotely Installed Identified Modules}) because if an exported type depends
130on a non-exported type within the module, the engine must also
131load the non-exported type.
133\section2 JavaScript Resource Declaration
136 <ResourceIdentifier> <InitialVersion> <File>
139Declares a JavaScript file to be made available by the module.
140The resource will be made available via the specified identifier
141with the specified version number.
143Zero or more JavaScript resource declarations may exist in the
144\c qmldir file. However, each JavaScript resource must have a unique
145identifier within any particular version of the module.
149 MyScript 1.0 MyScript.js
152See the documentation about \l{qtqml-javascript-resources.html}
153{defining JavaScript resources} and
154\l{qtqml-javascript-imports.html}
155{Importing JavaScript Resources In QML} for more information.
157\section2 Plugin Declaration
160 [optional] plugin <Name> [<Path>]
163Declares a plugin to be made available by the module.
166 \li \c optional denotes that the plugin itself does not contain
167 any relevant code and only serves to load a library it links
168 to. If given, and if any types for the module are already
169 available, indicating that the library has been loaded by some
170 other means, QML will not load the plugin.
171 \li \c <Name> is the plugin library name. This is usually not the
172 same as the file name of the plugin binary, which is platform
173 dependent. For example, the library \c MyAppTypes would produce
174 \c libMyAppTypes.so on Linux and \c MyAppTypes.dll on Windows.
175 \li \c <Path> (optional) specifies either:
177 \li an absolute path to the directory containing the plugin
179 \li a relative path from the directory containing the \c qmldir
180 file to the directory containing the plugin file.
184By default, the engine searches for the plugin library in the
185directory that contains the \c qmldir file. (The plugin search
186path can be queried with QQmlEngine::pluginPathList() and
187modified using QQmlEngine::addPluginPath().)
189Zero or more C++ plugin declarations may exist in the \c qmldir
190file. However, since plugin loading is a relatively expensive
191operation, clients are advised to specify at most a single plugin.
195 plugin MyPluginLibrary
198\section2 Plugin Classname Declaration
201 classname <C++ plugin class>
204Provides the class name of the C++ plugin used by the module.
206This information is required for all the QML modules that depend
207on a C++ plugin for additional functionality. Qt Quick applications
208built with static linking cannot resolve the module imports without
211\section2 Type Description File Declaration
217Declares a \l{Type Description Files}{type description file} for
218the module that can be read by QML tools such as Qt Creator to
219access information about the types defined by the module's plugins.
220\c <File> is the (relative) file name of a \c .qmltypes file.
224 typeinfo mymodule.qmltypes
227Without such a file, QML tools may be unable to offer features such
228as code completion for the types defined in your plugins.
230\section2 Module Dependencies Declaration
233 depends <ModuleIdentifier> <InitialVersion>
236Declares that this module depends on another.
240 depends MyOtherModule 1.0
243This declaration is necessary only in cases when the dependency is
244hidden: for example, when the C++ code for one module is used to
245load QML (perhaps conditionally), which then depends on other
246modules. In such cases, the \c depends declaration is necessary
247to include the other modules in application packages.
249\section2 Module Import Declaration
252 import <ModuleIdentifier> [<Version>]
255Declares that this module imports another.
259 import MyOtherModule 1.0
262The types from the other module are made available in the same type
263namespace as this module is imported into. Omitting the version
264imports the latest version available of the other module. Specifying
265\c auto as version imports the same version as the version of this
266module specified in the QML \c import statement.
268\section2 Designer Support Declaration
274Set this property if the plugin is supported by Qt Quick Designer.
275By default, the plugin will not be supported.
277A plugin that is supported by Qt Quick Designer has to be properly
278tested. This means that the plugin does not crash when running inside
279the qml2puppet that is used by Qt Quick Designer to execute QML.
280Generally, the plugin should work well in the Qt Quick Designer
281and not cause any show stoppers, like taking excessive amounts of memory,
282slowing down the qml2puppet heavily, or anything else that renders
283the plugin effectively unusable in the Qt Quick Designer.
285The items of an unsupported plugin are not painted in the Qt Quick Designer,
286but they are still available as empty boxes and the properties can be edited.
288\section2 Preferred Path Declaration
294This property directs the QML engine to load any further files for this
295module from <path>, rather than the current directory. This can be used
296to load files compiled with qmlcachegen.
298For example, you can add a module's QML files as resources to a resource
299path \c{:/my/path/MyModule/}. Then, add \c{prefer :/my/path/MyModule} to
300the qmldir file in order to use the files in the resource system, rather
301than the ones in the file system. If you then use qmlcachegen for those,
302the pre-compiled files will be available to any clients of the module.
304\section1 Versioning Semantics
306All QML types that are exported for a particular major version are available
307with the latest version of the same major version. For example, if a module
308provides a \c MyButton type in version 1.0 and \c MyWindow type in version 1.1,
309clients importing version \c 1.1 of the module get to use the \c MyButton and
310\c MyWindow types. However, the reverse is not true: a type exported for a
311particular minor version cannot be used by importing an older or earlier minor
312version. In the example mentioned earlier, if the client had imported version
313\c 1.0 of the module, they can use the \c MyButton type only but not the
316A module can offer multiple major versions but the clients have access
317to one major version only at a time. For example, importing
318\c{MyExampleModule 2.0} provides access to that major version only and not
319the previous major version. Although you can organize the artifacts that belong
320to different major versions under a sigle directory and a \c qmldir file, it is
321recommended to use different directories for each major version. If you
322choose to go with the earlier approach (one directory and a \c qmldir file),
323try to use the version suffix for the file names. For example, artifacts
324that belong to \c{MyExampleModule 2.0} can use \c .2 suffix in their file name.
326A version cannot be imported if no types have been explicitly exported for that
327version. If a module provides a \c MyButton type in version 1.0 and a
328\c MyWindow type in version 1.1, you cannot import version 1.2 or version 2.0 of
331A type can be defined by different files in different minor versions. In this case,
332the most closely matching version is used when imported by clients.
333For example, if a module had specified the following types via its \c qmldir
338MyButton 1.0 MyButton.qml
339MyButton 1.1 MyButton11.qml
340MyButton 1.3 MyButton13.qml
341MyRectangle 1.2 MyRectangle12.qml
344a client who imports version \c 1.2 of \c ExampleModule can use the \c MyButton
345type definition provided by \c MyButton11.qml as it is the latest version of that
346type, and the \c MyRectangle type definition provided by \c MyRectangle12.qml.
348The version system ensures that a given QML file works regardless of the
349version of installed software, as a versioned import only imports types
350for that version, leaving other identifiers available, even if the actual
351installed version might otherwise provide those identifiers.
353\section1 Example of a qmldir File
355One example of a \c qmldir file follows:
359CustomButton 2.0 CustomButton20.qml
360CustomButton 2.1 CustomButton21.qml
362MathFunctions 2.0 mathfuncs.js
365The above \c qmldir file defines a module called "ExampleModule". It defines
366the \c CustomButton QML object type in versions 2.0 and 2.1 of the
367module, with different implementations for each version. It specifies a plugin
368that must be loaded by the engine when the module is imported by clients, and
369that plugin may register various C++-defined types with the QML type system.
370On Unix-like systems the QML engine attempts to load \c libexamplemodule.so
371as a QQmlExtensionPlugin, and on Windows it loads \c examplemodule.dll as a
372QQmlExtensionPlugin. Finally, the \c qmldir file specifies a
373\l{qtqml-javascript-resources.html}{JavaScript resource}, which is
374only available if version 2.0 or a later version (under the same major version)
375of the module is imported.
377If the module is \l{qtqml-modules-identifiedmodules.html}{installed} into the
378QML import path, clients could import and use the module in the following
383import ExampleModule 2.1
388 color: "lightsteelblue"
393 onClicked: MathFunctions.generateRandom() > 10 ? color = "red" : color = "gray";
398The \c CustomButton type used above would come from the definition specified in
399the \c CustomButton21.qml file, and the JavaScript resource identified by the
400\c MathFunctions identifier would be defined in the \c mathfuncs.js file.
402\section1 Type Description Files
404QML modules may refer to one or more type information files in their
405\c qmldir file. These usually have the \c .qmltypes
406extension and are read by external tools to gain information about
407types defined in C++ and typically imported via plugins.
409As such qmltypes files have no effect on the functionality of a QML module.
410Their only use is to allow tools such as Qt Creator to provide code completion,
411error checking and other functionality to users of your module.
413Any module that defines QML types in C++ should also ship a type description
416The best way to create a qmltypes file for your module is to generate it
417using the build system and the \l QML_ELEMENT macros. If you follow the
418documentation on this, no further action is needed. qmltyperegistrar will
419automatically generate the \c .qmltypes files.
422If your module is in \c /tmp/imports/My/Module, a file called \c plugins.qmltypes
423should be generated alongside the actual plugin binary.
427typeinfo plugins.qmltypes
429to \c /tmp/imports/My/Module/qmldir to register it.