[sdk/kdesrc-build/docbook_historied_per_file] doc: Merge kdesrc-build doc updates from svn.

Michael Pyne null at kde.org
Fri May 10 10:15:11 BST 2024


Git commit 6c0bf1b29e0a9d7bebd9b7cc56fa8d20b6d6dae9 by Michael Pyne.
Committed on 30/01/2011 at 03:05.
Pushed by ashark into branch 'docbook_historied_per_file'.

Merge kdesrc-build doc updates from svn.

Awhile ago I started a subversion work branch so that I could
continue to update the Docbook docs for kdesrc-build. Now that
kdesrc-build is out of the SC (and the freeze is up anyways) I
can merge the changes/fixes back in.

Original commit: d066e357
https://invent.kde.org/sdk/kdesrc-build/-/commit/d066e3572f21e18f57b88eb51590d231c251c4fb

M  +5    -4    doc/getting-started/before-building.docbook
M  +55   -12   doc/getting-started/building-and-troubleshooting.docbook
M  +4    -20   doc/getting-started/configure-data.docbook
M  +2    -0    doc/getting-started/index.docbook
A  +179  -0    doc/getting-started/kde-modules-and-selection.docbook
M  +3    -2    doc/index.docbook
M  +1    -1    doc/introduction/index.docbook
M  +94   -1    doc/kdesrc-buildrc/conf-options-table.docbook

https://invent.kde.org/sdk/kdesrc-build/-/commit/6c0bf1b29e0a9d7bebd9b7cc56fa8d20b6d6dae9

diff --git a/doc/getting-started/before-building.docbook b/doc/getting-started/before-building.docbook
index 5d26642c..2f2026e4 100644
--- a/doc/getting-started/before-building.docbook
+++ b/doc/getting-started/before-building.docbook
@@ -50,10 +50,11 @@ should be set to go.</para></listitem>
 
 <listitem><para>If you are building &Qt; or any of the various &kde; modules
 that are available from <ulink url="http://gitorious.org/">Gitorious</ulink>
-then you will need the <ulink url="http://gitscm.org/">Git source control
-manager</ulink> installed as well.</para></listitem>
+(for &Qt;) or &kde;'s <ulink url="http://projects.kde.org/">git-based
+projects</ulink> then you will need the <ulink url="http://gitscm.org/">Git
+source control manager</ulink> installed as well.</para></listitem>
 
-<listitem><para>You will need a C++ development environment. GCC 3.4 or
+<listitem><para>You will need a C++ development environment. GCC 4.1 or
 later is recommended.</para></listitem>
 
 </itemizedlist>
@@ -86,7 +87,7 @@ to use the &Qt; copy, you need to do these things:</para>
 <listitem>
   <para>If you do not already have &Qt; installed, install it, including any
   relevant -dev or -devel packages. You will need at least
-  &Qt; 4.6 if you are building &kde; 4.</para>
+  &Qt; 4.7 if you are building &kde; 4.</para>
 </listitem>
 </itemizedlist>
 
diff --git a/doc/getting-started/building-and-troubleshooting.docbook b/doc/getting-started/building-and-troubleshooting.docbook
index d414d44a..b1e2a2e6 100644
--- a/doc/getting-started/building-and-troubleshooting.docbook
+++ b/doc/getting-started/building-and-troubleshooting.docbook
@@ -6,14 +6,43 @@ Now you are ready to run the script. From a terminal window,
 log in to the user you are using to compile &kde; and execute
 the script:
 <screen>
-<prompt>$</prompt><command>kdesrc-build</command>
+<prompt>%</prompt> <userinput><command>kdesrc-build</command></userinput>
 </screen>
 </para>
 
