1 files changed, 198 insertions, 0 deletions
diff --git a/src/qml/doc/src/modules/identifiedmodules.qdoc b/src/qml/doc/src/modules/identifiedmodules.qdoc
new file mode 100644
index 0000000000..fd7a339db9
--- /dev/null
+++ b/src/qml/doc/src/modules/identifiedmodules.qdoc
@@ -0,0 +1,198 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+\page qtqml-modules-identifiedmodules.html
+\title Identified Modules
+\brief Creating and importing identified modules
+
+Identified modules are modules that are installed and identifiable to the QML
+engine by a URI in the form of a dotted identifier string, which should be
+specified by the module in its \c qmldir file.  This enables such modules to
+be imported with a unique identifier that remains the same no matter where the
+module is located on the local file system.
+
+When importing an identified module, an unquoted identifier is used, with a
+mandatory version number:
+
+\snippet qml/imports/installed-module.qml imports
+
+Identified modules must be installed into the
+\l{qtqml-syntax-imports.html#qml-import-path}{import path} in order to be found
+by the QML engine.
+
+\section1 Locally Installed Identified Modules
+
+A directory of QML and/or C++ files can be shared as an identified module if it
+contains a \l{qtqml-modules-qmldir.html}{qmldir file} with the module metadata
+and is installed into the QML import path.  Any QML file on the local file
+system can import this directory as a module by using an
+\l{qtqml-syntax-imports.html}{import} statement that refers to the module's
+URI, enabling the file to use the \l{qtqml-typesystem-objecttypes.html}
+{QML object types} and \l{qtqml-javascript-resources.html}
+{JavaScript resources} defined by the module.
+
+The module's \c qmldir file must reside in a directory structure within the
+\l{qtqml-syntax-imports.html#qml-import-path}{import path} that reflects the
+URI dotted identifier string, where each dot (".") in the identifier reflects
+a sub-level in the directory tree. For example, the \c qmldir file of the
+module \c com.mycompany.mymodule must be located in the sub-path
+\c com/mycompany/mymodule/qmldir somewhere in the
+\l{qtqml-syntax-imports.html#qml-import-path}{import path}.
+
+It is possible to store different versions of a module in subdirectories of its
+own. For example, a version 2.1 of a module could be located under
+\c com/mycompany/mymodule.2/qmldir or \c com/mycompany/mymodule.2.1/qmldir.
+The engine will automatically load the module which matches best.
+
+Alternatively, versioning for different types can be defined within a qmldir
+file itself, however this can make updating such a module more difficult (as a
+\c qmldir file merge must take place as part of the update procedure).
+
+
+\section2 An Example
+
+Consider the following QML project directory structure. Under the top level
+directory \c myapp, there are a set of common UI components in a sub-directory
+named \c mycomponents, and the main application code in a sub-directory named
+\c main, like this:
+
+\code
+myapp
+    |- mycomponents
+        |- CheckBox.qml
+        |- DialogBox.qml
+        |- Slider.qml
+    |- main
+        |- application.qml
+\endcode
+
+To make the \c mycomponents directory available as an identified module, the
+directory must include a \l{qtqml-modules-qmldir.html}{qmldir file} that
+defines the module identifier, and describes the object types made available by
+the module. For example, to make the \c CheckBox, \c DialogBox and \c Slider
+types available for version 1.0 of the module, the \c qmldir file would contain
+the following:
+
+\code
+module myapp.mycomponents
+CheckBox 1.0 CheckBox.qml
+DialogBox 1.0 DialogBox.qml
+Slider 1.0 Slider.qml
+\endcode
+
+Additionally, the location of the \c qmldir file in the
+\l{qtqml-syntax-imports.html#qml-import-path}{import path} must match the
+module's dotted identifier string. So, say the top level \c myapp directory is
+located in \c C:\qml\projects, and say the module should be identified as
+"myapp.mycomponents". In this case:
+
+\list
+\li The path \c C:\qml\projects should be added to the
+    \l{qtqml-syntax-imports.html#qml-import-path}{import path}
+\li The qmldir file should be located under \c C:\qml\projects\myapp\mycomponents\qmldir
+\endlist
+
+Once this is done, a QML file located anywhere on the local filesystem can
+import the module by referring to its URI and the appropriate version:
+
+\qml
+import myapp.mycomponents 1.0
+
+DialogBox {
+    CheckBox {
+        // ...
+    }
+    Slider {
+        // ...
+    }
+}
+\endqml
+
+\section1 Remotely Installed Identified Modules
+
+Identified modules are also accessible as a network resource. In the previous
+example, if the \c C:\qml\projects directory was hosted as
+\c http://www.some-server.com/qml/projects and this URL was added to the QML
+import path, the module could be imported in exactly the same way.
+
+Note that when a file imports a module over a network, it can only access QML
+and JavaScript resources provided by the module; it cannot access any types
+defined by C++ plugins in the module.
+
+
+\section1 Semantics of Identified Modules
+
+An identified module is provided with the following guarantees by the QML
+engine:
+\list
+\li other modules are unable to modify or override types in the module's
+    namespace
+\li other modules are unable to register new types into the module's
+    namespace
+\li usage of type names by clients will resolve deterministically to a given
+    type definition depending on the versioning specified and the import order
+\endlist
+
+This ensures that clients which use the module can be certain that the
+object types defined in the module will behave as the module author documented.
+
+An identified module has several restrictions upon it:
+\list
+\li an identified module must must be installed into the
+    \l{qtqml-syntax-imports.html#qml-import-path}{QML import path}
+\li the module identifier specified in the \l{qtqml-modules-qmldir.html}
+    {module identifier directive} must match the install path of the module
+    (relative to the QML import path, where directory separators are replaced
+    with period characters)
+\li the module must register its types into the module identifier type
+    namespace
+\li the module may not register types into any other module's namespace
+\li clients must specify a version when importing the module
+\endlist
+
+For example, if an identified module is installed into
+\c{$QML_IMPORT_PATH/ExampleModule}, the module identifier directive must be:
+\code
+module ExampleModule
+\endcode
+
+If the strict module is installed into
+\c{$QML_IMPORT_PATH/com/example/CustomUi}, the module identifier directive
+must be:
+\code
+module com.example.CustomUi
+\endcode
+
+Clients will then be able to import the above module with the following import
+statement (assuming that the module registers types into version 1.0 of its
+namespace):
+\qml
+import com.example.CustomUi 1.0
+\endqml
+
+*/
+