Git commit 5d7e870dd7658498d427451aed386a60063e0e80 by Andrew Shark. Committed on 07/01/2024 at 10:09. Pushed by ashark into branch 'master'.
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. M +495 -479 doc/supported-cmdline-params.docbook https://invent.kde.org/sdk/kdesrc-build/-/commit/5d7e870dd7658498d427451aed386a60063e0e80 diff --git a/doc/supported-cmdline-params.docbook b/doc/supported-cmdline-params.docbook index e0258d42..3114de5f 100644 --- a/doc/supported-cmdline-params.docbook +++ b/doc/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.