Git commit bdd65e23ec996e9b2d286d556de32890e70833e6 by Andrew Shark. Committed on 05/01/2024 at 19:58. Pushed by ashark into branch 'master'.
doc: configure-data - separate docbook A +110 -0 doc/configure-data.docbook M +2 -110 doc/index.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/bdd65e23ec996e9b2d286d556de32890e70833e6 diff --git a/doc/configure-data.docbook b/doc/configure-data.docbook new file mode 100644 index 00000000..a4019619 --- /dev/null +++ b/doc/configure-data.docbook @@ -0,0 +1,110 @@ +<sect1 id="configure-data"> +<title>Setting the Configuration Data</title> + +<para> +To use &kdesrc-build;, you should have a file in your <filename>~/.config</filename> +(or in <envar>$XDG_CONFIG_HOME</envar>, if set) directory called +<filename>kdesrc-buildrc</filename>, which sets the general options and +specifies the modules you would like to download and build. +</para> + +<note><para> +It is possible to use different configuration files for &kdesrc-build;, which is +described in <xref linkend="kdesrc-buildrc" />. If you need to use multiple +configurations, please see that section. Here, we will assume that the +configuration is stored in <filename>~/.config/kdesrc-buildrc</filename>. +</para></note> + +<para> +The easiest way to proceed is to use the +<filename>kdesrc-buildrc-kf5-sample</filename> file as a template, changing global +options to match your wants, and also change the list of modules you want to +build. +</para> + +<para> +The default settings should be appropriate to perform a +&kde; build. Some settings that you may wish to alter include: +</para> + +<itemizedlist> +<listitem><para><link linkend="conf-install-dir">install-dir</link>, which changes the +destination directory that your &kde; software is installed to. This defaults to +<filename class="directory">~/kde/usr</filename>, which is a single-user +installation.</para></listitem> + +<listitem><para><link linkend="conf-branch-group">branch-group</link>, which can +be +used to choose the appropriate branch of development for the &kde; modules as a +whole. There are many supported build configurations but you will likely want to +choose <option>kf5-qt5</option> so that &kdesrc-build; downloads the latest code +based on &Qt; 5 and &kde; Frameworks 5.</para> + +<tip><para>&kdesrc-build; will use a default branch group if you do not choose +one, but this default will change over time, so it's better to choose one so +that the branch group does not change unexpectedly.</para></tip> +</listitem> + +<listitem><para><link linkend="conf-source-dir">source-dir</link>, to control the directory +&kdesrc-build; uses for downloading the source code, running the build process, and saving +logs. +This defaults to <filename class="directory">~/kde/src</filename>.</para></listitem> + +<listitem><para><link linkend="conf-cmake-options">cmake-options</link>, which +sets the options to pass to the &cmake; command when building each module. +Typically this is used to set between <quote>debug</quote> or +<quote>release</quote> builds, to enable (or disable) optional features, or to +pass information to the build process about the location of required libraries. +</para></listitem> + +<listitem><para><link linkend="conf-make-options">make-options</link>, which +sets the options used when actually running the <application>make</application> +command to build each module (once &cmake; has established the build system). +</para> + +<para>The most typical option is <option>-j<replaceable>N</replaceable></option>, +where <replaceable>N</replaceable> should be replaced with the maximum number of +compile jobs you wish to allow. A higher number (up to the number of logical CPUs +your system has available) leads to quicker builds, but requires more system resources. +</para> + +<tip><para>&kdesrc-build; sets the option <option><link linkend="conf-num-cores">num-cores</link></option> to +the detected number of available processing cores. You can use this value +in your own configuration file to avoid having to set it manually. +</para></tip> + +<example id="make-options-example"> +<title>Configuring Make to use all available CPUs, with exceptions</title> +<screen> +global + # This environment variable is automatically used by make, including + # make commands not run by kdesrc-build directly, such as Qt's configure + set-env MAKEFLAGS -j<literal>${num-cores}</literal> + … +end global + +… + +module-set <replaceable>big-module-set</replaceable> + repository kde-projects + use-modules <replaceable>calligra</replaceable> + make-options -j2 # Reduced number of build jobs for just these modules +end module-set +</screen> +</example> + +<note><para>Some very large Git repositories may swamp your system if you try to +compile with a too many build jobs at one time, especially repositories like the +&Qt; WebKit and &Qt; WebEngine repositories. To maintain system interactivity +you may have to reduce the number of build jobs for specific modules.</para> +<para><xref linkend="make-options-example"/> gives an example of how to do +this.</para> +</note> + +</listitem> +</itemizedlist> + +<para>You may want to select different modules to build, +which is described in <xref linkend="selecting-modules"/>.</para> + +</sect1> diff --git a/doc/index.docbook b/doc/index.docbook index 2df7f7b9..12020c0d 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -75,6 +75,7 @@ <!ENTITY building-specific-modules SYSTEM "building-specific-modules.docbook"> <!ENTITY cmdline SYSTEM "cmdline.docbook"> <!ENTITY conf-options-table SYSTEM "conf-options-table.docbook"> + <!ENTITY configure-data SYSTEM "configure-data.docbook"> ]> <book id="kdesrc-build" lang="&language;"> @@ -434,116 +435,7 @@ linkend="configure-data" /> and in <xref linkend="kdesrc-buildrc" />. </sect2> </sect1> -<sect1 id="configure-data"> -<title>Setting the Configuration Data</title> - -<para> -To use &kdesrc-build;, you should have a file in your <filename>~/.config</filename> -(or in <envar>$XDG_CONFIG_HOME</envar>, if set) directory called -<filename>kdesrc-buildrc</filename>, which sets the general options and -specifies the modules you would like to download and build. -</para> - -<note><para> -It is possible to use different configuration files for &kdesrc-build;, which is -described in <xref linkend="kdesrc-buildrc" />. If you need to use multiple -configurations, please see that section. Here, we will assume that the -configuration is stored in <filename>~/.config/kdesrc-buildrc</filename>. -</para></note> - -<para> -The easiest way to proceed is to use the -<filename>kdesrc-buildrc-kf5-sample</filename> file as a template, changing global -options to match your wants, and also change the list of modules you want to -build. -</para> - -<para> -The default settings should be appropriate to perform a -&kde; build. Some settings that you may wish to alter include: -</para> - -<itemizedlist> -<listitem><para><link linkend="conf-install-dir">install-dir</link>, which changes the -destination directory that your &kde; software is installed to. This defaults to -<filename class="directory">~/kde/usr</filename>, which is a single-user -installation.</para></listitem> - -<listitem><para><link linkend="conf-branch-group">branch-group</link>, which can -be -used to choose the appropriate branch of development for the &kde; modules as a -whole. There are many supported build configurations but you will likely want to -choose <option>kf5-qt5</option> so that &kdesrc-build; downloads the latest code -based on &Qt; 5 and &kde; Frameworks 5.</para> - -<tip><para>&kdesrc-build; will use a default branch group if you do not choose -one, but this default will change over time, so it's better to choose one so -that the branch group does not change unexpectedly.</para></tip> -</listitem> - -<listitem><para><link linkend="conf-source-dir">source-dir</link>, to control the directory -&kdesrc-build; uses for downloading the source code, running the build process, and saving -logs. -This defaults to <filename class="directory">~/kde/src</filename>.</para></listitem> - -<listitem><para><link linkend="conf-cmake-options">cmake-options</link>, which -sets the options to pass to the &cmake; command when building each module. -Typically this is used to set between <quote>debug</quote> or -<quote>release</quote> builds, to enable (or disable) optional features, or to -pass information to the build process about the location of required libraries. -</para></listitem> - -<listitem><para><link linkend="conf-make-options">make-options</link>, which -sets the options used when actually running the <application>make</application> -command to build each module (once &cmake; has established the build system). -</para> - -<para>The most typical option is <option>-j<replaceable>N</replaceable></option>, -where <replaceable>N</replaceable> should be replaced with the maximum number of -compile jobs you wish to allow. A higher number (up to the number of logical CPUs -your system has available) leads to quicker builds, but requires more system resources. -</para> - -<tip><para>&kdesrc-build; sets the option <option><link linkend="conf-num-cores">num-cores</link></option> to -the detected number of available processing cores. You can use this value -in your own configuration file to avoid having to set it manually. -</para></tip> - -<example id="make-options-example"> -<title>Configuring Make to use all available CPUs, with exceptions</title> -<screen> -global - # This environment variable is automatically used by make, including - # make commands not run by kdesrc-build directly, such as Qt's configure - set-env MAKEFLAGS -j<literal>${num-cores}</literal> - … -end global - -… - -module-set <replaceable>big-module-set</replaceable> - repository kde-projects - use-modules <replaceable>calligra</replaceable> - make-options -j2 # Reduced number of build jobs for just these modules -end module-set -</screen> -</example> - -<note><para>Some very large Git repositories may swamp your system if you try to -compile with a too many build jobs at one time, especially repositories like the -&Qt; WebKit and &Qt; WebEngine repositories. To maintain system interactivity -you may have to reduce the number of build jobs for specific modules.</para> -<para><xref linkend="make-options-example"/> gives an example of how to do -this.</para> -</note> - -</listitem> -</itemizedlist> - -<para>You may want to select different modules to build, -which is described in <xref linkend="selecting-modules"/>.</para> - -</sect1> +&configure-data; &building-and-troubleshooting;