Merge branch '1.3' into master.

Conflicts:
	qbs_version.pri
	src/app/qbs/commandlinefrontend.cpp
	src/lib/corelib/language/projectresolver.cpp
	version.js

Change-Id: I6b8a09faed7970821955ac329b0c244ddffb037c

1 files changed, 72 insertions, 1 deletions

diff --git a/doc/qbs.qdoc b/doc/qbs.qdoc
index d94475518..64fb1161c 100644
--- a/doc/qbs.qdoc
+++ b/doc/qbs.qdoc
@@ -70,6 +70,7 @@
                \li  \l{Running Applications}
                \li  \l{Installing Files}
                \li  \l{Using the Shell}
+               \li  \l{Custom Modules and Items}
            \endlist
        \li  \l{Reference}
     \endlist
@@ -276,6 +277,7 @@
         \li  \l{Running Applications}
         \li  \l{Installing Files}
         \li  \l{Using the Shell}
+        \li  \l{Custom Modules and Items}
     \endlist
 
 */
@@ -741,7 +743,7 @@
     \contentspage index.html
     \previouspage installing-files.html
     \page shell.html
-    \nextpage reference.html
+    \nextpage custom-modules.html
 
     \title Using the Shell
 
@@ -756,3 +758,72 @@
     will be set up.
 
 */
+
+/*!
+    \contentspage index.html
+    \previouspage shell.html
+    \page custom-modules.html
+    \nextpage reference.html
+
+    \title Custom Modules and Items
+
+    Users of \QBS are not limited to the pre-defined \l{List of Modules}{modules} and
+    \l{List of Language Items}{items}, they can also create their own. Here we describe how
+    to set up custom modules and items so that \QBS will find them.
+
+    \section1 File System Layout
+
+    Items and modules are located under a common base directory, whose name and location is
+    completely arbitrary. We will refer to it as \c search-path here. This directory has two
+    subdirectories \c modules and \c imports, which contain \QBS modules and items, respectively.
+
+
+    \section1 Custom Modules
+
+    To introduce a custom module \c mymodule, create a directory \c{search-path/modules/mymodule/}.
+    \note Module names are case-sensitive, and this also goes for the corresponding directory name.
+
+    Then, put a file containing an instance of the \l{Module Item} in there and give it the \c{.qbs}
+    extension. This module will be pulled in if a
+    \l{Product Item}{product} declares a \l{Depends Item}{dependency} on \c mymodule.
+
+
+    \section1 Custom Items
+
+    To introduce a custom item \c MyItem, create the file \c{search-path/imports/MyItem.qbs}.
+
+
+    \section1 Making \QBS Aware of Custom Modules and Items
+
+    To be able to use your custom modules and items, you need to make them known to \QBS. You can
+    do this per project or globally.
+
+    \section2 Project-specific Modules and Items
+
+    Let's assume you have a project that is located in \c{project_dir} and you have created some
+    modules in \c{project_dir/custom-stuff/modules/} as well as some items in
+    \c{project_dir/custom-stuff/imports/} that you want to use in the project.
+    To achieve this, your top-level project file should look like this:
+    \code
+    // ...
+    Project {
+        // ..
+        qbsSearchPaths: "custom-stuff"
+        // ..
+    }
+    \endcode
+    \note For technical reasons, the custom modules and items will not be available in the file
+          that contains the \c qbsSearchPaths property. Any product that wants
+          to make use of them needs to be in a different file that is pulled in
+          via the \c references property, for example. This is not a serious limitation, since
+          every well-structured project will be split up in this manner.
+
+    \section2 Making Custom Modules and Items Available Across Projects
+
+    What if your modules and items are generally useful and you want to access them in several
+    projects? In this case, it's best to add the location to your preferences. For example:
+    \code
+    qbs config preferences.qbsSearchPaths /usr/local/share/custom-qbs-extensions
+    \endcode
+
+*/