Git commit 3fca6a373cd094293c9f43dc69d010e9bfed7f8d by Andrew Shark. Committed on 29/11/2023 at 13:06. Pushed by ashark into branch 'docbook_historied_per_file'.
Add specification for configuration options Original commit: d9a2fb13 https://invent.kde.org/sdk/kdesrc-build/-/commit/d9a2fb130cd9a096df5bc6ea182e36a66d814b9d M +419 -258 doc/kdesrc-buildrc/conf-options-table.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/3fca6a373cd094293c9f43dc69d010e9bfed7f8d diff --git a/doc/kdesrc-buildrc/conf-options-table.docbook b/doc/kdesrc-buildrc/conf-options-table.docbook index df4ff911..5545dc53 100644 --- a/doc/kdesrc-buildrc/conf-options-table.docbook +++ b/doc/kdesrc-buildrc/conf-options-table.docbook @@ -20,53 +20,67 @@ option.</para></listitem> <table id="options-global-table"> <title>Global scope only options</title> -<tgroup cols="3"> +<tgroup cols="2"> <thead> <row> -<entry>Option-name</entry> -<entry>Module -> Global Behavior</entry> -<entry>Notes</entry> +<entry>Option name</entry> +<entry>Description</entry> </row> </thead> <tbody> <row id="conf-async"> <entry>async</entry> -<entry>Cannot be overridden</entry> -<entry><para>This option enables the asynchronous mode of operation, where the source +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>Boolean</member> +<member>Default value</member><member>True</member> +<member>Available since</member><member>1.6</member> +</simplelist> +<para>This option enables the asynchronous mode of operation, where the source code update and the build process will be performed in parallel, instead of waiting for -all of the source code updates before starting the build process. This option defaults -to enabling asynchronous mode. To disable, set this option to <userinput>false</userinput></para> -<para>This option is available since the 1.6 release.</para></entry> +all of the source code updates before starting the build process.</para></entry> </row> <row id="conf-colorful-output"> <entry>colorful-output</entry> -<entry>Cannot be overridden</entry> -<entry>Set this option to <userinput>false</userinput> to disable the colorful output of &kdesrc-build;. -This option defaults to <replaceable>true</replaceable>. Note that &kdesrc-build; will not output the +<entry><simplelist type='horiz' columns='2'> +<member>Type</member><member>Boolean</member> +<member>Default value</member><member>True</member> +</simplelist><para>Set this option to <userinput>false</userinput> to disable the colorful output of &kdesrc-build;. +Note that &kdesrc-build; will not output the color codes to anything but a terminal (such as xterm, &konsole;, or the normal -&Linux; console). +&Linux; console).</para> </entry> </row> <row id="conf-disable-agent-check"> <entry>disable-agent-check</entry> -<entry>Cannot be overridden</entry> -<entry>Normally if you are using &ssh; to download the &git; sources -(such as if you are using the git+ssh protocol), &kdesrc-build; will try and +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>Boolean</member> +<member>Default value</member><member>False</member> +</simplelist> +<para>If you are using &ssh; to download the &git; sources +(such as if you are using the git+ssh protocol), this option controls if &kdesrc-build; will try and make sure that if you are using ssh-agent, it is actually managing some &ssh; identities. This is to try and prevent &ssh; from asking for your pass phrase -for every module. You can disable this check by setting -<option>disable-agent-check</option> to <userinput>true</userinput>. +for every module.</para> </entry> </row> <row id="conf-git-desired-protocol"> <entry>git-desired-protocol</entry> -<entry>Cannot be overridden</entry> -<entry><para>This option only applies to modules from a <link +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Default value</member><member>git</member> +<member>History information</member><member>This option was added in &kdesrc-build; 1.16. Prior to 20.06 this option +was used to configure the fetch URL instead of the push URL. As of 20.06 +<literal>https</literal> is always used when updating KDE projects.</member> +</simplelist> +<para>This option only applies to modules from a <link linkend="kde-projects-module-sets">&kde; project</link> repository.</para> <para>What this option actually does is configure which network protocol to @@ -87,16 +101,17 @@ needed for network traffic.</para></tip> <para>In any other situation you should not set this option as the default protocol is most efficient.</para> -<para>This option was added in &kdesrc-build; 1.16. Prior to 20.06 this option -was used to configure the fetch URL instead of the push URL. As of 20.06 -<literal>https</literal> is always used when updating KDE projects.</para> </entry> </row> <row id="conf-git-repository-base"> <entry>git-repository-base</entry> -<entry>Cannot be overridden</entry> -<entry><para>This option, added in version 1.12.1, is used to create a short +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Available since</member><member>1.12.1</member> +</simplelist> +<para>This option is used to create a short name to reference a specific Git repository base URL in later <link linkend="module-sets">module set</link> declarations, which is useful for quickly declaring many Git modules to build.</para> @@ -105,26 +120,21 @@ quickly declaring many Git modules to build.</para> to the base URL, and the actual base URL itself. For example:</para> <para> -<informalexample> <programlisting> global -# other options - -# This is the common path to all anonymous Git server modules. -git-repository-base <replaceable>kde-git</replaceable> <replaceable>kde:</replaceable> + # other options + # This is the common path to all anonymous Git server modules. + git-repository-base <replaceable>kde-git</replaceable> <replaceable>kde:</replaceable> end global # Module declarations module-set -# Now you can use the alias you defined earlier, but <emphasis>only</emphasis> -# in a module-set. -repository <replaceable>kde-git</replaceable> - -<link linkend="conf-use-modules">use-modules</link> <replaceable>module1.git</replaceable> <replaceable>module2.git</replaceable> + # Now you can use the alias you defined earlier, but <emphasis>only</emphasis> in a module-set. + repository <replaceable>kde-git</replaceable> + <link linkend="conf-use-modules">use-modules</link> <replaceable>module1.git</replaceable> <replaceable>module2.git</replaceable> end module-set </programlisting> -</informalexample> </para> <para>The module-set's <literal>use-modules</literal> option created two modules @@ -132,11 +142,11 @@ internally, with &kdesrc-build; behaving as if it had read:</para> <programlisting> module module1 -repository kde:<replaceable>module1.git</replaceable> + repository kde:<replaceable>module1.git</replaceable> end module module module2 -repository kde:<replaceable>module2.git</replaceable> + repository kde:<replaceable>module2.git</replaceable> end module </programlisting> @@ -156,8 +166,12 @@ different module sets.</para></tip> <row id="conf-ignore-modules"> <entry>ignore-modules</entry> -<entry>Can't be overridden</entry> -<entry><para>Modules named by this option, which would be chosen by &kdesrc-build; +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Available since</member><member>1.16</member> +</simplelist> +<para>Modules named by this option, which would be chosen by &kdesrc-build; due to a <link linkend="conf-use-modules">use-modules</link> option, are instead skipped entirely. Use this option when you want to build an entire <link linkend="kde-projects-module-sets">kde-projects</link> project grouping @@ -176,15 +190,18 @@ result in both <symbol>kde/kdegraphics/libs</symbol> and is compared).</para> <tip><para>See also <xref linkend="example-ignoring-a-module"/>.</para></tip> - -<para>This option was introduced with &kdesrc-build; 1.16.</para> </entry> </row> <row id="conf-install-environment-driver"> <entry>install-environment-driver</entry> -<entry>Cannot be overridden</entry> -<entry><para>By default, &kdesrc-build; will install a shell script that can be +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>Boolean</member> +<member>Default value</member><member>True</member> +<member>Available since</member><member>17.08</member> +</simplelist> +<para>Install a shell script that can be sourced in a user's profile setup scripts to easily establish needed environment variables to run the Plasma desktop built by &kdesrc-build;.</para> @@ -205,8 +222,6 @@ can be set elsewhere by the user in their existing profile setup scripts.</para> linkend="conf-install-session-driver">install-session-driver</link> option is also disabled.</para> -<para>This option was introduced with &kdesrc-build; 17.08.</para> - <tip><para>&kdesrc-build; will not overwrite your existing files (if present) unless you also pass the <option><link linkend="cmdline-delete-my-settings">--delete-my-settings</link></option> @@ -216,8 +231,13 @@ command-line option.</para></tip> <row id="conf-install-session-driver"> <entry>install-session-driver</entry> -<entry>Cannot be overridden</entry> -<entry><para>If enabled, &kdesrc-build; will try to install a driver for the graphical +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>Boolean</member> +<member>Default value</member><member>True</member> +<member>Available since</member><member>1.16</member> +</simplelist> +<para>If enabled, &kdesrc-build; will try to install a driver for the graphical login manager that allows you to login to your &kdesrc-build;-built &kde; desktop.</para> <para>This driver will alter the following files:</para> @@ -232,8 +252,6 @@ login manager that allows you to login to your &kdesrc-build;-built &kde; deskto option to <replaceable>false</replaceable>. If enabled, this feature also enables the <link linkend="conf-install-environment-driver">install-environment-driver</link> feature.</para> -<para>This option was introduced with &kdesrc-build; 1.16.</para> - <tip><para>&kdesrc-build; will not overwrite your existing files (if present) unless you also pass the <option><link linkend="cmdline-delete-my-settings">--delete-my-settings</link></option> @@ -241,27 +259,48 @@ command-line option.</para></tip> </entry> </row> +<row id="conf-niceness"> +<entry>niceness</entry> +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>Integer</member> +<member>Default value</member><member>10</member> +</simplelist> +<para>Set this option to a number between 20 and 0. The higher the number, the +lower a priority &kdesrc-build; will set for itself, i.e. the higher the +number, the "nicer" the program is.</para> +</entry> +</row> + <row id="conf-num-cores"> <entry>num-cores</entry> -<entry>Cannot be overridden</entry> <entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>Integer</member> +<member>Default value</member><member>Depends on system</member> +<member>Available since</member><member>20.07</member> +</simplelist> <para>This option is defined by &kdesrc-build; (when using the kdesrc-build-setup tool -or <command>kdesrc-build --initial-setup</command>), set to be the number of +or <command>kdesrc-build --generate-config</command>), set to be the number of available CPUs (as indicated by the external application <application>nproc</application>). If &kdesrc-build; cannot detect the number of CPUs, this value is set to 4.</para> <para>See <xref linkend="make-options-example"/> for an example of this -option's usage. This option was added in version 20.07.</para> +option's usage.</para> </entry> </row> <row id="conf-num-cores-low-mem"> <entry>num-cores-low-mem</entry> -<entry>Cannot be overridden</entry> <entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>Integer</member> +<member>Default value</member><member>Depends on system</member> +<member>Available since</member><member>20.07</member> +</simplelist> <para>This option is defined by &kdesrc-build; (when using the kdesrc-build-setup tool -or <command>kdesrc-build --initial-setup</command>), set to be the number of +or <command>kdesrc-build --generate-config</command>), set to be the number of CPUs that is deemed safe for heavyweight or other highly-intensive modules, such as <literal>qtwebengine</literal>, to avoid running out of memory during the build.</para> @@ -277,14 +316,17 @@ any module in the same way that <option>num-cores</option> is used.</para> <para>If &kdesrc-build; cannot detect available memory then this value will be set to 2.</para> -<para>This option was added in version 20.07.</para> </entry> </row> <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 +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Available since</member><member>1.15</member> +</simplelist> +<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 @@ -294,41 +336,45 @@ be saved to <filename>~/.local/state/kdesrc-build-data</filename> 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> </row> <row id="conf-ssh-identity-file"> <entry>ssh-identity-file</entry> -<entry>Cannot be overridden</entry> <entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Available since</member><member>1.14.2</member> +</simplelist> <para>Set this option to control which private SSH key file is passed to the <command>ssh-add</command> command when &kdesrc-build; is downloading source code from repositories that require authentication. See also: <xref linkend="ssh-agent-reminder"/>.</para> - -<para>This option was added in version 1.14.2.</para> </entry> </row> <row id="conf-use-idle-io-priority"> <entry>use-idle-io-priority</entry> -<entry>Cannot be overridden</entry> -<entry>This option, added in &kdesrc-build; 1.12, will cause a lower priority -to be used for disk and other I/O usage, which can significantly improve the +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>Boolean</member> +<member>Default value</member><member>False</member> +<member>Available since</member><member>1.12</member> +</simplelist> +<para>Use lower priority for disk and other I/O, which can significantly improve the responsiveness of the rest of the system at the expense of slightly longer -running times for &kdesrc-build;. The default is to be disabled, to enable -the lower disk priority set this to <userinput>true</userinput>. +running times for &kdesrc-build;.</para> </entry> </row> <row id="conf-use-inactive-modules"> <entry>use-inactive-modules</entry> -<entry>Cannot be overridden</entry> -<entry>This option when enabled will allow kdesrc-build to also clone and -pull from repositories marked as inactive. The default is to be disabled, -to allow inactive modules set this to <userinput>true</userinput>. +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>Boolean</member> +<member>Default value</member><member>False</member> +</simplelist> +<para>Allow kdesrc-build to also clone and pull from repositories marked as inactive.</para> </entry> </row> @@ -340,13 +386,12 @@ to allow inactive modules set this to <userinput>true</userinput>. <table id="option-table"> <title>All scopes (module, module-set and global) options</title> -<tgroup cols="3"> +<tgroup cols="2"> <thead> <row> -<entry>Option-name</entry> -<entry>Module -> Global Behavior</entry> -<entry>Notes</entry> +<entry>Option name</entry> +<entry>Description</entry> </row> </thead> @@ -354,8 +399,11 @@ to allow inactive modules set this to <userinput>true</userinput>. <row id="conf-binpath"> <entry>binpath</entry> -<entry>Module setting overrides global</entry> -<entry><para>Set this option to set the environment variable PATH while building. +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +</simplelist> +<para>Set this option to set the environment variable PATH while building. You cannot override this setting in a module option. The default value is the $<envar>PATH</envar> that is set when the script starts. This environment variable should include the colon-separated paths of your development @@ -367,27 +415,25 @@ may use the tilde (~) for any paths you add using this option.</para> <row id="conf-branch"> <entry>branch</entry> -<entry>Module setting overrides global</entry> -<entry><para>Set this option to checkout from a branch of &kde; instead of the -default of <replaceable>master</replaceable> where &kde; development -occurs.</para> - -<para> -For instance, to checkout &kde; 4.6 branch, you would set this option to -<replaceable>4.6</replaceable>.</para> - +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Default value</member><member>master</member> +</simplelist> +<para>Checkout the specified branch instead of the default branch.</para> <note><para>For most &kde; modules you probably wish to use the <link linkend="conf-branch-group">branch-group</link> option instead and use this option for case-by-case exceptions.</para></note> - </entry> </row> <row id="conf-branch-group"> <entry>branch-group</entry> -<entry>Module setting overrides global</entry> <entry> - +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Available since</member><member>1.16-pre2</member> +</simplelist> <para>Set this option to a general group from which you want modules to be chosen.</para> @@ -409,8 +455,6 @@ changes.</para> same is true of other specific branch selection options such as <link linkend="conf-tag">tag</link>.</para> -<para>This option was added in &kdesrc-build; 1.16-pre2.</para> - <note><para>This option only applies to <literal>kde-projects</literal> &git; modules (the common case). See also <xref linkend="kde-projects-module-sets"/>. @@ -421,9 +465,14 @@ linkend="kde-projects-module-sets"/>. <row id="conf-build-dir"> <entry>build-dir</entry> -<entry>Module setting overrides global</entry> -<entry>Use this option to change the directory to contain the built sources. There -are three different ways to use it: +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Default value</member><member><filename class="directory">~/kde/build</filename></member> +</simplelist> +<para> +Use this option to change the directory to contain the built sources. There +are three different ways to use it:</para> <orderedlist> @@ -445,23 +494,24 @@ class="directory">/home/user-name/builddir</filename>.</para></listitem> </orderedlist> -<para>The default value is <filename class="directory">~/kde/build</filename>.</para> -Perhaps surprisingly, this option can be changed per module. - +<para>Perhaps surprisingly, this option can be changed per module.</para> </entry> </row> <row id="conf-build-when-unchanged"> <entry>build-when-unchanged</entry> -<entry>Module setting overrides global</entry> -<entry><para>Use this option in order to control whether &kdesrc-build; always +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>Boolean</member> +<member>Default value</member><member>True</member> +</simplelist> +<para>Control whether &kdesrc-build; always tries to build a module that has not had any source code updates.</para> <para>By setting <option>build-when-unchanged</option> to <userinput>true</userinput>, &kdesrc-build; always attempts the build phase -for a module, even if the module did not have any source code updates. This is -the default setting since it is more likely to lead to a correct -build.</para> +for a module, even if the module did not have any source code updates. +With this value it will more likely lead to a correct build.</para> <para>By setting <option>build-when-unchanged</option> to <userinput>false</userinput>, &kdesrc-build; will only attempt to run the @@ -479,13 +529,16 @@ change at all.</para></important> <row id="conf-cmake-generator"> <entry>cmake-generator</entry> -<entry>Module setting overrides global</entry> -<entry><para>Use this option to specify which generator to use with &cmake;. +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Default value</member><member>Unix Makefiles</member> +</simplelist> +<para>Specify which generator to use with &cmake;. Currently both <literal>Ninja</literal> and <literal>Unix Makefiles</literal> as well as extra generators based on them like <literal>Eclipse CDT4 - Ninja </literal> are supported. Invalid (unsupported) values are ignored and treated -as if unset. If not set <literal>Unix Makefiles</literal> will be used by -default. +as if unset. </para> <para>Note that if a valid generator is also specified through @@ -495,8 +548,11 @@ value for <literal>cmake-generator</literal>.</para></entry> <row id="conf-cmake-toolchain"> <entry>cmake-toolchain</entry> -<entry>Module setting overrides global</entry> -<entry><para>Use this option to specify a toolchain file to use with &cmake;. +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +</simplelist> +<para>Specify a toolchain file to use with &cmake;. </para> <para>When a valid toolchain file is configured, &kdesrc-build; will <emphasis>no longer set environment variables automatically</emphasis>. @@ -512,9 +568,13 @@ value for <literal>cmake-toolchain</literal>.</para></entry> <row id="conf-cmake-options"> <entry>cmake-options</entry> -<entry>Appends to global options for the default buildsystem, overrides global -for other buildsystems.</entry> -<entry><para>Use this option to specify what flags to pass to &cmake; when +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +</simplelist> +<para>Appends to global options for the default buildsystem, overrides global +for other buildsystems.</para> +<para>Use this option to specify what flags to pass to &cmake; when creating the build system for the module. When this is used as a global option, it is applied to all modules that this script builds. When used as a module option, it is added to the end of the global options. This allows you to @@ -538,8 +598,9 @@ toolchains are ignored and will not be passed to &cmake;. <para>Since these options are passed directly to the &cmake; command line, they should be given as they would be typed into &cmake;. For example:</para> -<screen> cmake-options -DCMAKE_BUILD_TYPE=RelWithDebInfo -</screen> +<programlisting> +cmake-options -DCMAKE_BUILD_TYPE=RelWithDebInfo +</programlisting> <para>Since this is a hassle, &kdesrc-build; takes pains to ensure that as long as the rest of the options are set correctly, you should be able to leave this @@ -549,32 +610,38 @@ are set for you automatically)</para></entry> <row id="conf-compile-commands-export"> <entry>compile-commands-export</entry> -<entry>Module setting overrides global</entry> <entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>Boolean</member> +<member>Default value</member><member>True</member> +</simplelist> <para>Enables the generation of a <literal>compile_commands.json</literal> via CMake inside the build directory. -This option defaults to <replaceable>true</replaceable>, set it to <userinput>false</userinput> to disable -this behavior. </para> </entry> </row> <row id="conf-compile-commands-linking"> <entry>compile-commands-linking</entry> -<entry>Module setting overrides global</entry> <entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>Boolean</member> +<member>Default value</member><member>False</member> +</simplelist> <para>Enables the creation of symbolic links from <literal>compile_commands.json</literal> generated via CMake inside the build directory to the matching source directory. -This option defaults to <replaceable>false</replaceable>, set it to <userinput>true</userinput> to enable -the automatic symbolic link creation. </para> </entry> </row> <row id="conf-configure-flags"> <entry>configure-flags</entry> -<entry>Appends to global options for the default buildsystem, overrides global -for other buildsystems.</entry> -<entry><para>Use this option to specify what flags to pass to ./configure when +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +</simplelist> +<para>Appends to global options for the default buildsystem, overrides global +for other buildsystems.</para> +<para>Use this option to specify what flags to pass to ./configure when creating the build system for the module. When this is used as a global-option, it is applied to all modules that this script builds. <emphasis>This option only works for qt.</emphasis></para> @@ -587,8 +654,10 @@ only works for qt.</emphasis></para> <row id="conf-custom-build-command"> <entry>custom-build-command</entry> -<entry>Module setting overrides global (build system option)</entry> <entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +</simplelist> <para>This option can be set to run a different command (other than <command>make</command>, for example) in order to perform the build process. &kdesrc-build; should in general do the right thing, so you @@ -605,9 +674,13 @@ only works for qt.</emphasis></para> <row id="conf-cxxflags"> <entry>cxxflags</entry> -<entry>Appends to global options for the default buildsystem, overrides global -for other buildsystems.</entry> -<entry><para>Use this option to specify what flags to use for building the +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +</simplelist> +<para>Appends to global options for the default buildsystem, overrides global +for other buildsystems.</para> +<para>Use this option to specify what flags to use for building the module. This option is specified here instead of with <link linkend="conf-configure-flags">configure-flags</link> or <link @@ -624,21 +697,27 @@ linkend="conf-cmake-options">cmake-options</link> option. <row id="conf-dest-dir"> <entry>dest-dir</entry> -<entry>Module setting overrides global</entry> -<entry>Use this option to change the name a module is given on disk. For +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +</simplelist> +<para>Use this option to change the name a module is given on disk. For example, if your module was extragear/network, you could rename it to extragear-network using this option. Note that although this changes the name of the module on disk, it is not a good idea to include directories or directory separators in the name as this will interfere with any <link linkend="conf-build-dir">build-dir</link> or -<link linkend="conf-source-dir">source-dir</link> options. +<link linkend="conf-source-dir">source-dir</link> options.</para> </entry> </row> <row id="conf-do-not-compile"> <entry>do-not-compile</entry> -<entry>Module setting overrides global</entry> -<entry><para>Use this option to select a specific set of directories not to be built in a +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +</simplelist> +<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> @@ -655,8 +734,11 @@ options.</para> <row id="conf-git-user"> <entry>git-user</entry> -<entry>Module setting overrides global</entry> <entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Available since</member><member>15.09</member> +</simplelist> <para>This option is intended for &kde; developers. If set, it will be used to automatically setup identity information for the &git; source control software for <emphasis>newly downloaded</emphasis> &git; modules (including the vast @@ -668,27 +750,25 @@ in to the values set by this option.</para> <para>The value must be specified in the form <option><replaceable>User Name</replaceable> <<replaceable>em...@example.com</replaceable>></option>.</para> -<para> -<informalexample> <para>For instance, a developer named <quote>Foo Barbaz</quote> with the email address <quote>f...@abc.xyz</quote> would use:</para> - -<screen> +<para> +<programlisting> <symbol>git-user</symbol> <replaceable>Foo Barbaz</replaceable> <<replaceable>f...@abc.xyz</replaceable>> -</screen> -</informalexample> +</programlisting> </para> -<para>This option was introduced in &kdesrc-build; 15.09. -</para> </entry> </row> <row id="conf-http-proxy"> <entry>http-proxy</entry> -<entry>Module setting overrides global</entry> - -<entry><para>This option, if set, uses the specified URL as a proxy server to use for +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Available since</member><member>1.16</member> +</simplelist> +<para>This option, if set, uses the specified URL as a proxy server to use for any HTTP network communications (for example, when downloading the <link linkend="kde-projects-module-sets">KDE project database</link>).</para> @@ -696,18 +776,19 @@ database</link>).</para> on also use that proxy server, if possible, by setting the <envar>http_proxy</envar> environment variable to the indicated server, <emphasis>if that environment variable is not already set</emphasis>.</para> - -<para>This option was introduced with &kdesrc-build; 1.16.</para> </entry> </row> <row id="conf-directory-layout"> <entry>directory-layout</entry> -<entry>Module setting overrides global</entry> -<entry><para>This option is used to configure the layout which &kdesrc-build; should use when +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Valid values</member><member><userinput>flat</userinput>, +<userinput>invent</userinput>, <userinput>metadata</userinput></member> +</simplelist> +<para>This option is used to configure the layout which &kdesrc-build; should use when creating source and build directories.</para> -<para>Currently, there are three possible values: <userinput>flat</userinput>, -<userinput>invent</userinput>, and <userinput>metadata</userinput>.</para> <para>The <userinput>flat</userinput> layout is the default value, and will group all modules directly underneath the top level source and build directories. For example, <literal>source/extragear/network/telepathy/ktp-text-ui</literal> in the <userinput>metadata</userinput> @@ -732,10 +813,12 @@ due to changes in the project metadata.</para> <row id="conf-include-dependencies"> <entry>include-dependencies</entry> -<entry>Module setting overrides global</entry> <entry> -<para>This option, when set to <userinput>true</userinput> requests that -&kdesrc-build; also include known dependencies of this module in its build, +<simplelist type='horiz' columns='2'> +<member>Type</member><member>Boolean</member> +<member>Default value</member><member>True</member> +</simplelist> +<para>Controls if &kdesrc-build; will include known dependencies of this module in its build, without requiring you to mention those dependencies (even indirectly).</para> <note><para>This option only works for <link @@ -744,7 +827,7 @@ modules</link>, and requires that the metadata maintained by the &kde; developers is accurate for your selected <link linkend="conf-branch-group">branch-group</link>.</para></note> -<para>This option is enabled by default, to support building applications +<para>This is to support building applications that need versions of &Qt; or &plasma; more recent than supported on common operating systems.</para> </entry> @@ -752,69 +835,92 @@ common operating systems.</para> <row id="conf-install-after-build"> <entry>install-after-build</entry> -<entry>Module setting overrides global</entry> -<entry>This option is used to install the package after it successfully builds. -This option is enabled by default. If you want to disable this, you need to set -this option to <userinput>false</userinput> in the <link -linkend="configure-data">configuration file</link>. You can also use the <link +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Default value</member><member>True</member> +</simplelist> +<para>This option is used to install the package after it successfully builds. +You can also use the <link linkend="cmdline-no-install"><option>--no-install</option></link> command line -flag. +flag.</para> </entry> </row> <row id="conf-kdedir"> <entry>kdedir</entry> -<entry>Module setting overrides global</entry> -<entry>This option sets the directory that &kde; will be installed to after it -is built. It defaults to <filename class="directory">~/kde/usr</filename>. If you +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Default value</member><member><filename class="directory">~/kde/usr</filename></member> +</simplelist> +<para>This option sets the directory that &kde; will be installed to after it +is built. If you change this to a directory needing root access, you may want to read about the <link linkend="conf-make-install-prefix">make-install-prefix</link> option as -well.</entry> +well.</para> +</entry> </row> <row id="conf-libname"> <entry>libname</entry> -<entry>Module setting overrides global</entry> -<entry>Set this option to change the default name of the installed library directory +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Default value</member><member>Auto detected</member> +</simplelist> +<para>Set this option to change the default name of the installed library directory inside $<envar>KDEDIR</envar> and $<envar>QTDIR</envar>. On many systems this is either "lib" or "lib64". Auto-detection is attempted to set the correct name by default, -but if the guess is wrong then it can be changed with this setting. +but if the guess is wrong then it can be changed with this setting.</para> </entry> </row> <row id="conf-libpath"> <entry>libpath</entry> -<entry>Module setting overrides global</entry> -<entry>Set this option to set the environment variable +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +</simplelist> +<para>Set this option to set the environment variable <envar>LD_LIBRARY_PATH</envar> while building. You cannot override this setting in a module option. The default value is blank, but the paths <filename class="directory">$<envar>KDEDIR</envar>/$<envar>LIBNAME</envar></filename> and <filename class="directory">$<envar>QTDIR</envar>/$<envar>LIBNAME</envar></filename> are automatically added. -You may use the tilde (~) for any paths you add using this option. +You may use the tilde (~) for any paths you add using this option.</para> </entry> </row> <row id="conf-log-dir"> <entry>log-dir</entry> -<entry>Module setting overrides global</entry> -<entry>Use this option to change the directory used to hold the log files -generated by the script. +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +</simplelist> +<para>Use this option to change the directory used to hold the log files +generated by the script.</para> </entry> </row> <row id="conf-make-install-prefix"> <entry>make-install-prefix</entry> -<entry>Module setting overrides global</entry> -<entry>Set this variable to a space-separated list, which is interpreted as a +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +</simplelist> +<para>Set this variable to a space-separated list, which is interpreted as a command and its options to precede the <userinput><command>make</command> <option>install</option></userinput> command used to install modules. This is useful for installing packages with &sudo; for example, but -please be careful while dealing with root privileges.</entry> +please be careful while dealing with root privileges.</para></entry> </row> <row id="conf-make-options"> <entry>make-options</entry> -<entry>Module setting overrides global (build system option)</entry> -<entry><para>Set this variable in order to pass command line options to the +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +</simplelist> +<para>Set this variable in order to pass command line options to the <command>make</command> command. This is useful for programs such as <ulink url="https://github.com/distcc/distcc"><application>distcc</application></ulink> or systems with more than one processor core.</para> @@ -828,38 +934,44 @@ setting.</para> <row id="conf-manual-build"> <entry>manual-build</entry> -<entry>Module setting overrides global</entry> -<entry>Set the option value to <userinput>true</userinput> to keep the +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>Boolean</member> +<member>Default value</member><member>False</member> +</simplelist> +<para>Set the option value to <userinput>true</userinput> to keep the build process from attempting to build this module. It will still be kept up-to-date when updating from &git;. This option is exactly equivalent -to the <link linkend="cmdline-no-build"><option>--no-build</option></link> +to the +<link linkend="cmdline-no-build"> +<option>--no-build</option> +</link> command line option. +</para> </entry> </row> <row id="conf-manual-update"> <entry>manual-update</entry> -<entry>Module setting overrides global</entry> -<entry>Set the option value to <userinput>true</userinput> to keep the +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>Boolean</member> +<member>Default value</member><member>False</member> +</simplelist> +<para>Set the option value to <userinput>true</userinput> to keep the build process from attempting to update (and by extension, build or install) this module. If you set this option for a module, then you have essentially -commented it out. -</entry> -</row> - -<row id="conf-niceness"> -<entry>niceness</entry> -<entry>Cannot be overridden</entry> -<entry>Set this option to a number between 20 and 0. The higher the number, the -lower a priority &kdesrc-build; will set for itself, i.e. the higher the -number, the "nicer" the program is. The default is 10. +commented it out.</para> </entry> </row> <row id="conf-ninja-options"> <entry>ninja-options</entry> -<entry>Module setting overrides global (build system option)</entry> -<entry><para>Set this variable in order to pass command line options to the +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +</simplelist> +<para>Set this variable in order to pass command line options to the <command>ninja</command> build command. This can be useful to enable <quote>verbose</quote> output or to manually reduce the number of parallel build jobs that <command>ninja</command> would @@ -873,7 +985,6 @@ In this situation, you can set <literal>NINJAFLAGS</literal> as a way to have <command>ninja</command>, by using <link linkend="conf-make-options">make-options</link>.</para> -<informalexample> <programlisting> options <replaceable>qtwebengine</replaceable> # Restrict make and ninja to using no more than 6 separate compile jobs even @@ -881,24 +992,32 @@ options <replaceable>qtwebengine</replaceable> <option><link linkend="conf-make-options">make-options</link></option> -j<replaceable>6</replaceable> NINJAFLAGS=-j<replaceable>6</replaceable> end options </programlisting> -</informalexample> </note> </entry> </row> <row id="conf-no-src"> <entry>no-src</entry> -<entry>Module setting overrides global</entry> -<entry>If this option is set to true then &kdesrc-build; will not update the +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>Boolean</member> +<member>Default value</member><member>False</member> +</simplelist> +<para>If this option is set to true then &kdesrc-build; will not update the source code for the module automatically. It will still try to build the -module if it normally would have tried anyways.</entry> +module if it normally would have tried anyways.</para> +</entry> </row> <row id="conf-override-build-system"> <entry>override-build-system</entry> -<entry>Module setting overrides global</entry> -<entry><para>This is an advanced option, added in &kdesrc-build; 1.16.</para> - +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Default value</member><member>Auto detected</member> +<member>Valid values</member><member>KDE, Qt, qmake, generic, autotools, meson</member> +<member>Available since</member><member>1.16</member> +</simplelist> <para>Normally &kdesrc-build; will detect the appropriate build system to use for a module after it is downloaded. This is done by checking for the existence of specific files in the module's source directory.</para> @@ -947,8 +1066,11 @@ the auto-detection. In this case you can manually specify the correct build type <row id="conf-prefix"> <entry>prefix</entry> -<entry>Module setting overrides global</entry> -<entry><para>This option controls where to install the module (normally the +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +</simplelist> +<para>This option controls where to install the module (normally the <option><link linkend="conf-kdedir">kdedir</link></option> setting is used). Using this option allows you to install a module to a different directory than where the KDE Platform libraries are installed, such as if you were using @@ -960,46 +1082,61 @@ in the path to have them expanded to the module's name.</para> <row id="conf-purge-old-logs"> <entry>purge-old-logs</entry> -<entry>Module setting overrides global</entry> -<entry><para>This option controls whether old log directories are automatically -deleted or not. The default value is <replaceable>true</replaceable>.</para> +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>Boolean</member> +<member>Default value</member><member>True</member> +</simplelist> +<para>This option controls whether old log directories are automatically +deleted or not.</para> </entry> </row> <row id="conf-qmake-options"> <entry>qmake-options</entry> -<entry>Module setting overrides global</entry> - -<entry><para>Any options specified here are passed to the +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Available since</member><member>1.16</member> +</simplelist> +<para>Any options specified here are passed to the <command>qmake</command> command, for modules that use the <symbol>qmake</symbol> build system. For instance, you can use the <userinput>PREFIX=/path/to/qt</userinput> option to qmake to override where it installs the module. </para> -<para>This option was added to &kdesrc-build; 1.16.</para> </entry> </row> <row id="conf-qtdir"> <entry>qtdir</entry> -<entry>Module setting overrides global</entry> -<entry>Set this option to set the environment variable <envar>QTDIR</envar> while building. +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +</simplelist> +<para>Set this option to set the environment variable <envar>QTDIR</envar> while building. If you do not specify this option, &kdesrc-build; will assume that &Qt; is provided by the operating system. +</para> </entry> </row> <row id="conf-remove-after-install"> <entry>remove-after-install</entry> -<entry>Module setting overrides global</entry> -<entry><para>If you are low on hard disk space, you may want to use this option +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Valid values</member><member>none, builddir, all</member> +<member>Default value</member><member>none</member> +</simplelist> +<para>If you are low on hard disk space, you may want to use this option in order to automatically delete the build directory (or both the source and build directories for one-time installs) after the module is successfully installed. </para> <para>Possible values for this option are: <itemizedlist> -<listitem><para>none - Do not delete anything (This is the default).</para></listitem> +<listitem><para>none - Do not delete anything.</para></listitem> <listitem><para>builddir - Delete the build directory, but not the source.</para></listitem> <listitem><para>all - Delete both the source code and build directory.</para></listitem> </itemizedlist> @@ -1013,8 +1150,12 @@ since &kdesrc-build; will be unable to perform incremental builds.</para> <row id="conf-repository"> <entry>repository</entry> -<entry>Module setting overrides global</entry> -<entry><para>This option was introduced with version 1.10, and is used to +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Available since</member><member>1.10</member> +</simplelist> +<para>This option is used to specify the &git; repository to download the source code for the module. &Qt; (and therefore qt) would need this option, as well as various &kde; modules that are in the process of conversion to use &git;.</para></entry> @@ -1022,39 +1163,47 @@ specify the &git; repository to download the source code for the module. <row id="conf-revision"> <entry>revision</entry> -<entry>Module setting overrides global</entry> -<entry><para>If this option is set to a value other than 0 (zero), &kdesrc-build; +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Available since</member><member>1.16</member> +</simplelist> +<para>If this option is set to a value other than 0 (zero), &kdesrc-build; will force the source update to bring the module to the exact revision given, even if options like <link linkend="conf-branch">branch</link> are in effect. If the module is already at the given revision then it will not be updated further unless this option is changed or removed from the configuration.</para> - -<note><para>This option did not work for git-based modules (including <link -linkend="kde-projects-module-sets">kde-projects</link> modules) until -&kdesrc-build; version 1.16.</para></note> - </entry> </row> <row id="conf-run-tests"> <entry>run-tests</entry> -<entry>Module setting overrides global (build system option)</entry> -<entry>If set to <userinput>true</userinput>, then the module will be +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>Boolean</member> +<member>Default value</member><member>False</member> +</simplelist> +<para>If set to <userinput>true</userinput>, then the module will be built with support for running its test suite, and the test suite will be executed as part of the build process. &kdesrc-build; will show a simple report of the test results. This is useful for developers or those who want -to ensure their system is setup correctly.</entry> +to ensure their system is setup correctly.</para></entry> </row> <row id="conf-set-env"> <entry>set-env</entry> -<entry>Module setting overrides global</entry> -<entry><para>This option accepts a space-separated set of values, where the first value +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +</simplelist> +<para>This option accepts a space-separated set of values, where the first value is the environment variable to set, and the rest of the values is what you want the variable set to. For example, to set the variable <envar>RONALD</envar> to McDonald, you would put in the appropriate section this command:</para> -<screen><command>set-env</command> <envar>RONALD</envar> <userinput>McDonald</userinput></screen> +<programlisting> +<command>set-env</command> <envar>RONALD</envar> <userinput>McDonald</userinput> +</programlisting> <para>This option is special in that it can be repeated without overriding earlier set-env settings in the same section of the <link linkend="configure-data">configuration file</link>. This way you can set more than one environment variable per module (or @@ -1064,40 +1213,53 @@ globally).</para> <row id="conf-source-dir"> <entry>source-dir</entry> -<entry>Module setting overrides global</entry> -<entry>This option is used to set the directory on your computer to store the &kde; -&git; sources at. If you do not specify this value, the default is -<filename class="directory">~/kde/src</filename>. You may use the tilde (~) -to represent the home directory if using this option. +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Default value</member><member><filename class="directory">~/kde/src</filename></member> +</simplelist> +<para>This option is used to set the directory on your computer to store the &kde; +&git; sources at. You may use the tilde (~) +to represent the home directory if using this option.</para> </entry> </row> <row id="conf-stop-on-failure"> <entry>stop-on-failure</entry> -<entry>Module setting overrides global</entry> -<entry>Setting this option to <userinput>false</userinput> allows the script to continue execution -after an error occurs during the build or install process. Default value is <literal>true</literal>. +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>Boolean</member> +<member>Default value</member><member>True</member> +</simplelist> +<para>Setting this option to <userinput>false</userinput> allows the script to continue execution +after an error occurs during the build or install process.</para> </entry> </row> <row id="conf-tag"> <entry>tag</entry> -<entry>Module setting overrides global</entry> -<entry><para>Use this option to download a specific release of a module.</para> +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Available since</member><member>1.16</member> +</simplelist> +<para>Use this option to download a specific release of a module.</para> <para><emphasis>Note:</emphasis> The odds are very good that you <emphasis>do not want</emphasis> to use this option. &kde; releases are available in tarball form from the <ulink url="https://download.kde.org/">&kde; download site</ulink>.</para> - -<note><para>This option has only been supported for git-based modules since -&kdesrc-build; 1.16.</para></note> </entry> </row> <row id="conf-use-clean-install"> <entry>use-clean-install</entry> -<entry>Module setting overrides global (build system option)</entry> -<entry><para>Set this option to <userinput>true</userinput> in order to +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>Boolean</member> +<member>Default value</member><member>False</member> +<member>Available since</member><member>1.12</member> +</simplelist> +<para>Set this option to <userinput>true</userinput> in order to have &kdesrc-build; run <command>make uninstall</command> directly before running <command>make install</command>.</para> @@ -1105,9 +1267,6 @@ running <command>make install</command>.</para> files, &cmake; metadata, etc. that can cause issues in long-lived &kde; installations. However this only works on build systems that support <command>make uninstall</command>.</para> - -<para>This option was added with &kdesrc-build; 1.12, but was not documented -until &kdesrc-build; 1.16.</para> </entry> </row> @@ -1119,26 +1278,28 @@ until &kdesrc-build; 1.16.</para> <table id="options-module-set-table"> <title>Module-set scope only options</title> -<tgroup cols="3"> +<tgroup cols="2"> <thead> <row> -<entry>Option-name</entry> -<entry>Module -> Global Behavior</entry> -<entry>Notes</entry> +<entry>Option name</entry> +<entry>Description</entry> </row> </thead> <tbody> <row id="conf-use-modules"> <entry>use-modules</entry> -<entry>Can only use in <link linkend="module-sets">module-set</link></entry> -<entry><para>This option, added in &kdesrc-build; 1.12.1, allows you to easily +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Available since</member><member>1.12.1</member> +</simplelist> +<para>This option allows you to easily specify many different modules to build at the same point in <link linkend="kdesrc-buildrc">the configuration file</link>.</para> -<para>This option <emphasis>must</emphasis> be used within a -<literal>module-set</literal>. Every identifier passed to this option is +<para>Every identifier passed to this option is internally converted to a &kdesrc-build; module, with a <link linkend="conf-repository"><option>repository</option></link> option set to the module-set's repository combined with the identifier name in order to setup the