+<para>Afterwards, you should see output similar to that in <xref
+linkend="example-single-module"/>:</para>
+
+<example id="example-single-module">
+<title>Example output of building a single module</title>
+<screen>
+<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>kdelibs</option></userinput>
+Script started processing at Wed Dec 22 13:21:45 2010
+<<<  Build Process  >>>
+Building kdelibs (1/1)
+        Waiting for source code update.
+        Source update complete for kdelibs: 48 files affected.
+        Checking for source conflicts...
+        Compiling...
+        Build succeeded after 13 minutes, and 6 seconds.
+        Installing kdelibs.
+        Overall time for kdelibs was 13 minutes, and 53 seconds.
+
+<<<  Build Done  >>>
+
+<<<  PACKAGES SUCCESSFULLY BUILT  >>>
+kdelibs
+
+Script finished processing at Wed Dec 22 13:35:38 2010
+Your logs are saved in /home/kde-src/log-kdesrc-build/2010-12-22-01
+</screen>
+</example>
+
 <para>
-Now, the script should start downloading the sources and compiling them. Depending on
-how many modules you are downloading, it is possible that &kdesrc-build;
-will not succeed the first time you compile &kde;. Do not despair!
+At this point, &kdesrc-build; should start downloading the sources and
+compiling them. Depending on how many modules you are downloading, it is
+possible that &kdesrc-build; will not succeed the first time you compile &kde;.
+Do not despair!
 </para>
 
 <para>&kdesrc-build; logs the output of every command it runs. By default,
@@ -21,18 +50,28 @@ the log files are kept in <filename class="directory">~/kdesrc/log</filename>. T
 the caused an error for a module in the last &kdesrc-build; command, usually
 it is sufficient to look at <filename class="directory">~/kdesrc/log/latest/<replaceable>module-name</replaceable>/error.log</filename>.</para>
 
+<tip><para>Perhaps the easiest way to find out what error caused a module to
+fail to build is to search backward with a case-insensitive search, starting
+from the end of the file looking for the word <literal>error</literal>.  Once
+that is found, scroll up to make sure there are no other error messages nearby.
+The first error message in a group is usually the underlying
+problem.</para></tip>
+
 <para>In that file, you will see the error that caused the build to fail for
 that module. If the file says (at the bottom) that you are missing some
 packages, try installing the package (including any appropriate -dev packages)
-before trying to build that module, and pass the <link
-linkend="cmdline-reconfigure">--reconfigure</link> option after installing the
-missing packages.</para>
+before trying to build that module again. Make sure that when you run
+&kdesrc-build; again to pass the <link
+linkend="cmdline-reconfigure">--reconfigure</link> option so that
+&kdesrc-build; forces the module to check for the missing packages
+again.</para>
 
-<para>Or, if the error appears to be a build error then it is probably an error
-with the &kde; source, which will hopefully be resolved within a few days. If
-it is not resolved within that time, feel free to mail the
-<email>kde-devel at kde.org</email> mailing list (subscription may be required
-first) in order to report the build failure.</para>
+<para>Or, if the error appears to be a build error (such as a syntax error,
+<quote>incorrect prototype</quote>, <quote>unknown type</quote>, or similar)
+then it is probably an error with the &kde; source, which will hopefully be
+resolved within a few days. If it is not resolved within that time, feel free
+to mail the <email>kde-devel at kde.org</email> mailing list (subscription may be
+required first) in order to report the build failure.</para>
 
 <para>You can find more common examples of things that can go wrong and their
 solutions, as well as general tips and strategies to build &kde; in the
@@ -40,6 +79,10 @@ solutions, as well as general tips and strategies to build &kde; in the
 Building &kde; 4 from Source</ulink>.
 </para>
 
+<para>On the other hand, assuming everything went well, you should have a new
+&kde; install on your computer, and now it is simply a matter of running
+it, described next in <xref linkend="environment"/>.</para>
+
 <note><para>For more information about &kdesrc-build;'s logging features,
 please see <xref linkend="kdesrc-build-logging"/>.</para></note>
 
diff --git a/doc/getting-started/configure-data.docbook b/doc/getting-started/configure-data.docbook
index 30b542d8..149c9ed4 100644
--- a/doc/getting-started/configure-data.docbook
+++ b/doc/getting-started/configure-data.docbook
@@ -24,10 +24,6 @@ The default settings should actually already be appropriate to perform a
 &kde; build. Some settings that you may wish to alter include:
 
 <itemizedlist>
