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-identifiedmodules.html
5\title Identified Modules
6\brief Creating and importing identified modules
8Identified modules are modules that are installed and identifiable to the QML
9engine by a URI in the form of a dotted identifier string, which should be
10specified by the module in its \c qmldir file. This enables such modules to
11be imported with a unique identifier that remains the same no matter where the
12module is located on the local file system.
14When importing an identified module, an unquoted identifier is used, with an
15optional version number:
17\snippet qml/imports/installed-module.qml imports
19Identified modules must be installed into the
20\l{qtqml-syntax-imports.html#qml-import-path}{import path} in order to be found
23Syntactically, each dot-separated segment of the URI must be a well-formed
24ECMAScript Identifier Name. This means, for example, the segments must not start
25with a number and they must not contain \e{-} (minus) characters. As the URI
26will be translated into directory names, you should restrict it to alphanumeric
27characters of the latin alphabet, underscores, and dots.
29\section1 Locally Installed Identified Modules
31A directory of QML and/or C++ files can be shared as an identified module if it
32contains a \l{qtqml-modules-qmldir.html}{qmldir file} with the module metadata
33and is installed into the QML import path. Any QML file on the local file
34system can import this directory as a module by using an
35\l{qtqml-syntax-imports.html}{import} statement that refers to the module's
36URI, enabling the file to use the \l{qtqml-typesystem-objecttypes.html}
37{QML object types} and \l{qtqml-javascript-resources.html}
38{JavaScript resources} defined by the module.
40The module's \c qmldir file must reside in a directory structure within the
41\l{qtqml-syntax-imports.html#qml-import-path}{import path} that reflects the
42URI dotted identifier string, where each dot (".") in the identifier reflects
43a sub-level in the directory tree. For example, the \c qmldir file of the
44module \c com.mycompany.mymodule must be located in the sub-path
45\c com/mycompany/mymodule/qmldir somewhere in the
46\l{qtqml-syntax-imports.html#qml-import-path}{import path}.
48It is possible to store different versions of a module in subdirectories of its
49own. For example, a version 2.1 of a module could be located under
50\c com/mycompany/mymodule.2/qmldir or \c com/mycompany/mymodule.2.1/qmldir.
51The engine will automatically load the module which matches best.
53Alternatively, versioning for different types can be defined within a qmldir
54file itself, however this can make updating such a module more difficult (as a
55\c qmldir file merge must take place as part of the update procedure).
60Consider the following QML project directory structure. Under the top level
61directory \c myapp, there are a set of common UI components in a sub-directory
62named \c mycomponents, and the main application code in a sub-directory named
75To make the \c mycomponents directory available as an identified module, the
76directory must include a \l{qtqml-modules-qmldir.html}{qmldir file} that
77defines the module identifier, and describes the object types made available by
78the module. For example, to make the \c CheckBox, \c DialogBox and \c Slider
79types available for version 1.0 of the module, the \c qmldir file would contain
83module myapp.mycomponents
84CheckBox 1.0 CheckBox.qml
85DialogBox 1.0 DialogBox.qml
89Additionally, the location of the \c qmldir file in the
90\l{qtqml-syntax-imports.html#qml-import-path}{import path} must match the
91module's dotted identifier string. So, say the top level \c myapp directory is
92located in \c C:\qml\projects, and say the module should be identified as
93"myapp.mycomponents". In this case:
96\li The path \c C:\qml\projects should be added to the
97 \l{qtqml-syntax-imports.html#qml-import-path}{import path}
98\li The qmldir file should be located under \c C:\qml\projects\myapp\mycomponents\qmldir
101Once this is done, a QML file located anywhere on the local filesystem can
102import the module by referring to its URI and the appropriate version:
105import myapp.mycomponents 1.0
117\section1 Remotely Installed Identified Modules
119Identified modules are also accessible as a network resource. In the previous
120example, if the \c C:\qml\projects directory was hosted as
121\c http://www.some-server.com/qml/projects and this URL was added to the QML
122import path, the module could be imported in exactly the same way.
124Note that when a file imports a module over a network, it can only access QML
125and JavaScript resources provided by the module; it cannot access any types
126defined by C++ plugins in the module.
129\section1 Semantics of Identified Modules
131An identified module is provided with the following guarantees by the QML
134\li other modules are unable to modify or override types in the module's
136\li other modules are unable to register new types into the module's
138\li usage of type names by clients will resolve deterministically to a given
139 type definition depending on the versioning specified and the import order
142This ensures that clients which use the module can be certain that the
143object types defined in the module will behave as the module author documented.
145An identified module has several restrictions upon it:
147\li an identified module must be installed into the
148 \l{qtqml-syntax-imports.html#qml-import-path}{QML import path}
149\li the module identifier specified in the \l{qtqml-modules-qmldir.html}
150 {module identifier directive} must match the install path of the module
151 (relative to the QML import path, where directory separators are replaced
152 with period characters)
153\li the module must register its types into the module identifier type
155\li the module may not register types into any other module's namespace
158For example, if an identified module is installed into
159\c{$QML_IMPORT_PATH/ExampleModule}, the module identifier directive must be:
164If the strict module is installed into
165\c{$QML_IMPORT_PATH/com/example/CustomUi}, the module identifier directive
168module com.example.CustomUi
171Clients will then be able to import the above module with the following import
174import com.example.CustomUi