[sdk/kdesrc-build/docbook_historied_per_file] doc/getting-started: Document kde-projects module grouping feature.

[Michael Pyne]

Git commit 1b87ff4055b51db4449c97dca1489f460595ff01 by Michael Pyne.
Committed on 28/02/2011 at 02:25.
Pushed by ashark into branch 'docbook_historied_per_file'.

Document kde-projects module grouping feature.

Original commit: 71b9a962
https://invent.kde.org/sdk/kdesrc-build/-/commit/71b9a9627fc87a142f6836aef2aed93e500b44f0

M  +104  -2    doc/getting-started/kde-modules-and-selection.docbook

https://invent.kde.org/sdk/kdesrc-build/-/commit/1b87ff4055b51db4449c97dca1489f460595ff01

diff --git a/doc/getting-started/kde-modules-and-selection.docbook b/doc/getting-started/kde-modules-and-selection.docbook
index 665fc8f5..0db4a038 100644
--- a/doc/getting-started/kde-modules-and-selection.docbook
+++ b/doc/getting-started/kde-modules-and-selection.docbook
@@ -148,7 +148,7 @@ module <replaceable>qt-copy</replaceable>
     # Options removed for brevity
 end module
 
-module-set # Note there's no name for this (or any) set
+module-set <replaceable>kde-support-libs</replaceable>
     <option><link linkend="conf-repository">repository</link></option> <replaceable>kde-git</replaceable>
     <option><link linkend="conf-use-modules">use-modules</link></option> <replaceable>automoc</replaceable> <replaceable>attica</replaceable> <replaceable>akonadi</replaceable>
 end module-set
@@ -169,11 +169,113 @@ module name.</para>
 <para>In addition, other options can be passed in a module set, which are
 copied to every new module that is created this way. By using module-set it is
 possible to quickly declare many Git modules that are all based on the same
-repository URL.</para>
+repository URL. In addition, since &kdesrc-build; 1.13, it is possible to
+give module-sets a name (as shown in the example), which allows you to quickly
+refer to the entire group of modules from the command line.</para>
+
+<note><para>Module sets are used in supporting module downloads from
+the &kde; <ulink url="https://projects.kde.org/">projects.kde.org</ulink>
+module database. See also <xref linkend="kde-projects-module-sets"/>.
+</para></note>
 
 <para>Module sets use the options <simplelist><member><link
 linkend="conf-git-repository-base">git-repository-base</link></member>
 <member><link
 linkend="conf-use-modules">use-modules</link></member></simplelist></para>
 </sect2>
+
+<sect2 id="kde-projects-module-sets">
+<title>Automatically finding modules from the official &kde; module
+database</title>
+
+<para>With the migration of &kde; source code to be hosted on git.kde.org,
+there has been an explosive growth in the number of modules (for instance,
+a single Subversion module called <literal>kdegraphics</literal> becomes
+16 different Git modules).</para>
+
+<para>This was done mostly because each Git module contains the entire project
+history (this is actually less wasteful of disk space than it sounds for the
+vast majority of &kde; repositories as &git; is highly efficient at storing
+repositories).</para>
+
+<para>&kde; allows for grouping Git repositories into collections
+of related modules (e.g. kdegraphics). These modules can themselves be grouped
+(e.g. &kde; Software Compilation). Git doesn't recognize these groupings, but
+&kdesrc-build; can be configured to handle these groups.</para>
+
+<para>The way this is done is by using <link linkend="module-sets">module
+sets</link>. Instead of using a specific <literal>git://</literal> repository,
+or a repository name created by <link
+linkend="conf-git-repository-base">git-repository-base</link>, a special
+repository name, <quote><literal>kde-projects</literal></quote> is used.</para>
+
+<para>&kdesrc-build; will recognize that the <literal>kde-projects</literal>
+repository requires special handling, and adjust the build process
+appropriately.  Among other things, &kdesrc-build; will:</para>
+
+<itemizedlist>
+
+<listitem><para>Download the latest module database from <ulink
+url="https://projects.kde.org/">projects.kde.org</ulink>.</para></listitem>
+
+<listitem><para>Try to find a module with the name given in the module set's
+<option>use-modules</option> setting.</para></listitem>
+
+<listitem><para>For every module that is found, &kdesrc-build; will see if a
+repository setting exists for that module in the database. If there is a
+repository, &kdesrc-build; will automatically use that to download or update
+the source code. If there is no repository, &kdesrc-build; treats that module
+like a group, and tries to include all &git; source repositories that it finds
+in that group.</para></listitem>
+
+</itemizedlist>
+
+<note><para>In the current database, some module groups not only have a
+collection of modules, but they <emphasis>also</emphasis> declare their own
+&git; repository. In these situations &kdesrc-build; will currently prefer the
+group's &git; repository instead of including the childrens' repositories.
+</para></note>
+
+<para>The following example shows how to use the &kde; module database to
+install the Phonon multimedia library.</para>
+
+<informalexample>
+<programlisting>
+module-set <replaceable>media-support</replaceable>
+    # This option must be kde-projects to use the module database.
+    <option><link linkend="conf-repository">repository</link></option> <literal>kde-projects</literal>
+
+    # This option chooses what modules to look for in the database.
+    <option><link linkend="conf-use-modules">use-modules</link></option> <replaceable>phonon</replaceable> <replaceable>phonon-gstreamer</replaceable> <replaceable>phonon-vlc</replaceable>
+end module-set
+</programlisting>
+</informalexample>
+
+<para>The following example is perhaps more realistic, and shows a feature only
+available with the &kde; module database: Building all of the &kde; Extragear
+with only a single declaration (32 individual applications/libraries as of this
+writing).</para>
+
+<important><para>Some things to keep in mind: This represents a significant
+amount of disk space and build time, not to mention network traffic. You
+probably don't actually want to build the entire Extragear suite at once.
+In addition, at this point &kdesrc-build; builds modules in the order they are
+given in the database, but this is not necessarily the proper order after all
+inter-module dependencies are accounted for, which may cause build failures.
+</para></important>
+
+<informalexample>
+<programlisting>
+module-set <replaceable>never-try-this</replaceable>
+    # This option must be kde-projects to use the module database.
+    <option><link linkend="conf-repository">repository</link></option> <literal>kde-projects</literal>
+
+    # This option chooses what modules to look for in the database.
+    <option><link linkend="conf-use-modules">use-modules</link></option> <replaceable>extragear</replaceable>
+end module-set
+</programlisting>
+</informalexample>
+
+</sect2>
+
 </sect1>