-<listitem><para><link linkend="conf-binpath">binpath</link>, to change the list of
-directories that will be searched for commands. This is exactly the same as
-the <envar>PATH</envar> variable in the shell.</para></listitem>
-
 <listitem><para><link linkend="conf-kdedir">kdedir</link>, which changes the
 destination directory that &kde; is installed to. This defaults to
 <filename class="directory">~/kde</filename>, which is a single-user installation.</para></listitem>
@@ -38,7 +34,8 @@ by &kdesrc-build;, using the special qt-copy module and the latest available
 source code.
 (<filename class="directory">~/kdesrc/build/qt-copy</filename>).</para>
 
-<para>This also controls where to install qt-copy.</para></listitem>
+<note><para>This also controls where to install qt-copy.</para></note>
+</listitem>
 
 <listitem><para><link linkend="conf-svn-server">svn-server</link>, which
 selects what &url; to download the sources from. This is useful if you are a
@@ -47,19 +44,6 @@ developer with a <ulink url="http://techbase.kde.org/Contribute/First_Steps_with
 </itemizedlist>
 </para>
 
-<para>
-After the global section is a list of modules to build, bracketed by
-module ... end module lines. Check if the listed modules are in fact the
-modules you want to build. The default options from the
-<filename>kdesrc-buildrc-sample</filename> file should be enough to get a
-fairly complete &kde; installation. Save the result as
-<filename>.kdesrc-buildrc</filename> in your home folder.
-</para>
-
-<para>
-If you wish to fine tune your <filename>.kdesrc-buildrc</filename>,
-consult <xref linkend="kdesrc-buildrc" /> for detailed information
-about all configuration options.
-</para>
-
+<para>Continue to <xref linkend="kde-modules-and-selection"/> to see how to
+change how much of &kde; is built.</para>
 </sect1>
diff --git a/doc/getting-started/index.docbook b/doc/getting-started/index.docbook
index ce6a64a4..0a9f0763 100644
--- a/doc/getting-started/index.docbook
+++ b/doc/getting-started/index.docbook
@@ -23,6 +23,8 @@ strategies and information about running your new &kde; installation.
 
 &configure-data;
 
+&kde-modules-and-selection;
+
 &building-and-troubleshooting;
 
 &environment;
