Git commit b9d905dff7bf8aaa0d943d96bac2bf69494161fe by Andrew Shark. Committed on 05/01/2024 at 19:56. Pushed by ashark into branch 'master'.
doc: appendix-modules - separate docbook A +131 -0 doc/appendix-modules.docbook M +2 -131 doc/index.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/b9d905dff7bf8aaa0d943d96bac2bf69494161fe diff --git a/doc/appendix-modules.docbook b/doc/appendix-modules.docbook new file mode 100644 index 00000000..109f2daf --- /dev/null +++ b/doc/appendix-modules.docbook @@ -0,0 +1,131 @@ +<appendix id="appendix-modules"> +<title>&kde; modules and source code organization</title> +<sect1 id="module-concept"> +<title>The <quote>Module</quote></title> + +<para>&kde; groups its software into <quote>modules</quote> of various size. +This was initially a loose grouping of a few large modules, but with the +introduction of the <ulink url="https://git-scm.com/";>Git</ulink>-based <ulink +url="https://commits.kde.org/";>source code repositories</ulink>, these large +modules were further split into many smaller modules. +</para> + +<para>&kdesrc-build; uses this module concept as well. In essence, a +<quote>module</quote> is a grouping of code that can be downloaded, built, +tested, and installed. +</para> + +<sect2 id="single-modules"> +<title>Individual modules</title> + +<para>It is easy to set &kdesrc-build; to build a single module. The following +listing is an example of what a declaration for a Git-based module would +look like in <link linkend="kdesrc-buildrc">the configuration +file</link>.</para> + +<programlisting> +module <replaceable>kdefoo</replaceable> + <option><replaceable>cmake-options -DCMAKE_BUILD_TYPE=Debug</replaceable></option> +end module +</programlisting> + +<tip><para>This is a Git-based module since it doesn't use a <link +linkend="conf-repository">repository</link> option. Also, the +<option>cmake-options</option> option is listed as an example only, it is not +required.</para></tip> + +</sect2> +<sect2 id="module-groups"> +<title>Groups of related modules</title> + +<para>Now most &kde; source modules are Git-based &kde;, and are normally +combined into groups of modules.</para> + +<para>&kdesrc-build; therefore supports groups of modules as well, using +<link linkend="module-sets">module sets</link>. An example:</para> + +<programlisting> +module-set <replaceable>base-modules</replaceable> + <option>repository</option> kde-projects + <option>use-modules</option> <replaceable>kde-runtime kde-workspace kde-baseapps</replaceable> +end module-set +</programlisting> + +<tip><para>You can leave the module set name (<replaceable>base-modules</replaceable> +in this case) empty if you like. This <option>repository</option> setting tells +&kdesrc-build; where to download the source from, but you can also use a +<symbol>git://</symbol> URL.</para></tip> + +<para>One special feature of the <quote><option>repository</option> +<literal>kde-projects</literal></quote> is that &kdesrc-build; will +automatically include any Git modules that are grouped under the modules you +list (in the KDE Project database).</para> +</sect2> + +<sect2 id="module-branch-groups"> +<title>Module <quote>branch groups</quote></title> + +<para>Taking the concept of a <link linkend="module-groups">group of +modules</link> further, the &kde; developers eventually found that +synchronizing the names of the Git branches across a large number of +repositories was getting difficult, especially during the development push for +the new &kde; Frameworks for &Qt; 5. +</para> + +<para>So the concept of <quote>branch groups</quote> was developed, to allow +users and developers to select one of only a few groups, and allow the script +to automatically select the appropriate Git branch. +</para> + +<para>&kdesrc-build; supports this feature as of version 1.16-pre2, via the +<link linkend="conf-branch-group">branch-group</link> option. +</para> + +<example id="ex-branch-group"> +<title>Example of using branch-group</title> + +<para>branch-group can be used in the configuration file as follows: +</para> + +<programlisting> +global + # Select KDE Frameworks 5 and other Qt5-based apps + <option>branch-group</option> <replaceable>kf5-qt5</replaceable> + + # Other global options here ... +end global + +module-set + # branch-group only works for kde-projects + <option>repository</option> kde-projects + + # branch-group is inherited from the one set globally, but could + # specified here. + + <option>use-modules</option> <replaceable>kdelibs kde-workspace</replaceable> +end module-set + +# kdelibs's branch will be "frameworks" +# kde-workspace's branch will be "master" (as of August 2013) +</programlisting> + +<para>In this case the same <literal>branch-group</literal> gives different +branch names for each Git module. +</para> +</example> + +<para>This feature requires some data maintained by the &kde; developers in a Git +repository named <literal>kde-build-metadata</literal>, however this module +will be included automatically by &kdesrc-build; (though you may see it appear +in the script output). +</para> + +<tip><para>&kde; modules that do not have a set branch name for the branch +group you choose will default to an appropriate branch name, as if you had not +specified <literal>branch-group</literal> at all. +</para></tip> + +</sect2> + +</sect1> +</appendix> diff --git a/doc/index.docbook b/doc/index.docbook index 228b67bb..db3eddcf 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -68,6 +68,7 @@ Just add them as necessary. --> <!ENTITY advanced-features SYSTEM "advanced-features.docbook"> + <!ENTITY appendix-modules SYSTEM "appendix-modules.docbook"> ]> <book id="kdesrc-build" lang="&language;"> @@ -4388,137 +4389,7 @@ as of &kdesrc-build; version 1.6.3. </chapter> -<appendix id="appendix-modules"> -<title>&kde; modules and source code organization</title> -<sect1 id="module-concept"> -<title>The <quote>Module</quote></title> - -<para>&kde; groups its software into <quote>modules</quote> of various size. -This was initially a loose grouping of a few large modules, but with the -introduction of the <ulink url="https://git-scm.com/";>Git</ulink>-based <ulink -url="https://commits.kde.org/";>source code repositories</ulink>, these large -modules were further split into many smaller modules. -</para> - -<para>&kdesrc-build; uses this module concept as well. In essence, a -<quote>module</quote> is a grouping of code that can be downloaded, built, -tested, and installed. -</para> - -<sect2 id="single-modules"> -<title>Individual modules</title> - -<para>It is easy to set &kdesrc-build; to build a single module. The following -listing is an example of what a declaration for a Git-based module would -look like in <link linkend="kdesrc-buildrc">the configuration -file</link>.</para> - -<programlisting> -module <replaceable>kdefoo</replaceable> - <option><replaceable>cmake-options -DCMAKE_BUILD_TYPE=Debug</replaceable></option> -end module -</programlisting> - -<tip><para>This is a Git-based module since it doesn't use a <link -linkend="conf-repository">repository</link> option. Also, the -<option>cmake-options</option> option is listed as an example only, it is not -required.</para></tip> - -</sect2> -<sect2 id="module-groups"> -<title>Groups of related modules</title> - -<para>Now most &kde; source modules are Git-based &kde;, and are normally -combined into groups of modules.</para> - -<para>&kdesrc-build; therefore supports groups of modules as well, using -<link linkend="module-sets">module sets</link>. An example:</para> - -<programlisting> -module-set <replaceable>base-modules</replaceable> - <option>repository</option> kde-projects - <option>use-modules</option> <replaceable>kde-runtime kde-workspace kde-baseapps</replaceable> -end module-set -</programlisting> - -<tip><para>You can leave the module set name (<replaceable>base-modules</replaceable> -in this case) empty if you like. This <option>repository</option> setting tells -&kdesrc-build; where to download the source from, but you can also use a -<symbol>git://</symbol> URL.</para></tip> - -<para>One special feature of the <quote><option>repository</option> -<literal>kde-projects</literal></quote> is that &kdesrc-build; will -automatically include any Git modules that are grouped under the modules you -list (in the KDE Project database).</para> -</sect2> - -<sect2 id="module-branch-groups"> -<title>Module <quote>branch groups</quote></title> - -<para>Taking the concept of a <link linkend="module-groups">group of -modules</link> further, the &kde; developers eventually found that -synchronizing the names of the Git branches across a large number of -repositories was getting difficult, especially during the development push for -the new &kde; Frameworks for &Qt; 5. -</para> - -<para>So the concept of <quote>branch groups</quote> was developed, to allow -users and developers to select one of only a few groups, and allow the script -to automatically select the appropriate Git branch. -</para> - -<para>&kdesrc-build; supports this feature as of version 1.16-pre2, via the -<link linkend="conf-branch-group">branch-group</link> option. -</para> - -<example id="ex-branch-group"> -<title>Example of using branch-group</title> - -<para>branch-group can be used in the configuration file as follows: -</para> - -<programlisting> -global - # Select KDE Frameworks 5 and other Qt5-based apps - <option>branch-group</option> <replaceable>kf5-qt5</replaceable> - - # Other global options here ... -end global - -module-set - # branch-group only works for kde-projects - <option>repository</option> kde-projects - - # branch-group is inherited from the one set globally, but could - # specified here. - - <option>use-modules</option> <replaceable>kdelibs kde-workspace</replaceable> -end module-set - -# kdelibs's branch will be "frameworks" -# kde-workspace's branch will be "master" (as of August 2013) -</programlisting> - -<para>In this case the same <literal>branch-group</literal> gives different -branch names for each Git module. -</para> -</example> - -<para>This feature requires some data maintained by the &kde; developers in a Git -repository named <literal>kde-build-metadata</literal>, however this module -will be included automatically by &kdesrc-build; (though you may see it appear -in the script output). -</para> - -<tip><para>&kde; modules that do not have a set branch name for the branch -group you choose will default to an appropriate branch name, as if you had not -specified <literal>branch-group</literal> at all. -</para></tip> - -</sect2> - -</sect1> -</appendix> +&appendix-modules; <appendix id="appendix-profile"> <title>Superseded profile setup procedures</title>
