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-de...@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-de...@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>