[sdk/kdesrc-build/docbook_historied_per_file] doc/cmdline: doc: Group cli parameters to logical sections
Andrew Shark <[email protected]>
| Newsgroups | gmane.comp.kde.cvs,gmane.comp.kde.doc |
|---|---|
| Message-ID | <[email protected]> |
Git commit 3665f792bc29c1072848f42671e7b62a27dda820 by Andrew Shark.
Committed on 07/01/2024 at 09:09.
Pushed by ashark into branch 'docbook_historied_per_file'.
doc: Group cli parameters to logical sections
- Indicate mandatory parameters of options.
- Add missing (undocumented) alternative option names
- Change semantic markup "parameter" -> "option" to differentiate with changing part ("replaceable")
- Fix some grammar
The https://l10n.kde.org/docs/doc-primer/actions-and-commands.html does not describe (at the moment of writing) the "parameter" tag for some reason.
Original commit: 5d7e870d
https://invent.kde.org/sdk/kdesrc-build/-/commit/5d7e870dd7658498d427451aed386a60063e0e80
M +495 -479 doc/cmdline/supported-cmdline-params.docbook
https://invent.kde.org/sdk/kdesrc-build/-/commit/3665f792bc29c1072848f42671e7b62a27dda820
diff --git a/doc/cmdline/supported-cmdline-params.docbook b/doc/cmdline/supported-cmdline-params.docbook
index f5c288dd..3114de5f 100644
--- a/doc/cmdline/supported-cmdline-params.docbook
+++ b/doc/cmdline/supported-cmdline-params.docbook
@@ -1,227 +1,254 @@
<sect1 id="supported-cmdline-params">
<title>Supported command-line parameters</title>
-<para>
-The script accepts the following command-line options:
-</para>
-
+<sect2>
+<title>Generic</title>
<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>
+<varlistentry id="cmdline-pretend">
+<term><option>--pretend</option> (or <option>--dry-run</option> or <option>-p</option>)</term>
<listitem><para>
-Only display simple help on this script.
-</para></listitem>
-</varlistentry>
+&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>
-<varlistentry id="cmdline-version">
-<term><parameter>--version</parameter> (or <parameter>-v</parameter>)</term>
-<listitem><para>
-Display the program version.
-</para></listitem>
-</varlistentry>
+<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>
-<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>
+<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-initial-setup">
-<term><parameter>--initial-setup</parameter></term>
+<varlistentry id="cmdline-include-dependencies">
+<term><option>--include-dependencies</option> (or <option>-d</option>), <option>--no-include-dependencies</option> (or <option>-D</option>)</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>
+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>
-<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>
+<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 configuration file option is
+<link linkend="conf-include-dependencies">include-dependencies</link>.</para>
+
+<para>This option is enabled by default.</para>
</listitem>
</varlistentry>
-<varlistentry id="cmdline-generate-config">
-<term><parameter>--generate-config</parameter></term>
+<varlistentry id="cmdline-ignore-modules">
+<term><option>--ignore-modules</option> (or <option>-!</option>) <parameter>module [module ...]</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>
+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-update-shellrc">
-<term><parameter>--update-shellrc</parameter></term>
+<varlistentry id="cmdline-run">
+<term><option>--run</option> (or <option>--start-program</option>) <parameter>program [parameters ...]</parameter></term>
<listitem><para>
-Edit the "~/.bashrc" (or other shell rc file) to add &kdesrc-build; to your $PATH variable and enable autocompletion.
+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>
-<para>See also <option><link linkend="cmdline-initial-setup">--initial-setup</link></option></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-author">
-<term><parameter>--author</parameter></term>
+<varlistentry id="cmdline-revision">
+<term><option>--revision</option> <replaceable>id</replaceable></term>
<listitem><para>
-Display contact information for the
-author.
-</para></listitem>
-</varlistentry>
+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>
-<varlistentry id="cmdline-color">
-<term><parameter>--color</parameter></term>
-<listitem><para>
-Enable colorful output. (This is the default for interactive terminals).
+<para>This option is likely not a good idea, and is only supported for
+compatibility with older scripts.
</para></listitem>
</varlistentry>
-<varlistentry id="cmdline-generate-vscode-project-config">
-<term><parameter>--generate-vscode-project-config</parameter></term>
+<varlistentry id="cmdline-delete-my-patches">
+<term><option>--delete-my-patches</option>, <option>--no-delete-my-patches</option></term>
<listitem><para>
-Generate a .vscode directory with configurations for building and debugging
-in Visual Studio Code.
-</para></listitem>
-</varlistentry>
+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>
-<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>
+<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-no-async">
-<term><parameter>--no-async</parameter></term>
+<varlistentry id="cmdline-delete-my-settings">
+<term><option>--delete-my-settings</option>, <option>--no-delete-my-settings</option></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>
+This option is used to let &kdesrc-build; overwrite existing files which may contain
+user data.</para>
-<varlistentry id="cmdline-no-color">
-<term><parameter>--no-color</parameter></term>
-<listitem><para>
-Disable colorful output.
-</para></listitem>
+<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-pretend">
-<term><parameter>--pretend</parameter> (or <parameter>-p</parameter>)</term>
+<varlistentry id="cmdline-global-option">
+<term><option>--<replaceable><option-name></replaceable></option> <replaceable>value</replaceable></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>
+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>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).
+<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-async">--no-async</link> command line options that are
+preferred by &kdesrc-build;.
</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>
+<varlistentry id="cmdline-module-option">
+<term><option>--set-module-option-value <replaceable><module-name></replaceable>,<replaceable><option-name></replaceable>,<replaceable><option-value></replaceable></option></term>
<listitem><para>
-Do not be as noisy with the output. With this switch only the basics are
-output.
+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>
-<varlistentry id="cmdline-really-quiet">
-<term><parameter>--really-quiet</parameter></term>
-<listitem><para>
-Only output warnings and errors.
-</para></listitem>
+</variablelist>
+</sect2>
+
+<sect2>
+<title>Resuming and stopping</title>
+<variablelist>
+
+<varlistentry id="cmdline-resume-from">
+<term><option>--resume-from</option> (or <option>--from</option> or <option>-f</option>) <replaceable>module</replaceable></term>
+<listitem><para>This option is used to resume the build starting from the given module. You should not
+specify other module names on the command line.
+</para>
+
+<note><para>If you want to avoid source updates
+when resuming, simply pass <option><option>--no-src</option></option>
+in addition to the other options.
+</para></note>
+
+<para>See also: <link linkend="cmdline-resume-after">--resume-after</link> 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-verbose">
-<term><parameter>--verbose</parameter></term>
+<varlistentry id="cmdline-resume-after">
+<term><option>--resume-after</option> (or <option>--after</option> or <option>-a</option>) <replaceable>module</replaceable></term>
<listitem><para>
-Be very descriptive about what is going on, and what &kdesrc-build; is doing.
-</para></listitem>
+This option is used to resume the build starting after the given module. You should not
+specify other module names on the command line.
+</para>
+
+<note><para>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: <link linkend="cmdline-resume-from">--resume-from</link> 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-src-only">
-<term><parameter>--src-only</parameter> (or <parameter>-s</parameter>)</term>
+<varlistentry id="cmdline-resume">
+<term><option>--resume</option></term>
<listitem><para>
-Only perform the source update.
+
+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></listitem>
</varlistentry>
-<varlistentry id="cmdline-build-only">
-<term><parameter>--build-only</parameter></term>
+<varlistentry id="cmdline-stop-before">
+<term><option>--stop-before</option> (or <option>--until</option>) <replaceable>module</replaceable></term>
<listitem><para>
-Only perform the build process.
+This 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></listitem>
</varlistentry>
-<varlistentry id="cmdline-install-only">
-<term><parameter>--install-only</parameter></term>
+<varlistentry id="cmdline-stop-after">
+<term><option>--stop-after</option> (or <option>--to</option>) <replaceable>module</replaceable></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).
+This 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></listitem>
</varlistentry>
-<varlistentry id="cmdline-metadata-only">
-<term><parameter>--metadata-only</parameter></term>
+<varlistentry id="cmdline-stop-on-failure">
+<term><option>--stop-on-failure</option>, <option>--no-stop-on-failure</option></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.
+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>
+See also the <link linkend="conf-stop-on-failure">stop-on-failure</link> configuration file option.
</para></listitem>
</varlistentry>
<varlistentry id="cmdline-rebuild-failures">
-<term><parameter>--rebuild-failures</parameter></term>
+<term><option>--rebuild-failures</option></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
@@ -230,138 +257,51 @@ 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
+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>
+</variablelist>
+</sect2>
-<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>
+<sect2>
+<title>Modules information</title>
+<variablelist>
<varlistentry id="cmdline-query">
-<term><parameter>--query</parameter>=<userinput><replaceable>mode</replaceable></userinput></term>
+<term><option>--query</option> <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
+<para>This option must be provided with a <quote>mode</quote>, which may be
one of the following:</para>
<itemizedlist>
- <listitem><para><option>source-dir</option>, which causes &kdesrc-build; to
+ <listitem><para><parameter>source-dir</parameter>, 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
+ <listitem><para><parameter>build-dir</parameter>, 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
+ <listitem><para><parameter>install-dir</parameter>, 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
+ <listitem><para><parameter>project-path</parameter>, 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
+ <listitem><para><parameter>branch</parameter>, 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.
+ <listitem><para>Any option name that is valid for modules in the
+ <link linkend="conf-options-table">configuration file</link>.
</para></listitem>
</itemizedlist>
@@ -372,14 +312,9 @@ the command line, then each line is prefixed by the name of the module. Either w
&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>
+<para>For example, the command <userinput><command>kdesrc-build</command>
+<option>--query</option> <option>branch</option> <replaceable>kactivities</replaceable> <replaceable>kdepim</replaceable></userinput>
might end up with output like:</para>
<screen>
kactivities: master
@@ -389,147 +324,9 @@ kdepim: master
</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>
+<term><option>--print-modules</option></term>
<listitem>
<para>
Takes all actions up to and including dependency reordering of the modules
@@ -559,7 +356,7 @@ If this file doesn't exist, <filename>~/.config/kdesrc-buildrc</filename>
</varlistentry>
<varlistentry id="cmdline-list-build">
-<term><parameter>--list-build</parameter></term>
+<term><option>--list-build</option></term>
<listitem>
<para>
Lists the modules that would be built, in the order in which they would be built.
@@ -576,19 +373,19 @@ If this file doesn't exist, <filename>~/.config/kdesrc-buildrc</filename>
</varlistentry>
<varlistentry id="cmdline-dependency-tree">
-<term><parameter>--dependency-tree</parameter></term>
+<term><option>--dependency-tree</option></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
+ is depended on and whether 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>
+<term><option>--dependency-tree-fullpath</option></term>
<listitem>
<para>
Prints out dependency information on the modules that would be built using a tree
@@ -598,61 +395,92 @@ If this file doesn't exist, <filename>~/.config/kdesrc-buildrc</filename>
</listitem>
</varlistentry>
-<varlistentry id="cmdline-run">
-<term><parameter>--run</parameter></term>
+</variablelist>
+</sect2>
+
+<sect2>
+<title>Exclude specific action</title>
+<variablelist>
+
+<varlistentry id="cmdline-no-metadata">
+<term><option>--no-metadata</option></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>
+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>
-<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>
+<varlistentry id="cmdline-no-src">
+<term><option>--no-src</option> (or <option>-S</option>)</term>
+<listitem><para>
+Skip contacting the &git; server.
+</para></listitem>
+</varlistentry>
-<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 id="cmdline-no-build">
+<term><option>--no-build</option></term>
+<listitem><para>
+Skip the build process.
+</para></listitem>
</varlistentry>
-<varlistentry id="cmdline-prefix">
-<term><parameter>--prefix=</path/to/kde></parameter></term>
+<varlistentry id="cmdline-no-install">
+<term><option>--no-install</option></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.
+Do not automatically install packages after they are built.
</para></listitem>
</varlistentry>
-<varlistentry id="cmdline-revision">
-<term><parameter>--revision</parameter></term>
+</variablelist>
+</sect2>
+
+<sect2>
+<title>Only specific action</title>
+<variablelist>
+
+<varlistentry id="cmdline-metadata-only">
+<term><option>--metadata-only</option></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>
+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>
-<para>This option is likely not a good idea, and is only supported for
-compatibility with older scripts.
+<varlistentry id="cmdline-src-only">
+<term><option>--src-only</option> (or <option>-s</option>)</term>
+<listitem><para>
+Only perform the source update.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-build-only">
+<term><option>--build-only</option></term>
+<listitem><para>
+Only perform the build process.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-install-only">
+<term><option>--install-only</option></term>
+<listitem><para>
+If this is the only command-line option, it tries to install all the modules
+contained in <filename>log/latest/build-status</filename>. If command-line
+options are specified after this option, 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-build-system-only">
-<term><parameter>--build-system-only</parameter></term>
+<term><option>--build-system-only</option></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
@@ -661,60 +489,248 @@ 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>
+</variablelist>
+</sect2>
-<para>You should not use this option normally,
-&kdesrc-build; will prompt to be re-run with it if it is needed.</para>
+<sect2>
+<title>Build behavior</title>
+<variablelist>
+
+<varlistentry id="cmdline-build-when-unchanged">
+<term><option>--build-when-unchanged</option> (or <option>--force-build</option>), <option>--no-build-when-unchanged</option> (or <option>--no-force-build</option>)</term>
+<listitem><para>
+Enabling 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. This option is enabled by default.</para>
</listitem>
</varlistentry>
-<varlistentry id="cmdline-delete-my-settings">
-<term><parameter>--delete-my-settings</parameter></term>
+<varlistentry id="cmdline-refresh-build">
+<term><option>--refresh-build</option> (or <option>-r</option>)</term>
<listitem><para>
-This option is used to let &kdesrc-build; overwrite existing files which may contain
-user data.</para>
+Recreate the build system and make from scratch.
+</para></listitem>
+</varlistentry>
-<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>
+<varlistentry id="cmdline-reconfigure">
+<term><option>--reconfigure</option></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-prefix">
+<term><option>--prefix <replaceable>/path/to/kde</replaceable></option></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"><option>--reconfigure</option></link>,
+but using <link linkend="cmdline-refresh-build"><option>--refresh-build</option></link>
+may still be required.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-generate-vscode-project-config">
+<term><option>--generate-vscode-project-config</option>, <option>--no-generate-vscode-project-config</option></term>
+<listitem><para>
+Generate a <filename>.vscode</filename> directory with configurations for building and debugging
+in Visual Studio Code. This option is disabled by default.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</sect2>
+
+<sect2>
+<title>Script runtime</title>
+<variablelist>
+
+<varlistentry id="cmdline-async">
+<term><option>--async</option>, <option>--no-async</option></term>
+<listitem><para>
+Enables or disables the <link linkend="conf-async">asynchronous mode</link>, which can
+perform the source code updates and module builds at the same time.
+If disabled, the update will be performed in its entirety before the build starts.
+Disabling this option will slow down the overall process. If you encounter IPC errors
+while running &kdesrc-build; try disabling it, and submitting a
+<ulink url="https://bugs.kde.org/">bug report</ulink>. This option is enabled by default.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-color">
+<term><option>--color</option> (or <option>--colorful-output</option>), <option>--no-color</option> (or <option>--no-colorful-output</option>)</term>
+<listitem><para>
+Enable or disable colorful output. By default, this option is enabled for interactive terminals.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-nice">
+<term><option>--nice</option> (or <option>--niceness</option>)<replaceable>value</replaceable></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 the lowest priority. This option defaults to 10.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-rc-file">
+<term><option>--rc-file</option> <replaceable>file</replaceable></term>
+<listitem><para>
+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>
+
+</variablelist>
+</sect2>
+
+<sect2>
+<title>Setup</title>
+<variablelist>
+
+<varlistentry id="cmdline-initial-setup">
+<term><option>--initial-setup</option></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-global-option">
-<term><parameter>--<replaceable><option-name></replaceable>=</parameter></term>
+<varlistentry id="cmdline-install-distro-packages">
+<term><option>--install-distro-packages</option></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>.
+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>
-<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>
+<varlistentry id="cmdline-generate-config">
+<term><option>--generate-config</option></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><option>--update-shellrc</option></term>
+<listitem><para>
+Edit the "~/.bashrc" (or other shell rc file) to add &kdesrc-build; to your <envar>$PATH</envar> variable and enable autocompletion.
+</para>
+<para>See also <option><link linkend="cmdline-initial-setup">--initial-setup</link></option></para>
</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>
+
+</variablelist>
+</sect2>
+
+<sect2>
+<title>Verbosity level</title>
+<para>
+
+</para>
+<variablelist>
+
+<varlistentry id="cmdline-debug">
+<term><option>--debug</option></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.
+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-quiet">
+<term><option>--quiet</option> (or <option>--quite</option> or <option>-q</option>)</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><option>--really-quiet</option></term>
+<listitem><para>
+Only output warnings and errors.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-verbose">
+<term><option>--verbose</option></term>
+<listitem><para>
+Be very descriptive about what is going on, and what &kdesrc-build; is doing.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</sect2>
+
+<sect2>
+<title>Script information</title>
+<variablelist>
+
+<varlistentry id="cmdline-version">
+<term><option>--version</option> (or <option>-v</option>)</term>
+<listitem><para>
+Display the program version.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-author">
+<term><option>--author</option></term>
+<listitem><para>
+Display contact information for the
+author.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-help">
+<term><option>--help</option> (or <option>-h</option>)</term>
+<listitem><para>
+Only display simple help on this script.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-show-info">
+<term><option>--show-info</option></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>
+</listitem>
+</varlistentry>
+
</variablelist>
+</sect2>
<para>
Any other command-line options are assumed to be modules to update and build.