[sdk/kdesrc-build] doc: doc: cmdline - separate docbook
Andrew Shark
null at kde.org
Fri Jan 5 19:07:02 GMT 2024
Git commit 6496ae8eabf61c86d586f11a0c4000bf9fb9076b by Andrew Shark.
Committed on 05/01/2024 at 19:58.
Pushed by ashark into branch 'master'.
doc: cmdline - separate docbook
A +837 -0 doc/cmdline.docbook
M +2 -837 doc/index.docbook
https://invent.kde.org/sdk/kdesrc-build/-/commit/6496ae8eabf61c86d586f11a0c4000bf9fb9076b
diff --git a/doc/cmdline.docbook b/doc/cmdline.docbook
new file mode 100644
index 00000000..ecec619f
--- /dev/null
+++ b/doc/cmdline.docbook
@@ -0,0 +1,837 @@
+<chapter id="cmdline">
+<title>Command Line Options and Environment Variables</title>
+
+<sect1 id="cmdline-usage">
+<title>Command Line Usage</title>
+
+<para>&kdesrc-build; is designed to be run as follows:</para>
+
+<cmdsynopsis>
+<command>kdesrc-build</command>
+<arg rep="repeat"><replaceable>--options</replaceable></arg>
+<arg rep="repeat"><replaceable>modules to build</replaceable></arg>
+</cmdsynopsis>
+
+<para>If no modules to build are specified on the command line, then
+kdesrc-build will build all modules defined in its configuration file, in the
+order listed in that file (although this can be modified by various
+configuration file options).</para>
+
+<sect2 id="cmdline-usage-options">
+<title>Commonly used command line options</title>
+
+<para>The full list of command line options is given in <xref
+linkend="supported-cmdline-params"/>. The most-commonly used options
+include:</para>
+
+<variablelist>
+ <varlistentry>
+ <term><option>--pretend</option> (or <option>-p</option>)</term>
+ <listitem><para>This option causes &kdesrc-build; to indicate what actions
+ it would take, without actually really implementing them. This can be
+ useful to make sure that the modules you think you are building will
+ actually get built.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--refresh-build</option></term>
+ <listitem><para>This option forces &kdesrc-build; to build the given
+ modules from an absolutely fresh start point. Any existing build directory
+ for that module is removed and it is rebuilt. This option is useful if you
+ have errors building a module, and sometimes is required when &Qt; or &kde;
+ libraries change.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--no-src</option></term>
+ <listitem><para>This option skips the source update process. You might use
+ it if you have very recently updated the source code (perhaps you did it
+ manually or recently ran &kdesrc-build;) but still want to rebuild some
+ modules.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--no-build</option></term>
+ <listitem><para>This option is similar to <option>--no-src</option> above,
+ but this time the build process is skipped.</para></listitem>
+ </varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2 id="cmdline-usage-modules">
+<title>Specifying modules to build</title>
+
+<para>In general, specifying modules to build is as simple as passing their
+module name as you defined it in the configuration file. You can also pass
+modules that are part of a module set, either as named on <link
+linkend="conf-use-modules">use-modules</link>, or the name of the entire module
+set itself, if you have given it a name.</para>
+
+<para>In the specific case of module sets based against the <link
+linkend="kde-projects-module-sets">KDE project database</link>, &kdesrc-build;
+will expand module name components to determine the exact module you
+want. For example, &kdesrc-build;'s KDE project entry locates the project in
+<literal>extragear/utils/kdesrc-build</literal>. You could specify any
+of the following to build &kdesrc-build;:</para>
+
+<informalexample>
+<screen>
+<prompt>%</prompt> <command>kdesrc-build</command> <option><replaceable>+extragear/utils/kdesrc-build</replaceable></option>
+<prompt>%</prompt> <command>kdesrc-build</command> <option><replaceable>+utils/kdesrc-build</replaceable></option>
+<prompt>%</prompt> <command>kdesrc-build</command> <option><replaceable>+kdesrc-build</replaceable></option>
+</screen>
+</informalexample>
+
+<note><para>The commands in the previous example preceded the module-name with
+a <symbol>+</symbol>. This forces the module name to be interpreted as a module
+from the KDE project database, even if that module hasn't been defined in your
+configuration file.
+</para></note>
+
+<para>Be careful about specifying very generic projects (e.g.
+<literal>extragear/utils</literal> by itself), as this can lead to a large
+amount of modules being built. You should use the <option>--pretend</option>
+option before building a new module set to ensure it is only building the
+modules you want.</para>
+
+</sect2>
+</sect1>
+
+<sect1 id="supported-envvars">
+<title>Supported Environment Variables</title>
+
+<para>
+&kdesrc-build; does not use environment variables. If you need to set environment
+variables for the build or install process, please see the <link
+linkend="conf-set-env">set-env</link> option.
+</para>
+
+</sect1>
+
+<sect1 id="supported-cmdline-params">
+<title>Supported command-line parameters</title>
+
+<para>
+The script accepts the following command-line options:
+</para>
+
+<variablelist>
+
+<varlistentry id="cmdline-async">
+<term><parameter>--async</parameter></term>
+<listitem><para>
+Enables the <link linkend="conf-async">asynchronous mode</link>, which can
+perform the source code updates and module builds at the same time. This is
+the default, this option only needs specified if you have disabled it in the
+configuration.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-help">
+<term><parameter>--help</parameter> (or <parameter>-h</parameter>)</term>
+<listitem><para>
+Only display simple help on this script.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-version">
+<term><parameter>--version</parameter> (or <parameter>-v</parameter>)</term>
+<listitem><para>
+Display the program version.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-show-info">
+<term><parameter>--show-info</parameter></term>
+<listitem><para>
+Displays information about &kdesrc-build; and the operating system, that may
+prove useful in bug reports or when asking for help in forums or mailing lists.
+</para>
+<para>Available since version 18.11.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-initial-setup">
+<term><parameter>--initial-setup</parameter></term>
+<listitem><para>
+Has &kdesrc-build; perform the one-time initial setup necessary to prepare
+the system for &kdesrc-build; to operate, and for the newly-installed &kde;
+software to run.
+</para>
+<para>This includes:</para>
+<itemizedlist>
+<listitem><para>Installing known dependencies (on supported &Linux; distributions)</para></listitem>
+<listitem><para>Adding required environment variables to <literal>~/.bashrc</literal></para></listitem>
+<listitem><para>Setting up a <link linkend="setup-rcfile">configuration file</link></para></listitem>
+</itemizedlist>
+<para>This option is exactly equivalent to using
+ <option><link linkend="cmdline-install-distro-packages">--install-distro-packages</link></option>
+ <option><link linkend="cmdline-generate-config">--generate-config</link></option>
+ <option><link linkend="cmdline-update-shellrc">--update-shellrc</link></option> at the same time.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-install-distro-packages">
+<term><parameter>--install-distro-packages</parameter></term>
+<listitem><para>
+Installs distro packages (on supported &Linux; distributions) necessary to prepare the system for &kdesrc-build; to operate, and for the newly-installed &kde;
+software to run.
+</para>
+<para>See also <option><link linkend="cmdline-initial-setup">--initial-setup</link></option></para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-generate-config">
+<term><parameter>--generate-config</parameter></term>
+<listitem><para>
+Generate the &kdesrc-build; configuration file.
+</para>
+<para>See also <option><link linkend="cmdline-initial-setup">--initial-setup</link></option></para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-update-shellrc">
+<term><parameter>--update-shellrc</parameter></term>
+<listitem><para>
+Edit the "~/.bashrc" (or other shell rc file) to add &kdesrc-build; to your $PATH variable and enable autocompletion.
+</para>
+<para>See also <option><link linkend="cmdline-initial-setup">--initial-setup</link></option></para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-author">
+<term><parameter>--author</parameter></term>
+<listitem><para>
+Display contact information for the
+author.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-color">
+<term><parameter>--color</parameter></term>
+<listitem><para>
+Enable colorful output. (This is the default for interactive terminals).
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-generate-vscode-project-config">
+<term><parameter>--generate-vscode-project-config</parameter></term>
+<listitem><para>
+Generate a .vscode directory with configurations for building and debugging
+in Visual Studio Code.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-nice">
+<term><parameter>--nice=<replaceable>value</replaceable></parameter></term>
+<listitem><para>
+This value adjusts the computer CPU priority requested by &kdesrc-build;, and
+should be in the range of 0-20. 0 is highest priority (because it is the
+least <quote>nice</quote>), 20 is lowest priority. &kdesrc-build; defaults
+to 10.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-no-async">
+<term><parameter>--no-async</parameter></term>
+<listitem><para>
+Disables the <link linkend="conf-async">asynchronous mode</link> of updating.
+Instead the update will be performed in its entirety before the build starts.
+This option will slow down the overall process, but if you encounter IPC errors
+while running &kdesrc-build; try using this option, and submitting a
+<ulink url="https://bugs.kde.org/">bug report</ulink>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-no-color">
+<term><parameter>--no-color</parameter></term>
+<listitem><para>
+Disable colorful output.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-pretend">
+<term><parameter>--pretend</parameter> (or <parameter>-p</parameter>)</term>
+<listitem><para>
+&kdesrc-build; will run through the update and build process, but instead of
+performing any actions to update or build, will instead output what the
+script would have done (e.g. what commands to run, general steps being taken,
+etc.).</para>
+
+<note><para>Simple read-only commands (such as reading file information) may
+still be run to make the output more relevant (such as correctly simulating
+whether source code would be checked out or updated).
+</para></note>
+
+<important><para>This option requires that some needed metadata is available,
+which is normally automatically downloaded, but downloads are disabled in
+pretend mode. If you've never run &kdesrc-build; (and therefore, don't have
+this metadata), you should run <command>kdesrc-build
+<option>--metadata-only</option></command> to download the required metadata
+first.
+</para></important>
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-quiet">
+<term><parameter>--quiet</parameter> (or <parameter>-q</parameter>)</term>
+<listitem><para>
+Do not be as noisy with the output. With this switch only the basics are
+output.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-really-quiet">
+<term><parameter>--really-quiet</parameter></term>
+<listitem><para>
+Only output warnings and errors.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-verbose">
+<term><parameter>--verbose</parameter></term>
+<listitem><para>
+Be very descriptive about what is going on, and what &kdesrc-build; is doing.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-src-only">
+<term><parameter>--src-only</parameter> (or <parameter>-s</parameter>)</term>
+<listitem><para>
+Only perform the source update.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-build-only">
+<term><parameter>--build-only</parameter></term>
+<listitem><para>
+Only perform the build process.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-install-only">
+<term><parameter>--install-only</parameter></term>
+<listitem><para>
+If this is the only command-line option, it tries to install all of the modules
+contained in <filename>log/latest/build-status</filename>. If command-line
+options are specified after <parameter>--install-only</parameter>, they are all
+assumed to be modules to install (even if they did not successfully build on
+the last run).
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-metadata-only">
+<term><parameter>--metadata-only</parameter></term>
+<listitem><para>
+Only perform the metadata download process. &kdesrc-build; normally handles this
+automatically, but you might manually use this to allow the <option><link
+linkend="cmdline-pretend">--pretend</link></option> command line option to work.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-rebuild-failures">
+<term><parameter>--rebuild-failures</parameter></term>
+<listitem><para>
+Use this option to build only those modules which failed to build on a previous
+&kdesrc-build; run. This is useful if a significant number of failures occurred mixed with
+successful builds. After fixing the issue causing the build failures you can then easily
+build only the modules that failed previously.</para>
+
+<note><para>Note that the list of <quote>previously-failed modules</quote> is
+reset every time a &kdesrc-build; run finishes with some module failures.
+However it is not reset by a completely successful build, so you can
+successfully rebuild a module or two and this flag will still
+work.</para></note>
+
+<para>This option was added for &kdesrc-build; 15.09.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-include-dependencies">
+<term><parameter>--include-dependencies</parameter> (or <parameter>-d</parameter>)</term>
+<term><parameter>--no-include-dependencies</parameter> (or <parameter>-D</parameter>)</term>
+<listitem><para>
+This option causes &kdesrc-build; to automatically include other &kde; and &Qt;
+modules in the build, if required for the modules you have requested to build
+on the command line or in your
+<link linkend="configure-data">configuration file</link>.</para>
+
+<para>The modules that are added are as recorded within the &kde; source code
+management system. See <xref linkend="kde-projects-module-sets"/>.</para>
+
+<para>The corresponding configure file option is
+<link linkend="conf-include-dependencies">include-dependencies</link>.</para>
+
+<para>You can also use <parameter>--no-include-dependencies</parameter>, which turns off
+automatic inclusion of additional dependency modules.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-ignore-modules">
+<term><parameter>--ignore-modules</parameter> (or <parameter>-!</parameter>)</term>
+<listitem><para>
+Do not include the modules passed on the rest of the command line in the
+update/build process (this is useful if you want to build most of the modules
+in your <link linkend="configure-data">configuration file</link> and just skip
+a few).
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-no-src">
+<term><parameter>--no-src</parameter> (or <parameter>-S</parameter>)</term>
+<listitem><para>
+Skip contacting the &git; server.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-no-build">
+<term><parameter>--no-build</parameter></term>
+<listitem><para>
+Skip the build process.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-no-metadata">
+<term><parameter>--no-metadata</parameter></term>
+<listitem><para>
+Do not automatically download the extra metadata needed for &kde; git modules.
+The source updates for the modules themselves will still occur unless you pass
+<link linkend="cmdline-no-src">--no-src</link> as well.
+</para><para>
+This can be useful if you are frequently re-running &kdesrc-build; since the
+metadata does not change very often. But note that many other features require
+the metadata to be available. You might want to consider running &kdesrc-build;
+with the <link linkend="cmdline-metadata-only">--metadata-only</link> option
+one time and then using this option for subsequent runs.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-no-install">
+<term><parameter>--no-install</parameter></term>
+<listitem><para>
+Do not automatically install packages after they are built.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-no-build-when-unchanged">
+<term><parameter>--no-build-when-unchanged</parameter></term>
+<term><parameter>--force-build</parameter></term>
+<listitem><para>
+This option explicitly disables skipping the build process (an optimization
+controlled by the <link
+linkend="conf-build-when-unchanged">build-when-unchanged</link> option). This is
+useful for making &kdesrc-build; run the build when you have changed something
+that &kdesrc-build; cannot check.</para>
+
+<para><parameter>--force-build</parameter> performs the exact same function, and
+is perhaps easier to remember.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-debug">
+<term><parameter>--debug</parameter></term>
+<listitem><para>
+Enables debug mode for the script. Currently this means that all output will be
+dumped to the standard output in addition to being logged in the log directory
+like normal. Also, many functions are much more verbose about what they are
+doing in debugging mode.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-query">
+<term><parameter>--query</parameter>=<userinput><replaceable>mode</replaceable></userinput></term>
+<listitem><para>
+This command causes &kdesrc-build; to query a parameter of the modules in the
+build list (either passed on the command line or read in from the configuration
+file), outputting the result to screen (one module per line).</para>
+
+<para>This option must be provided with a <quote>query mode</quote>, which should be
+one of the following:</para>
+ <itemizedlist>
+ <listitem><para><option>source-dir</option>, which causes &kdesrc-build; to
+ output the full path to where the module's source code is stored.
+ </para></listitem>
+ <listitem><para><option>build-dir</option>, which causes &kdesrc-build; to
+ output the full path to where the module build process occurs.
+ </para></listitem>
+ <listitem><para><option>install-dir</option>, which causes &kdesrc-build; to
+ output the full path to where the module will be installed.
+ </para></listitem>
+ <listitem><para><option>project-path</option>, which causes &kdesrc-build; to
+ output the location of the module within the hierarchy of KDE source
+ code repositories. See <xref linkend="kde-projects-module-sets"/> for
+ more information on this hierarchy.
+ </para></listitem>
+ <listitem><para><option>branch</option>, which causes &kdesrc-build; to
+ output the resolved git branch that will be used for each module, based
+ on the <link linkend="conf-tag">tag</link>, <link
+ linkend="conf-branch">branch</link> and <link
+ linkend="conf-branch-group">branch-group</link> settings in effect.
+ </para></listitem>
+ <listitem><para>Otherwise, option names that are valid for modules in the
+ <link linkend="conf-options-table">configuration file</link> can be
+ used, the resolved value of which will be listed for each module.
+ </para></listitem>
+ </itemizedlist>
+
+<para>
+If a single module is passed on the command line, then the output is simply the
+value of the parameter being queried. If multiple (or no) modules are passed on
+the command line, then each line is prefixed by the name of the module. Either way,
+&kdesrc-build; stops running once each value is output.
+</para>
+
+<para>This option was added with &kdesrc-build; 16.05.</para>
+
+<informalexample>
+<para>For example, the command <quote><command>kdesrc-build</command>
+ <parameter>--query</parameter>
+ <parameter><replaceable>branch</replaceable></parameter>
+ <parameter><replaceable>kactivities</replaceable></parameter>
+ <parameter><replaceable>kdepim</replaceable></parameter></quote>
+might end up with output like:</para>
+<screen>
+kactivities: master
+kdepim: master
+</screen>
+</informalexample>
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-refresh-build">
+<term><parameter>--refresh-build</parameter> (or <parameter>-r</parameter>)</term>
+<listitem><para>
+Recreate the build system and make from scratch.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-reconfigure">
+<term><parameter>--reconfigure</parameter></term>
+<listitem><para>
+Run <command>cmake</command> (for &kde; modules) or
+<command>configure</command> (for &Qt;) again, without cleaning the build
+directory. You should not normally have to specify this, as &kdesrc-build; will
+detect when you change the relevant options and automatically re-run the build
+setup. This option is implied if <parameter><link
+linkend="cmdline-refresh-build">--refresh-build</link></parameter> is used.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-resume-from">
+<term><parameter>--resume-from</parameter> (or <parameter>--from</parameter> or <parameter>-f</parameter>)</term>
+<listitem><para>
+This option is used to resume the build starting from the given module, which
+should be the next option on the command line. You should not
+specify other module names on the command line.
+</para>
+
+<note><para>This option formerly added <link
+ linkend="cmdline-no-src"><parameter>--no-src</parameter></link>, but does
+not any longer (since &kdesrc-build; 1.13). If you want to avoid source updates
+when resuming, simply pass <option><userinput>--no-src</userinput></option>
+in addition to the other options.
+</para></note>
+
+<para>See also: <xref linkend="cmdline-resume-after"/> and <xref
+linkend="resuming-failed"/>. You would prefer to use this command line option
+if you have fixed the build error and want &kdesrc-build; to complete the
+build.</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-resume-after">
+<term><parameter>--resume-after</parameter> (or <parameter>--after</parameter> or <parameter>-a</parameter>)</term>
+<listitem><para>
+This option is used to resume the build starting after the given module, which
+should be the next option on the command line. You should not
+specify other module names on the command line.
+</para>
+
+<note><para>This option formerly added <link
+ linkend="cmdline-no-src"><parameter>--no-src</parameter></link>, but does
+not any longer (since &kdesrc-build; 1.13). If you want to avoid source updates
+when resuming, simply pass <option><userinput>--no-src</userinput></option>
+in addition to the other options.
+</para></note>
+
+<para>See also: <xref linkend="cmdline-resume-from"/> and <xref
+linkend="resuming-failed"/>. You would prefer to use this command line option
+if you have fixed the build error and have also built and installed the module
+yourself, and want &kdesrc-build; to start again with the next
+module.</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-resume">
+<term><parameter>--resume</parameter></term>
+<listitem><para>
+
+This option can be used to run &kdesrc-build; after it has had a build failure.
+</para><para>
+
+It resumes the build from the module that failed, using the list of modules
+that were waiting to be built before, and disables source and metadata updates
+as well. The use case is when a simple mistake or missing dependency causes the
+build failure. Once you correct the error you can quickly get back into
+building the modules you were building before, without fiddling with
+<option><link linkend="cmdline-resume-from">--resume-from</link></option> and
+<option><link linkend="cmdline-stop-before">--stop-before</link></option>.
+
+</para><para>
+This option was added with &kdesrc-build; 1.16.
+
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-stop-before">
+<term><parameter>--stop-before</parameter> (or <parameter>--until</parameter>)</term>
+<listitem><para>
+This command line option is used to stop the normal build process just
+<emphasis>before</emphasis> a module would ordinarily be built.
+</para><para>
+For example, if the normal build list was <simplelist type="inline">
+<member>moduleA</member><member>moduleB</member><member>moduleC</member></simplelist>,
+then <option>--stop-before=<replaceable>moduleB</replaceable></option> would cause
+&kdesrc-build; to only build <literal>moduleA</literal>.
+</para><para>
+This command line option was added with &kdesrc-build; 1.16.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-stop-after">
+<term><parameter>--stop-after</parameter> (or <parameter>--to</parameter>)</term>
+<listitem><para>
+This command line option is used to stop the normal build process just
+<emphasis>after</emphasis> a module would ordinarily be built.
+</para><para>
+For example, if the normal build list was <simplelist type="inline">
+<member>moduleA</member><member>moduleB</member><member>moduleC</member></simplelist>,
+then <option>--stop-after=<replaceable>moduleB</replaceable></option> would cause
+&kdesrc-build; to build <literal>moduleA</literal> and <literal>moduleB</literal>.
+</para><para>
+This command line option was added with &kdesrc-build; 1.16.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-stop-on-failure">
+<term><parameter>--stop-on-failure</parameter></term>
+<term><parameter>--no-stop-on-failure</parameter></term>
+<listitem><para>
+This option controls if the build will be aborted as soon as a failure occurs.
+Default behavior is --stop-on-failure. You may override it if you wish to press on with the rest of the modules in the build,
+to avoid wasting time in case the problem is with a single module.
+</para><para>
+This option was added with &kdesrc-build; 1.16. See also the
+<link linkend="conf-stop-on-failure">stop-on-failure</link> configuration file option.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-rc-file">
+<term><parameter>--rc-file</parameter></term>
+<listitem><para>
+This interprets the next command line parameter as the file to read the
+configuration options from. The default value for this parameter is
+<filename>kdesrc-buildrc</filename> (checked in the current working directory).
+If this file doesn't exist, <filename>~/.config/kdesrc-buildrc</filename>
+(<filename>$XDG_CONFIG_HOME/kdesrc-buildrc</filename>, if
+<envar>$XDG_CONFIG_HOME</envar> is set) will be used instead. See also
+<xref linkend="kdesrc-buildrc"/>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-print-modules">
+<term><parameter>--print-modules</parameter></term>
+<listitem>
+<para>
+ Takes all actions up to and including dependency reordering of the modules
+ specified on the command line (or configuration file), prints the modules
+ that would be processed one per line, and then exits without further action.
+</para>
+<para>
+ The <literal>kde-project</literal> metadata is downloaded first (though, see
+ <link linkend="cmdline-pretend"><option>--pretend</option></link> or <link
+ linkend="cmdline-no-src"><option>--no-src</option></link>).
+</para>
+<para>
+ The output is not fully compatible with usage by scripts as other output messages
+ may be generated until the module list is shown.
+</para>
+<para>
+ This is mostly just useful for quickly determining what &kdesrc-build;
+ understands a module's dependencies to be, which means it's only useful for
+ <link
+ linkend="kde-projects-module-sets"><literal>kde-projects</literal></link>
+ modules. This option is also compatible with <link
+ linkend="cmdline-resume-from"><option>--resume-from</option></link>, <link
+ linkend="cmdline-resume-after"><option>--resume-after</option></link>,
+ <link linkend="cmdline-stop-before"><option>--stop-before</option></link>,
+ <link linkend="cmdline-stop-after"><option>--stop-after</option></link>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-list-build">
+<term><parameter>--list-build</parameter></term>
+<listitem>
+<para>
+ Lists the modules that would be built, in the order in which they would be built.
+ If applicable, the output listing also mentions which commit/branch/tag would be
+ selected for checkout.
+</para>
+<para>
+ This option is similar to
+ <link linkend="cmdline-print-modules"><option>--print-modules</option></link>.
+ For more detailed information on how modules relate to each other, see also:
+ <link linkend="cmdline-dependency-tree"><option>--dependency-tree</option></link>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-dependency-tree">
+<term><parameter>--dependency-tree</parameter></term>
+<listitem>
+<para>
+ Prints out dependency information on the modules that would be built using a tree
+ format (recursive). Listed information also includes which specific commit/branch/tag
+ is depended on and whether or not the dependency would be built. Note: the generated
+ output may become quite large for applications with many dependencies.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-dependency-tree-fullpath">
+<term><parameter>--dependency-tree-fullpath</parameter></term>
+<listitem>
+<para>
+ Prints out dependency information on the modules that would be built using a tree
+ format (recursive). In fullpath format. Note: the generated
+ output may become quite large for applications with many dependencies.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-run">
+<term><parameter>--run</parameter></term>
+<listitem><para>
+This option interprets the next item on the command line as a program to run,
+and &kdesrc-build; will then finish reading the configuration file, update the
+environment as normal, and then execute the given program.</para>
+
+<para>This will not work to start a shell with the &kdesrc-build; environment
+in most cases however, since interactive shells typically reset at least part
+of the environment variables (such as <envar>PATH</envar> and
+${install-dir}) in the startup sequence.
+</para>
+
+<tip><para>If you want to see the environment used by &kdesrc-build;, you
+can run the <command>printenv</command> command:</para>
+<informalexample>
+<screen>$ <command>kdesrc-build</command> <parameter>--run</parameter> <parameter>printenv</parameter>
+KDE_SESSION_VERSION=4
+SDL_AUDIODRIVER=alsa
+LANGUAGE=
+XCURSOR_THEME=Oxygen_Blue
+LESS=-R -M --shift 5
+QMAIL_CONTROLDIR=/var/qmail/control
+... etc.
+</screen>
+</informalexample></tip>
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-prefix">
+<term><parameter>--prefix=</path/to/kde></parameter></term>
+<listitem><para>
+This allows you to change the directory that &kde; will be installed to from
+the command line. This option implies <link
+linkend="cmdline-reconfigure"><parameter>--reconfigure</parameter></link>,
+but using <link linkend="cmdline-refresh-build"><parameter>--refresh-build</parameter></link>
+may still be required.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-revision">
+<term><parameter>--revision</parameter></term>
+<listitem><para>
+This option causes &kdesrc-build; to checkout a specific numbered revision
+for each &git; module, overriding any <link linkend="conf-branch">branch</link>,
+<link linkend="conf-tag">tag</link>, or <link linkend="conf-revision">revision</link>
+options already set for these modules.</para>
+
+<para>This option is likely not a good idea, and is only supported for
+compatibility with older scripts.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-build-system-only">
+<term><parameter>--build-system-only</parameter></term>
+<listitem><para>
+This option causes &kdesrc-build; to abort building a module just before
+the <command>make</command> command would have been run. This is supported
+for compatibility with older versions only, this effect is not helpful for
+the current &kde; build system.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-delete-my-patches">
+<term><parameter>--delete-my-patches</parameter></term>
+<listitem><para>
+This option is used to let &kdesrc-build; delete source directories that may
+contain user data, so that the module can be re-downloaded. This would normally
+only be useful for &kde; developers (who might have local changes that would be
+deleted).</para>
+
+<para>You should not use this option normally,
+&kdesrc-build; will prompt to be re-run with it if it is needed.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-delete-my-settings">
+<term><parameter>--delete-my-settings</parameter></term>
+<listitem><para>
+This option is used to let &kdesrc-build; overwrite existing files which may contain
+user data.</para>
+
+<para>This is currently only used for xsession setup for the login manager. You
+should not use this option normally, &kdesrc-build; will prompt to be re-run
+with it if it is needed.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-global-option">
+<term><parameter>--<replaceable><option-name></replaceable>=</parameter></term>
+<listitem><para>
+You can use this option to override an option in your <link linkend="configure-data">configuration file</link> for
+every module. For instance, to override the <link
+linkend="conf-log-dir">log-dir</link> option, you would do:
+<userinput><parameter>--log-dir=<filename class="directory"><replaceable>/path/to/dir</replaceable></filename></parameter></userinput>.
+</para>
+
+<note><para>This feature can only be used for option names already recognized
+by &kdesrc-build;, that are not already supported by relevant command line
+options. For example the <link linkend="conf-async">async</link> configuration
+file option has specific <link linkend="cmdline-async">--async</link> and <link
+linkend="cmdline-no-async">--no-async</link> command line options that are
+preferred by &kdesrc-build;.
+</para></note>
+
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-module-option">
+<term><parameter>--set-module-option-value=<replaceable><module-name></replaceable>,<replaceable><option-name></replaceable>,<replaceable><option-value></replaceable></parameter></term>
+<listitem><para>
+You can use this option to override an option in your <link linkend="configure-data">configuration file</link> for
+a specific module.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+<para>
+Any other command-line options are assumed to be modules to update and build.
+Please, do not mix building with installing.
+</para>
+
+</sect1>
+
+</chapter>
diff --git a/doc/index.docbook b/doc/index.docbook
index 55314add..c95a6fb2 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -73,6 +73,7 @@
<!ENTITY basic-features SYSTEM "basic-features.docbook">
<!ENTITY building-and-troubleshooting SYSTEM "building-and-troubleshooting.docbook">
<!ENTITY building-specific-modules SYSTEM "building-specific-modules.docbook">
+ <!ENTITY cmdline SYSTEM "cmdline.docbook">
]>
<book id="kdesrc-build" lang="&language;">
@@ -2906,843 +2907,7 @@ of its use and an example.</para>
</sect1>
</chapter>
-<chapter id="cmdline">
-<title>Command Line Options and Environment Variables</title>
-
-<sect1 id="cmdline-usage">
-<title>Command Line Usage</title>
-
-<para>&kdesrc-build; is designed to be run as follows:</para>
-
-<cmdsynopsis>
-<command>kdesrc-build</command>
-<arg rep="repeat"><replaceable>--options</replaceable></arg>
-<arg rep="repeat"><replaceable>modules to build</replaceable></arg>
-</cmdsynopsis>
-
-<para>If no modules to build are specified on the command line, then
-kdesrc-build will build all modules defined in its configuration file, in the
-order listed in that file (although this can be modified by various
-configuration file options).</para>
-
-<sect2 id="cmdline-usage-options">
-<title>Commonly used command line options</title>
-
-<para>The full list of command line options is given in <xref
-linkend="supported-cmdline-params"/>. The most-commonly used options
-include:</para>
-
-<variablelist>
- <varlistentry>
- <term><option>--pretend</option> (or <option>-p</option>)</term>
- <listitem><para>This option causes &kdesrc-build; to indicate what actions
- it would take, without actually really implementing them. This can be
- useful to make sure that the modules you think you are building will
- actually get built.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--refresh-build</option></term>
- <listitem><para>This option forces &kdesrc-build; to build the given
- modules from an absolutely fresh start point. Any existing build directory
- for that module is removed and it is rebuilt. This option is useful if you
- have errors building a module, and sometimes is required when &Qt; or &kde;
- libraries change.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--no-src</option></term>
- <listitem><para>This option skips the source update process. You might use
- it if you have very recently updated the source code (perhaps you did it
- manually or recently ran &kdesrc-build;) but still want to rebuild some
- modules.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--no-build</option></term>
- <listitem><para>This option is similar to <option>--no-src</option> above,
- but this time the build process is skipped.</para></listitem>
- </varlistentry>
-</variablelist>
-
-</sect2>
-
-<sect2 id="cmdline-usage-modules">
-<title>Specifying modules to build</title>
-
-<para>In general, specifying modules to build is as simple as passing their
-module name as you defined it in the configuration file. You can also pass
-modules that are part of a module set, either as named on <link
-linkend="conf-use-modules">use-modules</link>, or the name of the entire module
-set itself, if you have given it a name.</para>
-
-<para>In the specific case of module sets based against the <link
-linkend="kde-projects-module-sets">KDE project database</link>, &kdesrc-build;
-will expand module name components to determine the exact module you
-want. For example, &kdesrc-build;'s KDE project entry locates the project in
-<literal>extragear/utils/kdesrc-build</literal>. You could specify any
-of the following to build &kdesrc-build;:</para>
-
-<informalexample>
-<screen>
-<prompt>%</prompt> <command>kdesrc-build</command> <option><replaceable>+extragear/utils/kdesrc-build</replaceable></option>
-<prompt>%</prompt> <command>kdesrc-build</command> <option><replaceable>+utils/kdesrc-build</replaceable></option>
-<prompt>%</prompt> <command>kdesrc-build</command> <option><replaceable>+kdesrc-build</replaceable></option>
-</screen>
-</informalexample>
-
-<note><para>The commands in the previous example preceded the module-name with
-a <symbol>+</symbol>. This forces the module name to be interpreted as a module
-from the KDE project database, even if that module hasn't been defined in your
-configuration file.
-</para></note>
-
-<para>Be careful about specifying very generic projects (e.g.
-<literal>extragear/utils</literal> by itself), as this can lead to a large
-amount of modules being built. You should use the <option>--pretend</option>
-option before building a new module set to ensure it is only building the
-modules you want.</para>
-
-</sect2>
-</sect1>
-
-<sect1 id="supported-envvars">
-<title>Supported Environment Variables</title>
-
-<para>
-&kdesrc-build; does not use environment variables. If you need to set environment
-variables for the build or install process, please see the <link
-linkend="conf-set-env">set-env</link> option.
-</para>
-
-</sect1>
-
-<sect1 id="supported-cmdline-params">
-<title>Supported command-line parameters</title>
-
-<para>
-The script accepts the following command-line options:
-</para>
-
-<variablelist>
-
-<varlistentry id="cmdline-async">
-<term><parameter>--async</parameter></term>
-<listitem><para>
-Enables the <link linkend="conf-async">asynchronous mode</link>, which can
-perform the source code updates and module builds at the same time. This is
-the default, this option only needs specified if you have disabled it in the
-configuration.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-help">
-<term><parameter>--help</parameter> (or <parameter>-h</parameter>)</term>
-<listitem><para>
-Only display simple help on this script.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-version">
-<term><parameter>--version</parameter> (or <parameter>-v</parameter>)</term>
-<listitem><para>
-Display the program version.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-show-info">
-<term><parameter>--show-info</parameter></term>
-<listitem><para>
-Displays information about &kdesrc-build; and the operating system, that may
-prove useful in bug reports or when asking for help in forums or mailing lists.
-</para>
-<para>Available since version 18.11.</para>
-</listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-initial-setup">
-<term><parameter>--initial-setup</parameter></term>
-<listitem><para>
-Has &kdesrc-build; perform the one-time initial setup necessary to prepare
-the system for &kdesrc-build; to operate, and for the newly-installed &kde;
-software to run.
-</para>
-<para>This includes:</para>
-<itemizedlist>
-<listitem><para>Installing known dependencies (on supported &Linux; distributions)</para></listitem>
-<listitem><para>Adding required environment variables to <literal>~/.bashrc</literal></para></listitem>
-<listitem><para>Setting up a <link linkend="setup-rcfile">configuration file</link></para></listitem>
-</itemizedlist>
-<para>This option is exactly equivalent to using
- <option><link linkend="cmdline-install-distro-packages">--install-distro-packages</link></option>
- <option><link linkend="cmdline-generate-config">--generate-config</link></option>
- <option><link linkend="cmdline-update-shellrc">--update-shellrc</link></option> at the same time.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-install-distro-packages">
-<term><parameter>--install-distro-packages</parameter></term>
-<listitem><para>
-Installs distro packages (on supported &Linux; distributions) necessary to prepare the system for &kdesrc-build; to operate, and for the newly-installed &kde;
-software to run.
-</para>
-<para>See also <option><link linkend="cmdline-initial-setup">--initial-setup</link></option></para>
-</listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-generate-config">
-<term><parameter>--generate-config</parameter></term>
-<listitem><para>
-Generate the &kdesrc-build; configuration file.
-</para>
-<para>See also <option><link linkend="cmdline-initial-setup">--initial-setup</link></option></para>
-</listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-update-shellrc">
-<term><parameter>--update-shellrc</parameter></term>
-<listitem><para>
-Edit the "~/.bashrc" (or other shell rc file) to add &kdesrc-build; to your $PATH variable and enable autocompletion.
-</para>
-<para>See also <option><link linkend="cmdline-initial-setup">--initial-setup</link></option></para>
-</listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-author">
-<term><parameter>--author</parameter></term>
-<listitem><para>
-Display contact information for the
-author.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-color">
-<term><parameter>--color</parameter></term>
-<listitem><para>
-Enable colorful output. (This is the default for interactive terminals).
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-generate-vscode-project-config">
-<term><parameter>--generate-vscode-project-config</parameter></term>
-<listitem><para>
-Generate a .vscode directory with configurations for building and debugging
-in Visual Studio Code.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-nice">
-<term><parameter>--nice=<replaceable>value</replaceable></parameter></term>
-<listitem><para>
-This value adjusts the computer CPU priority requested by &kdesrc-build;, and
-should be in the range of 0-20. 0 is highest priority (because it is the
-least <quote>nice</quote>), 20 is lowest priority. &kdesrc-build; defaults
-to 10.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-no-async">
-<term><parameter>--no-async</parameter></term>
-<listitem><para>
-Disables the <link linkend="conf-async">asynchronous mode</link> of updating.
-Instead the update will be performed in its entirety before the build starts.
-This option will slow down the overall process, but if you encounter IPC errors
-while running &kdesrc-build; try using this option, and submitting a
-<ulink url="https://bugs.kde.org/">bug report</ulink>.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-no-color">
-<term><parameter>--no-color</parameter></term>
-<listitem><para>
-Disable colorful output.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-pretend">
-<term><parameter>--pretend</parameter> (or <parameter>-p</parameter>)</term>
-<listitem><para>
-&kdesrc-build; will run through the update and build process, but instead of
-performing any actions to update or build, will instead output what the
-script would have done (e.g. what commands to run, general steps being taken,
-etc.).</para>
-
-<note><para>Simple read-only commands (such as reading file information) may
-still be run to make the output more relevant (such as correctly simulating
-whether source code would be checked out or updated).
-</para></note>
-
-<important><para>This option requires that some needed metadata is available,
-which is normally automatically downloaded, but downloads are disabled in
-pretend mode. If you've never run &kdesrc-build; (and therefore, don't have
-this metadata), you should run <command>kdesrc-build
-<option>--metadata-only</option></command> to download the required metadata
-first.
-</para></important>
-</listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-quiet">
-<term><parameter>--quiet</parameter> (or <parameter>-q</parameter>)</term>
-<listitem><para>
-Do not be as noisy with the output. With this switch only the basics are
-output.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-really-quiet">
-<term><parameter>--really-quiet</parameter></term>
-<listitem><para>
-Only output warnings and errors.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-verbose">
-<term><parameter>--verbose</parameter></term>
-<listitem><para>
-Be very descriptive about what is going on, and what &kdesrc-build; is doing.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-src-only">
-<term><parameter>--src-only</parameter> (or <parameter>-s</parameter>)</term>
-<listitem><para>
-Only perform the source update.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-build-only">
-<term><parameter>--build-only</parameter></term>
-<listitem><para>
-Only perform the build process.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-install-only">
-<term><parameter>--install-only</parameter></term>
-<listitem><para>
-If this is the only command-line option, it tries to install all of the modules
-contained in <filename>log/latest/build-status</filename>. If command-line
-options are specified after <parameter>--install-only</parameter>, they are all
-assumed to be modules to install (even if they did not successfully build on
-the last run).
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-metadata-only">
-<term><parameter>--metadata-only</parameter></term>
-<listitem><para>
-Only perform the metadata download process. &kdesrc-build; normally handles this
-automatically, but you might manually use this to allow the <option><link
-linkend="cmdline-pretend">--pretend</link></option> command line option to work.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-rebuild-failures">
-<term><parameter>--rebuild-failures</parameter></term>
-<listitem><para>
-Use this option to build only those modules which failed to build on a previous
-&kdesrc-build; run. This is useful if a significant number of failures occurred mixed with
-successful builds. After fixing the issue causing the build failures you can then easily
-build only the modules that failed previously.</para>
-
-<note><para>Note that the list of <quote>previously-failed modules</quote> is
-reset every time a &kdesrc-build; run finishes with some module failures.
-However it is not reset by a completely successful build, so you can
-successfully rebuild a module or two and this flag will still
-work.</para></note>
-
-<para>This option was added for &kdesrc-build; 15.09.</para>
-</listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-include-dependencies">
-<term><parameter>--include-dependencies</parameter> (or <parameter>-d</parameter>)</term>
-<term><parameter>--no-include-dependencies</parameter> (or <parameter>-D</parameter>)</term>
-<listitem><para>
-This option causes &kdesrc-build; to automatically include other &kde; and &Qt;
-modules in the build, if required for the modules you have requested to build
-on the command line or in your
-<link linkend="configure-data">configuration file</link>.</para>
-
-<para>The modules that are added are as recorded within the &kde; source code
-management system. See <xref linkend="kde-projects-module-sets"/>.</para>
-
-<para>The corresponding configure file option is
-<link linkend="conf-include-dependencies">include-dependencies</link>.</para>
-
-<para>You can also use <parameter>--no-include-dependencies</parameter>, which turns off
-automatic inclusion of additional dependency modules.</para>
-</listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-ignore-modules">
-<term><parameter>--ignore-modules</parameter> (or <parameter>-!</parameter>)</term>
-<listitem><para>
-Do not include the modules passed on the rest of the command line in the
-update/build process (this is useful if you want to build most of the modules
-in your <link linkend="configure-data">configuration file</link> and just skip
-a few).
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-no-src">
-<term><parameter>--no-src</parameter> (or <parameter>-S</parameter>)</term>
-<listitem><para>
-Skip contacting the &git; server.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-no-build">
-<term><parameter>--no-build</parameter></term>
-<listitem><para>
-Skip the build process.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-no-metadata">
-<term><parameter>--no-metadata</parameter></term>
-<listitem><para>
-Do not automatically download the extra metadata needed for &kde; git modules.
-The source updates for the modules themselves will still occur unless you pass
-<link linkend="cmdline-no-src">--no-src</link> as well.
-</para><para>
-This can be useful if you are frequently re-running &kdesrc-build; since the
-metadata does not change very often. But note that many other features require
-the metadata to be available. You might want to consider running &kdesrc-build;
-with the <link linkend="cmdline-metadata-only">--metadata-only</link> option
-one time and then using this option for subsequent runs.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-no-install">
-<term><parameter>--no-install</parameter></term>
-<listitem><para>
-Do not automatically install packages after they are built.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-no-build-when-unchanged">
-<term><parameter>--no-build-when-unchanged</parameter></term>
-<term><parameter>--force-build</parameter></term>
-<listitem><para>
-This option explicitly disables skipping the build process (an optimization
-controlled by the <link
-linkend="conf-build-when-unchanged">build-when-unchanged</link> option). This is
-useful for making &kdesrc-build; run the build when you have changed something
-that &kdesrc-build; cannot check.</para>
-
-<para><parameter>--force-build</parameter> performs the exact same function, and
-is perhaps easier to remember.</para>
-</listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-debug">
-<term><parameter>--debug</parameter></term>
-<listitem><para>
-Enables debug mode for the script. Currently this means that all output will be
-dumped to the standard output in addition to being logged in the log directory
-like normal. Also, many functions are much more verbose about what they are
-doing in debugging mode.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-query">
-<term><parameter>--query</parameter>=<userinput><replaceable>mode</replaceable></userinput></term>
-<listitem><para>
-This command causes &kdesrc-build; to query a parameter of the modules in the
-build list (either passed on the command line or read in from the configuration
-file), outputting the result to screen (one module per line).</para>
-
-<para>This option must be provided with a <quote>query mode</quote>, which should be
-one of the following:</para>
- <itemizedlist>
- <listitem><para><option>source-dir</option>, which causes &kdesrc-build; to
- output the full path to where the module's source code is stored.
- </para></listitem>
- <listitem><para><option>build-dir</option>, which causes &kdesrc-build; to
- output the full path to where the module build process occurs.
- </para></listitem>
- <listitem><para><option>install-dir</option>, which causes &kdesrc-build; to
- output the full path to where the module will be installed.
- </para></listitem>
- <listitem><para><option>project-path</option>, which causes &kdesrc-build; to
- output the location of the module within the hierarchy of KDE source
- code repositories. See <xref linkend="kde-projects-module-sets"/> for
- more information on this hierarchy.
- </para></listitem>
- <listitem><para><option>branch</option>, which causes &kdesrc-build; to
- output the resolved git branch that will be used for each module, based
- on the <link linkend="conf-tag">tag</link>, <link
- linkend="conf-branch">branch</link> and <link
- linkend="conf-branch-group">branch-group</link> settings in effect.
- </para></listitem>
- <listitem><para>Otherwise, option names that are valid for modules in the
- <link linkend="conf-options-table">configuration file</link> can be
- used, the resolved value of which will be listed for each module.
- </para></listitem>
- </itemizedlist>
-
-<para>
-If a single module is passed on the command line, then the output is simply the
-value of the parameter being queried. If multiple (or no) modules are passed on
-the command line, then each line is prefixed by the name of the module. Either way,
-&kdesrc-build; stops running once each value is output.
-</para>
-
-<para>This option was added with &kdesrc-build; 16.05.</para>
-
-<informalexample>
-<para>For example, the command <quote><command>kdesrc-build</command>
- <parameter>--query</parameter>
- <parameter><replaceable>branch</replaceable></parameter>
- <parameter><replaceable>kactivities</replaceable></parameter>
- <parameter><replaceable>kdepim</replaceable></parameter></quote>
-might end up with output like:</para>
-<screen>
-kactivities: master
-kdepim: master
-</screen>
-</informalexample>
-</listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-refresh-build">
-<term><parameter>--refresh-build</parameter> (or <parameter>-r</parameter>)</term>
-<listitem><para>
-Recreate the build system and make from scratch.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-reconfigure">
-<term><parameter>--reconfigure</parameter></term>
-<listitem><para>
-Run <command>cmake</command> (for &kde; modules) or
-<command>configure</command> (for &Qt;) again, without cleaning the build
-directory. You should not normally have to specify this, as &kdesrc-build; will
-detect when you change the relevant options and automatically re-run the build
-setup. This option is implied if <parameter><link
-linkend="cmdline-refresh-build">--refresh-build</link></parameter> is used.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-resume-from">
-<term><parameter>--resume-from</parameter> (or <parameter>--from</parameter> or <parameter>-f</parameter>)</term>
-<listitem><para>
-This option is used to resume the build starting from the given module, which
-should be the next option on the command line. You should not
-specify other module names on the command line.
-</para>
-
-<note><para>This option formerly added <link
- linkend="cmdline-no-src"><parameter>--no-src</parameter></link>, but does
-not any longer (since &kdesrc-build; 1.13). If you want to avoid source updates
-when resuming, simply pass <option><userinput>--no-src</userinput></option>
-in addition to the other options.
-</para></note>
-
-<para>See also: <xref linkend="cmdline-resume-after"/> and <xref
-linkend="resuming-failed"/>. You would prefer to use this command line option
-if you have fixed the build error and want &kdesrc-build; to complete the
-build.</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-resume-after">
-<term><parameter>--resume-after</parameter> (or <parameter>--after</parameter> or <parameter>-a</parameter>)</term>
-<listitem><para>
-This option is used to resume the build starting after the given module, which
-should be the next option on the command line. You should not
-specify other module names on the command line.
-</para>
-
-<note><para>This option formerly added <link
- linkend="cmdline-no-src"><parameter>--no-src</parameter></link>, but does
-not any longer (since &kdesrc-build; 1.13). If you want to avoid source updates
-when resuming, simply pass <option><userinput>--no-src</userinput></option>
-in addition to the other options.
-</para></note>
-
-<para>See also: <xref linkend="cmdline-resume-from"/> and <xref
-linkend="resuming-failed"/>. You would prefer to use this command line option
-if you have fixed the build error and have also built and installed the module
-yourself, and want &kdesrc-build; to start again with the next
-module.</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-resume">
-<term><parameter>--resume</parameter></term>
-<listitem><para>
-
-This option can be used to run &kdesrc-build; after it has had a build failure.
-</para><para>
-
-It resumes the build from the module that failed, using the list of modules
-that were waiting to be built before, and disables source and metadata updates
-as well. The use case is when a simple mistake or missing dependency causes the
-build failure. Once you correct the error you can quickly get back into
-building the modules you were building before, without fiddling with
-<option><link linkend="cmdline-resume-from">--resume-from</link></option> and
-<option><link linkend="cmdline-stop-before">--stop-before</link></option>.
-
-</para><para>
-This option was added with &kdesrc-build; 1.16.
-
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-stop-before">
-<term><parameter>--stop-before</parameter> (or <parameter>--until</parameter>)</term>
-<listitem><para>
-This command line option is used to stop the normal build process just
-<emphasis>before</emphasis> a module would ordinarily be built.
-</para><para>
-For example, if the normal build list was <simplelist type="inline">
-<member>moduleA</member><member>moduleB</member><member>moduleC</member></simplelist>,
-then <option>--stop-before=<replaceable>moduleB</replaceable></option> would cause
-&kdesrc-build; to only build <literal>moduleA</literal>.
-</para><para>
-This command line option was added with &kdesrc-build; 1.16.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-stop-after">
-<term><parameter>--stop-after</parameter> (or <parameter>--to</parameter>)</term>
-<listitem><para>
-This command line option is used to stop the normal build process just
-<emphasis>after</emphasis> a module would ordinarily be built.
-</para><para>
-For example, if the normal build list was <simplelist type="inline">
-<member>moduleA</member><member>moduleB</member><member>moduleC</member></simplelist>,
-then <option>--stop-after=<replaceable>moduleB</replaceable></option> would cause
-&kdesrc-build; to build <literal>moduleA</literal> and <literal>moduleB</literal>.
-</para><para>
-This command line option was added with &kdesrc-build; 1.16.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-stop-on-failure">
-<term><parameter>--stop-on-failure</parameter></term>
-<term><parameter>--no-stop-on-failure</parameter></term>
-<listitem><para>
-This option controls if the build will be aborted as soon as a failure occurs.
-Default behavior is --stop-on-failure. You may override it if you wish to press on with the rest of the modules in the build,
-to avoid wasting time in case the problem is with a single module.
-</para><para>
-This option was added with &kdesrc-build; 1.16. See also the
-<link linkend="conf-stop-on-failure">stop-on-failure</link> configuration file option.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-rc-file">
-<term><parameter>--rc-file</parameter></term>
-<listitem><para>
-This interprets the next command line parameter as the file to read the
-configuration options from. The default value for this parameter is
-<filename>kdesrc-buildrc</filename> (checked in the current working directory).
-If this file doesn't exist, <filename>~/.config/kdesrc-buildrc</filename>
-(<filename>$XDG_CONFIG_HOME/kdesrc-buildrc</filename>, if
-<envar>$XDG_CONFIG_HOME</envar> is set) will be used instead. See also
-<xref linkend="kdesrc-buildrc"/>.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-print-modules">
-<term><parameter>--print-modules</parameter></term>
-<listitem>
-<para>
- Takes all actions up to and including dependency reordering of the modules
- specified on the command line (or configuration file), prints the modules
- that would be processed one per line, and then exits without further action.
-</para>
-<para>
- The <literal>kde-project</literal> metadata is downloaded first (though, see
- <link linkend="cmdline-pretend"><option>--pretend</option></link> or <link
- linkend="cmdline-no-src"><option>--no-src</option></link>).
-</para>
-<para>
- The output is not fully compatible with usage by scripts as other output messages
- may be generated until the module list is shown.
-</para>
-<para>
- This is mostly just useful for quickly determining what &kdesrc-build;
- understands a module's dependencies to be, which means it's only useful for
- <link
- linkend="kde-projects-module-sets"><literal>kde-projects</literal></link>
- modules. This option is also compatible with <link
- linkend="cmdline-resume-from"><option>--resume-from</option></link>, <link
- linkend="cmdline-resume-after"><option>--resume-after</option></link>,
- <link linkend="cmdline-stop-before"><option>--stop-before</option></link>,
- <link linkend="cmdline-stop-after"><option>--stop-after</option></link>.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-list-build">
-<term><parameter>--list-build</parameter></term>
-<listitem>
-<para>
- Lists the modules that would be built, in the order in which they would be built.
- If applicable, the output listing also mentions which commit/branch/tag would be
- selected for checkout.
-</para>
-<para>
- This option is similar to
- <link linkend="cmdline-print-modules"><option>--print-modules</option></link>.
- For more detailed information on how modules relate to each other, see also:
- <link linkend="cmdline-dependency-tree"><option>--dependency-tree</option></link>.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-dependency-tree">
-<term><parameter>--dependency-tree</parameter></term>
-<listitem>
-<para>
- Prints out dependency information on the modules that would be built using a tree
- format (recursive). Listed information also includes which specific commit/branch/tag
- is depended on and whether or not the dependency would be built. Note: the generated
- output may become quite large for applications with many dependencies.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-dependency-tree-fullpath">
-<term><parameter>--dependency-tree-fullpath</parameter></term>
-<listitem>
-<para>
- Prints out dependency information on the modules that would be built using a tree
- format (recursive). In fullpath format. Note: the generated
- output may become quite large for applications with many dependencies.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-run">
-<term><parameter>--run</parameter></term>
-<listitem><para>
-This option interprets the next item on the command line as a program to run,
-and &kdesrc-build; will then finish reading the configuration file, update the
-environment as normal, and then execute the given program.</para>
-
-<para>This will not work to start a shell with the &kdesrc-build; environment
-in most cases however, since interactive shells typically reset at least part
-of the environment variables (such as <envar>PATH</envar> and
-${install-dir}) in the startup sequence.
-</para>
-
-<tip><para>If you want to see the environment used by &kdesrc-build;, you
-can run the <command>printenv</command> command:</para>
-<informalexample>
-<screen>$ <command>kdesrc-build</command> <parameter>--run</parameter> <parameter>printenv</parameter>
-KDE_SESSION_VERSION=4
-SDL_AUDIODRIVER=alsa
-LANGUAGE=
-XCURSOR_THEME=Oxygen_Blue
-LESS=-R -M --shift 5
-QMAIL_CONTROLDIR=/var/qmail/control
-... etc.
-</screen>
-</informalexample></tip>
-</listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-prefix">
-<term><parameter>--prefix=</path/to/kde></parameter></term>
-<listitem><para>
-This allows you to change the directory that &kde; will be installed to from
-the command line. This option implies <link
-linkend="cmdline-reconfigure"><parameter>--reconfigure</parameter></link>,
-but using <link linkend="cmdline-refresh-build"><parameter>--refresh-build</parameter></link>
-may still be required.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-revision">
-<term><parameter>--revision</parameter></term>
-<listitem><para>
-This option causes &kdesrc-build; to checkout a specific numbered revision
-for each &git; module, overriding any <link linkend="conf-branch">branch</link>,
-<link linkend="conf-tag">tag</link>, or <link linkend="conf-revision">revision</link>
-options already set for these modules.</para>
-
-<para>This option is likely not a good idea, and is only supported for
-compatibility with older scripts.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-build-system-only">
-<term><parameter>--build-system-only</parameter></term>
-<listitem><para>
-This option causes &kdesrc-build; to abort building a module just before
-the <command>make</command> command would have been run. This is supported
-for compatibility with older versions only, this effect is not helpful for
-the current &kde; build system.
-</para></listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-delete-my-patches">
-<term><parameter>--delete-my-patches</parameter></term>
-<listitem><para>
-This option is used to let &kdesrc-build; delete source directories that may
-contain user data, so that the module can be re-downloaded. This would normally
-only be useful for &kde; developers (who might have local changes that would be
-deleted).</para>
-
-<para>You should not use this option normally,
-&kdesrc-build; will prompt to be re-run with it if it is needed.</para>
-</listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-delete-my-settings">
-<term><parameter>--delete-my-settings</parameter></term>
-<listitem><para>
-This option is used to let &kdesrc-build; overwrite existing files which may contain
-user data.</para>
-
-<para>This is currently only used for xsession setup for the login manager. You
-should not use this option normally, &kdesrc-build; will prompt to be re-run
-with it if it is needed.</para>
-</listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-global-option">
-<term><parameter>--<replaceable><option-name></replaceable>=</parameter></term>
-<listitem><para>
-You can use this option to override an option in your <link linkend="configure-data">configuration file</link> for
-every module. For instance, to override the <link
-linkend="conf-log-dir">log-dir</link> option, you would do:
-<userinput><parameter>--log-dir=<filename class="directory"><replaceable>/path/to/dir</replaceable></filename></parameter></userinput>.
-</para>
-
-<note><para>This feature can only be used for option names already recognized
-by &kdesrc-build;, that are not already supported by relevant command line
-options. For example the <link linkend="conf-async">async</link> configuration
-file option has specific <link linkend="cmdline-async">--async</link> and <link
-linkend="cmdline-no-async">--no-async</link> command line options that are
-preferred by &kdesrc-build;.
-</para></note>
-
-</listitem>
-</varlistentry>
-
-<varlistentry id="cmdline-module-option">
-<term><parameter>--set-module-option-value=<replaceable><module-name></replaceable>,<replaceable><option-name></replaceable>,<replaceable><option-value></replaceable></parameter></term>
-<listitem><para>
-You can use this option to override an option in your <link linkend="configure-data">configuration file</link> for
-a specific module.
-</para></listitem>
-</varlistentry>
-
-</variablelist>
-
-<para>
-Any other command-line options are assumed to be modules to update and build.
-Please, do not mix building with installing.
-</para>
-
-</sect1>
-
-</chapter>
+&cmdline;
<chapter id="using-kdesrc-build">
<title>Using &kdesrc-build;</title>
More information about the kde-doc-english
mailing list