diff --git a/doc/getting-started/kde-modules-and-selection.docbook b/doc/getting-started/kde-modules-and-selection.docbook
new file mode 100644
index 00000000..ae86ee46
--- /dev/null
+++ b/doc/getting-started/kde-modules-and-selection.docbook
@@ -0,0 +1,179 @@
+<sect1 id="kde-modules-and-selection">
+<title>Module Organization and selection</title>
+
+<sect2 id="kde-layers">
+<title>KDE Software Organization</title>
+
+<para>
+&kde; software is split into different components, many of which can be built
+by &kdesrc-build;. Understanding this organization will help you properly
+select the software modules that you want built.
+</para>
+
+<orderedlist>
+<listitem><para>At the lowest level comes Nokia's &Qt; library, which is a
+very powerful, cross-platform <quote>toolkit</quote> library. &kde; is based on
+&Qt;, and some of the non-&kde; libraries required by &kde; are also based on
+&Qt;. &kdesrc-build; can build &Qt;, or use the one already installed on your
+system if it is a recent enough version.</para></listitem>
+
+<listitem><para>On top of &Qt; are required libraries that are necessary for
+&kde; software to work. Some of these libraries are not considered part of
+&kde; itself due to their generic nature, but are still essential to the &kde;
+Platform. These libraries tended to get combined into a single
+<literal>kdesupport</literal> module.</para>
+
+<note><para>As of &kde; Platform 4.6, many of these kdesupport modules are being
+migrated over to <ulink url="http://projects.kde.org/">git.kde.org</ulink>,
+although they are still not considered part of the Platform.</para></note>
+</listitem>
+
+<listitem><para>On top of these essential libraries comes the &kde; Platform.
+These are the libraries that are required for &kde; applications to work. A
+full desktop environment is not provided by the Platform however.
+</para>
+
+<para>For &kdesrc-build;, the Platform layer consists of the <literal>kdelibs</literal>,
+<literal>kdepimlibs</literal>, and <literal>kdebase</literal> modules.</para>
+
+<note><para>Technically, only the <filename
+class="directory">/runtime</filename> directory of <literal>kdebase</literal>
+is part of the &kde; Platform. This will be corrected when kdebase is converted
+to use &git;.</para></note>
+</listitem>
+
+<listitem><para>On top of the Platform, come several different things:</para>
+    <itemizedlist>
+        <listitem><para><quote>Third-party</quote> applications. These are
+        applications that use the &kde; Platform but are not authored by or in
+        association with the &kde; project.</para></listitem>
+
+        <listitem><para>A full <quote>workspace</quote> desktop environment.
+        This is what users normally see when they <quote>log-in to
+        &kde;</quote>.  This is provided by the &plasma; Desktop, mostly in
+        <literal>kdebase/workspace</literal>.  </para></listitem>
+
+        <listitem><para>The &kde; Software Compilation. This is a collection of
+        useful software included with the Platform and &plasma; Desktop,
+        grouped into individual modules. These are the modules that have names
+        starting with <literal>kde</literal>. For example,
+        <literal>kdepim</literal> is a component of the Software Compilation
+        that contains email, news-reading, calendar/organizational software,
+        &etc;, while <literal>kdegames</literal> contains a collection of
+        high-quality games to while away the time.</para></listitem>
+
+        <listitem><para>Finally, there is a collection of software (also
+        collected in modules) whose development is supported by &kde; resources
+        (such as translation, source control, bug tracking, &etc;) but is not
+        released by &kde; or considered part of the Software Compilation. These
+        modules are known as <quote>Extragear</quote>, and have module names
+        such as <literal>extragear/network</literal>. As with
+        <literal>kdesupport</literal>, some of these Extragear applications are
+        migrating to <ulink
+        url="http://projects.kde.org/">git.kde.org</ulink>.</para></listitem>
+    </itemizedlist>
+</listitem>
+</orderedlist>
+</sect2>
+
+<sect2 id="selecting-modules">
+<title>Selecting modules to build</title>
+
+<para>Selecting which of the possible modules to build is controlled by
+<link linkend="kdesrc-buildrc">the configuration file</link>.
+After the <literal>global</literal> section is a list of modules to build,
+bracketed by module ... end module lines. An example entry for a module is
+shown in <xref linkend="conf-module-example"/>.</para>
+
+<example id="conf-module-example">
+<title>Example module entry in the configuration file</title>
+<programlisting>
+module <replaceable>module-name</replaceable>
+    # Options for this module go here, example:
+    <link linkend="conf-make-options">make-options</link> -j4 # Run 4 compiles at a time
+end module
+</programlisting>
+</example>
+
+<tip><para>It is possible to declare a module with no options. In fact, most of
+your modules will likely be declared this way.</para></tip>
+
+<para>&kdesrc-build; only builds the modules you have listed in your configuration
+file. In addition, the modules are built in the order specified in the configuration
+file. For this reason you should ensure that the order of modules in your
+configuration file is consistent with the organization given in
+<xref linkend="kde-layers"/>.</para>
+
+<para>There is a sample file that comes with &kdesrc-build; called
+<filename>kdesrc-buildrc-sample</filename>. It is recommended to copy this file
+to a file called <filename>~/.kdesrc-buildrc</filename> (<emphasis>Note the
+leading period in front of kdesrc-buildrc!</emphasis>). Afterwards, edit the
+new file to adjust the default options to your liking. (Each option is described
+in more detail in <xref linkend="kdesrc-buildrc"/>). The default modules
+should be enough to ensure a fairly complete &kde; installation, however you
+can remove many of the modules that show up after <literal>kdebase</literal>
+if you'd like to save disk space or build time.</para>
+
+</sect2>
+
+<sect2 id="module-sets">
+<title>Module Sets</title>
+
+<para>&kdesrc-build; is usually able to guess where to download the source code
+for a given module quite easily, by using your setting for <link
+linkend="conf-svn-server">svn-server</link> and the module name for each module
+to create a single Subversion URL, which describes exactly where to download
+the source code from.</para>
+
+<para>With the move to Git, many larger Subversion modules were further
+sub-divided in the process, and there was no guarantee of where to find a
+module based just on the module name. Because of this, a concept called
+<quote>module sets</quote> was developed for &kdesrc-build; 1.12.1.</para>
+
+<para>By using a module set, you can quickly declare many Git modules to be
+downloaded and built, as if you'd typed out a separate module declaration for
+each one. The <link linkend="conf-repository">repository</link> opiton is
+handled specially to setup where each module is downloaded from, which every
+other option contained in the module set is copied to every module generated
+in this fashion.</para>
+
+<example id="example-using-module-sets">
+<title>Using module sets</title>
+<programlisting>
+global
+    <option><link linkend="conf-git-repository-base">git-repository-base</link></option> <replaceable>kde-git</replaceable> <replaceable>git://anongit.kde.org/</replaceable>
+end global
+
+module <replaceable>qt-copy</replaceable>
+    # Options removed for brevity
+end module
+
+module-set # Note there's no name for this (or any) set
+    <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
+
+# Other modules as necessary...
+module <replaceable>kdesupport</replaceable>
+end module
+</programlisting>
+</example>
+
+<para>In <xref linkend="example-using-module-sets"/> a brief module set is
+shown.  When &kdesrc-build; encounters this module set, it acts as if, for
+every module given in <option>use-modules</option>, that an individual module
+has been declared, with its <option>repository</option> equal to the
+module-set's <option>repository</option> followed immediately by the given
+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>
+
+<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>
+</sect1>
diff --git a/doc/index.docbook b/doc/index.docbook
index d5bc5d5d..d76172ba 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -53,6 +53,7 @@
   <!ENTITY getting-started SYSTEM "getting-started/index.docbook">
   <!ENTITY before-building SYSTEM "getting-started/before-building.docbook">
   <!ENTITY configure-data SYSTEM "getting-started/configure-data.docbook">
