Add documentation about how to use custom modules.

We don't explain this anywhere at the moment, and users would very much
like to know.

Change-Id: Icf7c81d5931f1154d8a6fd978b8cfe5054180b4b
Reviewed-by: Jake Petroules <jake.petroules@petroules.com>
Reviewed-by: Joerg Bornemann <joerg.bornemann@digia.com>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@digia.com>

2 files changed, 75 insertions, 4 deletions

diff --git a/doc/qbs.qdoc b/doc/qbs.qdoc
index d207db332..1014b0134 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
+
+*/
diff --git a/src/lib/corelib/tools/preferences.cpp b/src/lib/corelib/tools/preferences.cpp
index 83c28a44c..2190540f1 100644
--- a/src/lib/corelib/tools/preferences.cpp
+++ b/src/lib/corelib/tools/preferences.cpp
@@ -83,8 +83,8 @@ QString Preferences::defaultBuildDirectory() const
 }
 
 /*!
- * \brief Returns the list of paths where qbs looks for module definitions and such.
- * If there is no such setting, they will be looked up at \c{baseDir}/share/qbs.
+ * \brief Returns the list of paths where qbs looks for modules and imports.
+ * In addition to user-supplied locations, they will also be looked up at \c{baseDir}/share/qbs.
  */
 QStringList Preferences::searchPaths(const QString &baseDir) const
 {
@@ -93,7 +93,7 @@ QStringList Preferences::searchPaths(const QString &baseDir) const
 
 /*!
  * \brief Returns the list of paths where qbs looks for plugins.
- * If there is no such setting, they will be looked up at \c{baseDir}/qbs/plugins.
+ * In addition to user-supplied locations, they will be looked up at \c{baseDir}/qbs/plugins.
  */
 QStringList Preferences::pluginPaths(const QString &baseDir) const
 {