[sdk/kdesrc-build/docbook_historied_per_file] doc/kdesrc-buildrc: Improve the documentation of the table of kdesrc-build options.
Michael Pyne
null at kde.org
Fri May 10 10:15:11 BST 2024
Git commit 514371e2c30ef1d530414b6c0f1c4060b05aebcb by Michael Pyne.
Committed on 27/08/2010 at 04:00.
Pushed by ashark into branch 'docbook_historied_per_file'.
Improve the documentation of the table of kdesrc-build options.
Remove internal names of removed options to ensure they are not referenced from
elsewhere in the documentation.
svn path=/trunk/KDE/kdesdk/doc/scripts/kdesrc-build/; revision=1168575
Original commit: 90963e41
https://invent.kde.org/sdk/kdesrc-build/-/commit/90963e4166cf08da0e6dad181c6556c2170eeb53
M +59 -48 doc/kdesrc-buildrc/conf-options-table.docbook
M +3 -19 doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook
https://invent.kde.org/sdk/kdesrc-build/-/commit/514371e2c30ef1d530414b6c0f1c4060b05aebcb
diff --git a/doc/kdesrc-buildrc/conf-options-table.docbook b/doc/kdesrc-buildrc/conf-options-table.docbook
index 054b1fd5..55b53bb2 100644
--- a/doc/kdesrc-buildrc/conf-options-table.docbook
+++ b/doc/kdesrc-buildrc/conf-options-table.docbook
@@ -1,11 +1,22 @@
<sect1 id="conf-options-table">
<title>Table of available configuration options</title>
-<para>
-Here is a table of the various options, and some comments on them. Any
-option which overrides the global option will override a command line setting
-as well.
-</para>
+<para>Here is a table of the various options, containing the following
+information:</para>
+
+<itemizedlist>
+
+<listitem><para>The option name</para></listitem>
+
+<listitem><para>A description of how &kdesrc-build; responds if the option is
+set in both the global section, and the module section of the <link
+linkend="configure-data">configuration file</link> while building a
+module.</para></listitem>
+
+<listitem><para>Special comments on the purpose and usage of the
+option.</para></listitem>
+
+</itemizedlist>
<table id="option-table">
<title>Table of Options</title>
@@ -21,9 +32,9 @@ as well.
<tbody>
-<row id="conf-apidox">
+<row>
<entry>apidox</entry>
-<entry>Overrides global</entry>
+<entry></entry>
<entry><para>This option was used to allow for building KDE module API documentation.
It was removed in &kdesrc-build; 1.6.3 due to it not being supported in KDE 4. Online
API documentation is available from <ulink url="http://api.kde.org/">kde.org</ulink>.
@@ -34,9 +45,9 @@ for older modules of course.</para>
</entry>
</row>
-<row id="conf-apply-qt-patches">
+<row>
<entry>apply-qt-patches</entry>
-<entry>Overrides global</entry>
+<entry></entry>
<entry>This option was removed in kdesrc-build 1.10. To get the same effect,
see <xref linkend="using-qt-copy" /> and the <link
linkend="conf-repository">repository</link> option.</entry>
@@ -54,7 +65,7 @@ to enabling asynchronous mode. To disable, set this option to <replaceable>fals
<row id="conf-binpath">
<entry>binpath</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry><para>Set this option to set the environment variable PATH while building.
You cannot override this setting in a module option. The default value is
the $<envar>PATH</envar> that is set when the script starts. This environment
@@ -67,7 +78,7 @@ may use the tilde (~) for any paths you add using this option.</para>
<row id="conf-branch">
<entry>branch</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry><para>Set this option to checkout from a branch of &kde; instead of the
default of <replaceable>trunk</replaceable>, where &kde; development occurs.
For instance, to checkout &kde; 4.5 branch, you would set this option to
@@ -83,7 +94,7 @@ linkend="conf-override-url">override-url</link> options.</para>
<row id="conf-build-dir">
<entry>build-dir</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry>Use this option to change the directory to contain the built sources. There
are three different ways to use it:
@@ -115,7 +126,7 @@ Perhaps surprisingly, this option can be changed per module.
<row id="conf-checkout-only">
<entry>checkout-only</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry><para>Set this option to checkout &subversion; sources piece by piece. The
value for this option should be a space-separated list of directories to
checkout. Although this option overrides the global option, be aware that
@@ -164,7 +175,7 @@ color codes to anything but a terminal (such as xterm, &konsole;, or the normal
<row id="conf-configure-flags">
<entry>configure-flags</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry><para>Use this option to specify what flags to pass to ./configure when
creating the build system for the module. When this is used as a global-option,
it is applied to all modules that this script builds. <emphasis>This option
@@ -194,7 +205,7 @@ CMAKE_BUILD_TYPE option to "none" when configuring the module. This can be done
<row id="conf-dest-dir">
<entry>dest-dir</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry>Use this option to change the name a module is given on disk. For
example, if your module was extragear/network, you could rename it to
extragear-network using this option. Note that although this changes the
@@ -219,7 +230,7 @@ for every module. You can disable this check by setting
<row id="conf-do-not-compile">
<entry>do-not-compile</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry><para>Use this option to select a specific set of directories not to be built in a
module (instead of all of them). The directories not to build should be space-separated.</para>
@@ -265,9 +276,9 @@ is usually not what you want.
</entry>
</row>
-<row id="conf-inst-apps">
+<row>
<entry>inst-apps</entry>
-<entry>Overrides global</entry>
+<entry></entry>
<entry>
This option was removed in version 1.10
</entry>
@@ -275,7 +286,7 @@ This option was removed in version 1.10
<row id="conf-install-after-build">
<entry>install-after-build</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry>This option is used to install the package after it successfully builds.
This option is enabled by default. If you want to disable this, you need to set
this option to <replaceable>false</replaceable> in the <link
@@ -287,7 +298,7 @@ flag.
<row id="conf-kdedir">
<entry>kdedir</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry>This option sets the directory that &kde; will be installed to after it
is built. It defaults to <filename class="directory">~/kde</filename>. If you
change this to a directory needing root access, you may want to read about the
@@ -321,7 +332,7 @@ something like: <userinput><option>kde-languages</option>
<row id="conf-libpath">
<entry>libpath</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry>Set this option to set the environment variable
<envar>LD_LIBRARY_PATH</envar> while building. You cannot override this setting
in a module option. The default value is blank, but the paths <filename
@@ -333,7 +344,7 @@ You may use the tilde (~) for any paths you add using this option.
<row id="conf-log-dir">
<entry>log-dir</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry>Use this option to change the directory used to hold the log files
generated by the script.
</entry>
@@ -341,7 +352,7 @@ generated by the script.
<row id="conf-make-install-prefix">
<entry>make-install-prefix</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry>Set this variable to a space-separated list, which is interpreted as a
command and its options to precede the <userinput><command>make</command> <option>install</option></userinput> command used to install
modules. This is useful for installing packages with &sudo; for example, but
@@ -350,7 +361,7 @@ please be careful while dealing with root privileges.</entry>
<row id="conf-make-options">
<entry>make-options</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry>Set this variable in order to pass command line options to the
<command>make</command> command. This is useful for programs such as <ulink
url="http://distcc.samba.org/"><application>distcc</application></ulink> or
@@ -360,7 +371,7 @@ systems with more than one processor core.
<row id="conf-manual-build">
<entry>manual-build</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry>Set the option value to <replaceable>true</replaceable> to keep the
build process from attempting to build this module. It will still be kept
up-to-date when updating from &subversion;. This option is exactly equivalent
@@ -371,7 +382,7 @@ command line option.
<row id="conf-manual-update">
<entry>manual-update</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry>Set the option value to <replaceable>true</replaceable> to keep the
build process from attempting to update (and by extension, build or install)
this module. If you set this option for a module, then you have essentially
@@ -381,7 +392,7 @@ commented it out.
<row id="conf-module-base-path">
<entry>module-base-path</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry><para>Set this option to override &kdesrc-build;'s default directory path to the
module in question. This can be used, for example, to pull specific branches
or tagged versions of libraries. <ulink url="http://websvn.kde.org/">The &kde;
@@ -414,22 +425,22 @@ number, the "nicer" the program is. The default is 10.
<row id="conf-no-svn">
<entry>no-svn</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry>If this option is set to true then &kdesrc-build; will not update the
source code for the module automatically. It will still try to build the
module if it normally would have tried anyways.</entry>
</row>
-<row id="conf-no-rebuild-on-fail">
+<row>
<entry>no-rebuild-on-fail</entry>
-<entry>Overrides global</entry>
+<entry></entry>
<entry>This option was removed in version 1.10, since this behavior no longer helps
due to fixes in the underlying build system.</entry>
</row>
<row id="conf-override-url">
<entry>override-url</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry>If you set this option, &kdesrc-build; will use its value as the &url;
to pass to &subversion; <emphasis>completely unchanged</emphasis>. You should
generally use this if you want to download a specific release but &kdesrc-build;
@@ -439,7 +450,7 @@ cannot figure out what you mean using <link linkend="conf-branch">branch</link>.
<row id="conf-prefix">
<entry>prefix</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry>This option controls where to install the module (normally the
<option><link linkend="conf-kdedir">kdedir</link></option> setting is used).
Using this option allows you to install a module to a different directory than
@@ -450,7 +461,7 @@ where the KDE Platform libraries are installed, such as if you were using
<row id="conf-purge-old-logs">
<entry>purge-old-logs</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry><para>This option controls whether old log directories are automatically
deleted or not. The default value is <replaceable>false</replaceable>.</para>
@@ -467,7 +478,7 @@ to be kdelibs.</para>
<row id="conf-qtdir">
<entry>qtdir</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry>Set this option to set the environment variable <envar>QTDIR</envar> while building.
You cannot override this setting in a module option. If you do not specify
this option, it defaults to
@@ -479,7 +490,7 @@ You may use a tilde (~) to represent your home directory.
<row id="conf-remove-after-install">
<entry>remove-after-install</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry><para>If you are low on hard disk space, you may want to use this option
in order to automatically delete the build directory (or both the source and
build directories for one-time installs) after the module is successfully
@@ -501,7 +512,7 @@ since &kdesrc-build; will be unable to perform incremental builds.</para>
<row id="conf-repository">
<entry>repository</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry><para>This option was introduced with version 1.10, and is used to
specify the &git; repository to download the source code for the module.
&Qt; (and therefore qt-copy) would need this option, as well as various
@@ -510,7 +521,7 @@ specify the &git; repository to download the source code for the module.
<row id="conf-revision">
<entry>revision</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry>If this option is set to a value other than 0 (zero), &kdesrc-build;
will force the &subversion; update to bring the module to the exact revision
given, even if options like <link linkend="conf-branch">branch</link> are in
@@ -521,7 +532,7 @@ configuration.</entry>
<row id="conf-run-tests">
<entry>run-tests</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry>If set to <replaceable>true</replaceable>, then the module will be
built with support for running its test suite, and the test suite will be
executed as part of the build process. &kdesrc-build; will show a simple
@@ -531,7 +542,7 @@ to ensure their system is setup correctly.</entry>
<row id="conf-set-env">
<entry>set-env</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry><para>This option accepts a space-separated set of values, where the first value
is the environment variable to set, and the rest of the values is what you
want the variable set to. For example, to set the variable <envar>RONALD</envar> to
@@ -546,7 +557,7 @@ globally).</para>
<row id="conf-source-dir">
<entry>source-dir</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry>This option is used to set the directory on your computer to store the &kde;
&subversion; sources at. If you do not specify this value, the default is
<filename class="directory">~/kdesrc</filename>. You may use the tilde (~)
@@ -556,7 +567,7 @@ to represent the home directory if using this option.
<row id="conf-stop-on-failure">
<entry>stop-on-failure</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry>Set this option value to <replaceable>true</replaceable> to cause the script to stop execution
after an error occurs during the build or install process. This option is off
by default.
@@ -565,7 +576,7 @@ by default.
<row id="conf-svn-server">
<entry>svn-server</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry><para>This option is used to set the server used to check out from &subversion;.
The default is the anonymous &subversion; repository, <filename>svn://anonsvn.kde.org/</filename></para>
<note><para>If you are developing for KDE, use the &subversion; repository that
@@ -576,7 +587,7 @@ anonymous repository.</para></note>
<row id="conf-tag">
<entry>tag</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry><para>Use this option to download a specific release of a module.</para>
<para><emphasis>Note:</emphasis> The odds are very good that you <emphasis>do not
want</emphasis> to use this option. &kde; releases are available in tarball form
@@ -585,9 +596,9 @@ url="http://download.kde.org/download.php">its mirrors</ulink>.</para>
</entry>
</row>
-<row id="conf-use-cmake">
+<row>
<entry>use-cmake</entry>
-<entry>Overrides global</entry>
+<entry></entry>
<entry>This option was removed in &kdesrc-build; 1.4 as all &kde; 4 modules
require &cmake;, and &cmake; use is not permitted on any other modules.
</entry>
@@ -606,15 +617,15 @@ the lower disk priority set this to <replaceable>true</replaceable>.
<row id="conf-use-qt-builddir-hack">
<entry>use-qt-builddir-hack</entry>
-<entry>Overrides global</entry>
+<entry>Module setting overrides global</entry>
<entry>This option has been removed due to improvements in the &Qt; build
system.
</entry>
</row>
-<row id="conf-use-stable-kde">
+<row>
<entry>use-stable-kde</entry>
-<entry>Cannot be overridden</entry>
+<entry></entry>
<entry><para>
This option was removed in version 1.10, which limits support to KDE 4,
removing the effect of this option.
diff --git a/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook b/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook
index fdfea54a..33fe1c66 100644
--- a/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook
+++ b/doc/kdesrc-buildrc/kdesrc-buildrc-overview.docbook
@@ -37,39 +37,23 @@ add to global options, and some global options simply cannot be overridden.
</para>
<para>
-The following is an alphabetized list of options you can use. Click on the
-option to find out more about it. If one is not documented, please e-mail the
-authors using the address you can find <link linkend="authors">above</link>.
+The following is a list of commonly-used options. Click on the
+option to find out more about it. To see the full list of options, see
+<xref linkend="conf-options-table"/>.
</para>
<itemizedlist>
-<listitem><para><link linkend="conf-async">async</link>, to update and build at the same time.</para></listitem>
-<listitem><para><link linkend="conf-binpath">binpath</link>, to set the <envar>PATH</envar> variable.</para></listitem>
<listitem><para><link linkend="conf-branch">branch</link>, to checkout from a branch instead of /trunk.</para></listitem>
<listitem><para><link linkend="conf-build-dir">build-dir</link>, to set the directory to build in.</para></listitem>
-<listitem><para><link linkend="conf-checkout-only">checkout-only</link>, to checkout only parts of a module.</para></listitem>
<listitem><para><link linkend="conf-cmake-options">cmake-options</link> to define what flags to configure a module with using &cmake;.</para></listitem>
-<listitem><para><link linkend="conf-colorful-output">colorful-output</link> to add color to the script output.</para></listitem>
<listitem><para><link linkend="conf-configure-flags">configure-flags</link> to define what flags to configure a module with.</para></listitem>
<listitem><para><link linkend="conf-cxxflags">cxxflags</link> to define the <envar>CXXFLAGS</envar> variable.</para></listitem>
-<listitem><para><link linkend="conf-dest-dir">dest-dir</link> to change the directory name for a module.</para></listitem>
-<listitem><para><link linkend="conf-disable-agent-check">disable-agent-check</link>, to keep &kdesrc-build; from checking on ssh-agent's status.</para></listitem>
-<listitem><para><link linkend="conf-do-not-compile">do-not-compile</link>, to mark directories to skip building.</para></listitem>
-<listitem><para><link linkend="conf-install-after-build">install-after-build</link>, to avoid installing after the build process.</para></listitem>
<listitem><para><link linkend="conf-kdedir">kdedir</link>, to set the directory to install &kde; to.</para></listitem>
<listitem><para><link linkend="conf-kde-languages">kde-languages</link>, to set the translation packages to download and install.</para></listitem>
-<listitem><para><link linkend="conf-libpath">libpath</link>, to set the <envar>LD_LIBRARY_PATH</envar> variable.</para></listitem>
-<listitem><para><link linkend="conf-make-install-prefix">make-install-prefix</link>, to run a helper program (like &sudo;) during <userinput><command>make</command> <option>install</option></userinput>.</para></listitem>
<listitem><para><link linkend="conf-make-options">make-options</link>, to pass options to the &make; program.</para></listitem>
-<listitem><para><link linkend="conf-manual-build">manual-build</link>, to avoid building the module automatically.</para></listitem>
-<listitem><para><link linkend="conf-manual-update">manual-update</link>, to avoid doing anything to the module automatically.</para></listitem>
-<listitem><para><link linkend="conf-module-base-path">module-base-path</link>, to change where to download the module from (useful for branches and tags).</para></listitem>
-<listitem><para><link linkend="conf-niceness">niceness</link>, to change the CPU priority.</para></listitem>
-<listitem><para><link linkend="conf-no-rebuild-on-fail">no-rebuild-on-fail</link>, to avoid running &make; again if it fails.</para></listitem>
<listitem><para><link linkend="conf-qtdir">qtdir</link>, to set the path to &Qt;.</para></listitem>
<listitem><para><link linkend="conf-set-env">set-env</link>, to set an environment variable.</para></listitem>
<listitem><para><link linkend="conf-source-dir">source-dir</link>, to change where to download the source code to.</para></listitem>
-<listitem><para><link linkend="conf-stop-on-failure">stop-on-failure</link>, to make &kdesrc-build; stop as soon as a failure is encountered.</para></listitem>
<listitem><para><link linkend="conf-svn-server">svn-server</link>, to change the server the sources are downloaded from.</para></listitem>
</itemizedlist>
More information about the kde-doc-english
mailing list