+  <!ENTITY kde-modules-and-selection SYSTEM "getting-started/kde-modules-and-selection.docbook">
   <!ENTITY building-and-troubleshooting SYSTEM "getting-started/building-and-troubleshooting.docbook">
   <!ENTITY environment SYSTEM "getting-started/environment.docbook">
   <!ENTITY features SYSTEM "features/index.docbook">
@@ -111,8 +112,8 @@
 
 <legalnotice>&FDLNotice;</legalnotice>
 
-<date>2010-01-30</date>
-<releaseinfo>1.12</releaseinfo>
+<date>2011-01-29</date>
+<releaseinfo>1.12.1</releaseinfo>
 
 <abstract>
 <para>&kdesrc-build; is a script which builds and installs &kde; software
diff --git a/doc/introduction/index.docbook b/doc/introduction/index.docbook
index 854c359d..5295e31d 100644
--- a/doc/introduction/index.docbook
+++ b/doc/introduction/index.docbook
@@ -18,9 +18,9 @@ operation:
 </para>
 
 <itemizedlist>
-<listitem><para>Notable <link linkend="features">features</link>.</para></listitem>
 <listitem><para>An <link linkend="getting-started">overview</link> of the steps
 required to get started.</para></listitem>
+<listitem><para>Notable <link linkend="features">features</link>.</para></listitem>
 <listitem><para>The <link linkend="configure-data">configuration file</link> syntax
 and options.</para></listitem>
 <listitem><para>The <link linkend="cmdline">command line options</link>.</para></listitem>
diff --git a/doc/kdesrc-buildrc/conf-options-table.docbook b/doc/kdesrc-buildrc/conf-options-table.docbook
index fdf70245..fcebb341 100644
--- a/doc/kdesrc-buildrc/conf-options-table.docbook
+++ b/doc/kdesrc-buildrc/conf-options-table.docbook
@@ -310,6 +310,62 @@ This option was removed in version 1.10
 </entry>
 </row>
 
