Git commit 23df6e04c36ac3b92e726852e5165906bb324c8d by Ignacy Kajdan. Committed on 21/01/2022 at 17:40. Pushed by ashark into branch 'docbook_historied_per_file'.
Use XDG_STATE_HOME for persistent data file Original commit: 4a2c0a8f https://invent.kde.org/sdk/kdesrc-build/-/commit/4a2c0a8fe776490fde92bec120bfae51d9e9c982 M +5 -3 doc/cmdline/supported-cmdline-params.docbook M +17 -13 doc/getting-started/before-building.docbook M +10 -7 doc/getting-started/configure-data.docbook M +26 -15 doc/kdesrc-buildrc/conf-options-table.docbook M +57 -7 doc/using-kdesrc-build/advanced-features.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/23df6e04c36ac3b92e726852e5165906bb324c8d diff --git a/doc/cmdline/supported-cmdline-params.docbook b/doc/cmdline/supported-cmdline-params.docbook index 25c4f8cc..75c2c452 100644 --- a/doc/cmdline/supported-cmdline-params.docbook +++ b/doc/cmdline/supported-cmdline-params.docbook @@ -496,9 +496,11 @@ This option was added with &kdesrc-build; 1.16. See also the <listitem><para> This interprets the next command line parameter as the file to read the configuration options from. The default value for this parameter is -<filename>kdesrc-buildrc</filename> (checked in the current directory) if -it is present, or <filename>~/.kdesrc-buildrc</filename> otherwise. See -also <xref linkend="kdesrc-buildrc" />. +<filename>kdesrc-buildrc</filename> (checked in the current working directory). +If this file doesn't exist, <filename>~/.config/kdesrc-buildrc</filename> +(<filename>$XDG_CONFIG_HOME/kdesrc-buildrc</filename>, if +<envar>$XDG_CONFIG_HOME</envar> is set) will be used instead. See also +<xref linkend="kdesrc-buildrc"/>. </para></listitem> </varlistentry> diff --git a/doc/getting-started/before-building.docbook b/doc/getting-started/before-building.docbook index d6920929..b4853081 100644 --- a/doc/getting-started/before-building.docbook +++ b/doc/getting-started/before-building.docbook @@ -151,15 +151,17 @@ without having to fully specify its path every time.</para></tip> <sect3 id="setup-rcfile"> <title>Prepare the configuration file</title> -<para>&kdesrc-build; uses a <link linkend="configure-data">configuration -file</link> (located at <filename>~/.kdesrc-buildrc</filename>) to control -which modules are built, where they are installed to, etc.</para> +<para>&kdesrc-build; uses a <link linkend="configure-data">configuration file</link> +to control which modules are built, where they are installed to, etc. +This file is located at <filename>~/.config/kdesrc-buildrc</filename> +(<filename>$XDG_CONFIG_HOME/kdesrc-buildrc</filename>, if +<envar>$XDG_CONFIG_HOME</envar> is set).</para> <para>You can use a program included with &kdesrc-build;, called <application>kdesrc-build-setup</application> in order to prepare a simple kdesrc-build configuration. You can then edit the -<filename>~/.kdesrc-buildrc</filename> from there to make any changes you see -fit.</para> +<filename>~/.config/kdesrc-buildrc</filename> configuration file to make +any changes you see fit.</para> <para><application>kdesrc-build-setup</application> itself runs from a terminal (instead of using a graphical interface), just like &kdesrc-build;, so you can @@ -169,17 +171,19 @@ use it even if you have no graphical interface available yet.</para> <title>Manual setup of configuration file</title> <para>You can also setup your configuration file manually, by copying the -included sample configuration file -<filename>kdesrc-buildrc-kf5-sample</filename> to -<filename>~/.kdesrc-buildrc</filename> and then editing the file. <xref -linkend="kdesrc-buildrc"/> will be a useful reference for this, especially its -<link linkend="conf-options-table">table of configuration options</link>. +included sample configuration file <filename>kdesrc-buildrc-kf5-sample</filename> +to <filename>~/.config/kdesrc-buildrc</filename> and then editing the file. +<xref linkend="kdesrc-buildrc"/> will be a useful reference for this, especially +its <link linkend="conf-options-table">table of configuration options</link>. </para> <para>&kdesrc-build; contains many recommended configuration files to support -&kde; Frameworks 5, &plasma; 5, and other &kde; applications. The <application>kdesrc-build-setup</application> refers to these files in the configuration file it generates, but you can also use them -yourself. See <xref linkend="kdesrc-buildrc-including"/> for information on how -to use other configuration files from your own <filename>~/.kdesrc-buildrc</filename>.</para> +&kde; Frameworks 5, &plasma; 5, and other &kde; applications. The +<application>kdesrc-build-setup</application> refers to these files in the +configuration file it generates, but you can also use them yourself. See +<xref linkend="kdesrc-buildrc-including"/> for information on how to use other +configuration files from your own <filename>kdesrc-buildrc</filename>. +</para> <para>You can find more information about the syntax of the <link linkend="configure-data">configuration file</link> in <xref diff --git a/doc/getting-started/configure-data.docbook b/doc/getting-started/configure-data.docbook index 5643e977..4ce65d40 100644 --- a/doc/getting-started/configure-data.docbook +++ b/doc/getting-started/configure-data.docbook @@ -2,15 +2,18 @@ <title>Setting the Configuration Data</title> <para> -To use &kdesrc-build;, you should have a file in your home directory called -<filename>.kdesrc-buildrc</filename>, which sets the general options and sets the modules -you would like to download and build. +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 the -configuration is stored in <filename>~/.kdesrc-buildrc</filename>.</para></note> +<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 diff --git a/doc/kdesrc-buildrc/conf-options-table.docbook b/doc/kdesrc-buildrc/conf-options-table.docbook index 64230a63..379cfa80 100644 --- a/doc/kdesrc-buildrc/conf-options-table.docbook +++ b/doc/kdesrc-buildrc/conf-options-table.docbook @@ -214,9 +214,16 @@ change at all.</para></important> <row id="conf-checkout-only"> <entry>checkout-only</entry> <entry>Module setting overrides global</entry> -<entry><para>This option was removed in January 2022. It used to control -the ability to checkout subsets of a module from a Subversion repository.</para> -</entry> +<entry><para>Set this option to checkout &subversion; sources piece by piece. The +value for this option should be a space-separated list of directories to +checkout. Although this option overrides the global option, be aware that +setting this as a global option makes no sense. +</para> + +<para>Note that this setting has no effect on &git; modules due to the +operation of the &git; source control system.</para> + +<para>See <xref linkend="checking-out-parts"/> for an example.</para></entry> </row> <row id="conf-cmake-generator"> @@ -405,13 +412,13 @@ for every module. You can disable this check by setting <entry><para>Use this option to select a specific set of directories not to be built in a module (instead of all of them). The directories not to build should be space-separated.</para> -<para>Note that the sources to the programs will still be downloaded.</para> +<para>Note that the sources to the programs will still be downloaded. You can use +the <link linkend="conf-checkout-only">checkout-only</link> +directive to choose directories that you want to check out.</para> -<para>For example, to disable building the <literal>codeeditor</literal> and <literal>minimaltest</literal> -directories of the <literal>syntaxhighlighting</literal> framework, you -would add <userinput>do-not-compile codeeditor minimaltest</userinput> -compiling, you would add "do-not-compile juk kscd" to your syntaxhighlighting -options.</para> +<para>For example, to hold &juk; and &kscd; in the kdemultimedia module from +compiling, you would add "do-not-compile juk kscd" to your kdemultimedia +settings.</para> <para>See <xref linkend="not-compiling"/> for an example.</para> </entry> @@ -1025,12 +1032,16 @@ cannot figure out what you mean using <link linkend="conf-branch">branch</link>. <row id="conf-persistent-data-file"> <entry>persistent-data-file</entry> <entry>Cannot be overridden</entry> -<entry><para>Use this option to change where &kdesrc-build; stores its persistent -data. The default is to store this data in a file called -<filename>.kdesrc-build-data</filename> placed in the same directory as the -configuration file in use. If you have multiple available configurations in the -same directory you may want to manually set this option so that the different -configurations do not end up with conflicting persistent data.</para> +<entry><para>Use this option to change where &kdesrc-build; stores its +persistent data. The default is to store this data in a file called +<filename>.kdesrc-build-data</filename>, placed in the same directory as the +configuration file in use. If the global configuration file is in use, it will +be saved to <filename>~/.local/state/kdesrc-build-data</filename> +(<filename>$XDG_STATE_HOME/kdesrc-build-data</filename>, if +<envar>$XDG_STATE_HOME</envar> is set). If you have multiple available +configurations in the same directory, you may want to manually set this option, +so that different configurations do not end up with conflicting persistent data. +</para> <para>This option was added with &kdesrc-build; 1.15.</para> </entry> diff --git a/doc/using-kdesrc-build/advanced-features.docbook b/doc/using-kdesrc-build/advanced-features.docbook index 6c41cc2e..45e73a44 100644 --- a/doc/using-kdesrc-build/advanced-features.docbook +++ b/doc/using-kdesrc-build/advanced-features.docbook @@ -9,19 +9,69 @@ has features to make this easy. There are several complementing ways to do this. </para> +<sect3 id="checking-out-parts"> +<title>Checking out portions of a module</title> + +<para>This is perhaps the best way to do this. When it works, it will save you +download time and disk space. What happens is that &kdesrc-build; will download +only the parts of a module that you specify. This is done using the &checkout-only; +option for a module, which will specify a list of directories to download. +</para> + +<tip><para> +If you do not already know what to download from a module, it may be a good idea +to browse the &subversion; layout for a module first, using +<ulink url="https://websvn.kde.org/branches/KDE/4.6/";>WebSVN</ulink>. <!--FIXME outdated--> +</para></tip> + +<informalexample> +<para>To only grab &kuser; and <application>KSystemLog</application> from +kdeadmin, you could use &checkout-only; like this:</para> + +<screen> +module <replaceable>kdeadmin</replaceable> + &checkout-only; <replaceable>kuser ksystemlog</replaceable> +end module +</screen> + +</informalexample> + +<important><para>The directories will be built in the order they are listed +in the option. If one of the directories needs something else from the module +to compile, then you need to make sure they are both in the &checkout-only; +line, and that the required dependency goes before the directory that needs it.</para> + +<para>Also, sometimes an application may need other directories and it is hard +to figure out what they are, which may require some trial and error of constantly +adding directories to the option to figure out. This option depends on support +from the build system of the module, so it is only useful for modules that are +collections of individual applications.</para> +</important> + +<para>One final note to make about this option: If you change the value of this +option, you should use <userinput><command>kdesrc-build</command> +<option>&cmd-refresh-build;</option> <option><replaceable>module</replaceable></option></userinput> +in order to ensure that the module is reconfigured properly. In addition, +&kdesrc-build; will never remove existing files if you take away the number of +directories from your &checkout-only; option, or add the option to a module that +has already been checked out.</para> + +</sect3> + <sect3 id="not-compiling"> <title>Removing directories from a build</title> -<para>It is possible to download an entire repository -but have the build system leave out a few directories when it does -the build. This requires that the module uses &cmake; and that the -module's build system allows the directory to remove to be -optional. +<para>Instead of restricting what is downloaded, it is possible to download +everything but have the build system leave out a few directories when it does +the build. This may be useful if one directory always breaks and is +unnecessary to the rest of the module. </para> -<para>This is controlled with the &do-not-compile; option.</para> +<para>This is controlled with the &do-not-compile; option. It works similar +to the &checkout-only; option just described, in that it is simply a list of +directories that should not be compiled.</para> <important><para> -This option requires at least that the +Also like &checkout-only;, this option requires at least that the build system for the module is reconfigured after changing it. This is done using the <userinput><command>kdesrc-build</command> <option>&cmd-reconfigure;</option>
