Git commit cce1c6a1d1d4332e84a6e2c681893e274f203a0d by Andrew Shark. Committed on 05/01/2024 at 19:58. Pushed by ashark into branch 'master'.
doc: conf-options-table - separate docbook A +1363 -0 doc/conf-options-table.docbook [INFRASTRUCTURE] M +2 -1363 doc/index.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/cce1c6a1d1d4332e84a6e2c681893e274f203a0d diff --git a/doc/conf-options-table.docbook b/doc/conf-options-table.docbook new file mode 100644 index 00000000..8c1a32e9 --- /dev/null +++ b/doc/conf-options-table.docbook @@ -0,0 +1,1363 @@ +<sect1 id="conf-options-table"> +<title>Table of available configuration options</title> + +<para>Here is a table of the various options, containing the following +information:</para> + +<itemizedlist> + +<listitem><para>The option name</para></listitem> + +<listitem><para>A description of how &kdesrc-build; responds if the option is +set in both the global section, and the module section of the <link +linkend="configure-data">configuration file</link> while building a +module.</para></listitem> + +<listitem><para>Special comments on the purpose and usage of the +option.</para></listitem> + +</itemizedlist> + +<table id="options-global-table"> +<title>Global scope only options</title> +<tgroup cols="2"> + +<thead> +<row> +<entry>Option name</entry> +<entry>Description</entry> +</row> +</thead> +<tbody> + +<row id="conf-async"> +<entry>async</entry> +<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.</para></entry> +</row> + +<row id="conf-colorful-output"> +<entry>colorful-output</entry> +<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).</para> +</entry> +</row> + +<row id="conf-disable-agent-check"> +<entry>disable-agent-check</entry> +<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.</para> +</entry> +</row> + +<row id="conf-git-desired-protocol"> +<entry>git-desired-protocol</entry> +<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 +prefer when pushing source code for these modules. Normally the very-efficient +<literal>git</literal> protocol is used, but this may be blocked in some +networks (e.g. corporate intranets, public Wi-Fi). An alternative protocol +which is much better supported is the <literal>https</literal> protocol used for +Internet web sites.</para> + +<para>If you are using one of these constrained networks you can set this +option to <userinput>http</userinput> to prefer <literal>https</literal> +communications instead.</para> + +<tip><para>You may also need the <link +linkend="conf-http-proxy">http-proxy</link> option if an HTTP proxy is also +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> + +</entry> +</row> + +<row id="conf-install-environment-driver"> +<entry>install-environment-driver</entry> +<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> + +<para>This driver will alter the following files:</para> + +<itemizedlist> +<listitem><para><filename>$XDG_CONFIG_HOME/kde-env-master.sh</filename> (normally found at <filename>~/.config/kde-env-master.sh</filename>).</para></listitem> +<listitem><para><filename>$XDG_CONFIG_HOME/kde-env-user.sh</filename> (normally found at <filename>~/.config/kde-env-user.sh</filename>).</para></listitem> +</itemizedlist> + +<para>The <filename>kde-env-user.sh</filename> is optional. It is +intended for user customizations (see the <ulink url="https://userbase.kde.org/KDE_System_Administration/Environment_Variables#Troubleshooting_and_Debugging";>Troubleshooting and Debugging</ulink> +section of the &kde; UserBase for examples of customizable settings), but these settings +can be set elsewhere by the user in their existing profile setup scripts.</para> + +<para>You can disable this feature by setting this option to +<replaceable>false</replaceable>, and ensuring that the <link +linkend="conf-install-session-driver">install-session-driver</link> option is +also disabled.</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> +command-line option.</para></tip> +</entry> +</row> + +<row id="conf-install-session-driver"> +<entry>install-session-driver</entry> +<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> + +<itemizedlist> +<listitem><para><filename>~/.xsession</filename></para></listitem> +<listitem><para><filename>$XDG_CONFIG_HOME/kde-env-master.sh</filename> (normally found at <filename>~/.config/kde-env-master.sh</filename>).</para></listitem> +<listitem><para><filename>$XDG_CONFIG_HOME/kde-env-user.sh</filename> (normally found at <filename>~/.config/kde-env-user.sh</filename>).</para></listitem> +</itemizedlist> + +<para>If you maintain your own login driver then you can disable this feature by setting this +option to <replaceable>false</replaceable>. If enabled, this feature also enables the +<link linkend="conf-install-environment-driver">install-environment-driver</link> feature.</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> +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> +<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 <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.</para> +</entry> +</row> + +<row id="conf-num-cores-low-mem"> +<entry>num-cores-low-mem</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 <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> + +<para>The typical calculation is one CPU core for every 2 +gigabytes (GiB) of total memory. At least 1 core will be specified, +and no more than <option><link linkend="conf-num-cores">num-cores</link></option> +cores will be specified.</para> + +<para>Although this option is intended to support &Qt; modules, you can use it for your +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> + +</entry> +</row> + +<row id="conf-persistent-data-file"> +<entry>persistent-data-file</entry> +<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 +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> +</entry> +</row> + +<row id="conf-ssh-identity-file"> +<entry>ssh-identity-file</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> +</entry> +</row> + +<row id="conf-use-idle-io-priority"> +<entry>use-idle-io-priority</entry> +<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;.</para> +</entry> +</row> + +<row id="conf-use-inactive-modules"> +<entry>use-inactive-modules</entry> +<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> + +</tbody> +</tgroup> +</table> + +<!-- Between tables --> + +<table id="option-table"> +<title>All scopes (module, module-set and global) options</title> +<tgroup cols="2"> + +<thead> +<row> +<entry>Option name</entry> +<entry>Description</entry> +</row> +</thead> + +<tbody> + +<row id="conf-binpath"> +<entry>binpath</entry> +<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 +toolchain. The paths <filename class="directory">install-dir/bin</filename> and +<filename class="directory">$<envar>QTDIR</envar>/bin</filename> are automatically added. You +may use the tilde (~) for any paths you add using this option.</para> +</entry> +</row> + +<row id="conf-branch"> +<entry>branch</entry> +<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> +<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> + +<para>For supported &git; module types, &kdesrc-build; will determine the +actual branch to use automatically based on rules encoded by the &kde; +developers (these rules may be viewed in the +<literal>kde-build-metadata</literal> source repository in your source +directory). After a branch is determined that branch is used as if you had +specified it yourself using the <link linkend="conf-branch">branch</link> +option. +</para> + +<para>This is useful if you're just trying to maintain up-to-date on some +normal development track without having to pay attention to all the branch name +changes.</para> + +<para>Note that if you <emphasis>do</emphasis> choose a +<literal>branch</literal> yourself, that it will override this setting. The +same is true of other specific branch selection options such as <link +linkend="conf-tag">tag</link>.</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"/>. +</para></note> + +</entry> +</row> + +<row id="conf-build-dir"> +<entry>build-dir</entry> +<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> + +<listitem><para>Relative to the &kde; &git; source directory (see <link +linkend="conf-source-dir">the source-dir option</link>). This is the default, +and is selected if you type a directory name that does not start with a tilde +(~) or a slash (/).</para></listitem> + +<listitem><para>Absolute path. If you specify a path that begins with a /, then +that path is used directly. For example, <filename +class="directory">/tmp/kde-obj-dir/</filename>.</para></listitem> + +<listitem><para>Relative to your home directory. If you specify a path that +begins with a ~, then the path is used relative to your home directory, +analogous to the shell's tilde-expansion. For example, <filename +class="directory">~/builddir</filename> would set the build directory to +<filename +class="directory">/home/user-name/builddir</filename>.</para></listitem> + +</orderedlist> + +<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> +<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. +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 +build phase for a module if the module has a source code update, or in other +situations where it is likely that a rebuild is actually required. This can save +time, especially if you run &kdesrc-build; daily, or more frequently.</para> + +<important><para>This feature is provided as an optimization only. Like many +other optimizations, there are trade-offs for the correctness of your +installation. For instance, changes to the qt or kdelibs modules may cause +a rebuild of other modules to be necessary, even if the source code doesn't +change at all.</para></important> +</entry> +</row> + +<row id="conf-cmake-generator"> +<entry>cmake-generator</entry> +<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. +</para> + +<para>Note that if a valid generator is also specified through +<link linkend="conf-cmake-options">cmake-options</link> it will override the +value for <literal>cmake-generator</literal>.</para></entry> +</row> + +<row id="conf-cmake-toolchain"> +<entry>cmake-toolchain</entry> +<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>. +You can use &set-env;, &binpath; and &libpath; to fix up the environment +manually if your toolchain file does not work out of the box with +&kdesrc-build;. Refer to <link linkend="kdesrc-build-std-flags">the overview +of standard flags added by &kdesrc-build;</link> for more information. +</para> +<para>Note that if a valid toolchain is also specified through +<link linkend="conf-cmake-options">cmake-options</link> it will override the +value for <literal>cmake-toolchain</literal>.</para></entry> +</row> + +<row id="conf-cmake-options"> +<entry>cmake-options</entry> +<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 +specify common &cmake; options in the global section.</para> + +<para>This option does not apply to qt (which does not use &cmake;). Use +<link linkend="conf-configure-flags">configure-flags</link> instead.</para> + +<para>If a valid generator is specified among the listed options it will +override the value of +<link linkend="conf-cmake-generator">cmake-generator</link>. Invalid +(unsupported) generators are ignored and will not be passed to &cmake;. +</para> + +<para>If a valid toolchain file is specified among the listed options it will +override the value of +<link linkend="conf-cmake-toolchain">cmake-toolchain</link>. Invalid +toolchains are ignored and will not be passed to &cmake;. +</para> + +<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> + +<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 +option blank. (In other words, <emphasis>required</emphasis> &cmake; parameters +are set for you automatically)</para></entry> +</row> + +<row id="conf-compile-commands-export"> +<entry>compile-commands-export</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. +</para> +</entry> +</row> + +<row id="conf-compile-commands-linking"> +<entry>compile-commands-linking</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. +</para> +</entry> +</row> + +<row id="conf-configure-flags"> +<entry>configure-flags</entry> +<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> + +<para>To change configuration settings for KDE modules, see +<link linkend="conf-cmake-options">cmake-options</link>. +</para> +</entry> +</row> + +<row id="conf-custom-build-command"> +<entry>custom-build-command</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 + should not need to set this option. However it can be useful to use + alternate build systems. + </para> + + <para>The value of this option is used as the command line to run, modified + by the <link linkend="conf-make-options">make-options</link> option as + normal. + </para> +</entry> +</row> + +<row id="conf-cxxflags"> +<entry>cxxflags</entry> +<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 +linkend="conf-cmake-options">cmake-options</link> because this option will also +set the environment variable <envar>CXXFLAGS</envar> during the build process.</para> + +<para>Note that for &kde; 4 and any other modules that use &cmake;, it is +necessary to set the CMAKE_BUILD_TYPE option to <userinput>none</userinput> +when configuring the module. This can be done using the <link +linkend="conf-cmake-options">cmake-options</link> option. +</para> +</entry> +</row> + +<row id="conf-dest-dir"> +<entry>dest-dir</entry> +<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.</para> +</entry> +</row> + +<row id="conf-do-not-compile"> +<entry>do-not-compile</entry> +<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> + +<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>See <xref linkend="not-compiling"/> for an example.</para> +</entry> +</row> + +<row id="conf-git-user"> +<entry>git-user</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 +majority of &kde; modules).</para> + +<para>Specifically, the user's name and email fields for each new &git; repository are filled +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>For instance, a developer named <quote>Foo Barbaz</quote> with the +email address <quote>f...@abc.xyz</quote> would use:</para> +<para> +<programlisting> + <symbol>git-user</symbol> <replaceable>Foo Barbaz</replaceable> <<replaceable>f...@abc.xyz</replaceable>> +</programlisting> +</para> + +</entry> +</row> + +<row id="conf-http-proxy"> +<entry>http-proxy</entry> +<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> + +<para>In addition, &kdesrc-build; will try to ensure that the tools it depends +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> +</entry> +</row> + +<row id="conf-directory-layout"> +<entry>directory-layout</entry> +<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>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> +layout would be <literal>source/ktp-text-ui</literal> using the <userinput>flat</userinput> layout +instead. +</para> +<para>The <userinput>invent</userinput> layout creates a directory hierarchy mirroring the relative +paths of repositories on <ulink url="https://invent.kde.org/";>invent.kde.org</ulink>. For example +<literal>source/kde/applications/kate</literal> in the <userinput>metadata</userinput> layout would +be <literal>source/utilities/kate</literal> using the <userinput>invent</userinput> layout instead. +This layout only affects KDE projects. It is a good choice for people starting out with +&kdesrc-build;. +</para> +<para>Finally, the <userinput>metadata</userinput> layout is the same as the old default +behaviour. This layout organises KDE projects according to the project paths specified in the +project metadata for these modules. This is a good choice if you want a directory layout which +tracks with certain KDE processes, but note that this path is therefore not always stable. As a +result, &kdesrc-build; may abandon an old copy of the repository and clone a new one for a project +due to changes in the project metadata.</para> +</entry> +</row> + +<row id="conf-generate-vscode-project-config"> +<entry>generate-vscode-project-config</entry> + +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>Boolean</member> +<member>Default value</member><member>False</member> +</simplelist> + +<para>Module setting overrides global</para> + +<para>Set this option to <userinput>true</userinput> to make +&kdesrc-build; create VS Code project files (.vscode directory) in the module +source directory.</para> + +<para>The .vscode folder will be created in the project source directory, only +if it does not already exist. The configurations will enable the use of LSP, +building, debugging, and running the project from within VS Code.</para> + +<para>The configuration also recommends extensions to install that are useful +for working on most KDE projects.</para> + +<para>You can also use the <link linkend="cmdline-generate-vscode-project-config"> +<option>--generate-vscode-project-config</option></link> command line flag.</para> +</entry> +</row> + +<row id="conf-include-dependencies"> +<entry>include-dependencies</entry> +<entry> +<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 +linkend="kde-projects-module-sets"><literal>kde-project</literal>-based +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 is to support building applications +that need versions of &Qt; or &plasma; more recent than supported on +common operating systems.</para> +</entry> +</row> + +<row id="conf-install-after-build"> +<entry>install-after-build</entry> +<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.</para> +</entry> +</row> + +<row id="conf-install-dir"> +<entry>install-dir</entry> +<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.</para> +</entry> +</row> + +<row id="conf-libname"> +<entry>libname</entry> +<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 ${install-dir} 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.</para> +</entry> +</row> + +<row id="conf-libpath"> +<entry>libpath</entry> +<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">${install-dir}/$<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.</para> +</entry> +</row> + +<row id="conf-log-dir"> +<entry>log-dir</entry> +<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> +<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.</para></entry> +</row> + +<row id="conf-make-options"> +<entry>make-options</entry> +<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> +<para>Note that not all supported build systems use <command>make</command>. For +build systems that use <command>ninja</command> for build (such as the +<link linkend="conf-override-build-system"><application>Meson</application> +build system</link>), see the <link linkend="conf-ninja-options">ninja-options</link> +setting.</para> +</entry> +</row> + +<row id="conf-manual-build"> +<entry>manual-build</entry> +<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> +command line option. +</para> +</entry> +</row> + +<row id="conf-manual-update"> +<entry>manual-update</entry> +<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.</para> +</entry> +</row> + +<row id="conf-ninja-options"> +<entry>ninja-options</entry> +<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 +use.</para> + +<note><para>Note that this setting only controls ninja when used by &kdesrc-build;. +The &Qt; <quote>webengine</quote> module uses <command>ninja</command> indirectly, but +only officially supports being built by <command>make</command>. +In this situation, you can set <literal>NINJAFLAGS</literal> as a way to have +<command>make</command> pass the appropriate flags when it later calls +<command>ninja</command>, by using +<link linkend="conf-make-options">make-options</link>.</para> + +<programlisting> +options <replaceable>qtwebengine</replaceable> + # Restrict make and ninja to using no more than 6 separate compile jobs even + # when more CPU is available, to avoid running out of memory + <option><link linkend="conf-make-options">make-options</link></option> -j<replaceable>6</replaceable> NINJAFLAGS=-j<replaceable>6</replaceable> +end options +</programlisting> +</note> +</entry> +</row> + +<row id="conf-no-src"> +<entry>no-src</entry> +<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.</para> +</entry> +</row> + +<row id="conf-override-build-system"> +<entry>override-build-system</entry> +<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> + +<para>Some modules may include more than one required set of files, which could confuse +the auto-detection. In this case you can manually specify the correct build type.</para> + +<para>Currently supported build types that can be set are:</para> + +<variablelist> + <varlistentry> + <term>KDE</term> + <listitem><para>Used to build &kde; modules. In reality it can be used to build + almost any module that uses &cmake; but it is best not to rely on this.</para></listitem> + </varlistentry> + <varlistentry> + <term>Qt</term> + <listitem><para>Used to build the &Qt; library itself.</para></listitem> + </varlistentry> + <varlistentry> + <term>qmake</term> + <listitem><para>Used to build &Qt; modules that use + <application>qmake</application>-style <literal>.pro</literal> + files.</para></listitem> + </varlistentry> + <varlistentry> + <term>generic</term> + <listitem><para>Used to build modules that use plain Makefiles and that do not + require any special configuration.</para></listitem> + </varlistentry> + <varlistentry> + <term>autotools</term> + <listitem><para>This is the standard configuration tool used for most Free and + open-source software not in any of the other categories.</para></listitem> + </varlistentry> + <varlistentry> + <term>meson</term> + <listitem><para>This is a <ulink url="https://mesonbuild.com";>relatively new + tool</ulink> gaining popularity as a replacement for the autotools and may + be required for some non-&kde; modules.</para></listitem> + </varlistentry> +</variablelist> + +</entry> +</row> + +<row id="conf-prefix"> +<entry>prefix</entry> +<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-install-dir">install-dir</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 +&kdesrc-build; only to build applications.</para> +<para>You can use <varname>${MODULE}</varname> or <varname>$MODULE</varname> +in the path to have them expanded to the module's name.</para> +</entry> +</row> + +<row id="conf-purge-old-logs"> +<entry>purge-old-logs</entry> +<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> +<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> +</entry> +</row> + +<row id="conf-qtdir"> +<entry>qtdir</entry> +<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> +<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.</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> +</para> + +<para>Note that using this option can have a significant detrimental impact on +both your bandwidth usage (if you use <replaceable>all</replaceable>) and the time taken to compile &kde; software, +since &kdesrc-build; will be unable to perform incremental builds.</para> +</entry> +</row> + +<row id="conf-repository"> +<entry>repository</entry> +<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> +</row> + +<row id="conf-revision"> +<entry>revision</entry> +<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> +</entry> +</row> + +<row id="conf-run-tests"> +<entry>run-tests</entry> +<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.</para></entry> +</row> + +<row id="conf-set-env"> +<entry>set-env</entry> +<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> +<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 +globally).</para> +</entry> +</row> + +<row id="conf-source-dir"> +<entry>source-dir</entry> +<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> +<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> +<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> +</entry> +</row> + +<row id="conf-use-clean-install"> +<entry>use-clean-install</entry> +<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> + +<para>This can be useful in ensuring that there are not stray old library +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> +</entry> +</row> + +</tbody> + +</tgroup> +</table> + + +<table id="options-module-set-table"> +<title>Module-set and global scope options</title> +<tgroup cols="2"> + +<thead> +<row> +<entry>Option name</entry> +<entry>Description</entry> +</row> +</thead> +<tbody> + +<row id="conf-git-repository-base"> +<entry>git-repository-base</entry> +<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> + +<para>You must specify two things (separated by a space): The name to assign +to the base URL, and the actual base URL itself. For example:</para> + +<para> +<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> +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> +end module-set +</programlisting> +</para> + +<para>The module-set's <literal>use-modules</literal> option created two modules +internally, with &kdesrc-build; behaving as if it had read:</para> + +<programlisting> +module module1 + repository kde:<replaceable>module1.git</replaceable> +end module + +module module2 + repository kde:<replaceable>module2.git</replaceable> +end module +</programlisting> + +<para>The <literal>kde:</literal> &git; repository prefix used above is a +shortcut which will be setup by &kdesrc-build; automatically. See the TechBase +<ulink +url="https://techbase.kde.org/Development/Git/Configuration#URL_Renaming";>URL +Renaming</ulink> article for more information. Note that unlike most other +options, this option can be specified multiple times in order to create as +many aliases as necessary.</para> + +<tip><para>It is not required to use this option to take advantage of module-set, +this option exists to make it easy to use the same repository across many +different module sets.</para></tip> +</entry> +</row> + +<row id="conf-ignore-modules"> +<entry>ignore-modules</entry> +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Available since</member><member>1.16</member> +</simplelist> +<para>Currently can only be used in module-set, see <ulink +url="https://bugs.kde.org/show_bug.cgi?id=472917";>Bug 472917</ulink>.</para> +<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 +<emphasis>except for</emphasis> some specific modules.</para> + +<para>The option value does not necessarily have to name the module directly. +Any module that has full consecutive parts of its <link +linkend="kde-projects-module-sets">&kde; projects module path</link> match one +of the option values will be ignored, so you can ignore multiple modules this +way.</para> + +<para>For example, an option value of <replaceable>libs</replaceable> would +result in both <symbol>kde/kdegraphics/libs</symbol> and +<symbol>playground/libs</symbol> being excluded (though not +<symbol>kde/kdelibs</symbol> since the full part <quote>kdelibs</quote> is what +is compared).</para> + +<tip><para>See also <xref linkend="example-ignoring-a-module"/>.</para></tip> +</entry> +</row> + +<row id="conf-use-modules"> +<entry>use-modules</entry> +<entry> +<simplelist type='horiz' columns='2'> +<member>Type</member><member>String</member> +<member>Available since</member><member>1.12.1</member> +</simplelist> +<para>Can only be used in <link linkend="module-sets">module-set</link>.</para> +<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>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 +final repository to download from. All other options that are assigned in the +module-set are also copied to the generated modules unaltered.</para> + +<para>The order that modules are defined in this option is important, because +that is also the order that &kdesrc-build; will process the generated modules +when updating, building, and installing. All modules defined in the given +module-set will be handled before &kdesrc-build; moves to the next module after +the module-set.</para> + +<para>If you need to change the options for a generated module, simply declare +the module again after it is defined in the module-set, and set your options +as needed. Although you will change the options set for the module this way, +the module will still be updated and built in the order set by the module-set +(i.e. you can't reorder the build sequence doing this).</para> + +<important><para>The name to use for the module if you do this is simply the +name that you passed to <option>use-modules</option>, with the exception that +any <literal>.git</literal> is removed.</para></important> + +<para>See <xref linkend="module-sets"/> and <link +linkend="conf-git-repository-base">git-repository-base</link> for a description +of its use and an example.</para> +</entry> +</row> + +</tbody> +</tgroup> +</table> + +</sect1> diff --git a/doc/index.docbook b/doc/index.docbook index c95a6fb2..2df7f7b9 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -74,6 +74,7 @@ <!ENTITY building-and-troubleshooting SYSTEM "building-and-troubleshooting.docbook"> <!ENTITY building-specific-modules SYSTEM "building-specific-modules.docbook"> <!ENTITY cmdline SYSTEM "cmdline.docbook"> + <!ENTITY conf-options-table SYSTEM "conf-options-table.docbook"> ]> <book id="kdesrc-build" lang="&language;"> @@ -1542,1369 +1543,7 @@ option to find out more about it. To see the full list of options, see </sect2> </sect1> -<sect1 id="conf-options-table"> -<title>Table of available configuration options</title> - -<para>Here is a table of the various options, containing the following -information:</para> - -<itemizedlist> - -<listitem><para>The option name</para></listitem> - -<listitem><para>A description of how &kdesrc-build; responds if the option is -set in both the global section, and the module section of the <link -linkend="configure-data">configuration file</link> while building a -module.</para></listitem> - -<listitem><para>Special comments on the purpose and usage of the -option.</para></listitem> - -</itemizedlist> - -<table id="options-global-table"> -<title>Global scope only options</title> -<tgroup cols="2"> - -<thead> -<row> -<entry>Option name</entry> -<entry>Description</entry> -</row> -</thead> -<tbody> - -<row id="conf-async"> -<entry>async</entry> -<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.</para></entry> -</row> - -<row id="conf-colorful-output"> -<entry>colorful-output</entry> -<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).</para> -</entry> -</row> - -<row id="conf-disable-agent-check"> -<entry>disable-agent-check</entry> -<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.</para> -</entry> -</row> - -<row id="conf-git-desired-protocol"> -<entry>git-desired-protocol</entry> -<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 -prefer when pushing source code for these modules. Normally the very-efficient -<literal>git</literal> protocol is used, but this may be blocked in some -networks (e.g. corporate intranets, public Wi-Fi). An alternative protocol -which is much better supported is the <literal>https</literal> protocol used for -Internet web sites.</para> - -<para>If you are using one of these constrained networks you can set this -option to <userinput>http</userinput> to prefer <literal>https</literal> -communications instead.</para> - -<tip><para>You may also need the <link -linkend="conf-http-proxy">http-proxy</link> option if an HTTP proxy is also -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> - -</entry> -</row> - -<row id="conf-install-environment-driver"> -<entry>install-environment-driver</entry> -<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> - -<para>This driver will alter the following files:</para> - -<itemizedlist> -<listitem><para><filename>$XDG_CONFIG_HOME/kde-env-master.sh</filename> (normally found at <filename>~/.config/kde-env-master.sh</filename>).</para></listitem> -<listitem><para><filename>$XDG_CONFIG_HOME/kde-env-user.sh</filename> (normally found at <filename>~/.config/kde-env-user.sh</filename>).</para></listitem> -</itemizedlist> - -<para>The <filename>kde-env-user.sh</filename> is optional. It is -intended for user customizations (see the <ulink url="https://userbase.kde.org/KDE_System_Administration/Environment_Variables#Troubleshooting_and_Debugging";>Troubleshooting and Debugging</ulink> -section of the &kde; UserBase for examples of customizable settings), but these settings -can be set elsewhere by the user in their existing profile setup scripts.</para> - -<para>You can disable this feature by setting this option to -<replaceable>false</replaceable>, and ensuring that the <link -linkend="conf-install-session-driver">install-session-driver</link> option is -also disabled.</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> -command-line option.</para></tip> -</entry> -</row> - -<row id="conf-install-session-driver"> -<entry>install-session-driver</entry> -<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> - -<itemizedlist> -<listitem><para><filename>~/.xsession</filename></para></listitem> -<listitem><para><filename>$XDG_CONFIG_HOME/kde-env-master.sh</filename> (normally found at <filename>~/.config/kde-env-master.sh</filename>).</para></listitem> -<listitem><para><filename>$XDG_CONFIG_HOME/kde-env-user.sh</filename> (normally found at <filename>~/.config/kde-env-user.sh</filename>).</para></listitem> -</itemizedlist> - -<para>If you maintain your own login driver then you can disable this feature by setting this -option to <replaceable>false</replaceable>. If enabled, this feature also enables the -<link linkend="conf-install-environment-driver">install-environment-driver</link> feature.</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> -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> -<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 <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.</para> -</entry> -</row> - -<row id="conf-num-cores-low-mem"> -<entry>num-cores-low-mem</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 <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> - -<para>The typical calculation is one CPU core for every 2 -gigabytes (GiB) of total memory. At least 1 core will be specified, -and no more than <option><link linkend="conf-num-cores">num-cores</link></option> -cores will be specified.</para> - -<para>Although this option is intended to support &Qt; modules, you can use it for your -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> - -</entry> -</row> - -<row id="conf-persistent-data-file"> -<entry>persistent-data-file</entry> -<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 -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> -</entry> -</row> - -<row id="conf-ssh-identity-file"> -<entry>ssh-identity-file</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> -</entry> -</row> - -<row id="conf-use-idle-io-priority"> -<entry>use-idle-io-priority</entry> -<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;.</para> -</entry> -</row> - -<row id="conf-use-inactive-modules"> -<entry>use-inactive-modules</entry> -<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> - -</tbody> -</tgroup> -</table> - -<!-- Between tables --> - -<table id="option-table"> -<title>All scopes (module, module-set and global) options</title> -<tgroup cols="2"> - -<thead> -<row> -<entry>Option name</entry> -<entry>Description</entry> -</row> -</thead> - -<tbody> - -<row id="conf-binpath"> -<entry>binpath</entry> -<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 -toolchain. The paths <filename class="directory">install-dir/bin</filename> and -<filename class="directory">$<envar>QTDIR</envar>/bin</filename> are automatically added. You -may use the tilde (~) for any paths you add using this option.</para> -</entry> -</row> - -<row id="conf-branch"> -<entry>branch</entry> -<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> -<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> - -<para>For supported &git; module types, &kdesrc-build; will determine the -actual branch to use automatically based on rules encoded by the &kde; -developers (these rules may be viewed in the -<literal>kde-build-metadata</literal> source repository in your source -directory). After a branch is determined that branch is used as if you had -specified it yourself using the <link linkend="conf-branch">branch</link> -option. -</para> - -<para>This is useful if you're just trying to maintain up-to-date on some -normal development track without having to pay attention to all the branch name -changes.</para> - -<para>Note that if you <emphasis>do</emphasis> choose a -<literal>branch</literal> yourself, that it will override this setting. The -same is true of other specific branch selection options such as <link -linkend="conf-tag">tag</link>.</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"/>. -</para></note> - -</entry> -</row> - -<row id="conf-build-dir"> -<entry>build-dir</entry> -<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> - -<listitem><para>Relative to the &kde; &git; source directory (see <link -linkend="conf-source-dir">the source-dir option</link>). This is the default, -and is selected if you type a directory name that does not start with a tilde -(~) or a slash (/).</para></listitem> - -<listitem><para>Absolute path. If you specify a path that begins with a /, then -that path is used directly. For example, <filename -class="directory">/tmp/kde-obj-dir/</filename>.</para></listitem> - -<listitem><para>Relative to your home directory. If you specify a path that -begins with a ~, then the path is used relative to your home directory, -analogous to the shell's tilde-expansion. For example, <filename -class="directory">~/builddir</filename> would set the build directory to -<filename -class="directory">/home/user-name/builddir</filename>.</para></listitem> - -</orderedlist> - -<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> -<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. -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 -build phase for a module if the module has a source code update, or in other -situations where it is likely that a rebuild is actually required. This can save -time, especially if you run &kdesrc-build; daily, or more frequently.</para> - -<important><para>This feature is provided as an optimization only. Like many -other optimizations, there are trade-offs for the correctness of your -installation. For instance, changes to the qt or kdelibs modules may cause -a rebuild of other modules to be necessary, even if the source code doesn't -change at all.</para></important> -</entry> -</row> - -<row id="conf-cmake-generator"> -<entry>cmake-generator</entry> -<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. -</para> - -<para>Note that if a valid generator is also specified through -<link linkend="conf-cmake-options">cmake-options</link> it will override the -value for <literal>cmake-generator</literal>.</para></entry> -</row> - -<row id="conf-cmake-toolchain"> -<entry>cmake-toolchain</entry> -<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>. -You can use &set-env;, &binpath; and &libpath; to fix up the environment -manually if your toolchain file does not work out of the box with -&kdesrc-build;. Refer to <link linkend="kdesrc-build-std-flags">the overview -of standard flags added by &kdesrc-build;</link> for more information. -</para> -<para>Note that if a valid toolchain is also specified through -<link linkend="conf-cmake-options">cmake-options</link> it will override the -value for <literal>cmake-toolchain</literal>.</para></entry> -</row> - -<row id="conf-cmake-options"> -<entry>cmake-options</entry> -<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 -specify common &cmake; options in the global section.</para> - -<para>This option does not apply to qt (which does not use &cmake;). Use -<link linkend="conf-configure-flags">configure-flags</link> instead.</para> - -<para>If a valid generator is specified among the listed options it will -override the value of -<link linkend="conf-cmake-generator">cmake-generator</link>. Invalid -(unsupported) generators are ignored and will not be passed to &cmake;. -</para> - -<para>If a valid toolchain file is specified among the listed options it will -override the value of -<link linkend="conf-cmake-toolchain">cmake-toolchain</link>. Invalid -toolchains are ignored and will not be passed to &cmake;. -</para> - -<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> - -<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 -option blank. (In other words, <emphasis>required</emphasis> &cmake; parameters -are set for you automatically)</para></entry> -</row> - -<row id="conf-compile-commands-export"> -<entry>compile-commands-export</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. -</para> -</entry> -</row> - -<row id="conf-compile-commands-linking"> -<entry>compile-commands-linking</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. -</para> -</entry> -</row> - -<row id="conf-configure-flags"> -<entry>configure-flags</entry> -<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> - -<para>To change configuration settings for KDE modules, see -<link linkend="conf-cmake-options">cmake-options</link>. -</para> -</entry> -</row> - -<row id="conf-custom-build-command"> -<entry>custom-build-command</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 - should not need to set this option. However it can be useful to use - alternate build systems. - </para> - - <para>The value of this option is used as the command line to run, modified - by the <link linkend="conf-make-options">make-options</link> option as - normal. - </para> -</entry> -</row> - -<row id="conf-cxxflags"> -<entry>cxxflags</entry> -<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 -linkend="conf-cmake-options">cmake-options</link> because this option will also -set the environment variable <envar>CXXFLAGS</envar> during the build process.</para> - -<para>Note that for &kde; 4 and any other modules that use &cmake;, it is -necessary to set the CMAKE_BUILD_TYPE option to <userinput>none</userinput> -when configuring the module. This can be done using the <link -linkend="conf-cmake-options">cmake-options</link> option. -</para> -</entry> -</row> - -<row id="conf-dest-dir"> -<entry>dest-dir</entry> -<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.</para> -</entry> -</row> - -<row id="conf-do-not-compile"> -<entry>do-not-compile</entry> -<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> - -<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>See <xref linkend="not-compiling"/> for an example.</para> -</entry> -</row> - -<row id="conf-git-user"> -<entry>git-user</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 -majority of &kde; modules).</para> - -<para>Specifically, the user's name and email fields for each new &git; repository are filled -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>For instance, a developer named <quote>Foo Barbaz</quote> with the -email address <quote>f...@abc.xyz</quote> would use:</para> -<para> -<programlisting> - <symbol>git-user</symbol> <replaceable>Foo Barbaz</replaceable> <<replaceable>f...@abc.xyz</replaceable>> -</programlisting> -</para> - -</entry> -</row> - -<row id="conf-http-proxy"> -<entry>http-proxy</entry> -<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> - -<para>In addition, &kdesrc-build; will try to ensure that the tools it depends -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> -</entry> -</row> - -<row id="conf-directory-layout"> -<entry>directory-layout</entry> -<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>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> -layout would be <literal>source/ktp-text-ui</literal> using the <userinput>flat</userinput> layout -instead. -</para> -<para>The <userinput>invent</userinput> layout creates a directory hierarchy mirroring the relative -paths of repositories on <ulink url="https://invent.kde.org/";>invent.kde.org</ulink>. For example -<literal>source/kde/applications/kate</literal> in the <userinput>metadata</userinput> layout would -be <literal>source/utilities/kate</literal> using the <userinput>invent</userinput> layout instead. -This layout only affects KDE projects. It is a good choice for people starting out with -&kdesrc-build;. -</para> -<para>Finally, the <userinput>metadata</userinput> layout is the same as the old default -behaviour. This layout organises KDE projects according to the project paths specified in the -project metadata for these modules. This is a good choice if you want a directory layout which -tracks with certain KDE processes, but note that this path is therefore not always stable. As a -result, &kdesrc-build; may abandon an old copy of the repository and clone a new one for a project -due to changes in the project metadata.</para> -</entry> -</row> - -<row id="conf-generate-vscode-project-config"> -<entry>generate-vscode-project-config</entry> - -<entry> -<simplelist type='horiz' columns='2'> -<member>Type</member><member>Boolean</member> -<member>Default value</member><member>False</member> -</simplelist> - -<para>Module setting overrides global</para> - -<para>Set this option to <userinput>true</userinput> to make -&kdesrc-build; create VS Code project files (.vscode directory) in the module -source directory.</para> - -<para>The .vscode folder will be created in the project source directory, only -if it does not already exist. The configurations will enable the use of LSP, -building, debugging, and running the project from within VS Code.</para> - -<para>The configuration also recommends extensions to install that are useful -for working on most KDE projects.</para> - -<para>You can also use the <link linkend="cmdline-generate-vscode-project-config"> -<option>--generate-vscode-project-config</option></link> command line flag.</para> -</entry> -</row> - -<row id="conf-include-dependencies"> -<entry>include-dependencies</entry> -<entry> -<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 -linkend="kde-projects-module-sets"><literal>kde-project</literal>-based -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 is to support building applications -that need versions of &Qt; or &plasma; more recent than supported on -common operating systems.</para> -</entry> -</row> - -<row id="conf-install-after-build"> -<entry>install-after-build</entry> -<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.</para> -</entry> -</row> - -<row id="conf-install-dir"> -<entry>install-dir</entry> -<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.</para> -</entry> -</row> - -<row id="conf-libname"> -<entry>libname</entry> -<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 ${install-dir} 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.</para> -</entry> -</row> - -<row id="conf-libpath"> -<entry>libpath</entry> -<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">${install-dir}/$<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.</para> -</entry> -</row> - -<row id="conf-log-dir"> -<entry>log-dir</entry> -<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> -<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.</para></entry> -</row> - -<row id="conf-make-options"> -<entry>make-options</entry> -<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> -<para>Note that not all supported build systems use <command>make</command>. For -build systems that use <command>ninja</command> for build (such as the -<link linkend="conf-override-build-system"><application>Meson</application> -build system</link>), see the <link linkend="conf-ninja-options">ninja-options</link> -setting.</para> -</entry> -</row> - -<row id="conf-manual-build"> -<entry>manual-build</entry> -<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> -command line option. -</para> -</entry> -</row> - -<row id="conf-manual-update"> -<entry>manual-update</entry> -<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.</para> -</entry> -</row> - -<row id="conf-ninja-options"> -<entry>ninja-options</entry> -<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 -use.</para> - -<note><para>Note that this setting only controls ninja when used by &kdesrc-build;. -The &Qt; <quote>webengine</quote> module uses <command>ninja</command> indirectly, but -only officially supports being built by <command>make</command>. -In this situation, you can set <literal>NINJAFLAGS</literal> as a way to have -<command>make</command> pass the appropriate flags when it later calls -<command>ninja</command>, by using -<link linkend="conf-make-options">make-options</link>.</para> - -<programlisting> -options <replaceable>qtwebengine</replaceable> - # Restrict make and ninja to using no more than 6 separate compile jobs even - # when more CPU is available, to avoid running out of memory - <option><link linkend="conf-make-options">make-options</link></option> -j<replaceable>6</replaceable> NINJAFLAGS=-j<replaceable>6</replaceable> -end options -</programlisting> -</note> -</entry> -</row> - -<row id="conf-no-src"> -<entry>no-src</entry> -<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.</para> -</entry> -</row> - -<row id="conf-override-build-system"> -<entry>override-build-system</entry> -<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> - -<para>Some modules may include more than one required set of files, which could confuse -the auto-detection. In this case you can manually specify the correct build type.</para> - -<para>Currently supported build types that can be set are:</para> - -<variablelist> - <varlistentry> - <term>KDE</term> - <listitem><para>Used to build &kde; modules. In reality it can be used to build - almost any module that uses &cmake; but it is best not to rely on this.</para></listitem> - </varlistentry> - <varlistentry> - <term>Qt</term> - <listitem><para>Used to build the &Qt; library itself.</para></listitem> - </varlistentry> - <varlistentry> - <term>qmake</term> - <listitem><para>Used to build &Qt; modules that use - <application>qmake</application>-style <literal>.pro</literal> - files.</para></listitem> - </varlistentry> - <varlistentry> - <term>generic</term> - <listitem><para>Used to build modules that use plain Makefiles and that do not - require any special configuration.</para></listitem> - </varlistentry> - <varlistentry> - <term>autotools</term> - <listitem><para>This is the standard configuration tool used for most Free and - open-source software not in any of the other categories.</para></listitem> - </varlistentry> - <varlistentry> - <term>meson</term> - <listitem><para>This is a <ulink url="https://mesonbuild.com";>relatively new - tool</ulink> gaining popularity as a replacement for the autotools and may - be required for some non-&kde; modules.</para></listitem> - </varlistentry> -</variablelist> - -</entry> -</row> - -<row id="conf-prefix"> -<entry>prefix</entry> -<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-install-dir">install-dir</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 -&kdesrc-build; only to build applications.</para> -<para>You can use <varname>${MODULE}</varname> or <varname>$MODULE</varname> -in the path to have them expanded to the module's name.</para> -</entry> -</row> - -<row id="conf-purge-old-logs"> -<entry>purge-old-logs</entry> -<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> -<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> -</entry> -</row> - -<row id="conf-qtdir"> -<entry>qtdir</entry> -<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> -<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.</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> -</para> - -<para>Note that using this option can have a significant detrimental impact on -both your bandwidth usage (if you use <replaceable>all</replaceable>) and the time taken to compile &kde; software, -since &kdesrc-build; will be unable to perform incremental builds.</para> -</entry> -</row> - -<row id="conf-repository"> -<entry>repository</entry> -<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> -</row> - -<row id="conf-revision"> -<entry>revision</entry> -<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> -</entry> -</row> - -<row id="conf-run-tests"> -<entry>run-tests</entry> -<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.</para></entry> -</row> - -<row id="conf-set-env"> -<entry>set-env</entry> -<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> -<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 -globally).</para> -</entry> -</row> - -<row id="conf-source-dir"> -<entry>source-dir</entry> -<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> -<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> -<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> -</entry> -</row> - -<row id="conf-use-clean-install"> -<entry>use-clean-install</entry> -<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> - -<para>This can be useful in ensuring that there are not stray old library -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> -</entry> -</row> - -</tbody> - -</tgroup> -</table> - - -<table id="options-module-set-table"> -<title>Module-set and global scope options</title> -<tgroup cols="2"> - -<thead> -<row> -<entry>Option name</entry> -<entry>Description</entry> -</row> -</thead> -<tbody> - -<row id="conf-git-repository-base"> -<entry>git-repository-base</entry> -<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> - -<para>You must specify two things (separated by a space): The name to assign -to the base URL, and the actual base URL itself. For example:</para> - -<para> -<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> -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> -end module-set -</programlisting> -</para> - -<para>The module-set's <literal>use-modules</literal> option created two modules -internally, with &kdesrc-build; behaving as if it had read:</para> - -<programlisting> -module module1 - repository kde:<replaceable>module1.git</replaceable> -end module - -module module2 - repository kde:<replaceable>module2.git</replaceable> -end module -</programlisting> - -<para>The <literal>kde:</literal> &git; repository prefix used above is a -shortcut which will be setup by &kdesrc-build; automatically. See the TechBase -<ulink -url="https://techbase.kde.org/Development/Git/Configuration#URL_Renaming";>URL -Renaming</ulink> article for more information. Note that unlike most other -options, this option can be specified multiple times in order to create as -many aliases as necessary.</para> - -<tip><para>It is not required to use this option to take advantage of module-set, -this option exists to make it easy to use the same repository across many -different module sets.</para></tip> -</entry> -</row> - -<row id="conf-ignore-modules"> -<entry>ignore-modules</entry> -<entry> -<simplelist type='horiz' columns='2'> -<member>Type</member><member>String</member> -<member>Available since</member><member>1.16</member> -</simplelist> -<para>Currently can only be used in module-set, see <ulink -url="https://bugs.kde.org/show_bug.cgi?id=472917";>Bug 472917</ulink>.</para> -<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 -<emphasis>except for</emphasis> some specific modules.</para> - -<para>The option value does not necessarily have to name the module directly. -Any module that has full consecutive parts of its <link -linkend="kde-projects-module-sets">&kde; projects module path</link> match one -of the option values will be ignored, so you can ignore multiple modules this -way.</para> - -<para>For example, an option value of <replaceable>libs</replaceable> would -result in both <symbol>kde/kdegraphics/libs</symbol> and -<symbol>playground/libs</symbol> being excluded (though not -<symbol>kde/kdelibs</symbol> since the full part <quote>kdelibs</quote> is what -is compared).</para> - -<tip><para>See also <xref linkend="example-ignoring-a-module"/>.</para></tip> -</entry> -</row> - -<row id="conf-use-modules"> -<entry>use-modules</entry> -<entry> -<simplelist type='horiz' columns='2'> -<member>Type</member><member>String</member> -<member>Available since</member><member>1.12.1</member> -</simplelist> -<para>Can only be used in <link linkend="module-sets">module-set</link>.</para> -<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>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 -final repository to download from. All other options that are assigned in the -module-set are also copied to the generated modules unaltered.</para> - -<para>The order that modules are defined in this option is important, because -that is also the order that &kdesrc-build; will process the generated modules -when updating, building, and installing. All modules defined in the given -module-set will be handled before &kdesrc-build; moves to the next module after -the module-set.</para> - -<para>If you need to change the options for a generated module, simply declare -the module again after it is defined in the module-set, and set your options -as needed. Although you will change the options set for the module this way, -the module will still be updated and built in the order set by the module-set -(i.e. you can't reorder the build sequence doing this).</para> - -<important><para>The name to use for the module if you do this is simply the -name that you passed to <option>use-modules</option>, with the exception that -any <literal>.git</literal> is removed.</para></important> - -<para>See <xref linkend="module-sets"/> and <link -linkend="conf-git-repository-base">git-repository-base</link> for a description -of its use and an example.</para> -</entry> -</row> - -</tbody> -</tgroup> -</table> - -</sect1> +&conf-options-table; </chapter> &cmdline;
