[sdk/kdesrc-build] doc: doc: building-and-troubleshooting - separate docbook
Andrew Shark
null at kde.org
Fri Jan 5 19:07:02 GMT 2024
Git commit 018dba9a0efa4a8ed0db24f8276a805f03c843f3 by Andrew Shark.
Committed on 05/01/2024 at 19:57.
Pushed by ashark into branch 'master'.
doc: building-and-troubleshooting - separate docbook
A +139 -0 doc/building-and-troubleshooting.docbook
M +2 -139 doc/index.docbook
https://invent.kde.org/sdk/kdesrc-build/-/commit/018dba9a0efa4a8ed0db24f8276a805f03c843f3
diff --git a/doc/building-and-troubleshooting.docbook b/doc/building-and-troubleshooting.docbook
new file mode 100644
index 00000000..b9d478eb
--- /dev/null
+++ b/doc/building-and-troubleshooting.docbook
@@ -0,0 +1,139 @@
+<sect1 id="building-and-troubleshooting">
+<title>Using the &kdesrc-build; script</title>
+<para>With the configuration data established, now you are ready to run the
+script. Even if you still have some tweaking or other reading you wish to do,
+it is a good idea to at least load the &kde; project metadata.</para>
+
+<sect2 id="loading-kdesrc-build-metadata">
+<title>Loading project metadata</title>
+
+<para>
+From a terminal window, log in to the user you are using to compile &kde; software and
+execute the script:
+</para>
+<screen>
+ <prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--metadata-only</option></userinput>
+</screen>
+
+<para>This command will setup the source directory and connect to the KDE &git;
+repositories to download the database of &kde; git repositories, and the
+database of dependency metadata, without making any further changes. It is
+useful to run this separately as this metadata is useful for other
+&kdesrc-build; commands. </para>
+
+</sect2>
+
+<sect2 id="pretend-mode">
+<title>Previewing what will happen when kdesrc-build runs</title>
+
+<para>With the project metadata installed, it is possible to preview what
+&kdesrc-build; will do when launched. This can be done with the <option><link
+linkend="cmdline-pretend">--pretend</link></option> command line option.</para>
+
+<screen>
+ <prompt>% </prompt><command>./kdesrc-build</command> <option>--pretend</option>
+</screen>
+
+<para>You should see a message saying that some packages were successfully built (although
+ nothing was actually built). If there were no significant problems shown, you can proceed
+ to actually running the script.</para>
+
+<screen>
+ <prompt>%</prompt> <userinput><command>kdesrc-build</command></userinput>
+</screen>
+
+<para>This command will download the appropriate source code, build and install each module in order. Afterwards, you should see output similar to that in <xref
+linkend="example-build-sequence"/>:</para>
+
+<example id="example-build-sequence">
+<title>Example output of a kdesrc-build run</title>
+<screen>
+<prompt>%</prompt> <userinput><command>kdesrc-build</command></userinput>
+Updating kde-build-metadata (to branch master)
+Updating sysadmin-repo-metadata (to branch master)
+
+Building libdbusmenu-qt (1/200)
+ No changes to libdbusmenu-qt source, proceeding to build.
+ Compiling... succeeded (after 0 seconds)
+ Installing.. succeeded (after 0 seconds)
+
+Building taglib (2/200)
+ Updating taglib (to branch master)
+ Source update complete for taglib: 68 files affected.
+ Compiling... succeeded (after 0 seconds)
+ Installing.. succeeded (after 0 seconds)
+
+Building extra-cmake-modules from <module-set at line 32> (3/200)
+ Updating extra-cmake-modules (to branch master)
+ Source update complete for extra-cmake-modules: 2 files affected.
+ Compiling... succeeded (after 0 seconds)
+ Installing.. succeeded (after 0 seconds)
+
+ ...
+
+Building kdevelop from kdev (200/200)
+ Updating kdevelop (to branch master)
+ Source update complete for kdevelop: 29 files affected.
+ Compiling... succeeded (after 1 minute, and 34 seconds)
+ Installing.. succeeded (after 2 seconds)
+
+<<< PACKAGES SUCCESSFULLY BUILT >>>
+Built 200 modules
+
+Your logs are saved in /home/kde-src/kdesrc/log/2018-01-20-07
+</screen>
+</example>
+</sect2>
+
+<sect2 id="fixing-build-failures">
+<title>Resolving build failures</title>
+
+<para>
+Depending on how many modules you are downloading, it is possible that
+&kdesrc-build; will not succeed the first time you compile &kde; software.
+Do not despair!
+</para>
+
+<para>&kdesrc-build; logs the output of every command it runs. By default,
+the log files are kept in <filename class="directory">~/kdesrc/log</filename>. To see what
+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 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 (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; software in the
+<ulink url="https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source">
+Build 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>
+</sect2>
+
+</sect1>
diff --git a/doc/index.docbook b/doc/index.docbook
index a7c4a39e..f7462149 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -71,6 +71,7 @@
<!ENTITY appendix-modules SYSTEM "appendix-modules.docbook">
<!ENTITY appendix-profile SYSTEM "appendix-profile.docbook">
<!ENTITY basic-features SYSTEM "basic-features.docbook">
+ <!ENTITY building-and-troubleshooting SYSTEM "building-and-troubleshooting.docbook">
]>
<book id="kdesrc-build" lang="&language;">
@@ -541,145 +542,7 @@ which is described in <xref linkend="selecting-modules"/>.</para>
</sect1>
-<sect1 id="building-and-troubleshooting">
-<title>Using the &kdesrc-build; script</title>
-<para>With the configuration data established, now you are ready to run the
-script. Even if you still have some tweaking or other reading you wish to do,
-it is a good idea to at least load the &kde; project metadata.</para>
-
-<sect2 id="loading-kdesrc-build-metadata">
-<title>Loading project metadata</title>
-
-<para>
-From a terminal window, log in to the user you are using to compile &kde; software and
-execute the script:
-</para>
-<screen>
- <prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--metadata-only</option></userinput>
-</screen>
-
-<para>This command will setup the source directory and connect to the KDE &git;
-repositories to download the database of &kde; git repositories, and the
-database of dependency metadata, without making any further changes. It is
-useful to run this separately as this metadata is useful for other
-&kdesrc-build; commands. </para>
-
-</sect2>
-
-<sect2 id="pretend-mode">
-<title>Previewing what will happen when kdesrc-build runs</title>
-
-<para>With the project metadata installed, it is possible to preview what
-&kdesrc-build; will do when launched. This can be done with the <option><link
-linkend="cmdline-pretend">--pretend</link></option> command line option.</para>
-
-<screen>
- <prompt>% </prompt><command>./kdesrc-build</command> <option>--pretend</option>
-</screen>
-
-<para>You should see a message saying that some packages were successfully built (although
- nothing was actually built). If there were no significant problems shown, you can proceed
- to actually running the script.</para>
-
-<screen>
- <prompt>%</prompt> <userinput><command>kdesrc-build</command></userinput>
-</screen>
-
-<para>This command will download the appropriate source code, build and install each module in order. Afterwards, you should see output similar to that in <xref
-linkend="example-build-sequence"/>:</para>
-
-<example id="example-build-sequence">
-<title>Example output of a kdesrc-build run</title>
-<screen>
-<prompt>%</prompt> <userinput><command>kdesrc-build</command></userinput>
-Updating kde-build-metadata (to branch master)
-Updating sysadmin-repo-metadata (to branch master)
-
-Building libdbusmenu-qt (1/200)
- No changes to libdbusmenu-qt source, proceeding to build.
- Compiling... succeeded (after 0 seconds)
- Installing.. succeeded (after 0 seconds)
-
-Building taglib (2/200)
- Updating taglib (to branch master)
- Source update complete for taglib: 68 files affected.
- Compiling... succeeded (after 0 seconds)
- Installing.. succeeded (after 0 seconds)
-
-Building extra-cmake-modules from <module-set at line 32> (3/200)
- Updating extra-cmake-modules (to branch master)
- Source update complete for extra-cmake-modules: 2 files affected.
- Compiling... succeeded (after 0 seconds)
- Installing.. succeeded (after 0 seconds)
-
- ...
-
-Building kdevelop from kdev (200/200)
- Updating kdevelop (to branch master)
- Source update complete for kdevelop: 29 files affected.
- Compiling... succeeded (after 1 minute, and 34 seconds)
- Installing.. succeeded (after 2 seconds)
-
-<<< PACKAGES SUCCESSFULLY BUILT >>>
-Built 200 modules
-
-Your logs are saved in /home/kde-src/kdesrc/log/2018-01-20-07
-</screen>
-</example>
-</sect2>
-
-<sect2 id="fixing-build-failures">
-<title>Resolving build failures</title>
-
-<para>
-Depending on how many modules you are downloading, it is possible that
-&kdesrc-build; will not succeed the first time you compile &kde; software.
-Do not despair!
-</para>
-
-<para>&kdesrc-build; logs the output of every command it runs. By default,
-the log files are kept in <filename class="directory">~/kdesrc/log</filename>. To see what
-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 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 (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; software in the
-<ulink url="https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source">
-Build 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>
-</sect2>
-
-</sect1>
+&building-and-troubleshooting;
<sect1 id="building-specific-modules">
<title>Building specific modules</title>
More information about the kde-doc-english
mailing list