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