+<row id="conf-git-repository-base">
+<entry>git-repository-base</entry>
+<entry>Cannot be overridden</entry>
+<entry><para>This option, added in version 1.12.1, is used to create a short
+name to reference a specific Git repository base URL in later <link
+linkend="module-sets">module set</link> declarations, which is useful for
+quickly declaring many Git modules to build.</para>
+
+<para>You must specific two things (separated by a space): The name to assign
+to the base URL, and the actual base URL itself. For example:</para>
+
+<para>
+<informalexample>
+<programlisting>
+global
+   # other options
+
+   # This is the common path to all anonymous Git server modules.
+   git-repository-base <replaceable>kde-git</replaceable> <replaceable>git://anongit.kde.org/</replaceable>
+end global
+
+# Module declarations
+
+module-set
+   # Now you can use the alias you defined earlier, but <emphasis>only</emphasis>
+   # in a module-set.
+   repository <replaceable>kde-git</replaceable>
+
+   <link linkend="conf-use-modules">use-modules</link> <replaceable>module1.git</replaceable> <replaceable>module2.git</replaceable>
+end module-set
+</programlisting>
+</informalexample>
+</para>
+
+<para>The module-set's <literal>use-modules</literal> option created two modules
+internally, with &kdesrc-build; behaving as if it had read:</para>
+
+<programlisting>
+module module1
+    repository git://anongit.kde.org/module1.git
+end module
+
+module module2
+    repository git://anongit.kde.org/module2.git
+end module
+</programlisting>
+
+<para>Unlike most other options, this option can be specified multiple times
+in order to create as many aliases as necessary.</para>
+
+<tip><para>It is not required to use this option to take advantage of module-set,
+this option exists to make it easy to use the same repository across many
+different module sets.</para></tip>
+</entry>
+</row>
+
 <row id="conf-install-after-build">
 <entry>install-after-build</entry>
 <entry>Module setting overrides global</entry>
@@ -337,7 +393,7 @@ well.</entry>
 <entry>Cannot be overridden</entry>
 <entry><para>This option allows you to choose to download and install
 localization packages along with &kde;. You might do this if you do not live in
-the United States and would like to &kde; translated into your native
+the United States and would like to use &kde; translated into your native
 language.</para>
 
 <para>To use this option, set it to a space-separated list of languages to
@@ -641,6 +697,43 @@ the lower disk priority set this to <replaceable>true</replaceable>.
 </entry>
 </row>
 
+<row id="conf-use-modules">
+<entry>use-modules</entry>
+<entry>Can only use in <link linkend="module-sets">module-set</link></entry>
+<entry><para>This option, added in &kdesrc-build; 1.12.1, allows you to easily
+specify many different modules to build at the same point in <link
+linkend="kdesrc-buildrc">the configuration file</link>.</para>
+
+<para>This option <emphasis>must</emphasis> be used within a
+<literal>module-set</literal>. Every identifier passed to this option is
+internally converted to a &kdesrc-build; module, with a <link
+linkend="conf-repository"><option>repository</option></link> option set to the
+module-set's repository combined with the identifier name in order to setup the
+final repository to download from. All other options that are assigned in the
+module-set are also copied to the generated modules unaltered.</para>
+
+<para>The order that modules are defined in this option is important, because
+that is also the order that &kdesrc-build; will process the generated modules
+when updating, building, and installing. All modules defined in the given
+module-set will be handled before &kdesrc-build; moves to the next module after
+the module-set.</para>
+
+<para>If you need to change the options for a generated module, simply declare
+the module again after it is defined in the module-set, and set your options
+as needed. Although you will change the options set for the module this way,
+the module will still be updated and built in the order set by the module-set
+(i.e. you can't reorder the build sequence doing this).</para>
+
+<important><para>The name to use for the module if you do this is simply the
+name that you passed to <option>use-modules</option>, with the exception that
+any <literal>.git</literal> is removed.</para></important>
+
+<para>See <xref linkend="module-sets"/> and <link
+linkend="conf-git-repository-base">git-repository-base</link> for a description
+of its use and an example.</para>
+</entry>
+</row>
+
 <row id="conf-use-qt-builddir-hack">
 <entry>use-qt-builddir-hack</entry>
 <entry>Module setting overrides global</entry>



More information about the kde-doc-english mailing list