[sdk/kdesrc-build/docbook_historied_per_file] doc: doc: Add a cmdline usage section

[Michael Pyne]

Git commit 4e1557b0443c92f974df1a18af02779f202bd7ee by Michael Pyne.
Committed on 08/09/2011 at 02:15.
Pushed by ashark into branch 'docbook_historied_per_file'.

doc: Add a cmdline usage section

Original commit: 8eb749bf
https://invent.kde.org/sdk/kdesrc-build/-/commit/8eb749bf96dc45d4637f8042851da7778810856b

A  +96   -0    doc/cmdline/cmdline-usage.docbook
M  +2    -0    doc/cmdline/index.docbook
M  +1    -0    doc/index.docbook

https://invent.kde.org/sdk/kdesrc-build/-/commit/4e1557b0443c92f974df1a18af02779f202bd7ee

diff --git a/doc/cmdline/cmdline-usage.docbook b/doc/cmdline/cmdline-usage.docbook
new file mode 100644
index 00000000..3bad3988
--- /dev/null
+++ b/doc/cmdline/cmdline-usage.docbook
@@ -0,0 +1,96 @@
+<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>
diff --git a/doc/cmdline/index.docbook b/doc/cmdline/index.docbook
index 78d69cf1..566bd623 100644
--- a/doc/cmdline/index.docbook
+++ b/doc/cmdline/index.docbook
@@ -1,6 +1,8 @@
 <chapter id="cmdline">
 <title>Command Line Options and Environment Variables</title>
 
+&cmdline-usage;
+
 &supported-envvars;
 
 &supported-cmdline-params;
diff --git a/doc/index.docbook b/doc/index.docbook
index 12d63fac..ada9e33f 100644
--- a/doc/index.docbook
+++ b/doc/index.docbook
@@ -63,6 +63,7 @@
   <!ENTITY kdesrc-buildrc-overview SYSTEM "kdesrc-buildrc/kdesrc-buildrc-overview.docbook">
   <!ENTITY conf-options-table SYSTEM "kdesrc-buildrc/conf-options-table.docbook">
   <!ENTITY cmdline SYSTEM "cmdline/index.docbook">
+  <!ENTITY cmdline-usage SYSTEM "cmdline/cmdline-usage.docbook">
   <!ENTITY supported-envvars SYSTEM "cmdline/supported-envvars.docbook">
   <!ENTITY supported-cmdline-params SYSTEM "cmdline/supported-cmdline-params.docbook">
   <!ENTITY using-kdesrc-build SYSTEM "using-kdesrc-build/index.docbook">