Git commit 894df557e1279b21d7f5249f12c76d33885bf4ad by Andrew Shark. Committed on 05/01/2024 at 19:59. Pushed by ashark into branch 'master'.
doc: introduction - separate docbook M +2 -67 doc/index.docbook A +67 -0 doc/introduction.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/894df557e1279b21d7f5249f12c76d33885bf4ad diff --git a/doc/index.docbook b/doc/index.docbook index 3038d2d2..39d821d5 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -82,6 +82,7 @@ <!ENTITY features SYSTEM "features.docbook"> <!ENTITY getting-started SYSTEM "getting-started.docbook"> <!ENTITY intro-toc SYSTEM "intro-toc.docbook"> + <!ENTITY introduction SYSTEM "introduction.docbook"> ]> <book id="kdesrc-build" lang="&language;"> @@ -142,73 +143,7 @@ directly from the &kde; project's source code repositories.</para> </bookinfo> -<chapter id="introduction"> -<title>Introduction</title> - -<sect1 id="brief-intro"> -<title>A brief introduction to &kdesrc-build;</title> - -<sect2 id="whatis-kdesrc-build"> -<title>What is &kdesrc-build;?</title> - -<para> -&kdesrc-build; is a script to help the &kde; community install <ulink -url="https://www.kde.org/";>&kde;</ulink> software from its <ulink -url="https://git-scm.com/";>&git;</ulink> source repositories, -and continue to update that software afterwards. -It is particularly intended to support those who need to supporting testing and -development of &kde; software, including users testing bugfixes and developers -working on new features. -</para> - -<para>The &kdesrc-build; script can be configured to maintain a single individual -module, a full &plasma; desktop with &kde; application set, or somewhere in between. -</para> - -<para>To get started, see <xref linkend="getting-started"/>, or continue reading for more -detail on how &kdesrc-build; works and what is covered in this documentation. -</para> -</sect2> - -<sect2 id="operation-in-a-nutshell"> -<title>&kdesrc-build; operation <quote>in a nutshell</quote></title> - -<para>&kdesrc-build; works by using the tools available to the user at the -command-line, using the same interfaces available to the user. When -&kdesrc-build; is run, the following sequence is followed: </para> - -<orderedlist> -<listitem><para>&kdesrc-build; reads in the <link linkend="cmdline">command -line</link> and <link linkend="configure-data">configuration file</link>, to -determine what to build, compile options to use, where to install, -&etc;</para></listitem> - -<listitem><para>&kdesrc-build; performs a source update for each <link -linkend="module-concept">module</link>. The update continues until all modules -have been updated. Modules that fail to update normally do not stop the build -– you will be notified at the end which modules did not -update.</para></listitem> - -<listitem><para>Modules that were successfully updated are built, have their -test suite run, and are then installed. To reduce the overall time spent, -&kdesrc-build; will by default start building the code as soon as the first -module has completed updating, and allow the remaining updates to continue -behind the scenes. -</para></listitem> -</orderedlist> - -<tip><para>A <emphasis>very good</emphasis> overview of how &kde; modules are -built, including informative diagrams, is provided on <ulink -url="https://www.davidrevoy.com/article193/guide-building-krita-on-linux-for- -cats">an online article discussing &kde;'s &krita; application</ulink>. This -workflow is what &kdesrc-build; automates for all &kde; modules.</para> -</tip> - -</sect2> -</sect1> - -&intro-toc; -</chapter> +&introduction; &getting-started; diff --git a/doc/introduction.docbook b/doc/introduction.docbook new file mode 100644 index 00000000..e6ca3256 --- /dev/null +++ b/doc/introduction.docbook @@ -0,0 +1,67 @@ +<chapter id="introduction"> +<title>Introduction</title> + +<sect1 id="brief-intro"> +<title>A brief introduction to &kdesrc-build;</title> + +<sect2 id="whatis-kdesrc-build"> +<title>What is &kdesrc-build;?</title> + +<para> +&kdesrc-build; is a script to help the &kde; community install <ulink +url="https://www.kde.org/";>&kde;</ulink> software from its <ulink +url="https://git-scm.com/";>&git;</ulink> source repositories, +and continue to update that software afterwards. +It is particularly intended to support those who need to supporting testing and +development of &kde; software, including users testing bugfixes and developers +working on new features. +</para> + +<para>The &kdesrc-build; script can be configured to maintain a single individual +module, a full &plasma; desktop with &kde; application set, or somewhere in between. +</para> + +<para>To get started, see <xref linkend="getting-started"/>, or continue reading for more +detail on how &kdesrc-build; works and what is covered in this documentation. +</para> +</sect2> + +<sect2 id="operation-in-a-nutshell"> +<title>&kdesrc-build; operation <quote>in a nutshell</quote></title> + +<para>&kdesrc-build; works by using the tools available to the user at the +command-line, using the same interfaces available to the user. When +&kdesrc-build; is run, the following sequence is followed: </para> + +<orderedlist> +<listitem><para>&kdesrc-build; reads in the <link linkend="cmdline">command +line</link> and <link linkend="configure-data">configuration file</link>, to +determine what to build, compile options to use, where to install, +&etc;</para></listitem> + +<listitem><para>&kdesrc-build; performs a source update for each <link +linkend="module-concept">module</link>. The update continues until all modules +have been updated. Modules that fail to update normally do not stop the build +– you will be notified at the end which modules did not +update.</para></listitem> + +<listitem><para>Modules that were successfully updated are built, have their +test suite run, and are then installed. To reduce the overall time spent, +&kdesrc-build; will by default start building the code as soon as the first +module has completed updating, and allow the remaining updates to continue +behind the scenes. +</para></listitem> +</orderedlist> + +<tip><para>A <emphasis>very good</emphasis> overview of how &kde; modules are +built, including informative diagrams, is provided on <ulink +url="https://www.davidrevoy.com/article193/guide-building-krita-on-linux-for- +cats">an online article discussing &kde;'s &krita; application</ulink>. This +workflow is what &kdesrc-build; automates for all &kde; modules.</para> +</tip> + +</sect2> +</sect1> + +&intro-toc; +</chapter>
