[sdk/kde-builder] /: Add documentation
Andrew Shark
null at kde.org
Sun Feb 25 20:12:00 GMT 2024
Git commit ea8bc1668d7e81dd1c96e7cb4ef357f917bdb0a7 by Andrew Shark.
Committed on 25/02/2024 at 20:09.
Pushed by ashark into branch 'master'.
Add documentation
A +139 -0 doc/README.md
A +420 -0 doc/advanced-features.docbook
A +131 -0 doc/appendix-modules.docbook
A +167 -0 doc/appendix-profile.docbook
A +204 -0 doc/basic-features.docbook
A +139 -0 doc/building-and-troubleshooting.docbook
A +62 -0 doc/building-specific-modules.docbook
A +117 -0 doc/cmdline.docbook
A +1482 -0 doc/conf-options-table.docbook [INFRASTRUCTURE]
A +110 -0 doc/configure-data.docbook
A +7 -0 doc/credits-and-license.docbook
A +33 -0 doc/developer-features.docbook
A +127 -0 doc/environment.docbook
A +185 -0 doc/features.docbook
A +223 -0 doc/getting-started.docbook
A +173 -0 doc/index.docbook
A +22 -0 doc/intro-toc.docbook
A +67 -0 doc/introduction.docbook
A +29 -0 doc/kde-cmake.docbook
A +353 -0 doc/kde-modules-and-selection.docbook
A +78 -0 doc/kdesrc-build-logging.docbook
A +101 -0 doc/kdesrc-build.desktop
A +261 -0 doc/kdesrc-buildrc.docbook
A +1282 -0 doc/man-kdesrc-build.1.docbook
A +175 -0 doc/other-features.docbook
A +17 -0 doc/quick-start-conclusion.docbook
A +243 -0 doc/source-reference/IPC-notes.md
A +81 -0 doc/source-reference/Internals.md
A +216 -0 doc/source-reference/Module.md
A +158 -0 doc/source-reference/index.md
A +668 -0 doc/supported-cmdline-params.docbook
A +10 -0 doc/supported-envvars.docbook
A +30 -0 doc/using-kdesrc-build.docbook
A +105 -0 scripts/build-docs
https://invent.kde.org/sdk/kde-builder/-/commit/ea8bc1668d7e81dd1c96e7cb4ef357f917bdb0a7
diff --git a/doc/README.md b/doc/README.md
new file mode 100644
index 00000000..9d51bc55
--- /dev/null
+++ b/doc/README.md
@@ -0,0 +1,139 @@
+# kdesrc-build Documentation
+
+If you're reading this, it's probably from Gitlab. Welcome!
+
+The documentation in this directory is split into two major categories:
+
+1. Documentation for end users.
+2. Documentation for kdesrc-build developers.
+
+## End User Documentation
+
+This documentation is not in *great* shape, but does exist. These docs are
+contained completely within index.docbook using the KDE DocBook XML
+documentation standards.
+
+Most users access these docs at
+[docs.kde.org](https://docs.kde.org/trunk5/en/kdesrc-build/kdesrc-build/), and
+kdesrc-build itself will show URLs to specific portions of this documentation
+if you run `kdesrc-build --help`, one pointing to the [table of configuration
+options](https://docs.kde.org/trunk5/en/kdesrc-build/kdesrc-build/conf-options-table.html)
+and the other to the [list of command-line
+options](https://docs.kde.org/trunk5/en/kdesrc-build/kdesrc-build/cmdline.html).
+
+To build these docs locally for testing, use the `build-docs` shell script here
+in the doc/ directory (requires that you've already installed kdoctools
+framework!), which will symlink the base KDE DocBook theme into the doc/
+directory and generate multiple HTML files from the index.docbook.
+
+### Man page
+
+There is also a man page, also authored in Docbook, at
+`man-kdesrc-build.1.docbook`. It will
+be built and installed to the KDE-specific `MANPATH` if you build kdesrc-build
+with CMake. The content is mostly the same as in the normal DocBook docs but
+can be more convenient at the command line, especially if Internet access is
+not available.
+
+## Documentation for kdesrc-build developers
+
+Documentation for kdesrc-build itself is mostly within the source files, but I've put
+scattered attempts together over time trying to improve that.
+
+Older bits of documentation can be found in source-reference directory.
+
+## kdesrc-build Tricks
+
+These are some kdesrc-build tricks that probably should be documented with the
+[KDE Community Wiki page](https://community.kde.org/Get_Involved/development#Set_up_kdesrc-build)
+but for now they're at least worth nothing here:
+
+- Use `kdesrc-build --rebuild-failures` (potentially with `--no-src`) to
+ rebuild modules that failed to build during the last kdesrc-build run. This
+ is particularly useful when a silly local error breaks an important module
+ and several dozen dependent modules.
+
+- Use the `--no-stop-on-failure` command-line option (or
+ the corresponding configuration file option) to make kdesrc-build not abort
+ after the first module fails to build.
+
+- Either way if you're running kdesrc-build frequently as part of a
+ debug/build/debug cycle, don't forget to throw `--no-src` on the command line
+ as appropriate. If the build failed halfway through it is likely that all
+ source updates completed, even for modules kdesrc-build didn't try to build.
+
+- It is possible to build many module types that are not official KDE projects.
+ This may be needed for upstream dependencies or simply because you only need
+ a module to support your KDE-based workspace or application.
+
+- There are many ways to have kdesrc-build find the right configuration. If you
+ have only a single configuration you want then a ~/.kdesrc-buildrc might be
+ the right call. If you want to support multiple configurations, then you can
+ create multiple directories and have a file "kdesrc-buildrc" in each
+ directory, which kdesrc-build will find if you run the script from that
+ directory.
+
+- Don't forget to have kdesrc-build update itself from git!
+
+- You can use the 'branch' and 'tag' options to kdesrc-build to manually choose
+ the proper git branch or tag to build. With KDE modules you should not
+ normally need this. If even these options are not specific enough, then
+ consider the 'revision' option, or manage the source code manually and use
+ `--no-src` for that module.
+
+- You can refer to option values that have been previously set in your
+ kdesrc-build configuration file, by using the syntax ${option-name}. There's
+ no need for the option to be recognized by kdesrc-build, so you can set
+ user-specific variables this way.
+
+- Low on disk space? Use the `remove-after-install` option to clean out
+ unneeded directories after your build, just don't be surprised when compile
+ times go up.
+
+- Need help setting up environment variables to run your shiny new desktop?
+ kdesrc-build offers a sample ~/.xsession setup (which is supported by many
+ login managers), which can be used by enabling the `install-session-driver`
+ option.
+
+- For KDE-based modules, kdesrc-build can install a module and all of its
+ dependencies, by using the `--include-dependencies` command line option.
+ You can also use `--no-include-dependencies` if you just want to build
+ a single module this time.
+
+- Use `--resume-from` (or `--resume-after`) to have kdesrc-build start the
+ build from a later module than normal, and `--stop-before` (or
+ `--stop-after`) to have kdesrc-build stop the build at an earlier module than
+ normal.
+
+- Use the `ignore-modules` option with your module sets if you want to build
+ every module in the set *except* for a few specific ones.
+
+- Annoyed by the default directory layout? Consider changing the `directory-layout`
+ configuration file option.
+
+- kdesrc-build supports building from behind a proxy, for all you corporate
+ types trying to get the latest-and-greatest desktop. Just make sure your
+ compilation toolchain is up to the challenge....
+
+- You can use the `custom-build-command` option to setup a custom build tool
+ (assumed to be make-compatible). For instance, cmake supports the `ninja`
+ tool, and kdesrc-build can use `ninja` as well via this option.
+
+- You can also wrap kdesrc-build itself in a script if you want to do things
+like unusual pre-build setup, post-install cleanup, etc. This also goes well
+with the [`--query`][query] option.
+
+### Troubleshooting
+
+- Is `build-when-unchanged` disabled? Did you try building from a clean build
+ directory? If your answer to either is "No" then try using `--refresh-build`
+ with your next kdesrc-build run to force a clean build directory to be used.
+
+- If you've been running a kdesrc-build-based install for a long time then it
+ may be time to clean out the installation directory as well, especially if
+ you don't use the [use-clean-install][] option to run `make uninstall` as
+ part of the install process. There's no kdesrc-build option to blow up your
+ installation prefix, but it's not hard to do yourself...
+
+[use-clean-install]: https://docs.kde.org/trunk5/en/kdesrc-build/kdesrc-build/conf-options-table.html#conf-use-clean-install
+[query]: https://docs.kde.org/trunk5/en/kdesrc-build/kdesrc-build/supported-cmdline-params.html#cmdline-query
diff --git a/doc/advanced-features.docbook b/doc/advanced-features.docbook
new file mode 100644
index 00000000..edb19da7
--- /dev/null
+++ b/doc/advanced-features.docbook
@@ -0,0 +1,420 @@
+<sect1 id="advanced-features">
+<title>Advanced features</title>
+
+<sect2 id="partial-builds">
+<title>Partially building a module</title>
+<para>It is possible to build only pieces from a single &kde; module. For
+example, you may want to compile only one program from a module. &kdesrc-build;
+has features to make this easy. There are several complementing ways to
+do this.
+</para>
+
+<sect3 id="not-compiling">
+<title>Removing directories from a build</title>
+<para>It is possible to download an entire repository
+but have the build system leave out a few directories when it does
+the build. This requires that the module uses &cmake; and that the
+module's build system allows the directory to remove to be
+optional.
+</para>
+
+<para>This is controlled with the &do-not-compile; option.</para>
+
+<important><para>
+This option requires at least that the
+build system for the module is reconfigured after changing
+it. This is done using the <userinput><command>kdesrc-build</command>
+<option>&cmd-reconfigure;</option>
+<option><replaceable>module</replaceable></option></userinput> command.
+</para></important>
+
+<informalexample>
+<para>To remove the <filename class="directory">python</filename> directory
+from the kdebindings build process:</para>
+
+<screen>
+module <replaceable>kdebindings</replaceable>
+ &do-not-compile; <replaceable>python</replaceable>
+end module
+</screen>
+
+</informalexample>
+
+<note><para>This function depends on some standard conventions used in most
+&kde; modules. Therefore it may not work for all programs.</para></note>
+
+</sect3>
+
+</sect2>
+
+<sect2 id="using-branches">
+<title>Branching and tagging support for &kdesrc-build;</title>
+
+<sect3 id="branches-and-tags">
+<title>What are branches and tags?</title>
+
+<para>&git; supports managing the history of the &kde; source code. &kde;
+uses this support to create branches for development, and to tag the repository
+every so often with a new version release.
+</para>
+
+<para>For example, the &kmail; developers may be working on a new feature in
+a different branch in order to avoid breaking the version being used by most
+developers. This branch has development ongoing inside it, even while the
+main branch (called master) may have development going on inside of it.
+</para>
+
+<para>A tag, on the other hand, is a specified point in the source code repository
+at a position in time. This is used by the &kde; administration team to mark
+off a version of code suitable for release and still allow the developers to
+work on the code.
+</para>
+
+</sect3>
+
+<sect3 id="branch-support">
+<title>How to use branches and tags</title>
+
+<para>Support for branches and tags is handled by a set of options, which
+range from a generic request for a version, to a specific &url; to download
+for advanced users.
+</para>
+
+<para>The easiest method is to use the &branch; and &tag; options. You simply
+use the option along with the name of the desired branch or tag for a module,
+and &kdesrc-build; will try to determine the appropriate location within the
+&kde; repository to download from. For most &kde; modules this works very
+well.</para>
+
+<informalexample>
+<para>To download kdelibs from &kde; 4.6 (which is simply known as the 4.6 branch):
+</para>
+
+<screen>
+module kdelibs
+ branch <replaceable>4.6</replaceable>
+ # other options...
+end module
+</screen>
+
+<para>Or, to download kdemultimedia as it was released with &kde; 4.6.1:</para>
+
+<screen>
+module kdemultimedia
+ tag <replaceable>4.6.1</replaceable>
+ # other options...
+end module
+</screen>
+
+</informalexample>
+
+<tip><para>You can specify a global branch value. But if you do so, do not forget
+to specify a different branch for modules that should not use the global branch!
+</para></tip>
+</sect3>
+
+</sect2>
+
+<sect2 id="stopping-the-build-early">
+<title>Stopping the build early</title>
+
+<sect3 id="the-build-continues">
+<title>The build normally continues even if failures occur</title>
+
+<para>&kdesrc-build; normally will update, build and install all modules
+in the specified list of modules to build, even if a module fails to build.
+This is usually a convenience to allow you to update software packages even
+if a simple mistake is made in one of the source repositories during
+development that causes the build to break.
+</para>
+
+<para>
+However you may wish for &kdesrc-build; to stop what it is doing once a
+module fails to build and install. This can help save you time that will be
+wasted trying to make progress when modules remaining in the build list will
+not be able to successfully build either, especially if you have not ever
+successfully built the modules in the list.
+</para>
+
+</sect3>
+
+<sect3 id="stop-on-failure-stops-early">
+<title>Not stopping early with --no-stop-on-failure</title>
+
+<para>
+The primary method to do this is to use the
+<link linkend="cmdline-stop-on-failure">--no-stop-on-failure</link>
+command line option when you run &kdesrc-build;.
+</para>
+
+<para>This option can also be set in the
+<link linkend="conf-stop-on-failure">configuration file</link> to make
+it the normal mode of operation.
+</para>
+
+<para>It is also possible to tell &kdesrc-build; at runtime to stop building
+<emphasis>after</emphasis> completing the current module it is working on.
+This is as opposed to interrupting &kdesrc-build; using a command like
+<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>, which interrupts
+&kdesrc-build; immediately, losing the progress of the current module.
+</para>
+
+<important><para>Interrupting &kdesrc-build; during a module install when
+the <link linkend="conf-use-clean-install">use-clean-install</link> option
+is enabled will mean that the interrupted module will be unavailable until
+&kdesrc-build; is able to successfully build the module!</para>
+
+<para>If you need to interrupt &kdesrc-build; without permitting a graceful shutdown
+in this situation, at least try to avoid doing this while &kdesrc-build; is
+installing a module.</para>
+</important>
+
+</sect3>
+
+<sect3 id="stopping-early-without-stop-on-failure">
+<title>Stopping &kdesrc-build; gracefully when stop-on-failure is false</title>
+
+<para>As mentioned above, it is possible to cause &kdesrc-build; to gracefully
+shutdown early once it has completed the module it is currently working on.
+To do this, you need to send the POSIX <literal>HUP</literal> signal to &kdesrc-build;
+</para>
+
+<para>You can do this with a command such as <command>pkill</command> (on &Linux; systems) as follows:</para>
+
+<programlisting>
+<prompt>$ </prompt><userinput><command>pkill <option>-HUP</option> kdesrc-build</command></userinput>
+</programlisting>
+
+<para>If done successfully, you will see a message in the &kdesrc-build; output similar
+to:</para>
+
+<programlisting>
+[ build ] recv SIGHUP, will end after this module
+</programlisting>
+
+<note>
+<para>&kdesrc-build; may show this message multiple times depending on the
+number of individual &kdesrc-build; processes that are active. This is
+normal and not an indication of an error.</para>
+</note>
+
+<para>
+Once &kdesrc-build; has acknowledged the signal, it will stop processing
+after the current module is built and installed. If &kdesrc-build; is still
+updating source code when the request is received, &kdesrc-build; will stop
+after the module source code update is complete. Once both the update and build
+processes have stopped early, &kdesrc-build; will print its partial results
+and exit.
+</para>
+
+</sect3>
+
+</sect2>
+
+<sect2 id="building-successfully">
+<title>How &kdesrc-build; tries to ensure a successful build</title>
+
+<sect3 id="automatic-rebuilds">
+<title>Automatic rebuilds</title>
+
+<para>&kdesrc-build; used to include features to automatically attempt to
+rebuild the module after a failure (as sometimes this re-attempt would work,
+due to bugs in the build system at that time). Thanks to switching to &cmake;
+the build system no longer suffers from these bugs, and so &kdesrc-build; will
+not try to build a module more than once. There are situations where
+&kdesrc-build; will automatically take action though:</para>
+
+<itemizedlist>
+
+<listitem><para>If you change <link linkend="conf-configure-flags">configure-flags</link>
+or <link linkend="conf-cmake-options">cmake-options</link> for a module, then
+&kdesrc-build; will detect that and automatically re-run configure or cmake
+for that module.</para></listitem>
+
+<listitem><para>If the buildsystem does not exist (even if &kdesrc-build; did
+not delete it) then &kdesrc-build; will automatically re-create it. This is
+useful to allow for performing a full <link
+linkend="cmdline-refresh-build">--refresh-build</link> for a specific module
+without having that performed on other modules.</para></listitem>
+
+</itemizedlist>
+
+</sect3>
+
+<sect3 id="manual-rebuilds">
+<title>Manually rebuilding a module</title>
+<para>If you make a change to a module's option settings, or the module's
+source code changes in a way &kdesrc-build; does not recognize, you may need to
+manually rebuild the module.</para>
+
+<para>You can do this by simply running <userinput><command>kdesrc-build</command>
+ <option>--refresh-build</option> <option><replaceable>module</replaceable></option></userinput>.
+</para>
+
+<para>If you would like to have &kdesrc-build; automatically rebuild the module
+during the next normal build update instead, you can create a special file.
+Every module has a build directory. If you create a file called <filename>.refresh-me</filename>
+in the build directory for a module, &kdesrc-build; will rebuild the module
+next time the build process occurs, even if it would normally perform the
+faster incremental build.</para>
+
+<tip>
+<para>By default, the build directory is <filename class="directory">~/kde/build/<replaceable>module</replaceable>/</filename>.
+If you change the setting of the &build-dir; option, then use that instead of
+<filename class="directory">~/kde/build</filename>.</para>
+</tip>
+
+<informalexample>
+<para>Rebuild using <filename>.refresh-me</filename> for module <replaceable>kdelibs</replaceable>:</para>
+<screen>
+<prompt>%</prompt> <userinput><command>touch</command> <filename>~/kdesrc/build/<replaceable>kdelibs</replaceable>/.refresh-me</filename></userinput>
+<prompt>%</prompt> <userinput><command>kdesrc-build</command></userinput>
+</screen>
+</informalexample>
+</sect3>
+
+</sect2>
+
+<sect2 id="changing-environment">
+<title>Changing environment variable settings</title>
+<para>Normally &kdesrc-build; uses the environment that is present when
+starting up when running programs to perform updates and builds. This is useful
+for when you are running &kdesrc-build; from the command line.</para>
+
+<para>However, you may want to change the setting for environment variables
+that &kdesrc-build; does not provide an option for directly. (For instance,
+to setup any required environment variables when running &kdesrc-build; on
+a timer such as &cron;) This is possible with the &set-env; option.</para>
+
+<para>Unlike most options, it can be set more than once, and it accepts two
+entries, separated by a space. The first one is the name of the environment
+variable to set, and the remainder of the line is the value.</para>
+
+<informalexample>
+<para>Set <userinput><envar>DISTRO</envar>=<replaceable>BSD</replaceable></userinput>
+for all modules:</para>
+<screen>
+global
+ set-env <replaceable>DISTRO</replaceable> <replaceable>BSD</replaceable>
+end global
+</screen>
+</informalexample>
+
+</sect2>
+
+<sect2 id="resuming">
+<title>Resuming builds</title>
+
+<sect3 id="resuming-failed">
+<title>Resuming a failed or canceled build</title>
+
+<para>You can tell &kdesrc-build; to start building from a different module
+than it normally would. This can be useful when a set of modules failed, or
+if you canceled a build run in the middle. You can control this using the
+&cmd-resume-from; option and the &cmd-resume-after; option.</para>
+
+<note><para>Older versions of &kdesrc-build; would skip the source update when
+resuming a build. This is no longer done by default, but you can always use
+the <option>--no-src</option> command line option
+to skip the source update.</para></note>
+
+<informalexample>
+<para>Resuming the build starting from kdebase:</para>
+
+<screen>
+<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--resume-from=<replaceable>kdebase</replaceable></option></userinput>
+</screen>
+</informalexample>
+
+<informalexample>
+<para>Resuming the build starting after kdebase (in case you manually fixed
+the issue and installed the module yourself):</para>
+
+<screen>
+<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--resume-after=<replaceable>kdebase</replaceable></option></userinput>
+</screen>
+</informalexample>
+
+<para>If the last &kdesrc-build; build ended with a build failure, you can also
+use the <link linkend="cmdline-resume">--resume</link> command line option,
+which resumes the last build starting at the module that failed. The source and
+metadata updates are skipped as well (but if you need these, it's generally
+better to use <link linkend="cmdline-resume-from">--resume-from</link>
+instead).</para>
+
+
+</sect3>
+
+<sect3 id="ignoring-modules">
+<title>Ignoring modules in a build</title>
+
+<para>Similar to the way you can <link linkend="resuming-failed">resume the
+build from a module</link>, you can instead choose to update and build everything
+normally, but ignore a set of modules.</para>
+
+<para>You can do this using the &cmd-ignore-modules; option. This option tells
+&kdesrc-build; to ignore all the modules on the command line when
+performing the update and build.</para>
+
+<informalexample>
+<para>Ignoring extragear/multimedia and kdereview during a full run:</para>
+<screen>
+<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--ignore-modules</option> <replaceable>extragear/multimedia kdereview</replaceable></userinput>
+</screen>
+</informalexample>
+
+</sect3>
+</sect2>
+
+<sect2 id="changing-env-from-cmd-line">
+<title>Changing options from the command line</title>
+
+<sect3 id="changing-global-opts">
+<title>Changing global options</title>
+<para>You can change the setting of options read from the <link linkend="configure-data">configuration file</link> directly
+from the command line. This change will override the configuration file
+setting, but is only temporary. It only takes effect as long as it is still
+present on the command line.</para>
+
+<para>&kdesrc-build; allows you to change options named like <replaceable>option-name</replaceable>
+by passing an argument on the command line in the form <userinput><option>--<replaceable>option-name</replaceable>=value</option></userinput>.
+&kdesrc-build; will recognize whether it does not know what the option is, and search
+for the name in its list of option names. If it does not recognize the name, it
+will warn you, otherwise it will remember the value you set it to and override
+any setting from the configuration file.</para>
+
+<informalexample>
+<para>Setting the &source-dir; option to <filename>/dev/null</filename> for
+testing:</para>
+
+<screen>
+<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--pretend</option> <option>--<replaceable>source-dir</replaceable>=<replaceable>/dev/null</replaceable></option></userinput>
+</screen>
+
+</informalexample>
+
+</sect3>
+
+<sect3 id="changing-module-opts">
+<title>Changing module options</title>
+<para>It is also possible to change options only for a specific module. The
+syntax is similar: --<replaceable>module</replaceable>,<replaceable>option-name</replaceable>=<replaceable>value</replaceable>.
+</para>
+
+<para>This change overrides any duplicate setting for the module found in the
+<link linkend="configure-data">configuration file</link>, and applies only while the option is passed on the command line.</para>
+
+<informalexample>
+<para>Using a different build directory for the kdeedu module:</para>
+
+<screen>
+<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--<replaceable>kdeedu</replaceable>,<replaceable>build-dir</replaceable>=<replaceable>temp-build</replaceable></option></userinput>
+</screen>
+
+</informalexample>
+
+</sect3>
+
+</sect2>
+
+</sect1>
diff --git a/doc/appendix-modules.docbook b/doc/appendix-modules.docbook
new file mode 100644
index 00000000..109f2daf
--- /dev/null
+++ b/doc/appendix-modules.docbook
@@ -0,0 +1,131 @@
+<appendix id="appendix-modules">
+<title>&kde; modules and source code organization</title>
+<sect1 id="module-concept">
+<title>The <quote>Module</quote></title>
+
+<para>&kde; groups its software into <quote>modules</quote> of various size.
+This was initially a loose grouping of a few large modules, but with the
+introduction of the <ulink url="https://git-scm.com/">Git</ulink>-based <ulink
+url="https://commits.kde.org/">source code repositories</ulink>, these large
+modules were further split into many smaller modules.
+</para>
+
+<para>&kdesrc-build; uses this module concept as well. In essence, a
+<quote>module</quote> is a grouping of code that can be downloaded, built,
+tested, and installed.
+</para>
+
+<sect2 id="single-modules">
+<title>Individual modules</title>
+
+<para>It is easy to set &kdesrc-build; to build a single module. The following
+listing is an example of what a declaration for a Git-based module would
+look like in <link linkend="kdesrc-buildrc">the configuration
+file</link>.</para>
+
+<programlisting>
+module <replaceable>kdefoo</replaceable>
+ <option><replaceable>cmake-options -DCMAKE_BUILD_TYPE=Debug</replaceable></option>
+end module
+</programlisting>
+
+<tip><para>This is a Git-based module since it doesn't use a <link
+linkend="conf-repository">repository</link> option. Also, the
+<option>cmake-options</option> option is listed as an example only, it is not
+required.</para></tip>
+
+</sect2>
+<sect2 id="module-groups">
+<title>Groups of related modules</title>
+
+<para>Now most &kde; source modules are Git-based &kde;, and are normally
+combined into groups of modules.</para>
+
+<para>&kdesrc-build; therefore supports groups of modules as well, using
+<link linkend="module-sets">module sets</link>. An example:</para>
+
+<programlisting>
+module-set <replaceable>base-modules</replaceable>
+ <option>repository</option> kde-projects
+ <option>use-modules</option> <replaceable>kde-runtime kde-workspace kde-baseapps</replaceable>
+end module-set
+</programlisting>
+
+<tip><para>You can leave the module set name (<replaceable>base-modules</replaceable>
+in this case) empty if you like. This <option>repository</option> setting tells
+&kdesrc-build; where to download the source from, but you can also use a
+<symbol>git://</symbol> URL.</para></tip>
+
+<para>One special feature of the <quote><option>repository</option>
+<literal>kde-projects</literal></quote> is that &kdesrc-build; will
+automatically include any Git modules that are grouped under the modules you
+list (in the KDE Project database).</para>
+</sect2>
+
+<sect2 id="module-branch-groups">
+<title>Module <quote>branch groups</quote></title>
+
+<para>Taking the concept of a <link linkend="module-groups">group of
+modules</link> further, the &kde; developers eventually found that
+synchronizing the names of the Git branches across a large number of
+repositories was getting difficult, especially during the development push for
+the new &kde; Frameworks for &Qt; 5.
+</para>
+
+<para>So the concept of <quote>branch groups</quote> was developed, to allow
+users and developers to select one of only a few groups, and allow the script
+to automatically select the appropriate Git branch.
+</para>
+
+<para>&kdesrc-build; supports this feature as of version 1.16-pre2, via the
+<link linkend="conf-branch-group">branch-group</link> option.
+</para>
+
+<example id="ex-branch-group">
+<title>Example of using branch-group</title>
+
+<para>branch-group can be used in the configuration file as follows:
+</para>
+
+<programlisting>
+global
+ # Select KDE Frameworks 5 and other Qt5-based apps
+ <option>branch-group</option> <replaceable>kf5-qt5</replaceable>
+
+ # Other global options here ...
+end global
+
+module-set
+ # branch-group only works for kde-projects
+ <option>repository</option> kde-projects
+
+ # branch-group is inherited from the one set globally, but could
+ # specified here.
+
+ <option>use-modules</option> <replaceable>kdelibs kde-workspace</replaceable>
+end module-set
+
+# kdelibs's branch will be "frameworks"
+# kde-workspace's branch will be "master" (as of August 2013)
+</programlisting>
+
+<para>In this case the same <literal>branch-group</literal> gives different
+branch names for each Git module.
+</para>
+</example>
+
+<para>This feature requires some data maintained by the &kde; developers in a Git
+repository named <literal>kde-build-metadata</literal>, however this module
+will be included automatically by &kdesrc-build; (though you may see it appear
+in the script output).
+</para>
+
+<tip><para>&kde; modules that do not have a set branch name for the branch
+group you choose will default to an appropriate branch name, as if you had not
+specified <literal>branch-group</literal> at all.
+</para></tip>
+
+</sect2>
+
+</sect1>
+</appendix>
diff --git a/doc/appendix-profile.docbook b/doc/appendix-profile.docbook
new file mode 100644
index 00000000..517465fc
--- /dev/null
+++ b/doc/appendix-profile.docbook
@@ -0,0 +1,167 @@
+<appendix id="appendix-profile">
+<title>Superseded profile setup procedures</title>
+
+<sect1 id="old-profile-setup">
+<title>Setting up a &kde; login profile</title>
+
+<para>These instructions cover how to setup the profile required to ensure your
+computer can login to your newly-built &kde; &plasma; desktop. &kdesrc-build;
+will normally try to do this automatically (see <xref
+linkend="session-driver"/>). This appendix section can be useful for those who
+cannot use &kdesrc-build;'s support for login profile setup. However the
+instructions may not always be up-to-date, it can also be useful to consult the
+<filename>kde-env-master.sh.in</filename> file included with the &kdesrc-build;
+source.</para>
+
+<sect2 id="changing-profile">
+<title>Changing your startup profile settings</title>
+
+<important><para>The <filename>.bash_profile</filename> is the login settings
+file for the popular <application>bash</application> shell used by many &Linux;
+distributions. If you use a different shell, then you may need to adjust the
+samples given in this section for your particular shell.</para></important>
+
+<para>
+Open or create the <filename>.bash_profile</filename> file in the home directory with your favorite editor,
+and add to the end of the file:
+
+If you are building the qt module (you are by default), add instead:
+
+<programlisting>
+PATH=${install-dir}/bin:${qt-install-dir}/bin:$PATH
+MANPATH=${qt-install-dir}/doc/man:$MANPATH
+
+# Act appropriately if LD_LIBRARY_PATH is not already set.
+if [ -z $LD_LIBRARY_PATH ]; then
+ LD_LIBRARY_PATH=${install-dir}:/lib:${qt-install-dir}/lib
+else
+ LD_LIBRARY_PATH=${install-dir}:/lib:${qt-install-dir}/lib:$LD_LIBRARY_PATH
+fi
+
+export PATH MANPATH LD_LIBRARY_PATH
+</programlisting>
+
+or, if you are not building qt (and are using your system &Qt; instead), add
+this instead:
+
+<programlisting>
+PATH=${install-dir}/bin:${qt-install-dir}/bin:$PATH
+
+# Act appropriately if LD_LIBRARY_PATH is not already set.
+if [ -z $LD_LIBRARY_PATH ]; then
+ LD_LIBRARY_PATH=${install-dir}/lib
+else
+ LD_LIBRARY_PATH=${install-dir}/lib:$LD_LIBRARY_PATH
+fi
+
+export PATH LD_LIBRARY_PATH
+</programlisting>
+</para>
+
+<para>
+If you are not using a dedicated user, set a different $<envar>KDEHOME</envar>
+for your new environment in your <filename>.bash_profile</filename>:
+
+<programlisting>
+export KDEHOME="${HOME}/.kde-git"
+
+# Create it if needed
+[ ! -e ~/.kde-git ] && mkdir ~/.kde-git
+</programlisting>
+</para>
+
+<note>
+<para>
+If later your K Menu is empty or too crowded with applications from your
+distribution, you may have to set the <acronym>XDG</acronym> environment
+variables in your <filename>.bash_profile</filename>:
+
+<programlisting>
+XDG_CONFIG_DIRS="/etc/xdg"
+XDG_DATA_DIRS="${install-dir}/share:/usr/share"
+export XDG_CONFIG_DIRS XDG_DATA_DIRS
+</programlisting>
+
+</para>
+</note>
+
+</sect2>
+<sect2 id="starting-kde">
+<title>Starting &kde;</title>
+
+<para>
+Now that you have adjusted your environment settings to use the correct &kde;,
+it is important to ensure that the correct <command>startkde</command> script
+is used as well.
+</para>
+
+<para>
+Open the <filename>.xinitrc</filename> text file from the home directory, or
+create it if necessary. Add the line:
+
+<programlisting>
+<command>exec</command> <option>${install-dir}/bin/startkde</option>
+</programlisting>
+</para>
+
+<important><para>On some distributions, it may be necessary to perform the same
+steps with the <filename>.xsession</filename> file, also in the home directory.
+This is especially true when using graphical login managers such as
+sddm, <application>gdm</application>, or <application>xdm</application>.</para>
+</important>
+
+<para>
+Now start your fresh &kde;: in &BSD; and &Linux; systems with virtual terminal support,
+<keycombo action="simul">&Ctrl;&Alt;<keycap>F1</keycap></keycombo> ... <keycombo action="simul">&Ctrl;&Alt;<keycap>F12</keycap></keycombo> keystroke combinations are used to switch to Virtual Console 1 through 12.
+This allows you to run more than one desktop environment at the same time. The fist six are
+text terminals and the following six are graphical displays.
+</para>
+
+<para>
+If when you start your computer you are presented to the graphical display
+manager instead, you can use the new &kde; environment, even if it is not listed
+as an option. Most display managers, including sddm, have an option to use
+a <quote>Custom Session</quote> when you login. With this option, your session settings are
+loaded from the <filename>.xsession</filename> file in your home directory. If
+you have already modified this file as described above, this option should load
+you into your new &kde; installation.
+</para>
+
+<para>If it does not, there is something else you can try that should normally
+work: Press <keycombo action="simul">&Ctrl;&Alt;<keycap>F2</keycap></keycombo>,
+and you will be presented to a text terminal. Log in using the dedicated user
+and type:
+</para>
+
+<screen>
+<command>startx</command> <option>--</option> <option>:1</option>
+</screen>
+
+<tip>
+<para>
+You can run the &kde; from sources and the old &kde; at the same time! Log in
+using your regular user, start the stable &kde; desktop. Press <keycombo
+action="simul">&Ctrl;&Alt;<keycap>F2</keycap></keycombo> (or
+<keycap>F1</keycap>, <keycap>F3</keycap>, etc..), and you will be presented
+with a text terminal. Log in using the dedicated &kde; &git; user and
+type:</para>
+
+<screen>
+<command>startx</command> <option>--</option> <option>:1</option>
+</screen>
+
+<para>You can go back to the &kde; desktop of your regular user by pressing the
+shortcut key for the already running desktop. This is normally
+<keycombo action="simul">&Ctrl;&Alt;<keycap>F7</keycap></keycombo>, you may need
+to use <keycap>F6</keycap> or <keycap>F8</keycap> instead. To return to your
+&kdesrc-build;-compiled &kde;, you would use the same sequence, except with the
+next function key. For example, if you needed to enter <keycombo action="simul">&Ctrl;&Alt;<keycap>F7</keycap></keycombo>
+to switch to your regular &kde;, you would need to enter
+<keycombo action="simul">&Ctrl;&Alt;<keycap>F8</keycap></keycombo> to go back
+to your &kdesrc-build; &kde;.</para>
+</tip>
+
+</sect2>
+</sect1>
+
+</appendix>
diff --git a/doc/basic-features.docbook b/doc/basic-features.docbook
new file mode 100644
index 00000000..f9ce58c1
--- /dev/null
+++ b/doc/basic-features.docbook
@@ -0,0 +1,204 @@
+<sect1 id="basic-features">
+<title>Basic &kdesrc-build; features</title>
+
+<sect2 id="using-qt">
+<title>qt support</title>
+<para>&kdesrc-build; supports building the &Qt; toolkit used by &kde; software
+as a convenience to users. This support is handled by a special module named
+qt.</para>
+
+<note><para>&Qt; is developed under a separate repository from &kde; software
+located at <ulink
+url="http://code.qt.io/cgit/qt/">http://code.qt.io/cgit/qt/</ulink>.</para></note>
+
+<para>In order to build &Qt;, you should make sure that the
+<link linkend="conf-qt-install-dir">qt-install-dir</link> option is set to the directory you'd
+like to install &Qt; to, as described in <xref linkend="configure-data"/>.</para>
+
+<para>You should then ensure that the qt module is added to
+your <filename>.kdesrc-buildrc</filename>, before any other modules in the
+file. If you are using the sample configuration file, you can simply
+uncomment the existing qt module entry.</para>
+
+<para>Now you should verify the <link
+linkend="conf-repository">repository</link> option and <link
+linkend="conf-branch">branch</link> options are set appropriately:</para>
+
+<orderedlist>
+<listitem><para>The first option is to build &Qt; using a mirror maintained
+on the &kde; source repositories (no other changes are applied, it is simply
+a clone of the official source). This is highly recommended due to occasional
+issues with cloning the full &Qt; module from its official repository.</para>
+
+<para>You can set the <option>repository</option> option for the qt
+module to <userinput>kde:qt</userinput> to use this option.</para>
+</listitem>
+
+<listitem><para>Otherwise, to build the standard &Qt;, set your
+<option>repository</option> option to
+<userinput>git://gitorious.org/qt/qt.git</userinput>. Note that you may
+experience problems performing the initial clone of &Qt; from this
+repository.</para></listitem>
+</orderedlist>
+
+<para>In both cases, the branch option should be set to <userinput>master</userinput> (unless you'd
+like to build a different branch).</para>
+
+</sect2>
+
+<sect2 id="kdesrc-build-std-flags">
+<title>Standard flags added by &kdesrc-build;</title>
+<para>Nota Bene: this section does not apply to modules for which you have
+configured a custom toolchain, using e.g.
+<link linkend="conf-cmake-toolchain">cmake-toolchain</link>.</para>
+
+<para>To save you time, &kdesrc-build; adds some standard paths to your
+environment for you:
+</para>
+
+<itemizedlist>
+<listitem><para>
+The path to the &kde; and &Qt; libraries is added to the
+<envar>LD_LIBRARY_PATH</envar> variable automatically. This means that you
+do not need to edit &libpath; to include them.
+</para></listitem>
+
+<listitem><para>
+The path to the &kde; and &Qt; development support programs are added to the
+<envar>PATH</envar> variable automatically. This means that you do not need to
+edit &binpath; to include them.
+</para></listitem>
+
+<listitem><para>
+The path to the &kde;-provided <application>pkg-config</application> is added
+automatically to <envar>PKG_CONFIG_PATH</envar>. This means that you do not
+need to use &set-env; to add these.
+</para></listitem>
+
+</itemizedlist>
+
+</sect2>
+
+<sect2 id="build-priority">
+<title>Changing &kdesrc-build;'s build priority</title>
+<para>Programs can run with different priority levels on Operating Systems,
+including &Linux; and &BSD;. This allows the system to allocate time for the
+different programs in accordance with how important they are.
+</para>
+
+<para>&kdesrc-build; will normally allocate itself a low priority so that the
+rest of the programs on your system are unaffected and can run normally.
+Using this technique, &kdesrc-build; will use extra CPU when it is available.
+</para>
+
+<para>&kdesrc-build; will still maintain a high enough priority level so that
+it runs before routine batch processes and before CPU donation programs
+such as <ulink url="http://setiathome.ssl.berkeley.edu/">Seti at Home</ulink>.
+</para>
+
+<para>To alter &kdesrc-build; so that it uses a higher (or lower) priority
+level permanently, then you need to adjust the &niceness; setting in the <link
+linkend="configure-data">configuration file</link>. The &niceness; setting
+controls how <quote>nice</quote> &kdesrc-build; is to other programs. In other
+words, having a higher &niceness; gives &kdesrc-build; a lower priority. So to
+give &kdesrc-build; a higher priority, reduce the &niceness; (and vice versa).
+The &niceness; can go from 0 (not nice at all, highest priority) to 20 (super
+nice, lowest priority).</para>
+
+<para>You can also temporarily change the priority for &kdesrc-build; by using
+the &cmd-nice; <link linkend="cmdline">command line option</link>. The value to
+the option is used exactly the same as for &niceness;.</para>
+
+<note><para>It is possible for some programs run by the super user to have a
+negative nice value, with a correspondingly even higher priority for such
+programs. Setting a negative (or even 0) &niceness; for &kdesrc-build; is not
+a great idea, as it will not help run time significantly, but will make your
+computer seem very sluggish should you still need to use it.
+</para></note>
+
+<informalexample>
+<para>To run &kdesrc-build; with a niceness of 15 (a lower priority than
+normal):</para>
+
+<screen>
+<prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--nice=<replaceable>15</replaceable></option></userinput>
+</screen>
+
+<para>Or, you can edit the <link linkend="configure-data">configuration file</link> to make the change permanent:</para>
+
+<screen>
+ &niceness; <replaceable>15</replaceable>
+</screen>
+</informalexample>
+
+<tip>
+<para>The <link linkend="conf-niceness">niceness</link> option only affects the
+usage of the computer's processor(s). One other major affect on computer
+performance relates to how much data input or output (<acronym>I/O</acronym>) a
+program uses. In order to control how much <acronym>I/O</acronym> a program can
+use, modern &Linux; operating systems support a similar tool called
+<application>ionice</application>. &kdesrc-build; supports
+<application>ionice</application>, (but only to enable or disable it
+completely) using the <link
+linkend="conf-use-idle-io-priority">use-idle-io-priority</link> option,
+since &kdesrc-build; version 1.12.
+</para>
+</tip>
+
+</sect2>
+
+<sect2 id="root-installation">
+<title>Installation as the superuser</title>
+<para>You may wish to have &kdesrc-build; run the installation with super user
+privileges. This may be for the unrecommended system-wide installation.
+This is also useful when using a recommended single user &kde; build, however.
+This is because some modules (especially kdebase) install programs that will
+briefly need elevated permissions when run. They are not able to achieve these
+permission levels unless they are installed with the elevated permissions.
+</para>
+
+<para>You could simply run &kdesrc-build; as the super user directly, but this
+is not recommended, since the program has not been audited for that kind of use.
+Although it should be safe to run the program in this fashion, it is better to
+avoid running as the super user when possible.</para>
+
+<para>To take care of this, &kdesrc-build; provides the &make-install-prefix;
+option. You can use this option to specify a command to use to perform the
+installation as another user. The recommended way to use this command is with
+the &sudo; program, which will run the install command as the super user.
+</para>
+
+<informalexample>
+<para>For example, to install all modules using &sudo;,
+you could do something like this:</para>
+
+<screen>
+global
+ &make-install-prefix; <replaceable>sudo</replaceable>
+ # Other options
+end global
+</screen>
+
+<para>To use &make-install-prefix; for only a single module, this would work:
+</para>
+
+<screen>
+module <replaceable>some-module-name</replaceable>
+ &make-install-prefix; <replaceable>sudo</replaceable>
+end module
+</screen>
+</informalexample>
+
+</sect2>
+
+<sect2 id="build-progress">
+<title>Showing the progress of a module build</title>
+<para>This feature is always available, and is automatically enabled when
+possible. What this does is display an estimated build progress while
+building a module; that way you know about how much longer it will take to
+build a module.
+</para>
+
+</sect2>
+
+</sect1>
diff --git a/doc/building-and-troubleshooting.docbook b/doc/building-and-troubleshooting.docbook
new file mode 100644
index 00000000..b9d478eb
--- /dev/null
+++ b/doc/building-and-troubleshooting.docbook
@@ -0,0 +1,139 @@
+<sect1 id="building-and-troubleshooting">
+<title>Using the &kdesrc-build; script</title>
+<para>With the configuration data established, now you are ready to run the
+script. Even if you still have some tweaking or other reading you wish to do,
+it is a good idea to at least load the &kde; project metadata.</para>
+
+<sect2 id="loading-kdesrc-build-metadata">
+<title>Loading project metadata</title>
+
+<para>
+From a terminal window, log in to the user you are using to compile &kde; software and
+execute the script:
+</para>
+<screen>
+ <prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--metadata-only</option></userinput>
+</screen>
+
+<para>This command will setup the source directory and connect to the KDE &git;
+repositories to download the database of &kde; git repositories, and the
+database of dependency metadata, without making any further changes. It is
+useful to run this separately as this metadata is useful for other
+&kdesrc-build; commands. </para>
+
+</sect2>
+
+<sect2 id="pretend-mode">
+<title>Previewing what will happen when kdesrc-build runs</title>
+
+<para>With the project metadata installed, it is possible to preview what
+&kdesrc-build; will do when launched. This can be done with the <option><link
+linkend="cmdline-pretend">--pretend</link></option> command line option.</para>
+
+<screen>
+ <prompt>% </prompt><command>./kdesrc-build</command> <option>--pretend</option>
+</screen>
+
+<para>You should see a message saying that some packages were successfully built (although
+ nothing was actually built). If there were no significant problems shown, you can proceed
+ to actually running the script.</para>
+
+<screen>
+ <prompt>%</prompt> <userinput><command>kdesrc-build</command></userinput>
+</screen>
+
+<para>This command will download the appropriate source code, build and install each module in order. Afterwards, you should see output similar to that in <xref
+linkend="example-build-sequence"/>:</para>
+
+<example id="example-build-sequence">
+<title>Example output of a kdesrc-build run</title>
+<screen>
+<prompt>%</prompt> <userinput><command>kdesrc-build</command></userinput>
+Updating kde-build-metadata (to branch master)
+Updating sysadmin-repo-metadata (to branch master)
+
+Building libdbusmenu-qt (1/200)
+ No changes to libdbusmenu-qt source, proceeding to build.
+ Compiling... succeeded (after 0 seconds)
+ Installing.. succeeded (after 0 seconds)
+
+Building taglib (2/200)
+ Updating taglib (to branch master)
+ Source update complete for taglib: 68 files affected.
+ Compiling... succeeded (after 0 seconds)
+ Installing.. succeeded (after 0 seconds)
+
+Building extra-cmake-modules from <module-set at line 32> (3/200)
+ Updating extra-cmake-modules (to branch master)
+ Source update complete for extra-cmake-modules: 2 files affected.
+ Compiling... succeeded (after 0 seconds)
+ Installing.. succeeded (after 0 seconds)
+
+ ...
+
+Building kdevelop from kdev (200/200)
+ Updating kdevelop (to branch master)
+ Source update complete for kdevelop: 29 files affected.
+ Compiling... succeeded (after 1 minute, and 34 seconds)
+ Installing.. succeeded (after 2 seconds)
+
+<<< PACKAGES SUCCESSFULLY BUILT >>>
+Built 200 modules
+
+Your logs are saved in /home/kde-src/kdesrc/log/2018-01-20-07
+</screen>
+</example>
+</sect2>
+
+<sect2 id="fixing-build-failures">
+<title>Resolving build failures</title>
+
+<para>
+Depending on how many modules you are downloading, it is possible that
+&kdesrc-build; will not succeed the first time you compile &kde; software.
+Do not despair!
+</para>
+
+<para>&kdesrc-build; logs the output of every command it runs. By default,
+the log files are kept in <filename class="directory">~/kdesrc/log</filename>. To see what
+the caused an error for a module in the last &kdesrc-build; command, usually
+it is sufficient to look at <filename class="directory">~/kdesrc/log/latest/<replaceable>module-name</replaceable>/error.log</filename>.</para>
+
+<tip><para>Perhaps the easiest way to find out what error caused a module to
+fail to build is to search backward with a case-insensitive search, starting
+from the end of the file looking for the word <literal>error</literal>. Once
+that is found, scroll up to make sure there are no other error messages nearby.
+The first error message in a group is usually the underlying
+problem.</para></tip>
+
+<para>In that file, you will see the error that caused the build to fail for
+that module. If the file says (at the bottom) that you are missing some
+packages, try installing the package (including any appropriate -dev packages)
+before trying to build that module again. Make sure that when you run
+&kdesrc-build; again to pass the <link
+linkend="cmdline-reconfigure">--reconfigure</link> option so that
+&kdesrc-build; forces the module to check for the missing packages
+again.</para>
+
+<para>Or, if the error appears to be a build error (such as a syntax error,
+<quote>incorrect prototype</quote>, <quote>unknown type</quote>, or similar)
+then it is probably an error with the &kde; source, which will hopefully be
+resolved within a few days. If it is not resolved within that time, feel free
+to mail the <email>kde-devel at kde.org</email> mailing list (subscription may be
+required first) in order to report the build failure.</para>
+
+<para>You can find more common examples of things that can go wrong and their
+solutions, as well as general tips and strategies to build &kde; software in the
+<ulink url="https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source">
+Build from Source</ulink>.
+</para>
+
+<para>On the other hand, assuming everything went well, you should have a new
+&kde; install on your computer, and now it is simply a matter of running
+it, described next in <xref linkend="environment"/>.</para>
+
+<note><para>For more information about &kdesrc-build;'s logging features,
+please see <xref linkend="kdesrc-build-logging"/>.</para></note>
+</sect2>
+
+</sect1>
diff --git a/doc/building-specific-modules.docbook b/doc/building-specific-modules.docbook
new file mode 100644
index 00000000..d0e30a76
--- /dev/null
+++ b/doc/building-specific-modules.docbook
@@ -0,0 +1,62 @@
+<sect1 id="building-specific-modules">
+<title>Building specific modules</title>
+
+<para>Rather than building every module all the time, you may only want to build a single
+ module, or other small subset. Rather than editing your configuration file, you can simply
+ pass the names of modules or module sets to build to the command line.</para>
+
+<example id="example-subset-build">
+<title>Example output of a kdesrc-build specific module build</title>
+<screen>
+ <prompt>%</prompt> <userinput><command>kdesrc-build</command> <option>--include-dependencies</option> <replaceable>dolphin</replaceable></userinput>
+Updating kde-build-metadata (to branch master)
+Updating sysadmin-repo-metadata (to branch master)
+
+Building extra-cmake-modules from frameworks-set (1/79)
+ Updating extra-cmake-modules (to branch master)
+ No changes to extra-cmake-modules source, proceeding to build.
+ Running cmake...
+ Compiling... succeeded (after 0 seconds)
+ Installing.. succeeded (after 0 seconds)
+
+Building phonon from phonon (2/79)
+ Updating phonon (to branch master)
+ No changes to phonon source, proceeding to build.
+ Compiling... succeeded (after 0 seconds)
+ Installing.. succeeded (after 0 seconds)
+
+Building attica from frameworks-set (3/79)
+ Updating attica (to branch master)
+ No changes to attica source, proceeding to build.
+ Compiling... succeeded (after 0 seconds)
+ Installing.. succeeded (after 0 seconds)
+
+ ...
+
+Building dolphin from base-apps (79/79)
+ Updating dolphin (to branch master)
+ No changes to dolphin source, proceeding to build.
+ Compiling... succeeded (after 0 seconds)
+ Installing.. succeeded (after 0 seconds)
+
+<<< PACKAGES SUCCESSFULLY BUILT >>>
+Built 79 modules
+
+Your logs are saved in /home/kde-src/kdesrc/log/2018-01-20-07
+</screen>
+</example>
+
+<para>In this case, although only the <replaceable>dolphin</replaceable>
+application was specified, the <option>--include-dependencies</option> flag
+caused &kdesrc-build; to include the dependencies listed for
+<replaceable>dolphin</replaceable> (by setting the <link
+linkend="conf-include-dependencies">include-dependencies</link> option).
+</para>
+
+<note><para>The dependency resolution worked in this case only because
+<replaceable>dolphin</replaceable> happened to be specified in a
+<literal>kde-projects</literal>-based module set (in this example, named
+<literal>base-apps</literal>). See <xref linkend="module-sets-kde"/>.
+</para></note>
+
+</sect1>
diff --git a/doc/cmdline.docbook b/doc/cmdline.docbook
new file mode 100644
index 00000000..0ad480d0
--- /dev/null
+++ b/doc/cmdline.docbook
@@ -0,0 +1,117 @@
+<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-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>
+
+<sect2 id="cmdline-commonly-used-options">
+ <title>Commonly used command line options</title>
+
+ <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>--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-include-dependencies</option> (or <option>-D</option>)</term>
+ <listitem><para>Only process the selected modules, skipping their dependencies.
+ Useful when you have changed only selected modules, and you are sure you
+ do not need to rebuild the others.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--refresh-build</option> (or <option>-r</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>--resume-from</option> module</term>
+ <listitem><para>Skips modules until just before the given module, then operates as normal.
+ Useful when the previous build failed on specific module, you fixed it, and then you
+ want to continue the with building the rest of initial set of modules.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--run</option> module</term>
+ <listitem><para>Launch the built application.</para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The full list of command line options is given in <xref
+ linkend="supported-cmdline-params"/>.</para>
+
+ </sect2>
+</sect1>
+
+&supported-envvars;
+
+&supported-cmdline-params;
+
+</chapter>
diff --git a/doc/conf-options-table.docbook b/doc/conf-options-table.docbook
new file mode 100644
index 00000000..b35d520c
--- /dev/null
+++ b/doc/conf-options-table.docbook
@@ -0,0 +1,1482 @@
+<sect1 id="conf-options-table">
+<title>Table of available configuration options</title>
+
+<para>Here are tables of various options, containing the following
+information:</para>
+
+<itemizedlist>
+
+<listitem><para>The option name</para></listitem>
+
+<listitem><para>The scope of the option: <emphasis>global</emphasis>, <emphasis>module</emphasis> or <emphasis>module-set</emphasis>.
+Options in <emphasis>module</emphasis> or/and <emphasis>module-set</emphasis> scope can also be defined in <emphasis>options</emphasis> sections.
+</para></listitem>
+
+<listitem><para>Special comments on the purpose and usage of the
+option.</para></listitem>
+
+</itemizedlist>
+
+<table id="options-global-table">
+<title>Global scope only options</title>
+<tgroup cols="2">
+
+<thead>
+<row>
+<entry>Option name</entry>
+<entry>Description</entry>
+</row>
+</thead>
+<tbody>
+
+<row id="conf-async">
+<entry><link linkend="conf-async">async</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>Boolean</member>
+<member>Default value</member><member>True</member>
+<member>Available since</member><member>1.6</member>
+</simplelist>
+<para>This option enables the asynchronous mode of operation, where the source
+code update and the build process will be performed in parallel, instead of waiting for
+all of the source code updates before starting the build process.</para>
+<para>Related command-line option: <xref linkend="cmdline-async"/></para>
+</entry>
+</row>
+
+<row id="conf-colorful-output">
+<entry><link linkend="conf-colorful-output">colorful-output</link></entry>
+<entry><simplelist type='horiz' columns='2'>
+<member>Type</member><member>Boolean</member>
+<member>Default value</member><member>True</member>
+</simplelist><para>Set this option to <userinput>false</userinput> to disable the colorful output of &kdesrc-build;.
+Note that &kdesrc-build; will not output the
+color codes to anything but a terminal (such as xterm, &konsole;, or the normal
+&Linux; console).</para>
+<para>Related command-line option: <xref linkend="cmdline-color"/></para>
+</entry>
+</row>
+
+<row id="conf-disable-agent-check">
+<entry><link linkend="conf-disable-agent-check">disable-agent-check</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>Boolean</member>
+<member>Default value</member><member>False</member>
+</simplelist>
+<para>If you are using &ssh; to download the &git; sources
+(such as if you are using the git+ssh protocol), this option controls if &kdesrc-build; will try and
+make sure that if you are using ssh-agent, it is actually managing some &ssh;
+identities. This is to try and prevent &ssh; from asking for your pass phrase
+for every module.</para>
+<para>Related command-line option: --disable-agent-check, --no-disable-agent-check</para>
+</entry>
+</row>
+
+<row id="conf-git-desired-protocol">
+<entry><link linkend="conf-git-desired-protocol">git-desired-protocol</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Default value</member><member>git</member>
+<member>History information</member><member>This option was added in &kdesrc-build; 1.16. Prior to 20.06 this option
+was used to configure the fetch URL instead of the push URL. As of 20.06
+<literal>https</literal> is always used when updating KDE projects.</member>
+</simplelist>
+<para>This option only applies to modules from a <link
+linkend="kde-projects-module-sets">&kde; project</link> repository.</para>
+
+<para>What this option actually does is configure which network protocol to
+prefer when pushing source code for these modules. Normally the very-efficient
+<literal>git</literal> protocol is used, but this may be blocked in some
+networks (e.g. corporate intranets, public Wi-Fi). An alternative protocol
+which is much better supported is the <literal>https</literal> protocol used for
+Internet web sites.</para>
+
+<para>If you are using one of these constrained networks you can set this
+option to <userinput>http</userinput> to prefer <literal>https</literal>
+communications instead.</para>
+
+<tip><para>You may also need the <link
+linkend="conf-http-proxy">http-proxy</link> option if an HTTP proxy is also
+needed for network traffic.</para></tip>
+
+<para>In any other situation you should not set this option as the default
+protocol is most efficient.</para>
+
+</entry>
+</row>
+
+<row id="conf-git-repository-base">
+<entry><link linkend="conf-git-repository-base">git-repository-base</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Available since</member><member>1.12.1</member>
+</simplelist>
+<para>This option is used to create a short
+name to reference a specific Git repository base URL in later <link
+linkend="module-sets">module set</link> declarations, which is useful for
+quickly declaring many Git modules to build.</para>
+
+<para>You must specify two things (separated by a space): The name to assign
+to the base URL, and the actual base URL itself. For example:</para>
+
+<para>
+<programlisting>
+global
+ # other options
+ # This is the common path to all anonymous Git server modules.
+ git-repository-base <replaceable>kde-git</replaceable> <replaceable>kde:</replaceable>
+end global
+
+# Module declarations
+
+module-set
+ # Now you can use the alias you defined earlier, but <emphasis>only</emphasis> in a module-set.
+ repository <replaceable>kde-git</replaceable>
+ <link linkend="conf-use-modules">use-modules</link> <replaceable>module1.git</replaceable> <replaceable>module2.git</replaceable>
+end module-set
+</programlisting>
+</para>
+
+<para>The module-set's <literal>use-modules</literal> option created two modules
+internally, with &kdesrc-build; behaving as if it had read:</para>
+
+<programlisting>
+module module1
+ repository kde:<replaceable>module1.git</replaceable>
+end module
+
+module module2
+ repository kde:<replaceable>module2.git</replaceable>
+end module
+</programlisting>
+
+<para>The <literal>kde:</literal> &git; repository prefix used above is a
+shortcut which will be setup by &kdesrc-build; automatically. See the TechBase
+<ulink
+url="https://techbase.kde.org/Development/Git/Configuration#URL_Renaming">URL
+Renaming</ulink> article for more information. Note that unlike most other
+options, this option can be specified multiple times in order to create as
+many aliases as necessary.</para>
+
+<tip><para>It is not required to use this option to take advantage of module-set,
+this option exists to make it easy to use the same repository across many
+different module sets.</para></tip>
+</entry>
+</row>
+
+<row id="conf-install-environment-driver">
+<entry><link linkend="conf-install-environment-driver">install-environment-driver</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>Boolean</member>
+<member>Default value</member><member>True</member>
+<member>Available since</member><member>17.08</member>
+</simplelist>
+<para>Install a shell script that can be
+sourced in a user's profile setup scripts to easily establish needed environment
+variables to run the Plasma desktop built by &kdesrc-build;.</para>
+
+<para>This driver will alter the following files:</para>
+
+<itemizedlist>
+<listitem><para><filename>$XDG_CONFIG_HOME/kde-env-master.sh</filename> (normally found at <filename>~/.config/kde-env-master.sh</filename>).</para></listitem>
+<listitem><para><filename>$XDG_CONFIG_HOME/kde-env-user.sh</filename> (normally found at <filename>~/.config/kde-env-user.sh</filename>).</para></listitem>
+</itemizedlist>
+
+<para>The <filename>kde-env-user.sh</filename> is optional. It is
+intended for user customizations (see the <ulink url="https://userbase.kde.org/KDE_System_Administration/Environment_Variables#Troubleshooting_and_Debugging">Troubleshooting and Debugging</ulink>
+section of the &kde; UserBase for examples of customizable settings), but these settings
+can be set elsewhere by the user in their existing profile setup scripts.</para>
+
+<para>You can disable this feature by setting this option to
+<replaceable>false</replaceable>, and ensuring that the <link
+linkend="conf-install-session-driver">install-session-driver</link> option is
+also disabled.</para>
+
+<tip><para>&kdesrc-build; will not overwrite your existing files (if present)
+unless you also pass the <option><link
+linkend="cmdline-delete-my-settings">--delete-my-settings</link></option>
+command-line option.</para></tip>
+<para>Related command-line option: --install-environment-driver, --no-install-environment-driver</para>
+</entry>
+</row>
+
+<row id="conf-install-session-driver">
+<entry><link linkend="conf-install-session-driver">install-session-driver</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>Boolean</member>
+<member>Default value</member><member>True</member>
+<member>Available since</member><member>1.16</member>
+</simplelist>
+<para>If enabled, &kdesrc-build; will try to install a driver for the graphical
+login manager that allows you to login to your &kdesrc-build;-built &kde; desktop.</para>
+
+<para>This driver will alter the following files:</para>
+
+<itemizedlist>
+<listitem><para><filename>~/.xsession</filename></para></listitem>
+<listitem><para><filename>$XDG_CONFIG_HOME/kde-env-master.sh</filename> (normally found at <filename>~/.config/kde-env-master.sh</filename>).</para></listitem>
+<listitem><para><filename>$XDG_CONFIG_HOME/kde-env-user.sh</filename> (normally found at <filename>~/.config/kde-env-user.sh</filename>).</para></listitem>
+</itemizedlist>
+
+<para>If you maintain your own login driver then you can disable this feature by setting this
+option to <replaceable>false</replaceable>. If enabled, this feature also enables the
+<link linkend="conf-install-environment-driver">install-environment-driver</link> feature.</para>
+
+<tip><para>&kdesrc-build; will not overwrite your existing files (if present)
+unless you also pass the <option><link
+linkend="cmdline-delete-my-settings">--delete-my-settings</link></option>
+command-line option.</para></tip>
+<para>Related command-line option: --install-session-driver, --no-install-session-driver</para>
+</entry>
+</row>
+
+<row id="conf-niceness">
+<entry><link linkend="conf-niceness">niceness</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>Integer</member>
+<member>Default value</member><member>10</member>
+</simplelist>
+<para>Set this option to a number between 20 and 0. The higher the number, the
+lower a priority &kdesrc-build; will set for itself, i.e. the higher the
+number, the "nicer" the program is.</para>
+<para>Related command-line option: <xref linkend="cmdline-nice"/></para>
+</entry>
+</row>
+
+<row id="conf-num-cores">
+<entry><link linkend="conf-num-cores">num-cores</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>Integer</member>
+<member>Default value</member><member>Depends on system</member>
+<member>Available since</member><member>20.07</member>
+</simplelist>
+<para>This option is defined by &kdesrc-build; (when using <command>kdesrc-build --generate-config</command>), set to be the number of
+available CPUs (as indicated by the external application
+<application>nproc</application>). If &kdesrc-build; cannot detect the
+number of CPUs, this value is set to 4.</para>
+
+<para>See <xref linkend="make-options-example"/> for an example of this
+option's usage.</para>
+<para>Related command-line option: --num-cores <replaceable>value</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-num-cores-low-mem">
+<entry><link linkend="conf-num-cores-low-mem">num-cores-low-mem</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>Integer</member>
+<member>Default value</member><member>Depends on system</member>
+<member>Available since</member><member>20.07</member>
+</simplelist>
+<para>This option is defined by &kdesrc-build; (when using <command>kdesrc-build --generate-config</command>), set to be the number of
+CPUs that is deemed safe for heavyweight or other highly-intensive modules,
+such as <literal>qtwebengine</literal>, to avoid running out of memory
+during the build.</para>
+
+<para>The typical calculation is one CPU core for every 2
+gigabytes (GiB) of total memory. At least 1 core will be specified,
+and no more than <option><link linkend="conf-num-cores">num-cores</link></option>
+cores will be specified.</para>
+
+<para>Although this option is intended to support &Qt; modules, you can use it for your
+any module in the same way that <option>num-cores</option> is used.</para>
+
+<para>If &kdesrc-build; cannot detect available memory then this value will be
+set to 2.</para>
+
+<para>Related command-line option: --num-cores-low-mem <replaceable>value</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-persistent-data-file">
+<entry><link linkend="conf-persistent-data-file">persistent-data-file</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Available since</member><member>1.15</member>
+</simplelist>
+<para>Use this option to change where &kdesrc-build; stores its
+persistent data. The default is to store this data in a file called
+<filename>.kdesrc-build-data</filename>, placed in the same directory as the
+configuration file in use. If the global configuration file is in use, it will
+be saved to <filename>~/.local/state/kdesrc-build-data</filename>
+(<filename>$XDG_STATE_HOME/kdesrc-build-data</filename>, if
+<envar>$XDG_STATE_HOME</envar> is set). If you have multiple available
+configurations in the same directory, you may want to manually set this option,
+so that different configurations do not end up with conflicting persistent data.
+</para>
+<para>Related command-line option: --persistent-data-file <replaceable>file</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-ssh-identity-file">
+<entry><link linkend="conf-ssh-identity-file">ssh-identity-file</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Available since</member><member>1.14.2</member>
+</simplelist>
+<para>Set this option to control which private SSH key file is passed to the
+<command>ssh-add</command> command when &kdesrc-build; is downloading source
+code from repositories that require authentication. See also: <xref
+linkend="ssh-agent-reminder"/>.</para>
+</entry>
+</row>
+
+<row id="conf-use-idle-io-priority">
+<entry><link linkend="conf-use-idle-io-priority">use-idle-io-priority</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>Boolean</member>
+<member>Default value</member><member>False</member>
+<member>Available since</member><member>1.12</member>
+</simplelist>
+<para>Use lower priority for disk and other I/O, which can significantly improve the
+responsiveness of the rest of the system at the expense of slightly longer
+running times for &kdesrc-build;.</para>
+<para>Related command-line option: --use-idle-io-priority, --no-use-idle-io-priority</para>
+</entry>
+</row>
+
+<row id="conf-use-inactive-modules">
+<entry><link linkend="conf-use-inactive-modules">use-inactive-modules</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>Boolean</member>
+<member>Default value</member><member>False</member>
+</simplelist>
+<para>Allow kdesrc-build to also clone and pull from repositories marked as inactive.</para>
+<para>Related command-line option: --use-inactive-modules, --no-use-inactive-modules</para>
+</entry>
+</row>
+
+</tbody>
+</tgroup>
+</table>
+
+<!-- Between tables -->
+
+<table id="option-table">
+<title>All scopes (module, module-set and global) options</title>
+<tgroup cols="2">
+
+<thead>
+<row>
+<entry>Option name</entry>
+<entry>Description</entry>
+</row>
+</thead>
+
+<tbody>
+
+<row id="conf-binpath">
+<entry><link linkend="conf-binpath">binpath</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+</simplelist>
+<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
+variable should include the colon-separated paths of your development
+toolchain. The paths <filename class="directory">${install-dir}/bin</filename> and
+<filename class="directory">${qt-install-dir}/bin</filename> are automatically added. You
+may use the tilde (~) for any paths you add using this option.</para>
+<para>Related command-line option: --binpath <replaceable>path</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-branch">
+<entry><link linkend="conf-branch">branch</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Default value</member><member>master</member>
+</simplelist>
+<para>Checkout the specified branch instead of the default branch.</para>
+<note><para>For most &kde; modules you probably wish to use the <link
+linkend="conf-branch-group">branch-group</link> option instead and use this
+option for case-by-case exceptions.</para></note>
+<para>Related command-line option: --branch <replaceable>value</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-branch-group">
+<entry><link linkend="conf-branch-group">branch-group</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Available since</member><member>1.16-pre2</member>
+</simplelist>
+<para>Set this option to a general group from which you want modules to be
+chosen.</para>
+
+<para>For supported &git; module types, &kdesrc-build; will determine the
+actual branch to use automatically based on rules encoded by the &kde;
+developers (these rules may be viewed in the
+<literal>kde-build-metadata</literal> source repository in your source
+directory). After a branch is determined that branch is used as if you had
+specified it yourself using the <link linkend="conf-branch">branch</link>
+option.
+</para>
+
+<para>This is useful if you're just trying to maintain up-to-date on some
+normal development track without having to pay attention to all the branch name
+changes.</para>
+
+<para>Note that if you <emphasis>do</emphasis> choose a
+<literal>branch</literal> yourself, that it will override this setting. The
+same is true of other specific branch selection options such as <link
+linkend="conf-tag">tag</link>.</para>
+
+<note><para>This option only applies to <literal>kde-projects</literal> &git;
+modules (the common case). See also <xref
+linkend="kde-projects-module-sets"/>.
+</para></note>
+
+<para>Related command-line option: --branch-group <replaceable>value</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-build-dir">
+<entry><link linkend="conf-build-dir">build-dir</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Default value</member><member><filename class="directory">~/kde/build</filename></member>
+</simplelist>
+<para>
+Use this option to change the directory to contain the built sources. There
+are three different ways to use it:</para>
+
+<orderedlist>
+
+<listitem><para>Relative to the &kde; &git; source directory (see <link
+linkend="conf-source-dir">the source-dir option</link>). This is the default,
+and is selected if you type a directory name that does not start with a tilde
+(~) or a slash (/).</para></listitem>
+
+<listitem><para>Absolute path. If you specify a path that begins with a /, then
+that path is used directly. For example, <filename
+class="directory">/tmp/kde-obj-dir/</filename>.</para></listitem>
+
+<listitem><para>Relative to your home directory. If you specify a path that
+begins with a ~, then the path is used relative to your home directory,
+analogous to the shell's tilde-expansion. For example, <filename
+class="directory">~/builddir</filename> would set the build directory to
+<filename
+class="directory">/home/user-name/builddir</filename>.</para></listitem>
+
+</orderedlist>
+
+<para>Perhaps surprisingly, this option can be changed per module.</para>
+<para>Related command-line option: --build-dir <replaceable>path</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-build-when-unchanged">
+<entry><link linkend="conf-build-when-unchanged">build-when-unchanged</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>Boolean</member>
+<member>Default value</member><member>True</member>
+</simplelist>
+<para>Control whether &kdesrc-build; always
+tries to build a module that has not had any source code updates.</para>
+
+<para>If set to <userinput>true</userinput>, &kdesrc-build; always attempts the build phase
+for a module, even if the module did not have any source code updates.
+With this value it will more likely lead to a correct build.</para>
+
+<para>If set to <userinput>false</userinput>, &kdesrc-build; will only attempt to run the
+build phase for a module if the module has a source code update, or in other
+situations where it is likely that a rebuild is actually required. This can save
+time, especially if you run &kdesrc-build; daily, or more frequently.</para>
+
+<important><para>This feature is provided as an optimization only. Like many
+other optimizations, there are trade-offs for the correctness of your
+installation. For instance, changes to the qt or kdelibs modules may cause
+a rebuild of other modules to be necessary, even if the source code doesn't
+change at all.</para></important>
+<para>Related command-line option: <xref linkend="cmdline-build-when-unchanged"/></para>
+</entry>
+</row>
+
+<row id="conf-cmake-generator">
+<entry><link linkend="conf-cmake-generator">cmake-generator</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Default value</member><member>Unix Makefiles</member>
+</simplelist>
+<para>Specify which generator to use with &cmake;.
+Currently both <literal>Ninja</literal> and <literal>Unix Makefiles</literal>
+as well as extra generators based on them like <literal>Eclipse CDT4 - Ninja
+</literal> are supported. Invalid (unsupported) values are ignored and treated
+as if unset.
+</para>
+
+<para>Note that if a valid generator is also specified through
+<link linkend="conf-cmake-options">cmake-options</link> it will override the
+value for <literal>cmake-generator</literal>.</para>
+<para>Related command-line option: --cmake-generator <replaceable>value</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-cmake-toolchain">
+<entry><link linkend="conf-cmake-toolchain">cmake-toolchain</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+</simplelist>
+<para>Specify a toolchain file to use with &cmake;.
+</para>
+<para>When a valid toolchain file is configured, &kdesrc-build; will
+<emphasis>no longer set environment variables automatically</emphasis>.
+You can use &set-env;, &binpath; and &libpath; to fix up the environment
+manually if your toolchain file does not work out of the box with
+&kdesrc-build;. Refer to <link linkend="kdesrc-build-std-flags">the overview
+of standard flags added by &kdesrc-build;</link> for more information.
+</para>
+<para>Note that if a valid toolchain is also specified through
+<link linkend="conf-cmake-options">cmake-options</link> it will override the
+value for <literal>cmake-toolchain</literal>.</para>
+<para>Related command-line option: --cmake-toolchain <replaceable>value</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-cmake-options">
+<entry><link linkend="conf-cmake-options">cmake-options</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+</simplelist>
+<para>Appends to global options for the default buildsystem, overrides global
+for other buildsystems.</para>
+<para>Use this option to specify what flags to pass to &cmake; 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. When used as a module
+option, it is added to the end of the global options. This allows you to
+specify common &cmake; options in the global section.</para>
+
+<para>This option does not apply to qt (which does not use &cmake;). Use
+<link linkend="conf-configure-flags">configure-flags</link> instead.</para>
+
+<para>If a valid generator is specified among the listed options it will
+override the value of
+<link linkend="conf-cmake-generator">cmake-generator</link>. Invalid
+(unsupported) generators are ignored and will not be passed to &cmake;.
+</para>
+
+<para>If a valid toolchain file is specified among the listed options it will
+override the value of
+<link linkend="conf-cmake-toolchain">cmake-toolchain</link>. Invalid
+toolchains are ignored and will not be passed to &cmake;.
+</para>
+
+<para>Since these options are passed directly to the &cmake; command line, they
+should be given as they would be typed into &cmake;. For example:</para>
+
+<programlisting>
+cmake-options -DCMAKE_BUILD_TYPE=RelWithDebInfo
+</programlisting>
+
+<para>Since this is a hassle, &kdesrc-build; takes pains to ensure that as long
+as the rest of the options are set correctly, you should be able to leave this
+option blank. (In other words, <emphasis>required</emphasis> &cmake; parameters
+are set for you automatically)</para>
+<para>Related command-line option: --cmake-options <replaceable>value</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-compile-commands-export">
+<entry><link linkend="conf-compile-commands-export">compile-commands-export</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>Boolean</member>
+<member>Default value</member><member>True</member>
+</simplelist>
+<para>Enables the generation of a <literal>compile_commands.json</literal> via CMake inside the build directory.
+</para>
+<para>Related command-line option: --compile-commands-export, --no-compile-commands-export</para>
+</entry>
+</row>
+
+<row id="conf-compile-commands-linking">
+<entry><link linkend="conf-compile-commands-linking">compile-commands-linking</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>Boolean</member>
+<member>Default value</member><member>False</member>
+</simplelist>
+<para>Enables the creation of symbolic links from <literal>compile_commands.json</literal> generated via CMake
+inside the build directory to the matching source directory.
+</para>
+<para>Related command-line option: --compile-commands-linking, --no-compile-commands-linking</para>
+</entry>
+</row>
+
+<row id="conf-configure-flags">
+<entry><link linkend="conf-configure-flags">configure-flags</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+</simplelist>
+<para>Appends to global options for the default buildsystem, overrides global
+for other buildsystems.</para>
+<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
+only works for qt.</emphasis></para>
+
+<para>To change configuration settings for KDE modules, see
+<link linkend="conf-cmake-options">cmake-options</link>.
+</para>
+<para>Related command-line option: --configure-flags <replaceable>value</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-custom-build-command">
+<entry><link linkend="conf-custom-build-command">custom-build-command</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+</simplelist>
+ <para>This option can be set to run a different command (other than
+ <command>make</command>, for example) in order to perform the build
+ process. &kdesrc-build; should in general do the right thing, so you
+ should not need to set this option. However it can be useful to use
+ alternate build systems.
+ </para>
+
+ <para>The value of this option is used as the command line to run, modified
+ by the <link linkend="conf-make-options">make-options</link> option as
+ normal.
+ </para>
+<para>Related command-line option: --custom-build-command <replaceable>value</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-cxxflags">
+<entry><link linkend="conf-cxxflags">cxxflags</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+</simplelist>
+<para>Appends to global options for the default buildsystem, overrides global
+for other buildsystems.</para>
+<para>Use this option to specify what flags to use for building the
+module. This option is
+specified here instead of with <link
+linkend="conf-configure-flags">configure-flags</link> or <link
+linkend="conf-cmake-options">cmake-options</link> because this option will also
+set the environment variable <envar>CXXFLAGS</envar> during the build process.</para>
+
+<para>Note that for &kde; 4 and any other modules that use &cmake;, it is
+necessary to set the CMAKE_BUILD_TYPE option to <userinput>none</userinput>
+when configuring the module. This can be done using the <link
+linkend="conf-cmake-options">cmake-options</link> option.
+</para>
+<para>Related command-line option: --cxxflags <replaceable>value</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-dest-dir">
+<entry><link linkend="conf-dest-dir">dest-dir</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+</simplelist>
+<para>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
+name of the module on disk, it is not a good idea to include directories
+or directory separators in the name as this will interfere with any
+<link linkend="conf-build-dir">build-dir</link> or
+<link linkend="conf-source-dir">source-dir</link> options.</para>
+<para>Related command-line option: --dest-dir <replaceable>path</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-do-not-compile">
+<entry><link linkend="conf-do-not-compile">do-not-compile</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+</simplelist>
+<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>
+
+<para>Note that the sources to the programs will still be downloaded.</para>
+
+<para>For example, to disable building the <literal>codeeditor</literal> and <literal>minimaltest</literal>
+directories of the <literal>syntaxhighlighting</literal> framework, you
+would add <userinput>do-not-compile codeeditor minimaltest</userinput>
+compiling, you would add "do-not-compile juk kscd" to your syntaxhighlighting
+options.</para>
+
+<para>See <xref linkend="not-compiling"/> for an example.</para>
+<para>Related command-line option: --do-not-compile <replaceable>value</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-git-user">
+<entry><link linkend="conf-git-user">git-user</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Available since</member><member>15.09</member>
+</simplelist>
+<para>This option is intended for &kde; developers. If set, it will be used to
+automatically setup identity information for the &git; source control software
+for <emphasis>newly downloaded</emphasis> &git; modules (including the vast
+majority of &kde; modules).</para>
+
+<para>Specifically, the user's name and email fields for each new &git; repository are filled
+in to the values set by this option.</para>
+
+<para>The value must be specified in the form <option><replaceable>User
+Name</replaceable> <<replaceable>email at example.com</replaceable>></option>.</para>
+
+<para>For instance, a developer named <quote>Foo Barbaz</quote> with the
+email address <quote>foo at abc.xyz</quote> would use:</para>
+<para>
+<programlisting>
+ <symbol>git-user</symbol> <replaceable>Foo Barbaz</replaceable> <<replaceable>foo at abc.xyz</replaceable>>
+</programlisting>
+</para>
+
+</entry>
+</row>
+
+<row id="conf-http-proxy">
+<entry><link linkend="conf-http-proxy">http-proxy</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Available since</member><member>1.16</member>
+</simplelist>
+<para>This option, if set, uses the specified URL as a proxy server to use for
+any HTTP network communications (for example, when downloading the <link linkend="kde-projects-module-sets">KDE project
+database</link>).</para>
+
+<para>In addition, &kdesrc-build; will try to ensure that the tools it depends
+on also use that proxy server, if possible, by setting the
+<envar>http_proxy</envar> environment variable to the indicated server,
+<emphasis>if that environment variable is not already set</emphasis>.</para>
+<para>Related command-line option: --http-proxy <replaceable>value</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-directory-layout">
+<entry><link linkend="conf-directory-layout">directory-layout</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Valid values</member><member><userinput>flat</userinput>,
+<userinput>invent</userinput>, <userinput>metadata</userinput></member>
+<member>Default value</member><member>flat</member>
+</simplelist>
+<para>This option is used to configure the layout which &kdesrc-build; should use when
+creating source and build directories.</para>
+<para>The <userinput>flat</userinput> layout will group all modules
+directly underneath the top level source and build directories. For example,
+<literal>source/extragear/network/telepathy/ktp-text-ui</literal> in the <userinput>metadata</userinput>
+layout would be <literal>source/ktp-text-ui</literal> using the <userinput>flat</userinput> layout
+instead.
+</para>
+<para>The <userinput>invent</userinput> layout creates a directory hierarchy mirroring the relative
+paths of repositories on <ulink url="https://invent.kde.org/">invent.kde.org</ulink>. For example
+<literal>source/kde/applications/kate</literal> in the <userinput>metadata</userinput> layout would
+be <literal>source/utilities/kate</literal> using the <userinput>invent</userinput> layout instead.
+This layout only affects KDE projects. It is a good choice for people starting out with
+&kdesrc-build;.
+</para>
+<para>Finally, the <userinput>metadata</userinput> layout is the same as the old default
+behaviour. This layout organises KDE projects according to the project paths specified in the
+project metadata for these modules. This is a good choice if you want a directory layout which
+tracks with certain KDE processes, but note that this path is therefore not always stable. As a
+result, &kdesrc-build; may abandon an old copy of the repository and clone a new one for a project
+due to changes in the project metadata.</para>
+<para>Related command-line option: --directory-layout <replaceable>value</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-generate-vscode-project-config">
+<entry><link linkend="conf-generate-vscode-project-config">generate-vscode-project-config</link></entry>
+
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>Boolean</member>
+<member>Default value</member><member>False</member>
+</simplelist>
+
+<para>Module setting overrides global</para>
+
+<para>Set this option to <userinput>true</userinput> to make
+&kdesrc-build; create VS Code project files (.vscode directory) in the module
+source directory.</para>
+
+<para>The .vscode folder will be created in the project source directory, only
+if it does not already exist. The configurations will enable the use of LSP,
+building, debugging, and running the project from within VS Code.</para>
+
+<para>The configuration also recommends extensions to install that are useful
+for working on most KDE projects.</para>
+
+<para>Related command-line option: <xref linkend="cmdline-generate-vscode-project-config"/></para>
+</entry>
+</row>
+
+<row id="conf-include-dependencies">
+<entry><link linkend="conf-include-dependencies">include-dependencies</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>Boolean</member>
+<member>Default value</member><member>True</member>
+</simplelist>
+<para>Controls if &kdesrc-build; will include known dependencies of this module in its build,
+without requiring you to mention those dependencies (even indirectly).</para>
+
+<note><para>This option only works for <link
+linkend="kde-projects-module-sets"><literal>kde-project</literal>-based
+modules</link>, and requires that the metadata maintained by the &kde;
+developers is accurate for your selected <link
+linkend="conf-branch-group">branch-group</link>.</para></note>
+
+<para>This is to support building applications
+that need versions of &Qt; or &plasma; more recent than supported on
+common operating systems.</para>
+<para>Related command-line option: <xref linkend="cmdline-include-dependencies"/></para>
+</entry>
+</row>
+
+<row id="conf-install-after-build">
+<entry><link linkend="conf-install-after-build">install-after-build</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Default value</member><member>True</member>
+</simplelist>
+<para>This option is used to install the package after it successfully builds.
+You can also use the <link
+linkend="cmdline-no-install"><option>--no-install</option></link> command line
+flag.</para>
+<para>Related command-line option: --install-after-build, --no-install-after-build</para>
+</entry>
+</row>
+
+<row id="conf-install-dir">
+<entry><link linkend="conf-install-dir">install-dir</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Default value</member><member><filename class="directory">~/kde/usr</filename></member>
+</simplelist>
+<para>This option controls where to install the module after it
+is built. If you
+change this to a directory needing root access, you may want to read about the
+<link linkend="conf-make-install-prefix">make-install-prefix</link> option as
+well.</para>
+<para>
+Changing this option for specific module allows you to install it to a different directory than
+where the &kde; Platform libraries are installed, such as if you were using
+&kdesrc-build; only to build applications.</para>
+<para>You can use <varname>${MODULE}</varname> or <varname>$MODULE</varname>
+in the path to have them expanded to the module's name.</para>
+<para>Related command-line option: <xref linkend="cmdline-install-dir"/></para>
+</entry>
+</row>
+
+<row id="conf-libname">
+<entry><link linkend="conf-libname">libname</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Default value</member><member>Auto detected</member>
+</simplelist>
+<para>Set this option to change the default name of the installed library directory
+inside ${install-dir} and ${qt-install-dir}. On many systems this is either
+"lib" or "lib64". Auto-detection is attempted to set the correct name by default,
+but if the guess is wrong then it can be changed with this setting.</para>
+<para>Related command-line option: --libname <replaceable>value</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-libpath">
+<entry><link linkend="conf-libpath">libpath</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+</simplelist>
+<para>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
+class="directory">${install-dir}/$<envar>LIBNAME</envar></filename> and <filename
+class="directory">${qt-install-dir}/$<envar>LIBNAME</envar></filename> are automatically added.
+You may use the tilde (~) for any paths you add using this option.</para>
+<para>Related command-line option: --libpath <replaceable>path</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-log-dir">
+<entry><link linkend="conf-log-dir">log-dir</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+</simplelist>
+<para>Use this option to change the directory used to hold the log files
+generated by the script.</para>
+<para>Related command-line option: --log-dir <replaceable>path</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-make-install-prefix">
+<entry><link linkend="conf-make-install-prefix">make-install-prefix</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+</simplelist>
+<para>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
+please be careful while dealing with root privileges.</para>
+<para>Related command-line option: --make-install-prefix <replaceable>value</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-make-options">
+<entry><link linkend="conf-make-options">make-options</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+</simplelist>
+<para>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="https://github.com/distcc/distcc"><application>distcc</application></ulink> or
+systems with more than one processor core.</para>
+<para>Note that not all supported build systems use <command>make</command>. For
+build systems that use <command>ninja</command> for build (such as the
+<link linkend="conf-override-build-system"><application>Meson</application>
+build system</link>), see the <link linkend="conf-ninja-options">ninja-options</link>
+setting.</para>
+<para>Related command-line option: --make-options <replaceable>value</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-manual-build">
+<entry><link linkend="conf-manual-build">manual-build</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>Boolean</member>
+<member>Default value</member><member>False</member>
+</simplelist>
+<para>Set the option value to <userinput>true</userinput> to keep the
+build process from attempting to build this module. It will still be kept
+up-to-date when updating from &git;. This option is exactly equivalent
+to the
+<link linkend="cmdline-no-build">
+<option>--no-build</option>
+</link>
+command line option.
+</para>
+</entry>
+</row>
+
+<row id="conf-manual-update">
+<entry><link linkend="conf-manual-update">manual-update</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>Boolean</member>
+<member>Default value</member><member>False</member>
+</simplelist>
+<para>Set the option value to <userinput>true</userinput> 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
+commented it out.</para>
+</entry>
+</row>
+
+<row id="conf-ninja-options">
+<entry><link linkend="conf-ninja-options">ninja-options</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+</simplelist>
+<para>Set this variable in order to pass command line options to the
+
+<command>ninja</command> build command. This can be useful to enable <quote>verbose</quote> output
+or to manually reduce the number of parallel build jobs that <command>ninja</command> would
+use.</para>
+
+<note><para>Note that this setting only controls ninja when used by &kdesrc-build;.
+The &Qt; <quote>webengine</quote> module uses <command>ninja</command> indirectly, but
+only officially supports being built by <command>make</command>.
+In this situation, you can set <literal>NINJAFLAGS</literal> as a way to have
+<command>make</command> pass the appropriate flags when it later calls
+<command>ninja</command>, by using
+<link linkend="conf-make-options">make-options</link>.</para>
+
+<programlisting>
+options <replaceable>qtwebengine</replaceable>
+ # Restrict make and ninja to using no more than 6 separate compile jobs even
+ # when more CPU is available, to avoid running out of memory
+ <option><link linkend="conf-make-options">make-options</link></option> -j<replaceable>6</replaceable> NINJAFLAGS=-j<replaceable>6</replaceable>
+end options
+</programlisting>
+</note>
+<para>Related command-line option: --ninja-options <replaceable>value</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-override-build-system">
+<entry><link linkend="conf-override-build-system">override-build-system</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Default value</member><member>Auto detected</member>
+<member>Valid values</member><member>KDE, Qt, qmake, generic, autotools, meson</member>
+<member>Available since</member><member>1.16</member>
+</simplelist>
+<para>Normally &kdesrc-build; will detect the appropriate build system to use
+for a module after it is downloaded. This is done by checking for the existence
+of specific files in the module's source directory.</para>
+
+<para>Some modules may include more than one required set of files, which could confuse
+the auto-detection. In this case you can manually specify the correct build type.</para>
+
+<para>Currently supported build types that can be set are:</para>
+
+<variablelist>
+ <varlistentry>
+ <term>KDE</term>
+ <listitem><para>Used to build &kde; modules. In reality it can be used to build
+ almost any module that uses &cmake; but it is best not to rely on this.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Qt</term>
+ <listitem><para>Used to build the &Qt; library itself.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>qmake</term>
+ <listitem><para>Used to build &Qt; modules that use
+ <application>qmake</application>-style <literal>.pro</literal>
+ files.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>generic</term>
+ <listitem><para>Used to build modules that use plain Makefiles and that do not
+ require any special configuration.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>autotools</term>
+ <listitem><para>This is the standard configuration tool used for most Free and
+ open-source software not in any of the other categories.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>meson</term>
+ <listitem><para>This is a <ulink url="https://mesonbuild.com">relatively new
+ tool</ulink> gaining popularity as a replacement for the autotools and may
+ be required for some non-&kde; modules.</para></listitem>
+ </varlistentry>
+</variablelist>
+
+<para>Related command-line option: --override-build-system <replaceable>value</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-purge-old-logs">
+<entry><link linkend="conf-purge-old-logs">purge-old-logs</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>Boolean</member>
+<member>Default value</member><member>True</member>
+</simplelist>
+<para>This option controls whether old log directories are automatically
+deleted or not.</para>
+<para>Related command-line option: --purge-old-logs, --no-purge-old-logs</para>
+</entry>
+</row>
+
+<row id="conf-qmake-options">
+<entry><link linkend="conf-qmake-options">qmake-options</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Available since</member><member>1.16</member>
+</simplelist>
+<para>Any options specified here are passed to the
+<command>qmake</command> command, for modules that use the
+<symbol>qmake</symbol> build system. For instance, you can use the
+<userinput>PREFIX=/path/to/qt</userinput> option to qmake to override where it
+installs the module.
+</para>
+<para>Related command-line option: --qmake-options <replaceable>value</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-qt-install-dir">
+<entry><link linkend="conf-qt-install-dir">qt-install-dir</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+</simplelist>
+<para>This option controls where to install qt modules after build.
+If you do not specify this option, &kdesrc-build; will assume that &Qt; is
+provided by the operating system.
+</para>
+<para>Related command-line option: --qt-install-dir <replaceable>path</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-remove-after-install">
+<entry><link linkend="conf-remove-after-install">remove-after-install</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Valid values</member><member>none, builddir, all</member>
+<member>Default value</member><member>none</member>
+</simplelist>
+<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
+installed.
+</para>
+<para>Possible values for this option are:
+<itemizedlist>
+<listitem><para>none - Do not delete anything.</para></listitem>
+<listitem><para>builddir - Delete the build directory, but not the source.</para></listitem>
+<listitem><para>all - Delete both the source code and build directory.</para></listitem>
+</itemizedlist>
+</para>
+
+<para>Note that using this option can have a significant detrimental impact on
+both your bandwidth usage (if you use <replaceable>all</replaceable>) and the time taken to compile &kde; software,
+since &kdesrc-build; will be unable to perform incremental builds.</para>
+<para>Related command-line option: --remove-after-install <replaceable>value</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-repository">
+<entry><link linkend="conf-repository">repository</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Available since</member><member>1.10</member>
+</simplelist>
+<para>This option is used to
+specify the &git; repository to download the source code for the module.
+&Qt; (and therefore qt) would need this option, as well as various
+&kde; modules that are in the process of conversion to use &git;.</para></entry>
+</row>
+
+<row id="conf-revision">
+<entry><link linkend="conf-revision">revision</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Available since</member><member>1.16</member>
+</simplelist>
+<para>If this option is set to a value other than 0 (zero), &kdesrc-build;
+will force the source update to bring the module to the exact revision
+given, even if options like <link linkend="conf-branch">branch</link> are in
+effect. If the module is already at the given revision then it will not be
+updated further unless this option is changed or removed from the
+configuration.</para>
+<para>Related command-line option: <xref linkend="cmdline-revision"/></para>
+</entry>
+</row>
+
+<row id="conf-run-tests">
+<entry><link linkend="conf-run-tests">run-tests</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>Boolean</member>
+<member>Default value</member><member>False</member>
+</simplelist>
+<para>If set to <userinput>true</userinput>, 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
+report of the test results. This is useful for developers or those who want
+to ensure their system is setup correctly.</para>
+<para>Related command-line option: --run-tests, --no-run-tests</para>
+</entry>
+</row>
+
+<row id="conf-set-env">
+<entry><link linkend="conf-set-env">set-env</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+</simplelist>
+<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
+McDonald, you would put in the appropriate section this command:</para>
+<programlisting>
+<command>set-env</command> <envar>RONALD</envar> <userinput>McDonald</userinput>
+</programlisting>
+<para>This option is special in that it can be repeated without overriding
+earlier set-env settings in the same section of the <link linkend="configure-data">configuration file</link>. This
+way you can set more than one environment variable per module (or
+globally).</para>
+</entry>
+</row>
+
+<row id="conf-source-dir">
+<entry><link linkend="conf-source-dir">source-dir</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Default value</member><member><filename class="directory">~/kde/src</filename></member>
+</simplelist>
+<para>This option is used to set the directory on your computer to store the &kde;
+&git; sources at. You may use the tilde (~)
+to represent the home directory if using this option.</para>
+<para>Related command-line option: --source-dir <replaceable>path</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-stop-on-failure">
+<entry><link linkend="conf-stop-on-failure">stop-on-failure</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>Boolean</member>
+<member>Default value</member><member>True</member>
+</simplelist>
+<para>Setting this option to <userinput>false</userinput> allows the script to continue execution
+after an error occurs during the build or install process.</para>
+<para>Related command-line option: <xref linkend="cmdline-stop-on-failure"/></para>
+</entry>
+</row>
+
+<row id="conf-tag">
+<entry><link linkend="conf-tag">tag</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Available since</member><member>1.16</member>
+</simplelist>
+<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
+from the <ulink
+url="https://download.kde.org/">&kde; download site</ulink>.</para>
+<para>Related command-line option: --tag <replaceable>value</replaceable></para>
+</entry>
+</row>
+
+<row id="conf-use-clean-install">
+<entry><link linkend="conf-use-clean-install">use-clean-install</link></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>Boolean</member>
+<member>Default value</member><member>False</member>
+<member>Available since</member><member>1.12</member>
+</simplelist>
+<para>Set this option to <userinput>true</userinput> in order to
+have &kdesrc-build; run <command>make uninstall</command> directly before
+running <command>make install</command>.</para>
+
+<para>This can be useful in ensuring that there are not stray old library
+files, &cmake; metadata, etc. that can cause issues in long-lived &kde;
+installations. However this only works on build systems that support
+<command>make uninstall</command>.</para>
+<para>Related command-line option: --use-clean-install, --no-use-clean-install</para>
+</entry>
+</row>
+
+</tbody>
+
+</tgroup>
+</table>
+
+<para>These options do not require any value (except "filter-out-phases"). They are applied if they are presented in a section.</para>
+<table id="options-phase-selection-table">
+<title>Phase selection options</title>
+<tgroup cols="2">
+
+<thead>
+<row>
+<entry>Option name</entry>
+<entry>Scope</entry>
+<entry>Description</entry>
+</row>
+</thead>
+<tbody>
+
+<row id="conf-no-src">
+<entry><link linkend="conf-no-src">no-src</link></entry>
+<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member></simplelist></entry>
+<entry>
+<para>Remove <emphasis>update</emphasis> phase. The other phases that were presented will still be processed.</para>
+<para>Related command-line option: <xref linkend="cmdline-no-src"/></para>
+</entry>
+</row>
+
+<row id="conf-no-install">
+<entry><link linkend="conf-no-install">no-install</link></entry>
+<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member></simplelist></entry>
+<entry>
+<para>Remove <emphasis>install</emphasis> phase. The other phases that were presented will still be processed.</para>
+<para>Related command-line option: <xref linkend="cmdline-no-install"/></para>
+</entry>
+</row>
+
+<row id="conf-no-tests">
+<entry><link linkend="conf-no-tests">no-tests</link></entry>
+<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member></simplelist></entry>
+<entry>
+<para>Remove <emphasis>test</emphasis> phase. The other phases that were presented will still be processed.</para>
+<para>Related command-line option: --no-tests</para>
+</entry>
+</row>
+
+<row id="conf-no-build">
+<entry><link linkend="conf-no-build">no-build</link></entry>
+<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member></simplelist></entry>
+<entry>
+<para>Remove <emphasis>build</emphasis> phase. The other phases that were presented will still be processed.</para>
+<para>Related command-line option: <xref linkend="cmdline-no-build"/></para>
+</entry>
+</row>
+
+<row id="conf-build-only">
+<entry><link linkend="conf-build-only">build-only</link></entry>
+<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member></simplelist></entry>
+<entry>
+<para>If had <emphasis>build</emphasis> phase, remove any other phases. Otherwise, remove all phases.</para>
+<para>Related command-line option: <xref linkend="cmdline-build-only"/></para>
+</entry>
+</row>
+
+<row id="conf-install-only">
+<entry><link linkend="conf-install-only">install-only</link></entry>
+<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member></simplelist></entry>
+<entry>
+<para>If had <emphasis>install</emphasis> phase, remove any other phases. Otherwise, remove all phases.</para>
+<para>Related command-line option: <xref linkend="cmdline-install-only"/></para>
+</entry>
+</row>
+
+<row id="conf-uninstall">
+<entry><link linkend="conf-uninstall">uninstall</link></entry>
+<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member></simplelist></entry>
+<entry>
+<para>If had <emphasis>uninstall</emphasis> phase, remove any other phases. Otherwise, remove all phases.</para>
+<para>Related command-line option: --uninstall</para>
+</entry>
+</row>
+
+<row id="conf-filter-out-phases">
+<entry><link linkend="conf-filter-out-phases">filter-out-phases</link></entry>
+<entry><simplelist type='vert'><member>global</member><member>module</member><member>module-set</member></simplelist></entry>
+<entry>
+<para>Remove those phases that are listed (space separated) in this option. The other phases that were presented will still be processed.</para>
+</entry>
+</row>
+
+</tbody>
+</tgroup>
+</table>
+
+<table id="options-module-set-table">
+<title>Modules selection options</title>
+<tgroup cols="2">
+
+<thead>
+<row>
+<entry>Option name</entry>
+<entry>Scope</entry>
+<entry>Description</entry>
+</row>
+</thead>
+<tbody>
+
+
+<row id="conf-ignore-modules">
+<entry><link linkend="conf-ignore-modules">ignore-modules</link></entry>
+<entry><simplelist type='vert'><member>global</member><member>module-set</member></simplelist></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Available since</member><member>1.16</member>
+</simplelist>
+<para>Note that when specified in global section, &cmd-ignore-modules; cmdline option does not override this, but instead appends.</para>
+<para>Modules named by this option, which would be chosen by &kdesrc-build;
+due to a <link linkend="conf-use-modules">use-modules</link> option, are
+instead skipped entirely. Use this option when you want to build an entire
+<link linkend="kde-projects-module-sets">kde-projects</link> project grouping
+<emphasis>except for</emphasis> some specific modules.</para>
+
+<para>The option value does not necessarily have to name the module directly.
+Any module that has full consecutive parts of its <link
+linkend="kde-projects-module-sets">&kde; projects module path</link> match one
+of the option values will be ignored, so you can ignore multiple modules this
+way.</para>
+
+<para>For example, an option value of <replaceable>libs</replaceable> would
+result in both <symbol>kde/kdegraphics/libs</symbol> and
+<symbol>playground/libs</symbol> being excluded (though not
+<symbol>kde/kdelibs</symbol> since the full part <quote>kdelibs</quote> is what
+is compared).</para>
+
+<tip><para>See also <xref linkend="example-ignoring-a-module"/>.</para></tip>
+<para>Related command-line option: <xref linkend="cmdline-ignore-modules"/></para>
+</entry>
+</row>
+
+<row id="conf-use-modules">
+<entry><link linkend="conf-use-modules">use-modules</link></entry>
+<entry><simplelist type='vert'><member>module-set</member></simplelist></entry>
+<entry>
+<simplelist type='horiz' columns='2'>
+<member>Type</member><member>String</member>
+<member>Available since</member><member>1.12.1</member>
+</simplelist>
+<para>This option allows you to easily
+specify many different modules to build at the same point in <link
+linkend="kdesrc-buildrc">the configuration file</link>.</para>
+
+<para>Every identifier passed to this option is
+internally converted to a &kdesrc-build; module, with a <link
+linkend="conf-repository"><option>repository</option></link> option set to the
+module-set's repository combined with the identifier name in order to setup the
+final repository to download from. All other options that are assigned in the
+module-set are also copied to the generated modules unaltered.</para>
+
+<para>The order that modules are defined in this option is important, because
+that is also the order that &kdesrc-build; will process the generated modules
+when updating, building, and installing. All modules defined in the given
+module-set will be handled before &kdesrc-build; moves to the next module after
+the module-set.</para>
+
+<para>If you need to change the options for a generated module, simply declare
+the module again after it is defined in the module-set, and set your options
+as needed. Although you will change the options set for the module this way,
+the module will still be updated and built in the order set by the module-set
+(i.e. you can't reorder the build sequence doing this).</para>
+
+<important><para>The name to use for the module if you do this is simply the
+name that you passed to <option>use-modules</option>, with the exception that
+any <literal>.git</literal> is removed.</para></important>
+
+<para>See <xref linkend="module-sets"/> and <link
+linkend="conf-git-repository-base">git-repository-base</link> for a description
+of its use and an example.</para>
+</entry>
+</row>
+
+</tbody>
+</tgroup>
+</table>
+
+</sect1>
diff --git a/doc/configure-data.docbook b/doc/configure-data.docbook
new file mode 100644
index 00000000..a4019619
--- /dev/null
+++ b/doc/configure-data.docbook
@@ -0,0 +1,110 @@
+<sect1 id="configure-data">
+<title>Setting the Configuration Data</title>
+
+<para>
+To use &kdesrc-build;, you should have a file in your <filename>~/.config</filename>
+(or in <envar>$XDG_CONFIG_HOME</envar>, if set) directory called
+<filename>kdesrc-buildrc</filename>, which sets the general options and
+specifies the modules you would like to download and build.
+</para>
+
+<note><para>
+It is possible to use different configuration files for &kdesrc-build;, which is
+described in <xref linkend="kdesrc-buildrc" />. If you need to use multiple
+configurations, please see that section. Here, we will assume that the
+configuration is stored in <filename>~/.config/kdesrc-buildrc</filename>.
+</para></note>
+
+<para>
+The easiest way to proceed is to use the
+<filename>kdesrc-buildrc-kf5-sample</filename> file as a template, changing global
+options to match your wants, and also change the list of modules you want to
+build.
+</para>
+
+<para>
+The default settings should be appropriate to perform a
+&kde; build. Some settings that you may wish to alter include:
+</para>
+
+<itemizedlist>
+<listitem><para><link linkend="conf-install-dir">install-dir</link>, which changes the
+destination directory that your &kde; software is installed to. This defaults to
+<filename class="directory">~/kde/usr</filename>, which is a single-user
+installation.</para></listitem>
+
+<listitem><para><link linkend="conf-branch-group">branch-group</link>, which can
+be
+used to choose the appropriate branch of development for the &kde; modules as a
+whole. There are many supported build configurations but you will likely want to
+choose <option>kf5-qt5</option> so that &kdesrc-build; downloads the latest code
+based on &Qt; 5 and &kde; Frameworks 5.</para>
+
+<tip><para>&kdesrc-build; will use a default branch group if you do not choose
+one, but this default will change over time, so it's better to choose one so
+that the branch group does not change unexpectedly.</para></tip>
+</listitem>
+
+<listitem><para><link linkend="conf-source-dir">source-dir</link>, to control the directory
+&kdesrc-build; uses for downloading the source code, running the build process, and saving
+logs.
+This defaults to <filename class="directory">~/kde/src</filename>.</para></listitem>
+
+<listitem><para><link linkend="conf-cmake-options">cmake-options</link>, which
+sets the options to pass to the &cmake; command when building each module.
+Typically this is used to set between <quote>debug</quote> or
+<quote>release</quote> builds, to enable (or disable) optional features, or to
+pass information to the build process about the location of required libraries.
+</para></listitem>
+
+<listitem><para><link linkend="conf-make-options">make-options</link>, which
+sets the options used when actually running the <application>make</application>
+command to build each module (once &cmake; has established the build system).
+</para>
+
+<para>The most typical option is <option>-j<replaceable>N</replaceable></option>,
+where <replaceable>N</replaceable> should be replaced with the maximum number of
+compile jobs you wish to allow. A higher number (up to the number of logical CPUs
+your system has available) leads to quicker builds, but requires more system resources.
+</para>
+
+<tip><para>&kdesrc-build; sets the option <option><link linkend="conf-num-cores">num-cores</link></option> to
+the detected number of available processing cores. You can use this value
+in your own configuration file to avoid having to set it manually.
+</para></tip>
+
+<example id="make-options-example">
+<title>Configuring Make to use all available CPUs, with exceptions</title>
+<screen>
+global
+ # This environment variable is automatically used by make, including
+ # make commands not run by kdesrc-build directly, such as Qt's configure
+ set-env MAKEFLAGS -j<literal>${num-cores}</literal>
+ …
+end global
+
+…
+
+module-set <replaceable>big-module-set</replaceable>
+ repository kde-projects
+ use-modules <replaceable>calligra</replaceable>
+ make-options -j2 # Reduced number of build jobs for just these modules
+end module-set
+</screen>
+</example>
+
+<note><para>Some very large Git repositories may swamp your system if you try to
+compile with a too many build jobs at one time, especially repositories like the
+&Qt; WebKit and &Qt; WebEngine repositories. To maintain system interactivity
+you may have to reduce the number of build jobs for specific modules.</para>
+<para><xref linkend="make-options-example"/> gives an example of how to do
+this.</para>
+</note>
+
+</listitem>
+</itemizedlist>
+
+<para>You may want to select different modules to build,
+which is described in <xref linkend="selecting-modules"/>.</para>
+
+</sect1>
diff --git a/doc/credits-and-license.docbook b/doc/credits-and-license.docbook
new file mode 100644
index 00000000..c1cde3c6
--- /dev/null
+++ b/doc/credits-and-license.docbook
@@ -0,0 +1,7 @@
+<chapter id="credits-and-license">
+<title>Credits And License</title>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+&underFDL;
+
+</chapter>
diff --git a/doc/developer-features.docbook b/doc/developer-features.docbook
new file mode 100644
index 00000000..1a5dc69a
--- /dev/null
+++ b/doc/developer-features.docbook
@@ -0,0 +1,33 @@
+<sect1 id="developer-features">
+<title>Features for &kde; developers</title>
+
+<sect2 id="ssh-agent-reminder">
+<title>&ssh; Agent checks</title>
+<para>&kdesrc-build; can ensure that &kde; developers that use &ssh; to
+access the &kde; source repository do not accidentally forget to leave the
+&ssh; Agent tool enabled. This can cause &kdesrc-build; to hang indefinitely
+waiting for the developer to type in their &ssh; password,
+so by default &kdesrc-build; will check if the Agent is running before
+performing source updates.
+</para>
+
+<note><para>This is only done for &kde; developers using &ssh;.
+</para></note>
+
+<para>You may wish to disable the &ssh; Agent check, in case of situations where
+&kdesrc-build; is mis-detecting the presence of an agent. To disable the
+agent check, set the <option>disable-agent-check</option> option to
+<userinput>true</userinput>.</para>
+
+<informalexample>
+<para>Disabling the &ssh; agent check:</para>
+<screen>
+global
+ disable-agent-check true
+end global
+</screen>
+</informalexample>
+
+</sect2>
+
+</sect1>
diff --git a/doc/environment.docbook b/doc/environment.docbook
new file mode 100644
index 00000000..d5929b59
--- /dev/null
+++ b/doc/environment.docbook
@@ -0,0 +1,127 @@
+<sect1 id="environment">
+<title>Setting the Environment to Run Your &kde; &plasma; Desktop</title>
+
+<para>
+Assuming you are using a dedicated user to build &kde; &plasma;, and you already have an
+installed &plasma; version, running your new &plasma; may be a bit tricky, as the new
+&plasma; has to take precedence over the old. You must change the environment
+variables of your login scripts to make sure the newly-built desktop is used.
+</para>
+
+<sect2 id="session-driver">
+<title>Automatically installing a login driver</title>
+
+<para>Starting from version 1.16, &kdesrc-build; will try to install an
+appropriate login driver, that will allow you to login to your
+&kdesrc-build;-built &kde; desktop from your login manager. This can be
+disabled by using the <option><link
+linkend="conf-install-session-driver">install-session-driver</link></option>
+configuration file option.</para>
+
+<note><para>Session setup does not occur while &kdesrc-build; is running
+in pretend mode.</para></note>
+
+<para>This driver works by setting up a custom <quote><literal>xsession</literal></quote>
+session type. This type of session should work by default with the sddm login
+manager (where it appears as a <quote>Custom</quote> session), but other login
+managers (such as <application>LightDM</application> and
+<application>gdm</application>) may require additional files installed to
+enable <literal>xsession</literal> support.</para>
+
+<sect3 id="xsession-distribution-setup">
+<title>Adding xsession support for distributions</title>
+
+<para>The default login managers for some distributions may require additional
+packages to be installed in order to support <literal>xsession</literal> logins.</para>
+
+<itemizedlist>
+<listitem><para>The <ulink url="https://getfedora.org/">Fedora</ulink>
+&Linux; distribution requires the <literal>xorg-x11-xinit-session</literal>
+package to be installed for custom <literal>xsession</literal> login
+support.</para></listitem>
+
+<listitem><para><ulink url="https://www.debian.org/">Debian</ulink> and
+Debian-derived &Linux; distributions should support custom
+<literal>xsession</literal> logins, but require the
+<option><userinput>allow-user-xsession</userinput></option> option to be set in
+<filename>/etc/X11/Xsession.options</filename>. See also the Debian <ulink
+url="https://www.debian.org/doc/manuals/debian-reference/ch07.en.html#_customizing_the_x_session_classic_method">documentation
+on customizing the X session.</ulink></para></listitem>
+
+<listitem><para>For other distributions, go to <xref
+linkend="xsession-manual-setup"/>.</para></listitem>
+</itemizedlist>
+
+</sect3>
+
+<sect3 id="xsession-manual-setup">
+<title>Manually adding support for xsession</title>
+
+<para>If there were no distribution-specific directions for your distribution
+in <xref linkend="xsession-distribution-setup"/>, you can manually add a
+<quote>Custom xsession login</quote> entry to your distribution's list of
+session types as follows:</para>
+
+<procedure id="proc-adding-xsession-type">
+<title>Adding an .xsession login session type.</title>
+
+<note><para>This procedure will likely require administrative privileges to
+complete.
+</para></note>
+
+<step performance="required">
+<para>Create the file
+<filename>/usr/share/xsessions/kdesrc-build.desktop</filename>.</para>
+</step>
+
+<step performance="required">
+<para>Ensure the file just created has the following text:</para>
+<literallayout><userinput>
+Type=XSession
+Exec=<co id="session-homedir"/><replaceable>$HOME</replaceable>/.xsession
+Name=KDE Plasma Desktop (unstable; kdesrc-build)
+</userinput></literallayout>
+
+<calloutlist>
+<callout arearefs="session-homedir"><para>
+The <replaceable>$HOME</replaceable> entry must be replaced by the full path to
+your home directory (example, <filename
+class="directory">/home/<replaceable>user</replaceable></filename>). The
+desktop entry specification does not allow for user-generic files.
+</para></callout>
+
+</calloutlist>
+</step>
+
+<step performance="optional"><para>When the login manager is restarted, it
+should show a new session type, <quote>KDE Plasma Desktop (unstable;
+kdesrc-build)</quote> in its list of sessions, which should try to run the
+<filename>.xsession</filename> file installed by &kdesrc-build; if it is
+selected when you login.</para>
+
+<note><para>It may be easiest to restart the computer to restart the login
+manager, if the login manager does not track updates to the <filename
+class="directory">/usr/share/xsessions</filename> directory.</para></note>
+
+</step>
+
+</procedure>
+
+</sect3>
+
+</sect2>
+
+<sect2 id="old-profile-instructions">
+<title>Setting up the environment manually</title>
+<para>This documentation used to include instruction on which environment
+variables to set in order to load up the newly-built desktop. These
+instructions have been moved to an appendix (<xref
+linkend="old-profile-setup"/>).</para>
+
+<para>If you intend to setup your own login support you can consult that
+appendix or view the <filename>kde-env-master.sh.in</filename> file
+included with the &kdesrc-build; source.</para>
+
+</sect2>
+
+</sect1>
diff --git a/doc/features.docbook b/doc/features.docbook
new file mode 100644
index 00000000..cbc46429
--- /dev/null
+++ b/doc/features.docbook
@@ -0,0 +1,185 @@
+<chapter id="features">
+<title>Script Features</title>
+
+<sect1 id="features-overview">
+<title>Feature Overview</title>
+
+<para>
+&kdesrc-build; features include:
+</para>
+
+<itemizedlist>
+
+<listitem><para>
+You can <quote>pretend</quote> to do the operations. If you pass
+<option>--pretend</option> or <option>-p</option> on the
+command line, the script will give a verbose description of the commands
+it is about to execute, without actually executing it. However if you've never
+run &kdesrc-build;, you would want to run the <command>kdesrc-build
+<option><link
+linkend="cmdline-metadata-only">--metadata-only</link></option></command>
+command first in order for <option>--pretend</option> to work.
+
+<tip><para>For an even more verbose description of what &kdesrc-build; is
+doing, try using the <option>--debug</option> option.
+</para></tip>
+
+</para></listitem>
+
+<listitem><para>
+&kdesrc-build; allows you to checkout modules quickly. If the module you are checking out
+has already been checked out previously, then &kdesrc-build; will download only commits
+that are not yet on your computer.
+</para>
+
+<tip><para>There is generally no need for any special preparation to perform
+the initial checkout of a Git module, as the entire Git repository must be
+downloaded anyways, so it is easy for the server to determine what to
+send.</para></tip>
+
+<para>This is faster for you, and helps to ease the load on the kde.org
+anonymous &git; servers.</para>
+</listitem>
+
+<listitem><para>
+Another speedup is provided by starting the build process for a module as soon
+as the source code for that module has been downloaded. (Available since
+version 1.6)
+</para></listitem>
+
+<listitem><para>
+Excellent support for building the &Qt; library (in case the &kde; software you
+are trying to build depends on a recent &Qt; not available in your
+distribution).
+</para></listitem>
+
+<listitem><para>
+&kdesrc-build; does not require a <acronym>GUI</acronym> present to operate. So,
+you can build &kde; software without needing a graphical environment.
+</para></listitem>
+
+<listitem><para>
+Supports setting default options for all modules (such as the compilation
+settings or the configuration options). Such options can normally be changed
+for specific modules as well.</para>
+
+<para>Also, &kdesrc-build; will <link linkend="kdesrc-build-std-flags">add
+standard flags</link> as appropriate to save you the trouble and possible
+errors from typing them yourself. Nota Bene: this does not apply when a (custom)
+toolchain is configured through e.g.:
+<link linkend="conf-cmake-toolchain">cmake-toolchain</link>
+</para></listitem>
+
+<listitem><para>
+&kdesrc-build; can checkout a specific <link linkend="using-branches">branch
+or tag</link> of a module. You can also ensure that a specific <link
+linkend="conf-revision">revision</link> is checked out of a module.
+</para></listitem>
+
+<listitem><para>
+&kdesrc-build; can automatically switch a source directory to checkout from
+a different repository, branch, or tag. This happens automatically when you
+change an option that changes what the repository &url; should be, but you must
+use the <link linkend="cmdline-src-only">--src-only</link> option to let
+&kdesrc-build; know that it is acceptable to perform the switch.
+</para></listitem>
+
+<listitem><para>
+&kdesrc-build; can <link linkend="partial-builds">checkout only portions of a
+module</link>, for those situations where you only need one program from a
+large module.
+</para></listitem>
+
+<listitem><para>
+For developers: &kdesrc-build; will <link linkend="ssh-agent-reminder">remind
+you</link> if you use git+ssh:// but <application>ssh-agent</application> is
+not running, as this will lead to repeated password requests from
+&ssh;.
+</para></listitem>
+
+<listitem><para>
+Can <link linkend="deleting-build-dir">delete the build directory</link> of a
+module after its installation to save space at the expense of future compilation
+time.
+</para></listitem>
+
+<listitem><para>
+The locations for the directories used by &kdesrc-build; are configurable (even
+per module).
+</para></listitem>
+
+<listitem><para>
+Can use &sudo;, or a different user-specified command
+to <link linkend="root-installation">install modules</link> so that
+&kdesrc-build; does not need to be run as the super user.
+</para></listitem>
+
+<listitem><para>
+&kdesrc-build; runs <link linkend="build-priority">with reduced priority</link>
+by default to allow you to still use your computer while &kdesrc-build; is
+working.
+</para></listitem>
+
+<listitem><para>
+Has support for using &kde;'s <link linkend="using-branches">tags and
+branches</link>.
+</para></listitem>
+
+<listitem><para>
+There is support for <link linkend="resuming">resuming a build</link> from a
+given module. You can even <link linkend="ignoring-modules">ignore some
+modules</link> temporarily for a given build.
+</para></listitem>
+
+<listitem><para>
+&kdesrc-build; will show the <link linkend="build-progress">progress of your
+build</link> when using &cmake;, and will always time the build
+process so you know after the fact how long it took.
+</para></listitem>
+
+<listitem><para>
+Comes built-in with a sane set of default options appropriate for building
+a base &kde; single-user installation from the anonymous source repositories.
+</para></listitem>
+
+<listitem><para>
+Tilde-expansion for your configuration options. For example, you can
+specify:
+<programlisting>install-dir ~/kde/usr</programlisting>
+</para></listitem>
+
+<listitem><para>
+Automatically sets up a build system, with the source directory not the
+same as the build directory, in order to keep the source directory
+pristine.
+</para></listitem>
+
+<listitem><para>
+You can specify global options to apply to every module to check out, and
+you can specify options to apply to individual modules as well.
+</para></listitem>
+
+<listitem><para>
+Forced full rebuilds, by running
+&kdesrc-build; with the <option>--refresh-build</option> option.
+</para></listitem>
+
+<listitem><para>
+You can specify various environment values to be used during the build,
+including <envar>DO_NOT_COMPILE</envar>
+and <envar>CXXFLAGS</envar>.
+</para></listitem>
+
+<listitem><para>
+Command logging. Logs are dated and numbered so that you always have a
+log of a script run. Also, a special symlink called latest is created to
+always point to the most recent log entry in the log directory.
+</para></listitem>
+
+</itemizedlist>
+
+</sect1>
+
+&kdesrc-build-logging;
+
+</chapter>
diff --git a/doc/getting-started.docbook b/doc/getting-started.docbook
new file mode 100644
index 00000000..657d8b59
--- /dev/null
+++ b/doc/getting-started.docbook
@@ -0,0 +1,223 @@
+<chapter id="getting-started">
+<title>Getting Started</title>
+
+<para>
+In this chapter, we show how to use the &kdesrc-build; to checkout modules from
+the &kde; repository and build them. We also provide a basic explanation of the
+&kde; source code structure and the steps you have to perform before running
+the script.
+</para>
+
+<para>
+All topics present in this chapter are covered with even more detail in the
+<ulink url="https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source">
+Build from Source</ulink> article, at the
+<ulink url="https://community.kde.org/">&kde; Community Wiki</ulink>.
+If you are compiling &kde; for the first time, it is a good idea to read
+it, or consult it as a reference source. You will find detailed information
+about packaging tools and requirements, common compilation pitfalls and
+strategies and information about running your new &kde; installation.
+</para>
+
+<sect1 id="before-building">
+<title>Preparing the System to Build &kde;</title>
+
+<sect2 id="before-building-users">
+<title>Setup a new user account</title>
+
+<para>
+It is recommended that you use a different user account to build, install,
+and run your &kde; software from, since less permissions are required, and
+to avoid interfering with your distribution's packages.
+If you already have &kde; packages installed, the best choice
+would be to create a different (dedicated) user to build and run the new &kde;.
+</para>
+
+<tip><para>Leaving your system &kde; untouched also allows you to have an
+emergency fallback in case a coding mistake causes your latest software build
+to be unusable.
+</para></tip>
+
+<para>
+You can do also setup to install to a system-wide directory (⪚ <filename
+class="directory">/usr/src/local</filename>) if you wish. This document
+does not cover this installation type, since we assume you know what you are doing.
+</para>
+
+</sect2>
+<sect2 id="before-building-preparation">
+<title>Ensure your system is ready to build &kde; software</title>
+
+<para>Before using the &kdesrc-build; script (or any other building
+strategy) you must install the development tools and libraries needed for &kde;.
+The nearly complete list of required tools can be found from
+the <ulink url="https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source#Install_required_devel_packages">&kde;
+Community Wiki Build Requirements</ulink> page.
+</para>
+
+<para>Here is a list of some of the things you will need:</para>
+<itemizedlist>
+
+<listitem><para>You will need &cmake;, this software is what &kde; uses to handle
+build-time configuration of the source code and generation of the specific build
+commands for your system. The required version will vary
+depending on what versions of &kde; software you are building (see TechBase for
+specifics), but with modern distributions the &cmake; included with your distribution
+should be quite sufficient.
+</para></listitem>
+
+<listitem><para>You must also install the source control clients needed to checkout
+the &kde; source code. This means you need at least the following:</para>
+
+<itemizedlist>
+<listitem><para>The <ulink url="https://git-scm.com/">Git
+source control manager</ulink>, which is used for all &kde; <ulink
+url=" https://commits.kde.org/">source code</ulink></para></listitem>
+
+<listitem><para>Although it is not required, the <ulink
+url="http://bazaar.canonical.com/">Bazaar</ulink> source control manager is
+used for a single module (libdbusmenu-qt) that is required for the &kde;
+libraries. Most users can install this library through their distribution
+packages but &kdesrc-build; supports building it as well if you desire. But to
+build libdbusmenu-qt, you must have Bazaar installed.</para></listitem>
+</itemizedlist></listitem>
+
+<listitem><para>The Perl scripting language is required for &kdesrc-build;, some &kde;
+repositories, and &Qt; (if you build that from source).</para>
+
+<para>The Perl that comes with your distribution should be suitable (it needs to be at
+least Perl 5.14), but you will also need some additional modules (&kdesrc-build;
+will warn if they are not present):</para>
+
+<itemizedlist>
+ <listitem><para>IO::Socket::SSL</para></listitem>
+ <listitem><para>JSON::PP or JSON::XS</para></listitem>
+ <listitem><para>YAML::PP, YAML::XS, or YAML::Syck</para></listitem>
+</itemizedlist>
+</listitem>
+
+<listitem><para>You will need a full C++ development environment (compiler, standard library, runtime,
+and any required development packages). The minimum required versions vary based on the &kde; module:
+the &kde; Frameworks 5 collection supports the oldest compilers, while &kde; Plasma 5 and &kde; Applications
+tend to require more recent compilers.</para>
+<para>The GCC 4.8 or Clang 4 compilers are the minimum recommended. Many distributions support easily
+installing these tools using a <quote>build-essentials</quote> package, an option to install
+"build dependencies" with &Qt;, or similar features. The KDE Community Wiki has a page <ulink url="https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source/Install_the_dependencies">tracking
+recommended packages for major distributions</ulink>.
+</para>
+</listitem>
+
+<listitem><para>You will need a build tool that actually performs the
+compilation steps (as generated by &cmake;). GNU Make is recommended and should
+be available through your package manager. &cmake; does support others options, such
+as the &ninja; build tool, which can be used by &kdesrc-build; using the
+<link linkend="conf-custom-build-command">custom-build-command</link> configuration file
+option.
+</para></listitem>
+
+<listitem><para>Finally, you will need the appropriate &Qt; libraries (including development packages)
+for the version of &kde; software you are building. &kdesrc-build; does not officially support building &Qt; 5 (the current major version), so it is recommended to use your distribution's development packages or to
+see the KDE Community wiki page on <ulink url="https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source/OwnQt5">self-building Qt 5</ulink>.
+</para></listitem>
+</itemizedlist>
+
+<note><para>Most operating system distributions include a method of easily
+installing required development tools. Consult the Community Wiki page <ulink
+url="https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source#Install_required_devel_packages"
+>Required devel packages</ulink> to see
+if these instructions are already available.</para></note>
+
+<important><para>
+Some of these packages are divided into libraries (or programs or utilities),
+and development packages. You will need at least the program or library
+<emphasis>and</emphasis> its development package.
+</para></important>
+
+</sect2>
+
+<sect2 id="before-building-prepare-script">
+<title>Setup &kdesrc-build;</title>
+
+<sect3 id="get-kdesrc-build">
+<title>Install &kdesrc-build;</title>
+<para>
+The &kde; developers make frequent changes to &kdesrc-build; to keep it in
+sync with advances in &kde; development, including improvements to the
+recommended &kdesrc-build; configuration, added modules, improving &cmake;
+flags, &etc;</para>
+
+<para>Because of this, we recommend obtaining &kdesrc-build; directly from its
+source repository and then periodically updating it.</para>
+
+<para>You can obtain &kdesrc-build; from its source repository by running:</para>
+<programlisting>
+<prompt>$ </prompt><userinput><command>git <option>clone</option> <option>https://invent.kde.org/sdk/kdesrc-build.git</option> <option><filename class="directory"><replaceable>~/kdesrc-build</replaceable></filename></option></command></userinput>
+</programlisting>
+
+<para>Replace <option><replaceable>~/kdesrc-build</replaceable></option> with
+the directory you would like to install to.
+</para>
+
+<para>You can update &kdesrc-build; later by running:</para>
+<programlisting>
+<prompt>$ </prompt><userinput><command>cd <option><filename class="directory"><replaceable>~/kdesrc-build</replaceable></filename></option></command></userinput>
+<prompt>$ </prompt><userinput><command>git <option>pull</option></command></userinput>
+</programlisting>
+
+<tip><para>We recommend adding the &kdesrc-build; installation directory to
+your <envar>PATH</envar> environment variable, so that you can run &kdesrc-build;
+without having to fully specify its path every time.</para></tip>
+</sect3>
+
+<sect3 id="setup-rcfile">
+<title>Prepare the configuration file</title>
+
+<para>&kdesrc-build; uses a <link linkend="configure-data">configuration file</link>
+to control which modules are built, where they are installed to, etc.
+This file is located at <filename>~/.config/kdesrc-buildrc</filename>
+(<filename>$XDG_CONFIG_HOME/kdesrc-buildrc</filename>, if
+<envar>$XDG_CONFIG_HOME</envar> is set).</para>
+
+<para>You can use <application>kdesrc-build --generate-config</application> in order to prepare a simple
+kdesrc-build configuration. You can then edit the
+<filename>~/.config/kdesrc-buildrc</filename> configuration file to make
+any changes you see fit.</para>
+
+<sect4 id="setup-rcfile-manually">
+<title>Manual setup of configuration file</title>
+
+<para>You can also setup your configuration file manually, by copying the
+included sample configuration file <filename>kdesrc-buildrc-kf5-sample</filename>
+to <filename>~/.config/kdesrc-buildrc</filename> and then editing the file.
+<xref linkend="kdesrc-buildrc"/> will be a useful reference for this, especially
+its <link linkend="conf-options-table">table of configuration options</link>.
+</para>
+
+<para>&kdesrc-build; contains many recommended configuration files to support
+&kde; Frameworks 5, &plasma; 5, and other &kde; applications. See
+<xref linkend="kdesrc-buildrc-including"/> for information on how to use other
+configuration files from your own <filename>kdesrc-buildrc</filename>.
+</para>
+
+<para>You can find more information about the syntax of the <link
+linkend="configure-data">configuration file</link> in <xref
+linkend="configure-data" /> and in <xref linkend="kdesrc-buildrc" />.
+</para>
+</sect4>
+</sect3>
+</sect2>
+</sect1>
+
+&configure-data;
+
+&building-and-troubleshooting;
+
+&building-specific-modules;
+
+&environment;
+
+&kde-modules-and-selection;
+
+&quick-start-conclusion;
+
+</chapter>
diff --git a/doc/index.docbook b/doc/index.docbook
new file mode 100644
index 00000000..e6164101
--- /dev/null
+++ b/doc/index.docbook
@@ -0,0 +1,173 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
+ <!--
+ Documentation for kdesrc-build.
+ Copyright (c) 2005-2008, 2010-2022 Michael Pyne <mpyne at kde.org>
+
+ Copyright (c) 2005 Carlos Leonhard Woelz <carloswoelz at imap-mail.com>
+ Copyright (c) 2009 Burkhard Lück <lueck at hube-lueck.de>
+ Copyright (c) 2007, 2011 Federico Zenith <federico.zenith at members.fsf.org>
+ Copyright (c) 2009-2011 Yuri Chornoivan <yurchor at ukr.net>
+ ... and possibly others. Check the git source repository for specifics.
+
+ Permission is granted to copy, distribute and/or modify this document under
+ the terms of the GNU Free Documentation License, Version 1.2 or any later
+ version published by the Free Software Foundation; with no Invariant
+ Sections, no Front-Cover Texts, and no Back-Cover Texts.
+
+ A copy of the license is included in COPYING.DOC. The license will be
+ included in the generated documentation as well.
+ -->
+ <!ENTITY kappname "kdesrc-build">
+ <!ENTITY package "kdesdk">
+ <!ENTITY % addindex "IGNORE">
+ <!ENTITY % English "INCLUDE"> <!-- Change language only here -->
+ <!ENTITY kdesrc-build "<application>kdesrc-build</application>">
+ <!ENTITY BSD '<acronym>BSD</acronym>'>
+ <!ENTITY git '<application>Git</application>'>
+ <!ENTITY cmake '<application>CMake</application>'>
+ <!ENTITY make '<application>Make</application>'>
+ <!ENTITY ninja '<application>Ninja</application>'>
+ <!ENTITY ssh '<application>SSH</application>'>
+ <!ENTITY cron '<application>Cron</application>'>
+ <!ENTITY sudo '<application>Sudo</application>'>
+ <!ENTITY url '<acronym>URL</acronym>'>
+
+ <!-- These define shortcut entities for some of the configuration options.
+ Just add them as necessary.
+ -->
+
+ <!ENTITY configure-flags '<link linkend="conf-configure-flags">configure-flags</link>'>
+ <!ENTITY install-dir '<link linkend="conf-install-dir">install-dir</link>'>
+ <!ENTITY build-dir '<link linkend="conf-build-dir">build-dir</link>'>
+ <!ENTITY source-dir '<link linkend="conf-source-dir">source-dir</link>'>
+ <!ENTITY colorful-output '<link linkend="conf-colorful-output">colorful-output</link>'>
+ <!ENTITY tag '<link linkend="conf-tag">tag</link>'>
+ <!ENTITY branch '<link linkend="conf-branch">branch</link>'>
+ <!ENTITY do-not-compile '<link linkend="conf-do-not-compile">do-not-compile</link>'>
+ <!ENTITY repository '<link linkend="conf-repository">repository</link>'>
+ <!ENTITY make-install-prefix '<link linkend="conf-make-install-prefix">make-install-prefix</link>'>
+ <!ENTITY niceness '<link linkend="conf-niceness">niceness</link>'>
+ <!ENTITY set-env '<link linkend="conf-set-env">set-env</link>'>
+ <!ENTITY libname '<link linkend="conf-libname">libname</link>'>
+ <!ENTITY libpath '<link linkend="conf-libpath">libpath</link>'>
+ <!ENTITY binpath '<link linkend="conf-binpath">binpath</link>'>
+
+ <!-- These define shortcut entities for some of the command line options.
+ Just add them as necessary.
+ -->
+ <!ENTITY cmd-nice '<link linkend="cmdline-nice">--nice</link>'>
+ <!ENTITY cmd-ignore-modules '<link linkend="cmdline-ignore-modules">--ignore-modules</link>'>
+ <!ENTITY cmd-resume-from '<link linkend="cmdline-resume-from">--resume-from</link>'>
+ <!ENTITY cmd-resume-after '<link linkend="cmdline-resume-after">--resume-after</link>'>
+ <!ENTITY cmd-reconfigure '<link linkend="cmdline-reconfigure">--reconfigure</link>'>
+ <!ENTITY cmd-refresh-build '<link linkend="cmdline-refresh-build">--refresh-build</link>'>
+
+ <!-- These define docbook files to include.
+ Just add them as necessary.
+ -->
+ <!ENTITY advanced-features SYSTEM "advanced-features.docbook">
+ <!ENTITY appendix-modules SYSTEM "appendix-modules.docbook">
+ <!ENTITY appendix-profile SYSTEM "appendix-profile.docbook">
+ <!ENTITY basic-features SYSTEM "basic-features.docbook">
+ <!ENTITY building-and-troubleshooting SYSTEM "building-and-troubleshooting.docbook">
+ <!ENTITY building-specific-modules SYSTEM "building-specific-modules.docbook">
+ <!ENTITY cmdline SYSTEM "cmdline.docbook">
+ <!ENTITY conf-options-table SYSTEM "conf-options-table.docbook">
+ <!ENTITY configure-data SYSTEM "configure-data.docbook">
+ <!ENTITY credits-and-license SYSTEM "credits-and-license.docbook">
+ <!ENTITY developer-features SYSTEM "developer-features.docbook">
+ <!ENTITY environment SYSTEM "environment.docbook">
+ <!ENTITY features SYSTEM "features.docbook">
+ <!ENTITY getting-started SYSTEM "getting-started.docbook">
+ <!ENTITY intro-toc SYSTEM "intro-toc.docbook">
+ <!ENTITY introduction SYSTEM "introduction.docbook">
+ <!ENTITY kde-cmake SYSTEM "kde-cmake.docbook">
+ <!ENTITY kde-modules-and-selection SYSTEM "kde-modules-and-selection.docbook">
+ <!ENTITY kdesrc-build-logging SYSTEM "kdesrc-build-logging.docbook">
+ <!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">
+ <!ENTITY supported-envvars SYSTEM "supported-envvars.docbook">
+ <!ENTITY using-kdesrc-build SYSTEM "using-kdesrc-build.docbook">
+]>
+
+<book id="kdesrc-build" lang="&language;">
+
+<bookinfo>
+<title>&kdesrc-build; Script Manual</title>
+
+<authorgroup id="authors">
+ <author>&Michael.Pyne; &Michael.Pyne.mail;</author>
+ <author>
+ <personname><firstname>Carlos</firstname><surname>Woelz</surname></personname>
+ <email>carloswoelz at imap-mail.com</email>
+ </author>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+
+</authorgroup>
+
+<copyright>
+<year>2006</year>
+<year>2007</year>
+<year>2008</year>
+<year>2009</year>
+<year>2010</year>
+<year>2011</year>
+<year>2012</year>
+<year>2013</year>
+<year>2014</year>
+<year>2015</year>
+<year>2016</year>
+<year>2017</year>
+<year>2018</year>
+<year>2019</year>
+<holder>Michael Pyne</holder>
+</copyright>
+
+<copyright>
+<year>2005</year>
+<holder>Carlos Woelz</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+<date>2018-01-20</date>
+<releaseinfo>&kdesrc-build; 17.12</releaseinfo>
+
+<abstract>
+<para>&kdesrc-build; is a script which builds and installs &kde; software
+directly from the &kde; project's source code repositories.</para>
+</abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>kdesdk</keyword>
+<keyword>git</keyword>
+<keyword>KDE development</keyword>
+</keywordset>
+
+</bookinfo>
+
+&introduction;
+
+&getting-started;
+
+&features;
+
+&kdesrc-buildrc;
+
+&cmdline;
+
+&using-kdesrc-build;
+
+&kde-cmake;
+
+&credits-and-license;
+
+&appendix-modules;
+
+&appendix-profile;
+</book>
diff --git a/doc/intro-toc.docbook b/doc/intro-toc.docbook
new file mode 100644
index 00000000..00b36bf6
--- /dev/null
+++ b/doc/intro-toc.docbook
@@ -0,0 +1,22 @@
+<sect1 id="intro-toc">
+<title>Documentation Overview</title>
+
+<para>
+This guide is an overview to describe the following aspects of &kdesrc-build;
+operation:
+</para>
+
+<itemizedlist>
+<listitem><para>An <link linkend="getting-started">overview</link> of the steps
+required to get started.</para></listitem>
+<listitem><para>Notable <link linkend="features">features</link>.</para></listitem>
+<listitem><para>The <link linkend="configure-data">configuration file</link> syntax
+and options.</para></listitem>
+<listitem><para>The <link linkend="cmdline">command line options</link>.</para></listitem>
+</itemizedlist>
+
+<para>Also documented are the steps which you should perform using
+other tools (&ie; steps that are not automatically performed by &kdesrc-build;).
+</para>
+
+</sect1>
diff --git a/doc/introduction.docbook b/doc/introduction.docbook
new file mode 100644
index 00000000..e6ca3256
--- /dev/null
+++ b/doc/introduction.docbook
@@ -0,0 +1,67 @@
+<chapter id="introduction">
+<title>Introduction</title>
+
+<sect1 id="brief-intro">
+<title>A brief introduction to &kdesrc-build;</title>
+
+<sect2 id="whatis-kdesrc-build">
+<title>What is &kdesrc-build;?</title>
+
+<para>
+&kdesrc-build; is a script to help the &kde; community install <ulink
+url="https://www.kde.org/">&kde;</ulink> software from its <ulink
+url="https://git-scm.com/">&git;</ulink> source repositories,
+and continue to update that software afterwards.
+It is particularly intended to support those who need to supporting testing and
+development of &kde; software, including users testing bugfixes and developers
+working on new features.
+</para>
+
+<para>The &kdesrc-build; script can be configured to maintain a single individual
+module, a full &plasma; desktop with &kde; application set, or somewhere in between.
+</para>
+
+<para>To get started, see <xref linkend="getting-started"/>, or continue reading for more
+detail on how &kdesrc-build; works and what is covered in this documentation.
+</para>
+</sect2>
+
+<sect2 id="operation-in-a-nutshell">
+<title>&kdesrc-build; operation <quote>in a nutshell</quote></title>
+
+<para>&kdesrc-build; works by using the tools available to the user at the
+command-line, using the same interfaces available to the user. When
+&kdesrc-build; is run, the following sequence is followed: </para>
+
+<orderedlist>
+<listitem><para>&kdesrc-build; reads in the <link linkend="cmdline">command
+line</link> and <link linkend="configure-data">configuration file</link>, to
+determine what to build, compile options to use, where to install,
+&etc;</para></listitem>
+
+<listitem><para>&kdesrc-build; performs a source update for each <link
+linkend="module-concept">module</link>. The update continues until all modules
+have been updated. Modules that fail to update normally do not stop the build
+– you will be notified at the end which modules did not
+update.</para></listitem>
+
+<listitem><para>Modules that were successfully updated are built, have their
+test suite run, and are then installed. To reduce the overall time spent,
+&kdesrc-build; will by default start building the code as soon as the first
+module has completed updating, and allow the remaining updates to continue
+behind the scenes.
+</para></listitem>
+</orderedlist>
+
+<tip><para>A <emphasis>very good</emphasis> overview of how &kde; modules are
+built, including informative diagrams, is provided on <ulink
+url="https://www.davidrevoy.com/article193/guide-building-krita-on-linux-for-
+cats">an online article discussing &kde;'s &krita; application</ulink>. This
+workflow is what &kdesrc-build; automates for all &kde; modules.</para>
+</tip>
+
+</sect2>
+</sect1>
+
+&intro-toc;
+</chapter>
diff --git a/doc/kde-cmake.docbook b/doc/kde-cmake.docbook
new file mode 100644
index 00000000..9c818591
--- /dev/null
+++ b/doc/kde-cmake.docbook
@@ -0,0 +1,29 @@
+<chapter id="kde-cmake">
+<title>&cmake;, the &kde; build system</title>
+
+<sect1 id="kde-cmake-intro">
+<title>Introduction to &cmake;</title>
+
+<para>In March 2006, the &cmake; program
+beat out several competitors and was selected to be the build system for &kde; 4, replacing the
+autotools-based system that &kde; had used from the beginning.</para>
+
+<para>A introduction to &cmake; page is available on the <ulink
+url="https://community.kde.org/Guidelines_HOWTOs/CMake">&kde; Community Wiki</ulink>.
+Basically, instead of running <userinput><command>make</command> <option>-f</option>
+<filename>Makefile.cvs</filename></userinput>, then <command>configure</command>,
+then &make;, we simply run &cmake; and then &make;.
+</para>
+
+<para>&kdesrc-build; has support for &cmake;. A few features of &kdesrc-build;
+were really features of the underlying buildsystem, including
+<link linkend="conf-configure-flags">configure-flags</link>
+and <link linkend="conf-do-not-compile">do-not-compile</link>. When equivalent
+features are available, they are provided. For instance, the equivalent to the
+configure-flags option is <link linkend="conf-cmake-options">cmake-options</link>, and the
+<link linkend="conf-do-not-compile">do-not-compile</link> option is also supported for &cmake;
+as of &kdesrc-build; version 1.6.3.
+</para>
+
+</sect1>
+</chapter>
diff --git a/doc/kde-modules-and-selection.docbook b/doc/kde-modules-and-selection.docbook
new file mode 100644
index 00000000..83697b3e
--- /dev/null
+++ b/doc/kde-modules-and-selection.docbook
@@ -0,0 +1,353 @@
+<sect1 id="kde-modules-and-selection">
+<title>Module Organization and selection</title>
+
+<sect2 id="kde-layers">
+<title>KDE Software Organization</title>
+
+<para>
+&kde; software is split into different components, many of which can be built
+by &kdesrc-build;. Understanding this organization will help you properly
+select the software modules that you want built.
+</para>
+
+<orderedlist>
+<listitem><para>At the lowest level comes the &Qt; library, which is a
+very powerful, cross-platform <quote>toolkit</quote> library. &kde; is based on
+&Qt;, and some of the non-&kde; libraries required by &kde; are also based on
+&Qt;. &kdesrc-build; can build &Qt;, or use the one already installed on your
+system if it is a recent enough version.</para></listitem>
+
+<listitem><para>On top of &Qt; are required libraries that are necessary for
+&kde; software to work. Some of these libraries are not considered part of
+&kde; itself due to their generic nature, but are still essential to the &kde;
+Platform. These libraries are collected under a <literal>kdesupport</literal>
+module grouping but are not considered part of the <quote>Frameworks</quote>
+libraries.</para>
+</listitem>
+
+<listitem><para>On top of these essential libraries come the <ulink
+url="https://community.kde.org/Frameworks">&kde; Frameworks</ulink>, sometimes
+abbreviated as KF5, which are essential libraries for the &kde; Plasma desktop,
+&kde; Applications, and other third-party software.
+</para> </listitem>
+
+<listitem><para>On top of the Frameworks, come several different things:</para>
+ <itemizedlist>
+ <listitem><para><quote>Third-party</quote> applications. These are
+ applications that use the &kde; Frameworks or are designed to run under
+ &kde; Plasma but are not authored by or in association with the &kde;
+ project.</para></listitem>
+
+ <listitem><para>Plasma, which is a full <quote>workspace</quote> desktop
+ environment. This is what users normally see when they <quote>log-in to
+ &kde;</quote>.</para></listitem>
+
+ <listitem><para>The &kde; Application suite. This is a collection of
+ useful software included with the Platform and &plasma; Desktop, grouped into
+ individual modules, including utilities like &dolphin;, games like
+ <application>KSudoku</application>, and productivity software released by &kde;
+ such as &kontact;.</para></listitem>
+
+ <listitem><para>Finally, there is a collection of software (also
+ collected in modules) whose development is supported by &kde; resources
+ (such as translation, source control, bug tracking, &etc;) but is not
+ released by &kde; as part of Plasma or the Application suite. These
+ modules are known as <quote>Extragear</quote>.
+ </para></listitem>
+ </itemizedlist>
+</listitem>
+</orderedlist>
+</sect2>
+
+<sect2 id="selecting-modules">
+<title>Selecting modules to build</title>
+
+<para>Selecting which of the possible modules to build is controlled by
+<link linkend="kdesrc-buildrc">the configuration file</link>.
+After the <literal>global</literal> section is a list of modules to build,
+bracketed by module ... end module lines. An example entry for a module is
+shown in <xref linkend="conf-module-example"/>.</para>
+
+<example id="conf-module-example">
+<title>Example module entry in the configuration file</title>
+<programlisting>
+module <replaceable>kdesrc-build-git</replaceable>
+ # Options for this module go here, example:
+ <link linkend="conf-repository">repository</link> kde:kdesrc-build
+ <link linkend="conf-make-options">make-options</link> -j4 # Run 4 compiles at a time
+end module
+</programlisting>
+</example>
+
+<note><para>In practice, this module construct is not usually used directly. Instead
+most modules are specified via module-sets as described below.</para></note>
+
+<para>When using only <literal>module</literal> entries, &kdesrc-build; builds them in the order
+you list, and does not attempt to download any other repositories other than what you specify
+directly.
+</para>
+
+</sect2>
+
+<sect2 id="module-sets">
+<title>Module Sets</title>
+
+<para>The &kde; source code is decomposed into a great number of relatively
+small Git-based repositories. To make it easier to manage the large number of
+repositories involved in any useful &kde;-based install, &kdesrc-build; supports
+grouping multiple modules and treating the group as a <quote>module set</quote>.
+</para>
+
+<sect3 id="module-set-concept">
+<title>The basic module set concept</title>
+
+<para>By using a module set, you can quickly declare many Git modules to be
+downloaded and built, as if you'd typed out a separate module declaration for
+each one. The <link linkend="conf-repository">repository</link> option is
+handled specially to setup where each module is downloaded from, and every
+other option contained in the module set is copied to every module generated
+in this fashion.</para>
+
+<example id="example-using-module-sets">
+<title>Using module sets</title>
+<programlisting>
+global
+ <option><link linkend="conf-git-repository-base">git-repository-base</link></option> <replaceable>kde-git</replaceable> <replaceable>kde:</replaceable>
+end global
+
+module <replaceable>qt</replaceable>
+ # Options removed for brevity
+end module
+
+module-set <replaceable>kde-support-libs</replaceable>
+ <option><link linkend="conf-repository">repository</link></option> <replaceable>kde-git</replaceable>
+ <option><link linkend="conf-use-modules">use-modules</link></option> <replaceable>automoc</replaceable> <replaceable>attica</replaceable> <replaceable>akonadi</replaceable>
+end module-set
+
+# Other modules as necessary...
+module <replaceable>kdesupport</replaceable>
+end module
+</programlisting>
+</example>
+
+<para>In <xref linkend="example-using-module-sets"/> a brief module set is
+shown. When &kdesrc-build; encounters this module set, it acts as if, for
+every module given in <option>use-modules</option>, that an individual module
+has been declared, with its <option>repository</option> equal to the
+module-set's <option>repository</option> followed immediately by the given
+module name.</para>
+
+<para>In addition, other options can be passed in a module set, which are
+copied to every new module that is created this way. By using module-set it is
+possible to quickly declare many Git modules that are all based on the same
+repository URL. In addition, it is possible to give module-sets a name (as shown
+in the example), which allows you to quickly refer to the entire group of
+modules from the command line.</para>
+
+</sect3>
+<sect3 id="module-sets-kde">
+<title>Special Support for KDE module sets</title>
+
+<para>The module set support described so far is general to any Git-based
+modules. For the &kde; Git repositories, &kdesrc-build; includes additional
+features to make things easier for users and developers. This support is
+enabled by specifying <literal>kde-projects</literal> as the
+<option>repository</option> for the module set.
+</para>
+
+<para>&kdesrc-build; normally only builds the modules you have listed in your
+configuration file, in the order you list them. But with a
+<literal>kde-projects</literal> module set, &kdesrc-build; can do dependency
+resolution of &kde;-specific modules, and in addition automatically include
+modules into the build even if only indirectly specified.</para>
+
+<example id="example-using-kde-module-sets">
+<title>Using kde-projects module sets</title>
+<programlisting>
+# Only adds a module for juk (the kde/kdemultimedia/juk repo)
+module-set <replaceable>juk-set</replaceable>
+ <option>repository</option> kde-projects
+ <option>use-modules</option> <replaceable>juk</replaceable>
+end module-set
+
+# Adds all modules that are in kde/multimedia/*, including juk,
+# but no other dependencies
+module-set <replaceable>multimedia-set</replaceable>
+ <option>repository</option> kde-projects
+ <option>use-modules</option> <replaceable>kde/multimedia</replaceable>
+end module-set
+
+# Adds all modules that are in kde/multimedia/*, and all kde-projects
+# dependencies from outside of kde/kdemultimedia
+module-set <replaceable>multimedia-deps-set</replaceable>
+ <option>repository</option> kde-projects
+ <option>use-modules</option> <replaceable>kde/multimedia</replaceable>
+ <option>include-dependencies</option> <replaceable>true</replaceable>
+end module-set
+
+# All modules created out of these three module sets are automatically put in
+# proper dependency order, regardless of the setting for include-dependencies
+</programlisting>
+</example>
+
+<tip><para>This <literal>kde-projects</literal> module set construct is the main method
+of declaring which modules you want to build.</para></tip>
+
+<para>All module sets use the <link linkend="conf-repository">repository</link>
+and <link linkend="conf-use-modules">use-modules</link> options. <link
+linkend="kde-projects-module-sets"><literal>kde-projects</literal></link> module
+sets have a predefined <option>repository</option> value, but other types of
+module sets also will use the <link
+linkend="conf-git-repository-base">git-repository-base</link> option.
+</para>
+</sect3>
+
+</sect2>
+
+<sect2 id="kde-projects-module-sets">
+<title>The official &kde; module database</title>
+
+<para>&kde;'s Git repositories allow for grouping related Git modules into
+collections of related modules (e.g. kdegraphics). Git doesn't recognize these
+groupings, but &kdesrc-build; can understand these groups, using <link
+linkend="module-sets">module sets</link> with a <option>repository</option>
+option set to <quote><literal>kde-projects</literal></quote>.</para>
+
+<para>&kdesrc-build; will recognize that the <literal>kde-projects</literal>
+repository requires special handling, and adjust the build process
+appropriately. Among other things, &kdesrc-build; will:</para>
+
+<itemizedlist>
+
+<listitem><para>Download the latest module database from the <ulink
+url=" https://commits.kde.org/">&kde; git archive</ulink>.</para></listitem>
+
+<listitem><para>Try to find a module with the name given in the module set's
+<option>use-modules</option> setting in that database.</para></listitem>
+
+<listitem><para>For every module that is found, &kdesrc-build; will lookup the
+appropriate repository in the database, based upon the <link
+linkend="conf-branch-group">branch-group</link> setting in effect. If a
+repository exists and is active for the branch group, &kdesrc-build; will
+automatically use that to download or update the source code.
+</para></listitem>
+
+</itemizedlist>
+
+<note><para>In the current database, some module groups not only have a
+collection of modules, but they <emphasis>also</emphasis> declare their own
+&git; repository. In these situations &kdesrc-build; will currently prefer the
+group's &git; repository instead of including the childrens' repositories.
+</para></note>
+
+<para>The following example shows how to use the &kde; module database to
+install the Phonon multimedia library.</para>
+
+<informalexample>
+<programlisting>
+module-set <replaceable>media-support</replaceable>
+ # This option must be kde-projects to use the module database.
+ <option><link linkend="conf-repository">repository</link></option> <literal>kde-projects</literal>
+
+ # This option chooses what modules to look for in the database.
+ <option><link linkend="conf-use-modules">use-modules</link></option> <replaceable>phonon/phonon</replaceable> <replaceable>phonon-gstreamer</replaceable> <replaceable>phonon-vlc</replaceable>
+end module-set
+</programlisting>
+</informalexample>
+
+<tip><para><literal>phonon/phonon</literal> is used since (with the current
+project database) &kdesrc-build; would otherwise have to decide between the
+group of projects called <quote>phonon</quote> or the individual project named
+<quote>phonon</quote>. Currently &kdesrc-build; would pick the former, which
+would build many more backends than needed.</para></tip>
+
+<para>The following example is perhaps more realistic, and shows a feature only
+available with the &kde; module database: Building all of the &kde; graphics
+applications with only a single declaration.</para>
+
+<informalexample>
+<programlisting>
+module-set <replaceable>kdegraphics</replaceable>
+ # This option must be kde-projects to use the module database.
+ <option><link linkend="conf-repository">repository</link></option> <literal>kde-projects</literal>
+
+ # This option chooses what modules to look for in the database.
+ <option><link linkend="conf-use-modules">use-modules</link></option> <literal>kdegraphics/libs</literal> <literal>kdegraphics/*</literal>
+end module-set
+</programlisting>
+</informalexample>
+
+<para>There are two important abilities demonstrated here:</para>
+
+<orderedlist>
+
+<listitem><para>&kdesrc-build; allows you to specify modules that are
+descendents of a given module, without building the parent module, by using the
+syntax <userinput><replaceable>module-name</replaceable>/*</userinput>. It is
+actually required in this case since the base module, kdegraphics, is marked as
+inactive so that it is not accidentally built along with its children modules.
+Specifying the descendent modules allows &kdesrc-build; to skip around the
+disabled module.
+</para></listitem>
+
+<listitem><para>&kdesrc-build; will also not add a given module to the build
+list more than once. This allows us to manually set
+<literal>kdegraphics/libs</literal> to build first, before the rest of
+<literal>kdegraphics</literal>, without trying to build
+<literal>kdegraphics/libs</literal> twice. This used to be required for proper
+dependency handling, and today remains a fallback option in case the &kde;
+project database is missing dependency metadata.
+</para></listitem>
+</orderedlist>
+</sect2>
+
+<sect2 id="ignoring-project-modules">
+<title>Filtering out &kde; project modules</title>
+
+<para>You might decide that you'd like to build all programs within a &kde;
+module grouping <emphasis>except</emphasis> for a given program.</para>
+
+<para>For instance, the <literal>kdeutils</literal> group includes a program
+named <application>kremotecontrol</application>. If your computer does not have
+the proper hardware to receive the signals sent by remote controls then you may
+decide that you'd rather not download, build, and install
+<application>kremotecontrol</application> every time you update
+<literal>kdeutils</literal>.</para>
+
+<para>You can achieve this by using the <link
+linkend="conf-ignore-modules">ignore-modules</link> configuration option.
+On the command line the
+<link linkend="ignoring-modules">&cmd-ignore-modules; option</link>
+does the same thing, but is more convenient for filtering out a module just once.
+</para>
+
+<example id="example-ignoring-a-module">
+<title>Example for ignoring a kde-project module in a group</title>
+<programlisting>
+module-set <replaceable>utils</replaceable>
+ <option><link linkend="conf-repository">repository</link></option> <literal>kde-projects</literal>
+
+ # This option chooses what modules to look for in the database.
+ <option><link linkend="conf-use-modules">use-modules</link></option> <replaceable>kdeutils</replaceable>
+
+ # This option "subtracts out" modules from the modules chosen by use-modules, above.
+ <option><link linkend="conf-ignore-modules">ignore-modules</link></option> <replaceable>kremotecontrol</replaceable>
+end module-set
+
+module-set <replaceable>graphics</replaceable>
+ <option><link linkend="conf-repository">repository</link></option> <literal>kde-projects</literal>
+
+ # This option chooses what modules to look for in the database.
+ <option><link linkend="conf-use-modules">use-modules</link></option> <replaceable>extragear/graphics</replaceable>
+
+ # This option "subtracts out" modules from the modules chosen by use-modules, above.
+ # In this case, *both* extragear/graphics/kipi-plugins and
+ # extragear/graphics/kipi-plugins/kipi-plugins-docs are ignored
+ <option><link linkend="conf-ignore-modules">ignore-modules</link></option> <replaceable>extragear/graphics/kipi-plugins</replaceable>
+end module-set
+</programlisting>
+</example>
+
+</sect2>
+
+</sect1>
diff --git a/doc/kdesrc-build-logging.docbook b/doc/kdesrc-build-logging.docbook
new file mode 100644
index 00000000..91f751ac
--- /dev/null
+++ b/doc/kdesrc-build-logging.docbook
@@ -0,0 +1,78 @@
+<sect1 id="kdesrc-build-logging">
+<title>&kdesrc-build;'s build logging</title>
+
+<sect2 id="logging-overview">
+<title>Logging overview</title>
+
+<para>Logging is a &kdesrc-build; feature whereby the output from every command
+that &kdesrc-build; runs is saved to a file for examination later, if
+necessary. This is done because it is often necessary to have the output of
+these programs when there is a build failure, because there are so many
+reasons why a build can fail in the first place.</para>
+
+<sect3 id="log-directory-layout">
+<title>Logging directory layout</title>
+
+<para>The logs are always stored under the log directory. The destination of
+the log directory is controlled by the <link linkend="conf-log-dir">log-dir</link>
+option, which defaults to <filename class="directory"><symbol>${source-dir}</symbol>/log</filename> (where
+<symbol>${source-dir}</symbol> is the value of the <link linkend="conf-source-dir">source-dir</link>
+option. The in rest of this section, this value will be referred to as
+<symbol>${log-dir}</symbol>).</para>
+
+<para>Under <symbol>${log-dir}</symbol>, is a set of directories, one for every
+time that &kdesrc-build; was run. Each directory is named with the date, and
+the run number. For instance, the second time that &kdesrc-build; is run on
+May 26, 2004, it would create a directory called <filename>2004-05-26-02</filename>,
+where the 2004-05-26 is for the date, and the -02 is the run number.</para>
+
+<para>For your convenience, &kdesrc-build; will also create a link to the
+logs for your latest run, called <filename class="directory">latest</filename>. So the logs for
+the most recent &kdesrc-build; run should always be under <filename class="directory"><symbol>${log-dir}</symbol>/latest</filename>.
+</para>
+
+<para>Now, each directory for a &kdesrc-build; run will itself contain a set of
+directories, one for every &kde; module that &kdesrc-build; tries to build. Also,
+a file called <filename>build-status</filename> will be contained in the directory,
+which will allow you to determine which modules built and which failed.</para>
+
+<note><para>
+If a module itself has a submodule (such as extragear/multimedia,
+playground/utils, or KDE/kdelibs), then there would actually be a matching
+layout in the log directory. For example, the logs for KDE/kdelibs after the
+last &kdesrc-build; run would be found in <filename class="directory"><symbol>${log-dir}</symbol>/latest/KDE/kdelibs</filename>,
+and not under <filename class="directory"><symbol>${log-dir}</symbol>/latest/kdelibs</filename>.
+</para></note>
+
+<para>In each module log directory, you will find a set of files for each
+operation that &kdesrc-build; performs. If &kdesrc-build; updates a module,
+you may see filenames such as <filename>git-checkout-update.log</filename> (for a
+module checkout or when updating a module
+that has already been checked out). If the <command>configure</command>
+command was run, then you would expect to see a <filename>configure.log</filename>
+in that directory.</para>
+
+<para>If an error occurred, you should be able to see an explanation of why in
+one of the files. To help you determine which file contains the error,
+&kdesrc-build; will create a link from the file containing the error (such as
+<filename>build-1.log</filename> to a file called <filename>error.log</filename>).</para>
+
+<para>The upshot to all of this is that to see why a module failed to build
+after your last &kdesrc-build;, the file you should look at first is
+<filename><symbol>${log-dir}</symbol>/latest/<replaceable>module-name</replaceable>/error.log</filename>.
+</para>
+
+<tip><para>If the file <filename>error.log</filename> is empty (especially after
+an installation), then perhaps there was no error. Some of the tools used by
+the &kde; build system will sometimes mistakenly report an error when there was
+none.</para>
+
+<para>Also, some commands will evade &kdesrc-build;'s output redirection and
+bypass the log file in certain circumstances (normally when performing the
+first &git; checkout), and the error output in that case is not in the log file
+but is instead at the &konsole; or terminal where you ran &kdesrc-build;.</para>
+</tip>
+
+</sect3>
+</sect2>
+</sect1>
diff --git a/doc/kdesrc-build.desktop b/doc/kdesrc-build.desktop
new file mode 100644
index 00000000..0a229bf3
--- /dev/null
+++ b/doc/kdesrc-build.desktop
@@ -0,0 +1,101 @@
+# KDE Config File
+[Desktop Entry]
+Type=Application
+X-DocPath=kdesrc-build/index.html
+Name=KDE Source Builder
+Name[bs]=KDE graditelj izvornog koda
+Name[ca]=Constructor del codi font del KDE
+Name[ca at valencia]=Constructor del codi font de KDE
+Name[cs]=Sestavování KDE ze zdrojových kódů
+Name[da]=KDE Source Builder
+Name[de]=KDE-Source-Builder
+Name[el]=Κατασκευαστής πηγής του KDE
+Name[en_GB]=KDE Source Builder
+Name[eo]=KDE Source Builder
+Name[es]=Constructor del código fuente de KDE
+Name[et]=KDE lähtekoodi ehitaja
+Name[eu]=KDE sorburuaren eraikitzailea
+Name[fi]=KDE-lähdekoodin kääntämisohjelma
+Name[fr]=Compilateur de sources KDE
+Name[ga]=Tógálaí Foinse KDE
+Name[gl]=Compilador do código de KDE
+Name[hi]=केडीई स्त्रोत निर्माता
+Name[hu]=KDE forrásfordító
+Name[ia]=Constructor de Fonte de KDE
+Name[it]=Generazione del sorgente di KDE
+Name[ka]=KDE-ის კოდიდან ამგები
+Name[km]=កម្មវិធីស្ថាបនាប្រភពរបស់ KDE
+Name[ko]=KDE 소스 빌더
+Name[lt]=KDE kodo kompiliuoklis
+Name[mr]=केडीई स्रोतबिल्डर
+Name[nb]=KDE kildebygger
+Name[nds]=KDE-Bornkode-Buumoduul
+Name[nl]=KDE Source Builder
+Name[nn]=Byggjar for KDE-kjeldekode
+Name[pa]=KDE ਸਰੋਤ ਬਿਲਡਰ
+Name[pl]=Budowanie KDE ze źródeł
+Name[pt]=Compilação do Código do KDE
+Name[pt_BR]=Compilação do código do KDE
+Name[ru]=Сборка KDE из исходного кода
+Name[sk]=Prekladač zdrojového kódu KDE
+Name[sl]=Izgrajevalnik izvorne kode za KDE
+Name[sr]=Градња КДЕ‑а из извора
+Name[sr at ijekavian]=Градња КДЕ‑а из извора
+Name[sr at ijekavianlatin]=Gradnja KDE‑a iz izvora
+Name[sr at latin]=Gradnja KDE‑a iz izvora
+Name[sv]=KDE-källkodsbyggare
+Name[tr]=KDE Kaynakları Yapıcısı
+Name[ug]=KDE Source Builder
+Name[uk]=Програма для збирання KDE з початкових кодів
+Name[x-test]=xxKDE Source Builderxx
+Name[zh_CN]=KDE 源代码构建器
+Name[zh_TW]=KDE Source Builder
+Comment=Builds the KDE Platform and associated software from its source code. A command-line only program.
+Comment[bs]=Gradi platformu KDE‑a i pridruženi softver iz izvornog koda. Program komandne linije.
+Comment[ca]=Construeix la plataforma del KDE i el programari associat des del seu codi font. Un programa que només és per a la línia d'ordres.
+Comment[ca at valencia]=Construïx la plataforma de KDE i el programari associat des del seu codi font. Un programa que només és per a la línia d'ordres.
+Comment[cs]=Sestaví ze zdrojových kódů platformu KDE a přidružený software. Nástroj pouze pro příkazovou řádku.
+Comment[da]=Bygger KDE Platform og tilknyttet software fra kildekode. Et program kun til kommandolinjen.
+Comment[de]=Erstellt KDE und dazugehörige Software aus den Quelltexten. Es ist ein reines Befehlszeilenprogramm.
+Comment[el]=Δημιουργεί την πλατφόρμα του KDE και το αντίστοιχο λογισμικό από τον πηγαίο κώδικα. Ένα πρόγραμμα μόνο γραμμής εντολών.
+Comment[en_GB]=Builds the KDE Platform and associated software from its source code. A command-line only program.
+Comment[eo]=Konstruas la KDE Platform kaj rilatan programaron el sia fontkodo. Nur-komandlinia programo.
+Comment[es]=Construye la Plataforma KDE y el software asociado desde su código fuente. Un programa solo para la línea de órdenes.
+Comment[et]=KDE platvormi ja sellega seotud tarkvara ehitamine lähtekoodist. Ainult käsureal kasutatav programm.
+Comment[eu]=KDE Plataforma eta harekin lotutako softwarea bere sorburu kodetik abiatuta eraikitzen du. Bakarrik komando-lerroko programa bat da.
+Comment[fi]=Kääntää KDE-alustan ja siihen liittyvät ohjelmistot lähdekoodista. On vain komentoriviohjelma.
+Comment[fr]=Construit la plate-forme KDE et les logiciels associés à partir de son code source. Uniquement un programme en ligne de commandes.
+Comment[gl]=Compila a plataforma KDE e o software asociado a partires do código fonte. Programa de só liña de ordes.
+Comment[hi]=स्त्रोत कोड से केडीई प्लैटफ़ार्म तथा सम्बन्धित सॉफ़्टवेयर का निर्माण करता ह।केवल कमांड लाईन में उपलब्ध
+Comment[hu]=Lefordítja a KDE platformot és a kapcsolódó szoftvereket a forráskódjukból. Kizárólag parancssoros program.
+Comment[ia]=Construe le Platteforma de KDE e software associate ex su codice fonte. Un programma solmente de linea de commando.
+Comment[it]=Genera la piattaforma di KDE e il software ad essa associato dal codice sorgente. Un programma disponibile solo dalla riga di comando.
+Comment[ka]=KDE-ის პლატფორმისა და მასთან ასოცირებული პროგრამებს კოდიდან აგება. მუშაობს მხოლოდ ბრძანებების სტრიქონში (CLI).
+Comment[km]=ស្ថាបនាកម្មវិធីរបស់ KDE និងកម្មវិធីដែលភ្ជាប់ពីកូដប្រភពរបស់វា ។ កម្មវិធីបន្ទាត់ពាក្យបញ្ជាតែប៉ុណ្ណោះ ។
+Comment[ko]=KDE 플랫폼과 소프트웨어를 소스 코드에서 빌드합니다. 명령행 전용 프로그램입니다.
+Comment[lt]=Kompiliuoja KDE platformą ir susijusią programinę įrangą iš išeities kodo. Tik komandinės eilutės programa.
+Comment[nb]=Bygger KDE-plattformen og tilordnede programmer fra kildekoden. Dette er et program med bare kommandolinje.
+Comment[nds]=Buut de KDE-Systemümgeven un tohören Programmen ut den Bornkode. Bloots en Konsoolprogramm.
+Comment[nl]=Bouwt het KDE-platform en geassocieerde software uit zijn broncode. Werkt alleen op de opdrachtregel.
+Comment[nn]=Byggjer KDE-plattforma og tilhøyrande programvare frå kjeldekoden. Er eit kommandolinjebasert program.
+Comment[pl]=Budowanie Środowiska KDE i związanego z nim oprogramowania z kodu źródłowego. Program działa tylko w linii poleceń.
+Comment[pt]=Compila a Plataforma do KDE e os programas associados a partir do seu código-fonte. Um programa apenas para a linha de comandos.
+Comment[pt_BR]=Compila a Plataforma do KDE e os programas associados a partir do seu código-fonte. Um programa apenas para a linha de comando.
+Comment[ru]=Собирает платформу KDE и основанное на ней программное обеспечение из исходного кода. Программа предназначена только для запуска из командной строки.
+Comment[sk]=Vybuduje KDE platformu a asociovaný softvér z jeho zdrojového kódu. Program iba pre príkazový riadok.
+Comment[sl]=Izgradi okolje KDE in povezane programe iz izvorne kode. Gre za program ukazne vrstice.
+Comment[sr]=Гради платформу КДЕ‑а и придружени софтвер из изворног кода. Програм командне линије.
+Comment[sr at ijekavian]=Гради платформу КДЕ‑а и придружени софтвер из изворног кода. Програм командне линије.
+Comment[sr at ijekavianlatin]=Gradi platformu KDE‑a i pridruženi softver iz izvornog koda. Program komandne linije.
+Comment[sr at latin]=Gradi platformu KDE‑a i pridruženi softver iz izvornog koda. Program komandne linije.
+Comment[sv]=Bygger KDE-plattformen och tillhörande programvara från dess källkod. Ett program som bara använder kommandoraden.
+Comment[tr]=KDE Platformunu ve ilişkili yazılımları kaynak kodundan yapar. Yalnızca komut satırından oluşan bir uygulamadır.
+Comment[ug]=KDE سۇپىسى ۋە مۇناسىۋەتلىك يۇمشاق دېتاللارنى ئەسلى كودىدىن ھاسىل قىلىش. پەقەتلا بۇيرۇق قۇرىدا ئىشلەيدۇ.
+Comment[uk]=Збирає Платформу KDE і пов’язане з нею програмне забезпечення з початкових кодів. Керується за допомогою командного рядка.
+Comment[x-test]=xxBuilds the KDE Platform and associated software from its source code. A command-line only program.xx
+Comment[zh_CN]=从源代码构建 KDE 平台和相关软件。纯命令行程序。
+Comment[zh_TW]=從源碼建立 KDE 平台與相關軟體。是一個只有命令列的程式。
+Categories=Qt;KDE;Development;
+Exec=kdialog --sorry "kdesrc-build is a command-line only program. Please read the handbook at help:/kdesrc-build for more information."
+Terminal=true
+NoDisplay=true
diff --git a/doc/kdesrc-buildrc.docbook b/doc/kdesrc-buildrc.docbook
new file mode 100644
index 00000000..dd038296
--- /dev/null
+++ b/doc/kdesrc-buildrc.docbook
@@ -0,0 +1,261 @@
+<chapter id="kdesrc-buildrc">
+<title>Configuring &kdesrc-build;</title>
+
+<sect1 id="kdesrc-buildrc-overview">
+<title>Overview of &kdesrc-build; configuration</title>
+
+<para>
+To use the script, you must have a file in your home directory called
+<filename>.kdesrc-buildrc</filename>, which describes the modules you would
+like to download and build, and any options or configuration parameters to
+use for these modules.
+</para>
+
+<sect2 id="kdesrc-buildrc-layout">
+<title>Layout of the configuration file</title>
+
+<sect3 id="kdesrc-buildrc-layout-global">
+<title>Global configuration</title>
+
+<para>
+The configuration file starts with the global options, specified like the
+following:
+</para>
+
+<programlisting>
+global
+<replaceable>option-name option-value</replaceable>
+<replaceable>[...]</replaceable>
+end global
+</programlisting>
+
+</sect3>
+<sect3 id="kdesrc-buildrc-layout-modules">
+<title>Module configuration</title>
+
+<para>
+It is then followed by one or more module sections, specified in one of the
+following two forms:
+</para>
+
+<itemizedlist>
+<listitem>
+<programlisting>
+module <replaceable>module-name</replaceable>
+<replaceable>option-name option-value</replaceable>
+<replaceable>[...]</replaceable>
+end module
+</programlisting>
+</listitem>
+
+<listitem>
+<programlisting>
+module-set <replaceable>module-set-name</replaceable>
+ repository <userinput>kde-projects</userinput> or <userinput><replaceable>git://host.org/path/to/repo.git</replaceable></userinput>
+ use-modules <replaceable>module-names</replaceable>
+
+# Other options may also be set
+<replaceable>option-name option-value</replaceable>
+<replaceable>[...]</replaceable>
+end module-set
+</programlisting>
+</listitem>
+</itemizedlist>
+
+<important><para>Note that the second form, module sets, <emphasis>only works
+for Git-based modules</emphasis>.</para></important>
+
+<para>
+For Git modules, <replaceable>module-name</replaceable> must be a module
+from the &kde; &git; repository (for example, kdeartwork or
+kde-wallpapers).
+</para>
+
+<para>
+For Git modules, the module name can be essentially whatever you'd like, as
+long as it does not duplicate any other module name in the configuration. Keep
+in mind the source and build directory layout will be based on the module name
+if you do not use the <link linkend="conf-dest-dir">dest-dir</link> option.
+</para>
+
+<para>However, for Git <emphasis>module sets</emphasis> the
+<replaceable>module-names</replaceable> must correspond with actual git modules
+in the chosen <option>repository</option>. See <link
+linkend="conf-git-repository-base">git-repository-base</link> or <link
+linkend="conf-use-modules">use-modules</link> for more information.
+</para>
+
+</sect3>
+
+<sect3 id="kdesrc-buildrc-option-values">
+<title>Processing of option values</title>
+
+<para>In general, the entire line contents after the
+<replaceable>option-name</replaceable> is used as the
+<replaceable>option-value</replaceable>.</para>
+
+<para>One modification that &kdesrc-build; performs is that a sequence
+"<userinput>${<replaceable>name-of-option</replaceable>}</userinput>" is replaced
+with the value of that option from the global configuration. This allows you
+to reference the value of existing options, including options already set by
+&kdesrc-build;.</para>
+
+<para>
+To see an example of this in use, see
+<xref linkend="make-options-example"/>.</para>
+
+<para>You can also introduce your own non-standard global variables for referencing them further in the config.
+To do this, your option name should be prepended with underscore symbol. Example:
+<example id="custom-global-option-example">
+<title>Introducing your own global option for referencing later in config</title>
+<programlisting>
+global
+ _ver 6 # ← your custom variable (starting with underscore)
+ _kde ~/kde${_ver} # ← custom variable can contain another defined variable
+ source-dir ${_kde}/src # ← note that nested variable (_kde → _ver) is also resolved
+end global
+
+options kdepim
+ log-dir /custom/path/logs${_ver} # ← you can use custom variable just like a standard
+end options
+</programlisting>
+</example>
+</para>
+
+</sect3>
+
+<sect3 id="kdesrc-buildrc-options-groups">
+<title><quote>options</quote> modules</title>
+
+<para>There is a final type of configuration file entry,
+<literal>options</literal> groups, which may be given wherever a
+<literal>module</literal> or <literal>module-set</literal> may be used.</para>
+
+<programlisting>
+options <replaceable>module-name</replaceable>
+<replaceable>option-name option-value</replaceable>
+<replaceable>[...]</replaceable>
+end options
+</programlisting>
+
+<para>An <literal>options</literal> group may have options set for it just like
+a module declaration, and is associated with an existing module. Any options
+set these way will be used to <emphasis>override</emphasis> options set for the
+associated module.</para>
+
+<important><para>The associated module name <emphasis>must</emphasis> match the
+name given in the <literal>options</literal> declaration. Be careful of
+mis-typing the name.</para></important>
+
+<para>This is useful to allow for declaring an entire
+<literal>module-set</literal> worth of modules, all using the same options, and
+then using <literal>options</literal> groups to make individual changes.</para>
+
+<para><literal>options</literal> groups can also apply to named module sets.
+This allows expert users to use a common configuration file (which includes
+<literal>module-set</literal> declarations) as a baseline, and then make changes
+to the options used by those module-sets in configuration files that
+use the <literal><link
+linkend="kdesrc-buildrc-including">include</link></literal> command to reference
+the base configuration.</para>
+
+<example id="ex-options-group">
+<title>Example of using options</title>
+
+<para>In this example we choose to build all modules from the &kde; multimedia
+software grouping. However we want to use a different version of the &kmix;
+application (perhaps for testing a bug fix). It works as follows:</para>
+
+<programlisting>
+module-set <replaceable>kde-multimedia-set</replaceable>
+ repository <userinput>kde-projects</userinput>
+ use-modules <replaceable>kde/kdemultimedia</replaceable>
+ branch <replaceable>master</replaceable>
+end module-set
+
+# kmix is a part of kde/kdemultimedia group, even though we never named
+# kmix earlier in this file, &kdesrc-build; will figure out the change.
+options <replaceable>kmix</replaceable>
+ branch <replaceable>KDE/4.12</replaceable>
+end options
+</programlisting>
+
+<para>Now when you run &kdesrc-build;, all of the &kde; multimedia programs will
+be built from the <quote>master</quote> branch of the source repository, but
+&kmix; will be built from the older <quote>KDE/4.12</quote> branch. By using
+<literal>options</literal> you didn't have to individually list all the
+<emphasis>other</emphasis> &kde; multimedia programs to give them the right
+branch option.</para>
+
+</example>
+
+<note>
+<para>Note that this feature is only available in &kdesrc-build; from version
+1.16, or using the development version of &kdesrc-build; after
+2014-01-12.</para></note>
+
+</sect3>
+
+</sect2>
+
+<sect2 id="kdesrc-buildrc-including">
+<title>Including other configuration files</title>
+
+<para>
+Within the configuration file, you may reference other files by using the
+<literal>include</literal> keyword with a file, which will act as if the file
+referenced had been inserted into the configuration file at that point.
+</para>
+
+<informalexample><para>For example, you could have something like this:</para>
+<programlisting>
+global
+ include <replaceable>~/common-kdesrc-build-options</replaceable>
+
+ # Insert specific options here.
+
+end global
+</programlisting>
+</informalexample>
+
+<note><para>If you don't specify the full path to the file to include, then
+the file will be searched for starting from the directory containing the source
+file. This works recursively as well.</para></note>
+
+<para>You can use variables in the value of include instruction:</para>
+<programlisting>
+global
+ <replaceable>_ver</replaceable> <replaceable>6</replaceable>
+ source-dir ~/kde<replaceable>${_ver}</replaceable>/src
+ ...
+ persistent-data-file ~/kde<replaceable>${_ver}</replaceable>/persistent-options.json
+end global
+
+include ~/kde6/src/kdesrc-build/data/build-include/kf<replaceable>${_ver}</replaceable>-qt<replaceable>${_ver}</replaceable>.ksb
+
+</programlisting>
+</sect2>
+
+<sect2 id="kdesrc-buildrc-common">
+<title>Commonly used configuration options</title>
+
+<para>
+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-cmake-options">cmake-options</link> to define what flags to configure a module with using &cmake;.</para></listitem>
+<listitem><para><link linkend="conf-branch">branch</link>, to checkout from a branch instead of <literal>master</literal>.</para></listitem>
+<listitem><para><link linkend="conf-configure-flags">configure-flags</link> to define what flags to configure &Qt; with.</para></listitem>
+<listitem><para><link linkend="conf-install-dir">install-dir</link>, to set the directory to install &kde; to.</para></listitem>
+<listitem><para><link linkend="conf-make-options">make-options</link>, to pass options to the &make; program (such as number of CPUs to use).</para></listitem>
+<listitem><para><link linkend="conf-qt-install-dir">qt-install-dir</link>, to set the directory to install &Qt; to.</para></listitem>
+<listitem><para><link linkend="conf-source-dir">source-dir</link>, to change where to download the source code to.</para></listitem>
+</itemizedlist>
+
+</sect2>
+</sect1>
+&conf-options-table;
+</chapter>
diff --git a/doc/man-kdesrc-build.1.docbook b/doc/man-kdesrc-build.1.docbook
new file mode 100644
index 00000000..514db8ae
--- /dev/null
+++ b/doc/man-kdesrc-build.1.docbook
@@ -0,0 +1,1282 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
+<!ENTITY % English "INCLUDE">
+<!ENTITY kdesrc-build "<application>kdesrc-build</application>">
+]>
+
+<!--
+ Man page for kdesrc-build.
+ Copyright (c) 2011, 2014-2020, 2022 Michael Pyne <mpyne at kde.org>
+
+ Permission is granted to copy, distribute and/or modify this document under
+ the terms of the GNU Free Documentation License, Version 1.2 or any later
+ version published by the Free Software Foundation; with no Invariant
+ Sections, no Front-Cover Texts, and no Back-Cover Texts.
+ -->
+
+<refentry lang="&language;">
+<refentryinfo>
+<title>kdesrc-build User's Manual</title>
+<author>
+ <personname><firstname>Michael</firstname><surname>Pyne</surname></personname>
+ <email>mpyne at kde.org</email>
+ <personblurb><para>Authored man page</para></personblurb>
+</author>
+<date>2019-08-31</date>
+<releaseinfo>kdesrc-build 19.08</releaseinfo>
+</refentryinfo>
+
+<refmeta>
+<refentrytitle><command>kdesrc-build</command></refentrytitle>
+<manvolnum>1</manvolnum>
+<refmiscinfo class="version">19.08</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+ <refname><command>kdesrc-build</command></refname>
+ <refpurpose>Downloads, builds and installs &kde; software.</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv id="_synopsis">
+<cmdsynopsis>
+<command>kdesrc-build</command>
+<arg rep="repeat"><replaceable>OPTIONS</replaceable></arg>
+<arg rep="repeat"><replaceable>Module name | Module set name</replaceable></arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>DESCRIPTION</title>
+
+<para>The <command>kdesrc-build</command> command is used in order to download and build
+&kde; software directly from its source Git repositories.
+It interfaces with the &kde; project database, and
+supports controlling which options are passed to <command>make</command>(1) and
+<command>cmake</command>(1). The operation of <command>kdesrc-build</command>
+is driven by a configuration file, typically <filename>~/.config/kdesrc-buildrc</filename>
+(<filename>$XDG_CONFIG_HOME/kdesrc-buildrc</filename>, if <envar>$XDG_CONFIG_HOME</envar>
+is set).
+</para>
+
+<para>The <replaceable>module name</replaceable> or <replaceable>module set
+name</replaceable> as given on the command line should be as those names were
+defined in the configuration file (either in a <symbol>module</symbol>
+definition or <option>use-modules</option> declaration, or in a
+<option>module-set</option> definition). In addition, it can be the name of a
+&kde; module listed in the &kde; project database (and you can precede the
+module name with <symbol>+</symbol> to force this).</para>
+
+<para><command>kdesrc-build</command> is designed to be able to be completely
+headless (however, see <emphasis role="strong">ENVIRONMENT</emphasis>), and so
+typically ignores its input completely. Command output is logged instead of
+being shown on the kdesrc-build output.</para>
+
+<para>Modules are built one after the other. If a module fails to update then
+it is not built. <command>kdesrc-build</command> will not abort just because of
+a module failure, instead it will keep trying to update and build subsequent
+modules. By default, <command>kdesrc-build</command> will commence building a
+module as soon as the source code update is complete for that module, even if
+other updates are occurring concurrently.</para>
+
+<para>At the end <command>kdesrc-build</command> will show which modules failed
+to build, and where the logs were kept for that build run.</para> </refsect1>
+
+<refsect1>
+<title>OPTIONS</title>
+
+<para><emphasis role="strong">NOTE</emphasis>: Some options have short forms,
+but the <command>kdesrc-build</command> option parser does not support
+combining short options into one at this point. (E.g. running
+<option>kdesrc-build -pv</option> would not be the same as
+<option>kdesrc-build --pretend --verbose</option>).</para>
+
+<variablelist>
+
+<varlistentry>
+<term>
+<option>-h, --help</option>
+</term>
+
+<listitem>
+<para>
+ Shows a brief synopsis and frequently-used command line options.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--show-info</option>
+</term>
+
+<listitem>
+<para>
+ Shows information about &kdesrc-build; and the operating system which may
+ be useful in bug reports or when requesting help on forums or mailing
+ lists.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--initial-setup</option>
+</term>
+
+<listitem>
+<para>
+ Performs one-time setup for users running &kdesrc-build; on common
+ distributions. This includes installation of known system dependencies, a
+ default configuration file setup, and changes to your ~/.bashrc to make the
+ software installed by &kdesrc-build; accessible.
+
+ This is exactly equivalent to using "--install-distro-packages --generate-config" at the same time.
+ In kdesrc-build (perl implementation) it additionally uses "--install-distro-packages-perl".
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--install-distro-packages</option>
+</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>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--generate-config</option>
+</term>
+
+<listitem>
+<para>
+Generate the &kdesrc-build; configuration file.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>-p, --pretend</option>
+</term>
+
+<listitem>
+<para>
+ Operate in a "dry run" mode. No network accesses are made, no log files are
+ created, no modules are built, and no other permanent changes to disk are
+ made. One <emphasis>important exception</emphasis> is that if you try to
+ build a module that comes from the &kde; project database, and the
+ database hasn't been downloaded yet, the database will be downloaded
+ since the pretend-mode output may change significantly based on the
+ database results.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--install-only</option>
+</term>
+
+<listitem>
+<para>
+ Skips the update and build phase and immediately attempts to install the
+ modules given.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--uninstall</option>
+</term>
+
+<listitem>
+<para>
+ Skips the update and build phase and immediately attempts to uninstall the
+ modules given. <emphasis role="strong">NOTE</emphasis>: This is only
+ supported for buildsystems that supports the <command>make
+ uninstall</command> command (e.g. &kde; CMake-based).
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>-S, --no-src</option>
+</term>
+
+<listitem>
+<para>
+ Skips the source update phase. Other phases are included as normal.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>-M, --no-metadata</option>
+</term>
+
+<listitem>
+<para>
+ Skips the metadata update phase for KDE modules. Other phases (including
+ the source update phase) are included as normal. If you wish to avoid all network
+ updates you should also pass <option>--no-src</option>.
+</para>
+
+<para>
+ This option can be useful if you are frequently running
+ <command>kdesrc-build</command> since the metadata itself does not change
+ very often.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--no-install</option>
+</term>
+
+<listitem>
+<para>
+ Skips the install phase from the build. Other phases are included as
+ normal.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--no-build</option>
+</term>
+
+<listitem>
+<para>
+ Skips the build phase for the build. Internally the install phase depends
+ on the build phase completing so this is effectively equivalent to
+ <option>--src-only</option>, but the semantics may change in the future
+ (e.g. when test suites are moved into their own phase).
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--no-tests</option>
+</term>
+
+<listitem>
+<para>
+ Disables running the test suite for CMake-based modules. To be fully
+ effective this requires re-running CMake, which can be forced by using the
+ <option>--reconfigure</option> or <option>--refresh-build</option> options.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>-s, --src-only</option>
+</term>
+
+<listitem>
+<para>
+ Only performs the source update phase, does not build or install.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--build-only</option>
+</term>
+
+<listitem>
+<para>
+ Forces the build process to be performed without updating source code
+ first. In addition, installation is not performed. (Testing is still
+ performed if applicable, but this will change in a future release)
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--metadata-only</option>
+</term>
+
+<listitem>
+<para>
+ Only updates the build metadata needed for KDE modules, then exits. This is
+ useful to allow the <option>--pretend</option> option to work if you've never
+ run kdesrc-build. See also <option>--no-metadata</option>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>-r, --refresh-build</option>
+</term>
+
+<listitem>
+<para>
+ Removes the build directory for a module before the build phase starts.
+ This has the desired side effect of forcing <command>kdesrc-build</command> to re-configure
+ the module and build it from a "pristine" state with no existing temporary
+ or intermediate output files. Use this option if you have problems getting
+ a module to build but realize it will take longer (possibly much longer)
+ for the build to complete as a result. When in doubt use this option for
+ the entire <command>kdesrc-build</command> run.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--reconfigure</option>
+</term>
+
+<listitem>
+<para>
+ Force CMake to be re-run, but without deleting the build directory.
+ Usually you actually want <option>--refresh-build</option>, but if you are
+ 100% sure your change to <option>cmake-options</option> will not
+ invalidate your current intermediate output then this can save some time.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--build-system-only</option>
+</term>
+
+<listitem>
+<para>
+ Interrupts the build process for each module built: The build process
+ consists of normal setup up to and including running
+ <command>cmake</command> or <command>configure</command> (as appropriate),
+ but <command>make</command> is not run and no installation
+ is attempted. This is mostly only useful to get things like
+ <command>configure --help</command> and <command>cmake-gui</command> to
+ work. Normally you want <option>--reconfigure</option> or
+ <option>--refresh-build</option>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--resume-from=<replaceable>foo</replaceable></option>,
+<option>--from=<replaceable>foo</replaceable></option>,
+<option>-f <replaceable>foo</replaceable></option>,
+</term>
+
+<listitem>
+<para>
+ Use this option to skip module processing until the module
+ <replaceable>foo</replaceable> is encountered.
+ <replaceable>foo</replaceable> and all subsequent modules will be processed
+ normally as if they had been specified on the command line. If you use this
+ option because of a build failure you may want to consider using
+ <option>--no-src</option> in addition to skip the resultant source update
+ phase.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--resume-after=<replaceable>foo</replaceable></option>,
+<option>--after=<replaceable>foo</replaceable></option>,
+<option>-a <replaceable>foo</replaceable></option>
+</term>
+
+<listitem>
+<para>
+ This is just like <option>--resume-from</option>, except that the module
+ <replaceable>foo</replaceable> is <emphasis>not</emphasis> included in the
+ list of modules to consider. You might use this if you've manually
+ built/installed foo after fixing the build and just want to resume from
+ there.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--resume</option>
+</term>
+
+<listitem>
+<para>
+ This option can be used to run <command>kdesrc-build</command> 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>--resume-from</option> and
+ <option>--stop-before</option>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--stop-before=<replaceable>foo</replaceable></option>,
+<option>--until=<replaceable>foo</replaceable></option>
+</term>
+
+<listitem>
+<para>
+ This is similar to the <option>--resume-from</option> flag. This option
+ causes the module list for the given build to be truncated just
+ <emphasis>before</emphasis> <replaceable>foo</replaceable> would normally
+ have been built. <replaceable>foo</replaceable> is <emphasis>not</emphasis>
+ built (but see <option>--stop-after</option>).
+</para>
+
+<para>
+ This flag may be used with <option>--resume-from</option> or
+ <option>--resume-after</option>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--stop-after=<replaceable>foo</replaceable></option>,
+<option>--to=<replaceable>foo</replaceable></option>
+</term>
+
+<listitem>
+<para>
+ This is just like <option>--stop-before</option>, except that the given module
+ <emphasis>is</emphasis> included in the build.
+</para>
+
+<para>
+ This flag may be used with <option>--resume-from</option> or
+ <option>--resume-after</option>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>-d, --include-dependencies</option>
+</term>
+
+<listitem>
+<para>
+ This causes <command>kdesrc-build</command> to include not only the modules
+ it would normally build (either because they were specified on the command
+ line, or mentioned in the configuration file), but also to include
+ <emphasis>known dependencies</emphasis> of those modules in the build.
+ This is normally the default; you can use <option>--no-include-dependencies</option>
+ to disable this effect.
+</para>
+
+<para>
+ Dependencies are <quote>known</quote> to <command>kdesrc-build</command> based on the
+ contents of the special <emphasis>kde-build-metadata</emphasis> git
+ repository, which is managed for you by the script (see also the
+ <option>--metadata-only</option> option). The KDE community keeps the
+ dependency information in that module up to date, so if
+ <command>kdesrc-build</command> appears to show the wrong dependencies then
+ it may be due to missing or incorrect dependency information.
+</para>
+
+<para>
+ All known dependencies will be included, which may be more than you need.
+ Consider using the <option>--resume-from</option> option (and similar
+ options) to control the build list when using this option.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>-D, --no-include-dependencies</option>
+</term>
+
+<listitem>
+<para>
+ This is the negation of <option>--include-dependencies</option>, for use if you have
+ configured dependencies to be included by default.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--rebuild-failures</option>
+</term>
+
+<listitem>
+<para>
+ Use this option to build only those modules which failed to build on a
+ previous <command>kdesrc-build</command> 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>
+
+ <para>Note that the list of <quote>previously-failed modules</quote> is
+ reset every time a <command>kdesrc-build</command> 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>
+
+ <para>This option was added for kdesrc-build 15.09.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--stop-on-failure, --no-stop-on-failure</option>
+</term>
+
+<listitem>
+<para>
+ This option causes the build to abort as soon as a failure occurs. This is the default.
+ With negative flag, <command>kdesrc-build</command>
+ will try 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>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>-!, --ignore-modules</option>
+</term>
+
+<listitem>
+<para>
+ Forces <emphasis role="strong">ALL</emphasis> modules that follow this
+ option to be excluded from consideration by
+ <command>kdesrc-build</command>. This might be useful if you know you want
+ to process all modules except for specific exceptions.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--rc-file=<replaceable>foo</replaceable></option>
+</term>
+
+<listitem>
+<para>
+ Use the given file, <replaceable>foo</replaceable>, for the configuration
+ instead of <filename>./kdesrc-buildrc</filename> or
+ <filename>~/.config/kdesrc-buildrc</filename>. The file can be empty, but it
+ must exist.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--nice=<replaceable>foo</replaceable></option>
+</term>
+
+<listitem>
+<para>
+ Changes the CPU priority given to <command>kdesrc-build</command> (and all
+ processes used by <command>kdesrc-build</command> e.g.
+ <command>make</command>(1)). <replaceable>foo</replaceable> should be an
+ integer number between -20 and 19. Positive values are "nicer" to the rest
+ of the system (i.e. lower priority).
+</para>
+
+<para>
+ Note that the possible priorities available on your system may be different
+ than listed here, see <command>nice</command>(2) for more information. Note
+ also that this only changes <emphasis>CPU</emphasis> priority, often you
+ want to change <emphasis>I/O</emphasis> priority on systems where that is
+ supported. There is no command-line option for I/O priority adjustment, but
+ there is a configuration file option: <option>use-idle-io-priority</option>
+ (although like all options, there is a generic way to set this from the
+ command line).
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--run=<replaceable>foo</replaceable></option>
+</term>
+
+<listitem>
+<para>
+ Runs the program named by <replaceable>foo</replaceable> using
+ prefix.sh environment variables. All command
+ line arguments present after this option are passed to
+ <replaceable>foo</replaceable> as it is run.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--query=<replaceable>mode</replaceable></option>
+</term>
+
+<listitem>
+<para>
+This command causes <command>kdesrc-build</command> 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
+ <command>kdesrc-build</command> to output the full path to where the
+ module's source code is stored.
+ </para></listitem>
+ <listitem><para><option>build-dir</option>, which causes
+ <command>kdesrc-build</command> to output the full path to where the
+ module build process occurs.
+ </para></listitem>
+ <listitem><para><option>install-dir</option>, which causes
+ <command>kdesrc-build</command> to output the full path to where the
+ module will be installed.
+ </para></listitem>
+ <listitem><para><option>project-path</option>, which causes
+ <command>kdesrc-build</command> to output the location of the module
+ within the hierarchy of KDE source code repositories.
+ </para></listitem>
+ <listitem><para><option>branch</option>, which causes
+ <command>kdesrc-build</command> to output the resolved git branch that
+ will be used for each module, based on the <option>tag</option>,
+ <option>branch</option> and <option>branch-group</option> settings in
+ effect.
+ </para></listitem>
+ <listitem><para><option>module-set</option>, which causes &kdesrc-build; to
+ output the name of module-set which contains the module. This can be used
+ to generate zsh autocompletion cache.</para></listitem>
+ <listitem><para><option>build-system</option>, which causes &kdesrc-build; to
+ output the name of build system detected for the module. This can be used
+ to debug build system auto-detection problems, or when developing tests for specific build systems.
+ </para></listitem>
+ <listitem><para>Otherwise, option names that are valid for modules in the
+ configuration file can be used, the resolved value of which will be
+ listed for each module.
+ </para></listitem>
+ </itemizedlist>
+
+<para>This option was added with <command>kdesrc-build</command> 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>
+<term>
+<option>--dependency-tree</option>
+</term>
+
+<listitem>
+<para>
+ Takes all actions up to and including dependency reordering of the modules
+ specified on the command line (or configuration file), and prints dependency
+ information for each selected module in a (recursive) tree output format. Generated
+ information includes which specific commit/branch/tag is depended on, as well as
+ whether the module would be built. Note that the output can become quite large for
+ applications with many dependencies or when many modules are (implicitly) selected.
+</para>
+
+<para>
+ The <literal>kde-project</literal> metadata is downloaded first (though, see
+ <option>--pretend</option> or <option>--no-src</option>).
+</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>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--color</option>
+</term>
+
+<listitem>
+<para>
+ Enables "colorful output". (Enabled by default).
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--no-color</option>
+</term>
+
+<listitem>
+<para>
+ Disables "colorful output". This can be made permanent by setting the
+ <option>colorful-output</option> option to false (or 0) in your
+ configuration file.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--async</option>
+</term>
+
+<listitem>
+<para>
+ Have <command>kdesrc-build</command> start the build process for a module
+ as soon as the source code has finished downloading. Without this option
+ <command>kdesrc-build</command> performs all source updates at once and
+ only then starts with the build process. This option is enabled by default.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--no-async</option>
+</term>
+
+<listitem>
+<para>
+ Disables asynchronous building of modules. See <option>--async</option> for
+ a more detailed description. Note that <command>kdesrc-build</command>'s
+ output will be slightly different in this mode.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--verbose</option>
+</term>
+
+<listitem>
+<para>
+ Increases the level of verbosity of <command>kdesrc-build</command> output
+ (which is already fairly verbose!)
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>-q, --quiet</option>
+</term>
+
+<listitem>
+<para>
+ Makes <command>kdesrc-build</command> less noisy. Only important messages
+ are shown.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--really-quiet</option>
+</term>
+
+<listitem>
+<para>
+ Makes <command>kdesrc-build</command> even less noisy. Only warnings/errors
+ are shown.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--debug</option>
+</term>
+
+<listitem>
+<para>
+ This will fill your terminal with descriptions and debugging output,
+ usually unintelligible, describing what <command>kdesrc-build</command> is
+ doing (and thinks it should be doing). The flag is included since the
+ output may sometimes prove useful for debugging.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--force-build</option>
+</term>
+
+<listitem>
+<para>
+ Normally when <command>kdesrc-build</command> notices that there is no
+ source update on a module which was previously successfully installed, it
+ does not attempt to build or install that module. You can pass this flag to
+ disable that behavior and always run <command>make</command>.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--delete-my-patches</option>
+</term>
+
+<listitem>
+<para>
+ This option must be passed to allow <command>kdesrc-build</command> to
+ remove conflicting source directories. Currently even this only happens
+ when trying to clone a git-based module if an existing source directory is
+ present. Never specify this option unless it is suggested by
+ <command>kdesrc-build</command>, and only if you don't mind the source
+ directories that are referenced being deleted and re-cloned.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--<replaceable>foo</replaceable>=<replaceable>bar</replaceable></option>
+</term>
+
+<listitem>
+<para>
+ Any option not listed above is checked to see if it matches the list of
+ possible configuration file options. If so, the configuration file option
+ <option>foo</option> is temporarily set to <option>bar</option> for the
+ duration of this run.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<option>--set-module-option-value=<replaceable>module</replaceable>,<replaceable>foo</replaceable>,<replaceable>bar</replaceable></option>
+</term>
+
+<listitem>
+<para>
+ Like above, but option <option>foo</option> is only set to
+ <option>bar</option> for the module <option>module</option>. This does not
+ work for module sets yet, you must repeat this for each module you want to
+ be affected. (Of course, you could simply edit your configuration file...)
+
+ This option worked slightly differently prior to version 1.16.
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</refsect1>
+
+<refsect1>
+<title>EXIT STATUS</title>
+
+<variablelist>
+
+<varlistentry>
+<term>
+<emphasis role="strong">0</emphasis>
+</term>
+
+<listitem>
+<para>
+ Success
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<emphasis role="strong">1</emphasis>
+</term>
+
+<listitem>
+<para>
+ Normally this means some part of the update, build or install process
+ failed, but is also used for any abnormal program end not otherwise covered
+ below.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<emphasis role="strong">5</emphasis>
+</term>
+
+<listitem>
+<para>
+ A signal was received that killed <command>kdesrc-build</command>, but it
+ attempted to perform normal closedown.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<emphasis role="strong">8</emphasis>
+</term>
+
+<listitem>
+<para>
+ Unknown option was passed on the command line.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<emphasis role="strong">99</emphasis>
+</term>
+
+<listitem>
+<para>
+ An exception was raised that forced <command>kdesrc-build</command> to
+ abort early.
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</refsect1>
+
+<refsect1>
+<title>ENVIRONMENT</title>
+
+<variablelist>
+
+<varlistentry>
+<term>
+<envar>HOME</envar>
+</term>
+
+<listitem>
+<para>
+ Used for tilde-expansion of file names, and is the default base for the
+ source, build, and installation directories.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<envar>PATH</envar>
+</term>
+
+<listitem>
+<para>
+ This environment variable controls the default search path for executables.
+ You can use the <option>binpath</option> configuration file option to add
+ to this variable (e.g. for running from <command>cron</command>(8)).
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<envar>LC_</envar>*
+</term>
+
+<listitem>
+<para>
+ Environment variables starting with LC_ control the locale used by
+ <command>kdesrc-build</command>. Although <command>kdesrc-build</command>
+ is still not localizable at this point, many of the commands it uses are.
+ <command>kdesrc-build</command> normally sets <envar>LC_ALL</envar>=C for
+ commands that its must examine the output of but you can manually do this
+ as well. If setting <envar>LC_ALL</envar>=C fixes a
+ <command>kdesrc-build</command> problem please submit a bug report.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<envar>SSH_AGENT_PID</envar>
+</term>
+
+<listitem>
+<para>
+ This environment variable is checked to see if
+ <command>ssh-agent</command>(1) is running, but only if
+ <command>kdesrc-build</command> determines that you are checking out a
+ module that requires an SSH login (but you should know this as no module
+ requires this by default).
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<envar>KDESRC_BUILD_USE_TTY</envar>
+</term>
+
+<listitem>
+<para>
+ If set, this variable forces <command>kdesrc-build</command> not to close
+ its input while executing system processes. Normally
+ <command>kdesrc-build</command> closes <symbol>stdin</symbol> since the
+ <symbol>stdout</symbol> and <symbol>stderr</symbol> for its child processes
+ are redirected and therefore the user would never see an input prompt
+ anyways.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+<envar>KDESRC_BUILD_DUMP_CONTEXT</envar>
+</term>
+
+<listitem>
+<para>
+ If set, this variable prints out a description of its "build context" just
+ after reading options and command line arguments and determining which
+ modules to build. You pretty much never want to set this.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+others
+</term>
+
+<listitem>
+<para>
+ Many programs are used by <command>kdesrc-build</command> in the course of
+ its execution, including
+ <command>git</command>(1), <command>make</command>(1), and
+ <command>cmake</command>(1). Each of these programs may have their own
+ response to environment variables being set.
+ <command>kdesrc-build</command> will pass environment variables that are
+ set when it is run onto these processes. You can ensure certain environment
+ variables (e.g. <envar>CC</envar> or <envar>CXX</envar>) are set by using
+ the <option>set-env</option> configuration file option.
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</refsect1>
+
+<refsect1>
+<title>SIGNALS</title>
+
+<para>&kdesrc-build; supports <literal>SIGHUP</literal>, which if received
+will cause &kdesrc-build; to exit after the current modules for the
+build thread (and update thread, if still active) have completed.</para>
+
+</refsect1>
+
+<refsect1>
+<title>FILES</title>
+
+<para><filename>~/.config/kdesrc-buildrc</filename>
+(<filename>$XDG_CONFIG_HOME/kdesrc-buildrc</filename>, if
+<envar>$XDG_CONFIG_HOME</envar> is set) - Default global configuration file.
+</para>
+
+<para><filename>kdesrc-buildrc</filename> - If this file is found in the
+<emphasis role="strong">current directory</emphasis> when kdesrc-build is run,
+this file will be used for the configuration instead of
+<filename>~/.config/kdesrc-buildrc</filename>.
+</para>
+
+<para><filename>~/.local/state/kdesrc-build-data</filename>
+(<filename>$XDG_STATE_DIR/kdesrc-buildrc</filename>, if
+<envar>$XDG_STATE_DIR</envar> is set) - <command>kdesrc-build</command> uses
+this file to store persistent data (such as last CMake options used, last
+revision successfully installed, etc.). It can be safely deleted.
+</para>
+
+</refsect1>
+
+<refsect1>
+<title>BUGS</title>
+
+<para>See <ulink url="https://bugs.kde.org/">https://bugs.kde.org/</ulink>. Be
+sure to search against the <command>kdesrc-build</command> product.</para>
+
+</refsect1>
+
+<refsect1>
+<title>EXAMPLE</title>
+
+<variablelist>
+
+<varlistentry>
+<term>
+$ <userinput><command>kdesrc-build</command></userinput>
+</term>
+
+<listitem>
+<para>
+ Downloads, builds and installs all modules listed in the configuration
+ file, in the order defined therein.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+$ <userinput><command>kdesrc-build</command> <option>--pretend</option></userinput>
+</term>
+
+<listitem>
+<para>
+ Same as above, except no permanent actions are taken (specifically no log
+ files are created, downloads performed, build processes run, etc.).
+ <emphasis role="strong">EXCEPTION</emphasis>: If you are trying to build a
+ module defined in the &kde; project database, and the database has not been
+ downloaded yet, <command>kdesrc-build</command> will download the database
+ since this can significantly affect the final build order.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+$ <userinput><command>kdesrc-build</command> <option>--no-src</option> <option>--refresh-build</option> <symbol>kdebase</symbol></userinput>
+</term>
+
+<listitem>
+<para>
+ Deletes the build directory for the <emphasis>kdebase</emphasis> module set
+ (<option>--refresh-build</option>) and then starts the build process again
+ without updating the source code in-between.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+$ <userinput><command>kdesrc-build</command> <option>--rc-file</option> <filename>/dev/null</filename> <option>--pretend</option></userinput>
+</term>
+
+<listitem>
+<para>
+ Forces <command>kdesrc-build</command> to read an empty configuration file
+ and simulate the resultant build process. This shows what would happen by
+ default with no configuration file, without an error message about a
+ missing configuration file.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+$ <userinput><command>kdesrc-build</command> <symbol>+kdebase/kde-baseapps</symbol></userinput>
+</term>
+
+<listitem>
+<para>
+ Downloads, builds and installs the <symbol>kde-baseapps</symbol> module
+ from the &kde; project database. Since the module name is preceded by a
+ <symbol>+</symbol> it is assumed to defined in the &kde; project
+ database even if this hasn't been specifically configured in the
+ configuration file.
+</para>
+<para>
+ The <symbol>kdebase/</symbol> portion forces
+ <command>kdesrc-build</command> to ignore any <symbol>kde-baseapps</symbol>
+ modules that are not children of the <symbol>kdebase</symbol> supermodule
+ in the project database (although it is contrived for this example).
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
+$ <userinput><command>kdesrc-build</command> <option>--refresh-build</option> <option>--cmake-options=<replaceable>"-DCMAKE_BUILD_TYPE=Debug"</replaceable></option></userinput>
+</term>
+
+<listitem>
+<para>
+ Downloads, builds and installs all modules defined in the configuration
+ file but overrides the <symbol>cmake-options</symbol> option to have
+ the value given on the command line for this run only. Any further
+ <command>kdesrc-build</command> runs will use the
+ <symbol>cmake-options</symbol> given in the configuration file.
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</refsect1>
+
+<refsect1>
+<title>SEE ALSO</title>
+
+<para>build-tool - A program by Michael Jansen which can build &kde; software
+based on included recipes.</para>
+
+</refsect1>
+
+<refsect1>
+<title>RESOURCES</title>
+
+<para>Main web site: <ulink
+url="https://apps.kde.org/kdesrc_build/">https://apps.kde.org/kdesrc_build/</ulink></para>
+
+<para>Documentation: <ulink
+url="https://docs.kde.org/?application=kdesrc-build">https://docs.kde.org/?application=kdesrc-build</ulink></para>
+
+</refsect1>
+
+<refsect1>
+<title>COPYING</title>
+
+<para>Copyright (C) 2003-2022 Michael Pyne.</para>
+
+<para>This program is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by the Free
+Software Foundation; either version 2 of the License, or (at your option) any
+later version.</para>
+
+<para>This program is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+details.</para>
+
+<para>You should have received a copy of the GNU General Public License along
+with this program; if not, write to the Free Software Foundation, Inc., 51
+Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA</para>
+
+</refsect1>
+
+</refentry>
diff --git a/doc/other-features.docbook b/doc/other-features.docbook
new file mode 100644
index 00000000..c42d97fe
--- /dev/null
+++ b/doc/other-features.docbook
@@ -0,0 +1,175 @@
+<sect1 id="other-features">
+<title>Other &kdesrc-build; features</title>
+
+<sect2 id="changing-verbosity">
+<title>Changing the amount of output from &kdesrc-build;</title>
+<para>&kdesrc-build; has several options to control the amount of output the
+script generates. In any case, errors will always be output.</para>
+
+<table>
+ <title>Table of debug levels</title>
+ <tgroup cols="3">
+
+ <thead>
+ <row>
+ <entry>Debug level</entry>
+ <entry>Level name</entry>
+ <entry>Command line option</entry>
+ </row>
+ </thead>
+ <tbody>
+
+ <row>
+ <entry>0</entry>
+ <entry>DEBUG</entry>
+ <entry>--debug</entry>
+ </row>
+
+ <row>
+ <entry>1</entry>
+ <entry>WHISPER</entry>
+ <entry>--verbose</entry>
+ </row>
+
+ <row>
+ <entry>2</entry>
+ <entry>INFO</entry>
+ <entry>Selected by default</entry>
+ </row>
+
+ <row>
+ <entry>3</entry>
+ <entry>NOTE</entry>
+ <entry>--quiet</entry>
+ </row>
+
+ <row>
+ <entry>4</entry>
+ <entry>WARNING</entry>
+ <entry>--really-quiet</entry>
+ </row>
+
+ <row>
+ <entry>5</entry>
+ <entry>ERROR</entry>
+ <entry>No way to select</entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+</table>
+
+</sect2>
+
+<sect2 id="kdesrc-build-color">
+<title>Color output</title>
+<para>When being run from &konsole; or a different terminal, &kdesrc-build;
+will normally display with colorized text.</para>
+
+<para>You can disable this by using the <option>--no-color</option> on the
+command line, or by setting the &colorful-output; option in the <link linkend="configure-data">configuration file</link> to
+<userinput>false</userinput>.
+</para>
+
+<informalexample>
+<para>Disabling color output in the configuration file:</para>
+<screen>
+global
+ colorful-output false
+end global
+</screen>
+</informalexample>
+
+</sect2>
+
+<sect2 id="deleting-build-dir">
+<title>Removing unneeded directories after a build</title>
+<para>Are you short on disk space but still want to run a bleeding-edge
+&kde; checkout? &kdesrc-build; can help reduce your disk usage when building
+&kde; from &git;.</para>
+
+<note><para>Be aware that building &kde; does take a lot of space. There are
+several major space-using pieces when using &kdesrc-build;:</para></note>
+
+<orderedlist>
+<listitem><para>The actual source checkout can take up a fair amount of space.
+The default modules take up about 1.6 gigabytes of on-disk space. You can reduce
+this amount by making sure that you are only building as many modules as you
+actually want. &kdesrc-build; will not delete source code from disk even if you
+delete the entry from the <link linkend="configure-data">configuration file</link>, so make sure that you go and delete unused
+source checkouts from the source directory. Note that the source files are
+downloaded from the Internet, you <emphasis>should not</emphasis> delete them
+if you are actually using them, at least until you are done using
+&kdesrc-build;.</para>
+
+<para>Also, if you already have a &Qt; installed by your distribution (and
+the odds are good that you do), you probably do not need to install the
+qt module. That will shave about 200 megabytes off of the on-disk source
+size.</para>
+</listitem>
+
+<listitem>
+<para>&kdesrc-build; will create a separate build directory to build the source
+code in. Sometimes &kdesrc-build; will have to copy a source directory to
+create a fake build directory. When this happens, space-saving symlinks are
+used, so this should not be a hassle on disk space. The build directory will
+typically be much larger than the source directory for a module. For example,
+the build directory for kdebase is about 1050 megabytes, whereas kdebase's
+source is only around 550 megabytes.</para>
+
+<para>Luckily, the build directory is not required after a module has
+successfully been built and installed. &kdesrc-build; can automatically
+remove the build directory after installing a module, see the examples below
+for more information. Note that taking this step will make it impossible
+for &kdesrc-build; to perform the time-saving incremental builds.</para>
+</listitem>
+
+<listitem><para>
+Finally, there is disk space required for the actual installation of
+&kde;, which does not run from the build directory. This typically takes less
+space than the build directory. It is harder to get exact figures however.
+</para></listitem>
+</orderedlist>
+
+<para>How do you reduce the space requirements of &kde;? One way is to
+use the proper compiler flags, to optimize for space reduction instead of
+for speed. Another way, which can have a large effect, is to remove debugging
+information from your &kde; build.
+</para>
+
+<warning><para>
+You should be very sure you know what you are doing before deciding to remove
+debugging information. Running bleeding-edge software means you are running
+software which is potentially much more likely to crash than a stable release.
+If you are running software without debugging information, it can be very
+hard to create a good bug report to get your bug resolved, and you will likely
+have to re-enable debugging information for the affected application and
+rebuild to help a developer fix the crash. So, remove debugging information
+at your own risk!
+</para></warning>
+
+<informalexample>
+<para>Removing the build directory after installation of a module. The source
+directory is still kept, and debugging is enabled:</para>
+
+<screen>
+global
+ configure-flags --enable-debug
+ remove-after-install builddir # Remove build directory after install
+end global
+</screen>
+
+<para>Removing the build directory after installation, without debugging
+information, with size optimization.</para>
+
+<screen>
+global
+ cxxflags -Os # Optimize for size
+ configure-flags --disable-debug
+ remove-after-install builddir # Remove build directory after install
+end global
+</screen>
+</informalexample>
+</sect2>
+
+</sect1>
diff --git a/doc/quick-start-conclusion.docbook b/doc/quick-start-conclusion.docbook
new file mode 100644
index 00000000..d4a42fce
--- /dev/null
+++ b/doc/quick-start-conclusion.docbook
@@ -0,0 +1,17 @@
+<sect1 id="quick-start-conclusion">
+<title>Getting Started Conclusion</title>
+<para>These are the major features and concepts needed to get started with
+&kdesrc-build;</para>
+
+<para>For additional information, you could keep reading through this
+documentation. In particular, the <link linkend="supported-cmdline-params">list
+of command-line options</link> and the <link linkend="conf-options-table">table
+of configuration file options</link> are useful references.</para>
+
+<para>The &kde; Community also maintains <ulink
+url="https://community.kde.org/Guidelines_and_HOWTOs/Build_from_source">an
+online Wiki reference for how to build the source code</ulink>, which refers to
+&kdesrc-build; and includes tips and other guidelines on how to use the
+tool.</para>
+
+</sect1>
diff --git a/doc/source-reference/IPC-notes.md b/doc/source-reference/IPC-notes.md
new file mode 100644
index 00000000..5b34a83b
--- /dev/null
+++ b/doc/source-reference/IPC-notes.md
@@ -0,0 +1,243 @@
+# IPC Notes
+
+To support the [async](https://docs.kde.org/trunk5/en/kdesrc-build/kdesrc-build/conf-options-table.html#conf-async)
+parameter, which permits network updates to be run in parallel with the build process, kdesrc-build implements
+some limited inter-process communication (IPC).
+
+In reality there are 3 separate long-term processes during an async build:
+
+ +-----------------+ +---------------+ +------------+
+ | | | | | |
+ | main / build <------ monitor <--------- update |
+ | | ^ | | ^ | |
+ +--------^--------+ | +---------------+ | +------------+
+ | | |
+ | $ipc $updaterToMonitorIPC
+ |
+ |
+ +--------v--------+
+ | |
+ user ------->| TTY |
+ | |
+ +-----------------+
+
+- 1. The main (build) process
+- 2. The update process, normally squelched
+- 3. A "monitor" process, connected to the other two
+
+## Why IPC is necessary
+
+IPC is used to carry information about the status of build updates back to the main process.
+
+Over the years this has evolved to include, using a custom app-specific protocol:
+
+- 1. Success/failure codes (per-module)
+- 2. Whether the module was even attempted to be updated at all
+- 3. Failure codes (overall)
+- 4. Log messages for a module (normally squelched during update)
+- 5. Changes to persistent options (must be forwarded to main proc to be persisted)
+- 6. "Post build" messages, which must be shown by the main thread just before exit.
+
+You could in principle do most of this by doing something like serializing
+changes into a file after each module update and then reading the results from
+the file in the main thread using file locking or similar. However it seemed
+simpler to ferry the information over IPC pipes instead.
+
+## How it works, today
+
+At this stage, the IPC data flow is mediated by [ksb::IPC](https://metacpan.org/pod/ksb%3A%3AIPC), which is an
+interface class with a couple of methods meant to be reimplemented by
+subclasses, and which implements the IPC API on top of those subclass-defined
+methods.
+
+The user code in kdesrc-build is required to create the IPC object before
+forking using ["fork" in perlfunc](https://metacpan.org/pod/perlfunc#fork). The parent then declares that it will be the
+receiver and the child declared that it will be the sender.
+
+### Monitor process
+
+Early experiments used only the two build (main) and update processes. However
+this quickly ran into issues trying to keep the main process U/I in sync.
+During a build there was no easy way to monitor the build child's output along
+with the update child's, and the update child would block if it tried to write
+too much output to the build process if the build process was itself blocked
+waiting for a build.
+
+The solution was to reinvent a message queue, poorly, for much the same reason
+you would use a message queue today in a distributed architecture. It
+simplified the problem for build and update and allowed the update process to
+send at will without blocking, and likewise the build thread did not have to
+worry about blocking by trying to read from the child unless it was safe to
+wait.
+
+The monitor simply uses a second [ksb::IPC](https://metacpan.org/pod/ksb%3A%3AIPC) object to connect to the update
+child process, and feeds messages it receives from the child to the parent, in
+the order received and exactly once.
+
+### Ordering the update and build
+
+To keep the build from proceeding before the update has completed, the IPC
+class supports methods to wait for the module to complete if it hasn't already.
+By their nature these are blocking methods, ultimately these block waiting on
+I/O from the monitor.
+
+This means that the build process will block forever if the update thread
+forgets to send the right message. The update process should build modules in
+the same order the build process will expect them, though this won't cause the
+build to block forever if it does not.
+
+### Squelching log messages
+
+The various logging methods all output the message immediately. This is
+problematic in the context of concurrent build and update processes, especially
+since most log messages do not duplicate the name of the module (since it's
+normally nearby in the U/I output).
+
+We resolve this tension by having the update process pass the IPC object into
+ksb::Debug, which will then feed the output to the IPC handle instead of
+STDOUT/STDERR. In the build process, as log messages are read in from the
+update process, they are stored and then printed out once it comes time to
+build the module.
+
+This system only works because the update and build processes are separate
+processes. The 'modern' scheme I'm building towards does not require the
+existence of a separate update process at all, but we may still retain it to
+make squelching work.
+
+### Commands that do not require IPC
+
+The log\_command() call in [ksb::Util](https://metacpan.org/pod/ksb%3A%3AUtil) also uses a fork-based construct to read
+I/O from a child (to redirect output to the log file and/or to a callback).
+
+It is safe to use this function from the update thread, as long as we are
+disciplined about using unique names for each log-file. The update process will
+set the `latest` and `error.log` symlinks as necessary, and the main process
+will find `error.log` where it expects to when making the report at the end.
+
+Note that this works only if the base log directory for the module is created
+in [ksb::BuildContext](https://metacpan.org/pod/ksb%3A%3ABuildContext) before the fork occurs!
+
+## How it will work, tomorrow
+
+Looking back, the IPC stuff I coded isn't as bad as I remember it to be. However
+there are still good reasons to work to replace it with some of the superior options
+supported by [Mojolicious](https://docs.mojolicious.org/).
+
+- Easier use of the Web and APIs
+
+ A lot of this work was kicked off based on conversations at Akademy 2018, where
+ people asked about a way to track the progress of a kdesrc-build build using
+ APIs or RPC. kdesrc-build isn't setup today to host a web server interface
+ **during** the build, and the [ksb::IPC](https://metacpan.org/pod/ksb%3A%3AIPC) stuff isn't helping on that front.
+
+ But this is what Mojolicious is built for.
+
+ However not only would it be good to have kdesrc-build be able to feed
+ information to e.g. a running Plasma applet, but it would also be good for
+ kdesrc-build to be able to make API calls to KDE infrastructure, for things
+ like bug management, creating new work branches in Gitlab, and so on.
+
+ For all these things it will be greatly helpful to have the Web-native
+ capability and event loop provided by Mojolicious.
+
+- Improved API
+
+ In addition, Mojolicious's concurrent code is just a simpler API. It doesn't
+ hurt that their "promise"-based API is the same API you'd find in JavaScript,
+ including browsers and Node.js ecosystems.
+
+ Unfortunately a lot of this is a fair bit different than what kdesrc-build has
+ been built to date. But I think I understand how to port it over time without
+ breaking everything.
+
+- Improved code correctness
+
+ Even though we ferry a lot of information from the update process to the main
+ process, there are still information types we do not that might be considered
+ bugs. For example, [ksb::OptionsBase](https://metacpan.org/pod/ksb%3A%3AOptionsBase)'s `getOption`/`setOption` methods
+ (which power the same in [ksb::Module](https://metacpan.org/pod/ksb%3A%3AModule) and [ksb::BuildContext](https://metacpan.org/pod/ksb%3A%3ABuildContext) do not make
+ any attempt to forward changes to the options dictionaries in the update
+ process back to the main process.
+
+ Mojolicious's "subprocess" feature would allow us to move the blocking portions
+ of the update command into a subprocess, while allowing the business logic to
+ be retained in the main process. This way there is only one place to call
+ `getOption`/`setOption` from, simplifying how the information flows.
+
+- Fewer bugs
+
+ Mojolicious has quite a few more users testing their code base compared to my
+ custom IPC stuff.
+
+- Finer granularity
+
+ Ultimately, Mojolicious would permit the main process to split the work of the
+ build process up to an even finer degree than "module update" or "module
+ build". This will allow the operating system a better opportunity to let
+ kdesrc-build use whatever is available between disk I/O, CPU, or network I/O.
+
+### The plan
+
+Ultimately, the plan is to introduce some porting-aid functions to [ksb::Util](https://metacpan.org/pod/ksb%3A%3AUtil)
+and use these to slowly port calls to `log_command()` to split the function into
+two parts:
+
+- 1. Generate a promise-based logging command
+- 2. Wait on the promise for the result
+
+By splitting the work into two steps we can avoid changing too much at once,
+while allowing for the slow merger of promise-based code into a chain of
+promises that can be handled at once using standard [Mojo::Promise](https://metacpan.org/pod/Mojo%3A%3APromise) methods.
+
+The significant limitation to this is that we **cannot call `promise->wait`**
+recursively!
+
+#### The recursive promise->wait issue
+
+The issue is that `promise->wait` requires that the I/O loop **not** be
+running, for much the same reason that we avoid nested event loops with
+Qt-based GUI programs. `wait` is simply a convenience method to run the event
+loop just long enough for the given promise to resolve or reject.
+
+If multiple promises are trying to `wait` at the same time in the presence of truly
+concurrent code then nothing good can happen.
+
+It might be possible to do this safely with structured concurrency (i.e. if the
+second promise being awaited were _guaranteed_ to always complete before the
+first promise then it should not be an issue). There might be a way to create a
+new [Mojo::IOLoop](https://metacpan.org/pod/Mojo%3A%3AIOLoop) to use with the inner promise so that we can safely wait on
+it.
+
+But it's better to avoid it entirely. That's why the porting methods I've written
+check to see if the I/O loop is running and, if it is, aborts the program.
+
+#### Implication of recursive waiting problems
+
+Since we can't wait recursively on promises, we generally need to port from
+blocking code to promises from leaf function calls on up.
+
+As an example if a call tree looks like:
+
+ + runAllTasks
+ \-+ handle_update
+ \-+ ksb::Module::update
+ \-+ ksb::Updater::Git::updateInternal
+ \-+ ksb::Updater::Git::updateExistingClone
+ +-+ ksb::Updater::Git::_auxFunction1
+ | \-- ksb::Updater::Git::_nestedAuxFunction1
+ \---- ksb::Updater::Git::_nestedAuxFunction2
+
+We might first port the "nested aux functions", making them create promises and
+then immediately await them so that they remain blocking.
+
+However, once we port their caller `_auxFunction1`, and make `_auxFunction1`
+create a promise and then await it to remain blocking, we **must** get rid of
+the blocking calls within the "nested aux functions", and have them deal only
+in promises.
+
+This will apply so on up the chain. At each level of the call tree that we want
+to block on a promise for each of porting, **all child calls** must be
+promise-native with no blocking at all!
+
+This can require rewriting complicated functions that have several
+"await\_result" calls to instead return a chain of promises.
diff --git a/doc/source-reference/Internals.md b/doc/source-reference/Internals.md
new file mode 100644
index 00000000..e11d8b18
--- /dev/null
+++ b/doc/source-reference/Internals.md
@@ -0,0 +1,81 @@
+# Module list construction
+
+An overview of the steps performed in constructing the module list:
+
+There are two parallel flows performed for module list construction
+
+1. Configuration file module list processing. The configuration file supports
+modules of various types along with module-sets. Modules of the kde-project
+type (available *only* from a module-set) can be converted later into 0, 1, or
+more git modules. Modules are formed into the list in the order given in the
+configuration file, but any modules implictly pulled in from the kde-project
+modules will be sorted appropriately by repo-metadata/dependencies.
+
+2. Modules can be directly specified on the command line. kde-projects modules
+can be forced by preceding the module name with a '+'.
+
+After processing command line module names, any modules that match a module
+(or module-set) given from the configuration file will have the configuration
+file version of that module spliced into the list to replace the command line
+one.
+
+So a graphical overview of configuration file modules
+
+> git, setA/git, setA/git, setA/git, setB/proj
+
+which is proj-expanded to form (for instance)
+
+> git, setA/git, setA/git, setA/git, setB/git, setB/git
+
+and is then filtered (respecting --resume-{from,after})
+
+> setA/git, setA/git, setA/git, setB/git, setB/git
+
+(and even this leaves out some details, e.g. l10n).
+
+Command-line modules:
+
+kdesrc-build also constructs a list of command-line-passed modules. Since the
+module names are read before the configuration file is even named (let alone
+read) kdesrc-build has to hold onto the list until much later in
+initialization before it can really figure out what's going on with the
+command line. So the sequence looks more like:
+
+> nameA/??, nameB/??, +nameC/??, nameD/??
+
+Then + names are forced to be proj-type
+
+> nameA/??, nameB/??, nameC/proj, nameD/??
+
+From here we "splice" in configuration file modules that have matching names
+to modules from the command line.
+
+> nameA/??, nameB/git, nameC/proj, nameD/??
+
+Following this we run a filter pass to remove whole module-sets that we don't
+care about (as the applyModuleFilters function cares only about
+$module->name(). In this example nameA happened to match a module-set name
+only.
+
+> nameB/git, nameC/proj, nameD/??
+
+Finally we match and expand potential module-sets
+
+> nameB/git, nameC/proj, nameE/proj, nameF/proj
+
+Not only does this expansion try to splice in modules under a named
+module-set, but it forces each module that doesn't already have a type into
+having a 'proj' type but with a special "guessed name" annotation, which is
+used later for proj-expansion.
+
+At this point we should be at the same point as if there were no command-line
+modules, just before we expand kde-projects modules (yes, this means that the
+--resume-* flags are checked twice for this case). At this point there is a
+separate pass to ensure that all modules respect the --no-{src,build,etc.}
+options if they had been read from the command line, but that could probably
+be done at any time and still work just fine.
+
+One other nuance is that if _nameD/??_ above had *not* actually been part of a
+module-set and was also not the name of an existing kde-project module, then
+trying to proj-expand it would have resulted in an exception being thrown
+(this is where the check for unknown modules occurs).
diff --git a/doc/source-reference/Module.md b/doc/source-reference/Module.md
new file mode 100644
index 00000000..108510c6
--- /dev/null
+++ b/doc/source-reference/Module.md
@@ -0,0 +1,216 @@
+# ksb::Module
+
+## DESCRIPTION
+
+This is ksb::Module, one of the core classes within kdesrc-build. It represents
+any single "buildable" module that kdesrc-build can manage. It acts as a common
+interface to the multiple types of build systems and source control management
+systems that kdesrc-build supports.
+
+The many options available to the user are managed using setOption/getOption
+(but see also the ksb::OptionsBase class that this derives from).
+
+kdesrc-build manages persistent metadata for each module as well, see
+{set,get}PersistentOption
+
+## METHODS
+
+The basic description of each method is listed here for ease of reference. See
+the source code itself for more detail.
+
+### Perl integration
+
+These functions are used to integrate into the Perl runtime or for use from
+other Perl modules.
+
+* ``new``, creates a new ksb::Module, and sets any provided options.
+
+* ``toString``, for "stringifying" a module into a quoted string.
+
+* ``compare``, for sorting ksb::Modules amongst each other based on name.
+
+### CONFIGURATION
+
+These functions are used to configure what the ksb::Module object should do,
+change settings, etc.
+
+* ``setModuleSet``, optional, specifies the ksb::ModuleSet this module was
+ spawned from.
+
+* ``setScmType``, sets the source control plugin (git, kde-projects) based
+ on the given scmType name. Normally auto-detection is used instead, this
+ permits manual setup.
+
+* ``buildSystemFromName``, as with ``setScmType``, used to manually set the
+ build system plugin. This is exposed to the user as *override-build-system*.
+
+* ``setBuildSystem``, like ``buildSystemFromName``, but passes the proper
+ ksb::BuildSystem directly.
+
+* ``setOption``, sets a configuration option that can be checked later using
+ getOption. Normally set from user input (cmdline or rc-file) but supports
+ ways for kdesrc-build to internally override user settings or set hidden
+ flags for action in later phases. Does not survive beyond the current
+ execution.
+
+* ``setPersistentOption``, sets an option to a string value that will be
+ read-in again on the next kdesrc-build run and can then be queried again.
+
+* ``unsetPersistentOption``, removes an existing persistent option.
+
+### INTROSPECTION
+
+These functions are generally just read-only accessors of information about the
+object.
+
+#### BASIC INFORMATION
+
+* ``name``, returns the module name. Only one module with a given name can be
+ present during a build.
+
+* ``buildContext``, returns the ksb::BuildContext (as set when the object
+ was constructed)
+
+* ``phases``, returns the list of execution phases (update, buildsystem, test,
+ etc.) that apply to this module in this execution.
+
+* ``moduleSet``, returns the ksb::ModuleSet that was assigned earlier as the
+ source set. If no module set was assigned, returns a valid (but null) set.
+
+#### PLUGIN HANDLERS
+
+* ``scm``, **autodetects** the appropriate scm plugin if not already done (or
+ manually set), and then returns the ksb::Updater plugin.
+
+* ``buildSystem``, **autodetects** the appropriate build system plugin if not
+ already done (or manually set) and then returns the
+ ksb::BuildSystem|ksb/BuildSystem.pm plugin.
+
+* ``scmType``, returns the **name** of the scm plugin (as determined by
+ scm(), which can itself cause an autodetection pass.
+
+* ``buildSystemType``, returns the **name** of the build system plugin (as
+ determined by buildSystem(), which can itself cause an autodetection pass.
+
+* ``currentScmRevision``, returns a string with an scm-specific revision ID.
+ Can be a Git-style SHA or something else entirely.
+ Can case an autodetection of the scm plugin.
+
+#### PATHS
+
+Various path-handling functions. These aren't always easy to tell what they do
+just from the method name, sadly.
+
+* ``getSubdirPath``, maps a path from the rc-file (based on the option-name to
+ pass to getOption) to a potential absolute path (handling tilde expansion
+ and relative paths). Does not handle colon-separated paths.
+
+* ``getInstallPathComponents``, returns information about the directory the
+ module should be installed to. See the detailed docs for this method at its
+ decl, but generally you can just call fullpath today.
+
+* ``getSourceDir``, returns absolute base path to the source directory (not
+ including dest-dir, module name, or anything else specific to this module).
+
+* ``getLogDir``, returns the base path to use for logs for this module during
+ this execution. **NOTE** Different modules can have different base paths.
+
+* ``getLogPath``, returns the absolute filename to open() for a log file for
+ this module based on the given basename. Updates the 'latest' symlink, which
+ can trigger clean up of old log dirs after all modules are built. Only use
+ when you're really going to open a log file!
+
+* ``fullpath``, returns the absolute full path to the source or build
+ directory, including any module name or dest-dir accoutrement. This is the
+ directory you can git-clone to, cd to for build, etc.
+
+* ``destDir``, returns the 'dest-dir' for the module. dest-dir is effectively
+ just a way to modify the on-disk module name. It used to be used more heavily
+ to allow for having multiple build/source directories for a given
+ module (varying by branch or tag), but even with git this value may change
+ for KDE-based repositories to set subdirectories that match KDE project
+ paths. Supports expanding '$MODULE' or '${MODULE}' sequences to what
+ otherwise would have been the dest-dir.
+
+* ``installationPath``, as labeled on the tin. Prefers the 'prefix' option but
+ falls back to 'install-dir' if not set.
+
+#### USER AND PERSISTENT OPTIONS
+
+* ``getOption``, returns the value of the given named option. If no such option
+ exists, inherits the same value from the module's build context. If no such
+ option exists there either, returns an empty string. Option values are used
+ by this function only exist during this script's execution. There is magic to
+ permit build jobs that run in a subprocess to feed option changes back to the
+ parent process.
+
+ * accepts an option name, normally as set in the rc-file. Can also accept a
+ second parameter 'module', to prevent falling back to a global option.
+ However doing this also permits ``undef`` to be returned so you must check
+ whether the result is defined.
+
+ * Options starting with '#' can only be set internally (i.e. not from rc-file
+ or cmdline) so this can be used as a way to tag modules with data meant not
+ to be user-accessible... but this should probably be factored into a
+ dedicated parallel option stack.
+
+ * The combination of module-specific and global options also contains a wee
+ bit of magic to control things like whether option values combine
+ ("$global-value $module-value" style) or whether a module setting
+ completely masks a global setting.
+
+* ``getPersistentOption``, similar to ``getOption``, only without the
+ module/global magic and the append/mask magic, and the subprocess-support
+ magic. But this function can return options that have been set in a previous
+ kdesrc-build run. kdesrc-build uses the location of the rc-file to determine
+ where to look for data from prior runs.
+
+#### KDE-SPECIFIC HANDLERS
+
+* ``fullProjectPath``, returns the logical module path in the git.kde.org
+ infrastructure for the module, if it's defined from a kde-projects module
+ set. E.g. for the 'juk' module, would return 'kde/kdemultimedia/juk'.
+
+* ``isKDEProject``, returns true if the module was sourced from the special
+ ``kde-projects`` module set in the user's rc-file. In this case the module's
+ ``moduleSet()`` function should return a ksb::ModuleSet that is-a
+ ksb::ModuleSet::KDEProjects.
+
+### OPERATIONS
+
+* ``update``, which executes the update (or pretends to do so) using the
+ appropriate source control system and returns a true/false value reflecting
+ success. Note this can also throw exceptions and future code is moving more
+ to this mode of error-handling.
+
+* ``build``, which executes the build **and** install (or pretends to in pretend
+ mode) using the appropriate build system and returns a true/false value
+ reflecting success. Can also run the testsuite as part of the build. Note
+ this can also throw exceptions and future code is moving more to this as the
+ error-handling mechanism.
+
+* ``setupBuildSystem``, which sets up the build system for the module to permit
+ ``build`` to work, including creating build dir, running cmake/configure/etc.
+ as appropriate. It is called automatically but will not take any action if
+ the build system is already established.
+
+* ``install``, which installs (or pretends to install) the module. Called
+ automatically by ``build``.
+
+* ``uninstall``, which uninstalls (or pretends to uninstall) the module. Not
+ normally called but can be configured to be called.
+
+* ``applyUserEnvironment``, this adds ``set-env`` module-specific environment
+ variable settings into the module's build context, called by
+ ``setupEnvironment``. This is needed since $ENV is not actually updated by
+ ksb::BuildContext until after a new child process is ``fork``'ed.
+
+* ``setupEnvironment``, called by the kdesrc-build build driver, running in a
+ subprocess, before calling the appropriate update/build/install etc. method.
+
+* ``getPostBuildMessages``, which returns a list of messages intended to be shown
+ to the user at the end of the build because they are so important that they should
+ not be missed. These should be used lightly, if at all.
+
+* ``addPostBuildMessage``, which pairs with ``getPostBuildMessages`` to add a message
+ to show to the user at the end of the build.
diff --git a/doc/source-reference/index.md b/doc/source-reference/index.md
new file mode 100644
index 00000000..b80ec7de
--- /dev/null
+++ b/doc/source-reference/index.md
@@ -0,0 +1,158 @@
+# kdesrc-build documentation
+
+Michael Pyne <mpyne at kde.org>
+v18.12, 2018-11-22
+
+kdesrc-build is intended to build KDE-based software from its source repository, although it can build
+other types of software from its native source control system(s) as well.
+
+This documentation is intended for developers to aid in hacking on kdesrc-build itself, or porting the same concepts
+to other build systems if necessary.
+
+## Concepts
+
+Some basic concepts are assumed throughout for brevity.
+
+### Modules
+
+kdesrc-build uses the "module" as the most granular level of buildable
+software. Each module has a name, unique in the list of all modules.
+Each module can have a specific source control system plugin (Git,
+KDE's git, etc.) and a build system plugin (qmake, CMake, KDE's
+CMake, autotools, etc.)
+
+### Build Phases
+
+A module's build process progresses through build phases, which are often
+optional.
+
+The normal progression is:
+
+. Update
+. Uninstall (not normally seen)
+. Build system setup and configuration
+. Build
+. Testsuite (if enabled)
+. Install
+
+The update phase can happen concurrently with other modules' build/install
+phases, under the theory that the build phase is usually CPU-heavy so it makes
+sense to start on subsequent network (IO-heavy) updates while the build
+progresses.
+
+### Build Context
+
+To group global settings and status together that exist across individual
+modules, a "build context" is used, shared across the entire application.
+
+Each module can refer to the global build context.
+
+### Configuration file (rc-file)
+
+kdesrc-build uses a configuration file (usually abbreviated the `rc-file`) to
+store:
+
+. The list of modules to build, and
+. The dependency order in which to build modules (the order seen in the rc-file), and
+. The build or configuration options to use by default or on a per-module
+basis.
+
+When kdesrc-build is run, it will use `kdesrc-buildrc` located in the current
+working directory. If this file is not present, the global rc-file at
+`~/.config/kdesrc-build/kdesrc-buildrc`
+(`$XDG_CONFIG_HOME/kdesrc-build/kdesrc-buildrc`, if `XDG_CONFIG_HOME`
+environment variable is set) is used instead.
+
+If neither of above is found, kdesrc-build will fallback to `~/.kdesrc-buildrc`.
+This location is checked only for backward compatibility; it is advised to move
+the configuration file to the XDG compliant path instead.
+
+### Command line
+
+kdesrc-build uses the command line (seen as "cmdline" in the source and commit
+logs) to override the list of modules to build (nearly always still requiring
+that any modules built are visible from the rc-file). The command line is also
+used to override various options (such as skipping source update phases),
+control output verbosity and so on.
+
+In theory every option in the rc-file can be set from the cmdline, and cmdline
+entries override and mask any options used by default or read from an rc-file.
+
+### Module Sets
+
+With the adoption of git, KDE exploded to having hundreds of repositories. It
+would be annoying and error-prone to try to manually update the rc-file with
+the list of modules to build and the proper ordering.
+
+Because of this, kdesrc-build supports grouping modules into "module sets" of
+modules that have common options and a common repository URL prefix, as if the
+user had manually entered those modules one by one.
+
+NOTE: This is controlled by the `git-repository-base` option to set the URL
+prefix, the `repository` option to choose one of the defined bases, and the
+`use-modules` option to list module names.
+
+#### KDE module sets
+
+To support the KDE repositories in particular, a special module set repository
+is defined, `kde-projects`. Use of this repository enables some extra magic
+in the modules that are ultimately defined from such a module set, including
+automagic dependency handling and inclusion of modules based on a virtual KDE
+project structure.
+
+NOTE: Inclusion of modules is **separate** from dependency handling, which is
+also supported!
+
+### Pretend mode
+
+The user can pass a `--pretend` cmdline flag to have kdesrc-build not
+actually undertake the more time or resource intensive actions, so that the
+user can see what kdesrc-build would do and tweak their cmdline until it looks
+correct, and then remove the --pretend flag from there.
+
+This significantly influences the design of the script, both in action and
+output.
+
+### Logs and build output
+
+All build commands are logged to a file (see `log_command` in ksb::Util).
+This is both to declutter the terminal output and to enable troubleshooting
+after a build failure.
+
+The logs are generally kept in a separate directory for each separate run of
+kdesrc-build. A "latest" symlink is created for each module name, which points
+to the last instance of a script run.
+
+If a build ends in a failure, an error.log symlink is created in the specific
+log directory for that module, which points to the specific build phase output
+file where the build was determined to have failed.
+
+Sometimes there is no log though (e.g. an internal kdesrc-build failure outside
+of log_command)!
+
+Some users prefer to have TTY output. For now the --debug cmdline option is
+useful for that, but --debug has a significant amount of other changes as well.
+
+## Basic flow
+
+For each script execution, kdesrc-build generically goes through the following
+steps:
+
+. Read the cmdline to determine global options, list of module *selectors*
+(modules are defined later) and potentially alternate rc-files to use.
+. Opens the selected rc-file (chosen on cmdline or based on `$PWD`) and reads
+in the list of modules and module-sets in the rc-file along with the options
+chosen for each.
+. Ensures that the KDE git repository metadata is available (containing
+dependency information and the virtual project path hierarchy)
+. If module selectors are available from the cmdline, creates the build list by
+expanding those selectors into the appropriate modules from the rc-file. If no
+selectors, uses all module sets and modules from the rc-file.
+ * Either mode can involve resolving dependencies for KDE-based modules.
+. Forks additional children to serve as a way to perform updates and build in
+separate processes so that they may proceed concurrently. Once ready, performs
+these two steps concurrently:
+.. Updates each module in order, and
+.. Performs remaining module build steps in order (waiting for the update if
+ needed).
+. When all update/build processes are done, displays the results to the user.
diff --git a/doc/supported-cmdline-params.docbook b/doc/supported-cmdline-params.docbook
new file mode 100644
index 00000000..25ccfc7c
--- /dev/null
+++ b/doc/supported-cmdline-params.docbook
@@ -0,0 +1,668 @@
+<sect1 id="supported-cmdline-params">
+<title>Supported command-line parameters</title>
+
+<sect2>
+<title>Generic</title>
+<variablelist>
+
+<varlistentry id="cmdline-pretend">
+<term><option><link linkend="cmdline-pretend">--pretend</link></option> (or <option>--dry-run</option> or <option>-p</option>)</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-include-dependencies">
+<term><option><link linkend="cmdline-include-dependencies">--include-dependencies</link></option> (or <option>-d</option>), <option>--no-include-dependencies</option> (or <option>-D</option>)</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 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-ignore-modules">
+<term><option><link linkend="cmdline-ignore-modules">--ignore-modules</link></option> (or <option>-!</option>) <parameter>module [module ...]</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>
+<para>Note that this option does not override <link linkend="conf-ignore-modules">ignore-modules</link> config option in global section. Instead, it appends it.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-run">
+<term><option><link linkend="cmdline-run">--run</link></option> (or <option>--start-program</option>) [-e|--exec name] [-f|--fork] <parameter>program [parameters ...]</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, source the
+prefix.sh to apply environment variables, and then execute the given program.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-revision">
+<term><option><link linkend="cmdline-revision">--revision</link></option> <replaceable>id</replaceable></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-delete-my-patches">
+<term><option><link linkend="cmdline-delete-my-patches">--delete-my-patches</link></option>, <option>--no-delete-my-patches</option></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><option><link linkend="cmdline-delete-my-settings">--delete-my-settings</link></option>, <option>--no-delete-my-settings</option></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-option-name">
+<term><option><link linkend="cmdline-option-name">--<replaceable><option-name></replaceable></link></option> <replaceable>value</replaceable></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-async">--no-async</link> command line options that are
+preferred by &kdesrc-build;.
+</para></note>
+
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-set-module-option-value">
+<term><option><link linkend="cmdline-set-module-option-value">--set-module-option-value</link> <replaceable><module-name></replaceable>,<replaceable><option-name></replaceable>,<replaceable><option-value></replaceable></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.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</sect2>
+
+<sect2>
+<title>Resuming and stopping</title>
+<variablelist>
+
+<varlistentry id="cmdline-resume-from">
+<term><option><link linkend="cmdline-resume-from">--resume-from</link></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>--no-src</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-resume-after">
+<term><option><link linkend="cmdline-resume-after">--resume-after</link></option> (or <option>--after</option> or <option>-a</option>) <replaceable>module</replaceable></term>
+<listitem><para>
+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-resume">
+<term><option><link linkend="cmdline-resume">--resume</link></option></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></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-stop-before">
+<term><option><link linkend="cmdline-stop-before">--stop-before</link></option> (or <option>--until</option>) <replaceable>module</replaceable></term>
+<listitem><para>
+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-stop-after">
+<term><option><link linkend="cmdline-stop-after">--stop-after</link></option> (or <option>--to</option>) <replaceable>module</replaceable></term>
+<listitem><para>
+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-stop-on-failure">
+<term><option><link linkend="cmdline-stop-on-failure">--stop-on-failure</link></option>, <option>--no-stop-on-failure</option></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>
+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><option><link linkend="cmdline-rebuild-failures">--rebuild-failures</link></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
+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>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</sect2>
+
+<sect2>
+<title>Modules information</title>
+<variablelist>
+
+<varlistentry id="cmdline-query">
+<term><option><link linkend="cmdline-query">--query</link></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>mode</quote>, which may be
+one of the following:</para>
+ <itemizedlist>
+ <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><parameter>build-dir</parameter>, which causes &kdesrc-build; to
+ output the full path to where the module build process occurs.
+ </para></listitem>
+ <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><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><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><parameter>module-set</parameter>, which causes &kdesrc-build; to
+ output the name of module-set which contains the module. This can be used
+ to generate zsh autocompletion cache.
+ </para></listitem>
+ <listitem><para><parameter>build-system</parameter>, which causes &kdesrc-build; to
+ output the name of build system detected for the module. This can be used
+ to debug build system auto-detection problems, or when developing tests for specific build systems.
+ </para></listitem>
+ <listitem><para>Any option name that is valid for modules in the
+ <link linkend="conf-options-table">configuration file</link>.
+ </para></listitem>
+ </itemizedlist>
+
+<informalexample>
+<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
+kdepim: master
+</screen>
+</informalexample>
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-dependency-tree">
+<term><option><link linkend="cmdline-dependency-tree">--dependency-tree</link></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 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><option><link linkend="cmdline-dependency-tree-fullpath">--dependency-tree-fullpath</link></option></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-list-installed">
+<term><option><link linkend="cmdline-list-installed">--list-installed</link></option></term>
+<listitem>
+<para>
+Print installed modules and exit. This can be used to generate autocompletion for the --run option.
+</para>
+</listitem>
+</varlistentry>
+
+</variablelist>
+</sect2>
+
+<sect2>
+<title>Exclude specific action</title>
+<variablelist>
+
+<varlistentry id="cmdline-no-metadata">
+<term><option><link linkend="cmdline-no-metadata">--no-metadata</link></option> (or <option>-M</option>)</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-src">
+<term><option><link linkend="cmdline-no-src">--no-src</link></option> (or <option>-S</option>)</term>
+<listitem><para>
+Skip contacting the &git; server.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-no-build">
+<term><option><link linkend="cmdline-no-build">--no-build</link></option></term>
+<listitem><para>
+Skip the build process.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-no-install">
+<term><option><link linkend="cmdline-no-install">--no-install</link></option></term>
+<listitem><para>
+Do not automatically install packages after they are built.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</sect2>
+
+<sect2>
+<title>Only specific action</title>
+<variablelist>
+
+<varlistentry id="cmdline-metadata-only">
+<term><option><link linkend="cmdline-metadata-only">--metadata-only</link></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.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-src-only">
+<term><option><link linkend="cmdline-src-only">--src-only</link></option> (or <option>-s</option>)</term>
+<listitem><para>
+Only perform the source update.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-build-only">
+<term><option><link linkend="cmdline-build-only">--build-only</link></option></term>
+<listitem><para>
+Only perform the build process.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-install-only">
+<term><option><link linkend="cmdline-install-only">--install-only</link></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><option><link linkend="cmdline-build-system-only">--build-system-only</link></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
+for compatibility with older versions only, this effect is not helpful for
+the current &kde; build system.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</sect2>
+
+<sect2>
+<title>Build behavior</title>
+<variablelist>
+
+<varlistentry id="cmdline-build-when-unchanged">
+<term><option><link linkend="cmdline-build-when-unchanged">--build-when-unchanged</link></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-refresh-build">
+<term><option><link linkend="cmdline-refresh-build">--refresh-build</link></option> (or <option>-r</option>)</term>
+<listitem><para>
+Recreate the build system and make from scratch.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-reconfigure">
+<term><option><link linkend="cmdline-reconfigure">--reconfigure</link></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-install-dir">
+<term><option><link linkend="cmdline-install-dir">--install-dir</link> <replaceable>path</replaceable></option></term>
+<listitem><para>
+This allows you to change the directory where modules will be installed to. 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><link linkend="cmdline-generate-vscode-project-config">--generate-vscode-project-config</link></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><link linkend="cmdline-async">--async</link></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><link linkend="cmdline-color">--color</link></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><link linkend="cmdline-nice">--nice</link></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><link linkend="cmdline-rc-file">--rc-file</link></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><link linkend="cmdline-initial-setup">--initial-setup</link></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>
+</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>
+ at the same time.
+ In kdesrc-build (perl implementation) it additionally uses "--install-distro-packages-perl".
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-install-distro-packages">
+<term><option><link linkend="cmdline-install-distro-packages">--install-distro-packages</link></option></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><option><link linkend="cmdline-generate-config">--generate-config</link></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>
+
+</variablelist>
+</sect2>
+
+<sect2>
+<title>Verbosity level</title>
+<para>
+
+</para>
+<variablelist>
+
+<varlistentry id="cmdline-debug">
+<term><option><link linkend="cmdline-debug">--debug</link></option></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-quiet">
+<term><option><link linkend="cmdline-quiet">--quiet</link></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><link linkend="cmdline-really-quiet">--really-quiet</link></option></term>
+<listitem><para>
+Only output warnings and errors.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-verbose">
+<term><option><link linkend="cmdline-verbose">--verbose</link></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><link linkend="cmdline-version">--version</link></option> (or <option>-v</option>)</term>
+<listitem><para>
+Display the program version.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="cmdline-help">
+<term><option><link linkend="cmdline-help">--help</link></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><link linkend="cmdline-show-info">--show-info</link></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>
+
+<varlistentry id="cmdline-show-options-specifiers">
+<term><option><link linkend="cmdline-show-options-specifiers">--show-options-specifiers</link></option></term>
+<listitem><para>
+Print the specifier lines (in the format that GetOpts::Long accepts) for all command line options supported by the script.
+This may be used by developers, for example, for generating zsh autocompletion functions.
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+</sect2>
+</sect1>
diff --git a/doc/supported-envvars.docbook b/doc/supported-envvars.docbook
new file mode 100644
index 00000000..772b325b
--- /dev/null
+++ b/doc/supported-envvars.docbook
@@ -0,0 +1,10 @@
+<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>
diff --git a/doc/using-kdesrc-build.docbook b/doc/using-kdesrc-build.docbook
new file mode 100644
index 00000000..5c3fabd2
--- /dev/null
+++ b/doc/using-kdesrc-build.docbook
@@ -0,0 +1,30 @@
+<chapter id="using-kdesrc-build">
+<title>Using &kdesrc-build;</title>
+
+<sect1 id="using-kdesrc-build-preface">
+<title>Preface</title>
+
+<para>Normally using &kdesrc-build; after you have gone through <xref linkend="getting-started" />
+is as easy as doing the following from a terminal prompt:</para>
+
+<screen>
+<prompt>%</prompt> <command><userinput>kdesrc-build</userinput></command>
+</screen>
+
+<para>&kdesrc-build; will then download the sources for &kde;, try to configure
+and build them, and then install them.</para>
+
+<para>Read on to discover how &kdesrc-build; does this, and what else you can
+do with this tool.</para>
+
+</sect1>
+
+&basic-features;
+
+&advanced-features;
+
+&developer-features;
+
+&other-features;
+
+</chapter>
diff --git a/scripts/build-docs b/scripts/build-docs
new file mode 100755
index 00000000..20220b25
--- /dev/null
+++ b/scripts/build-docs
@@ -0,0 +1,105 @@
+#!/bin/bash
+
+# Builds a local copy of KDE Docbook-based documentation for testing
+# during development.
+
+# Turn on sanity checking
+set -e
+set -u
+# set -o pipefail is a bashism unfortunately
+
+# Change if you want to render to several separate files (a crutch to workaround non-working kde-nochunk.xsl)
+SINGLE_FILE_OUTPUT=0
+
+function render_docbook() {
+ local PATH_TO_DOCBOOK="${PWD}/$1"
+ local DEST_DIR="$2"
+ local XSLT="$3"
+
+ local LANG_ISO3166_2="en"
+
+ # The kdoctools install process installs support files for DocBook handling to
+ # the application data dir. We need some of these xsl files for meinproc to
+ # use.
+ local DATA_DIR
+ DATA_DIR=$(kf5-config --install data)
+ DATA_DIR=${DATA_DIR%/} # Remove trailing /
+
+ local COMMON_DIR="kdoctools5-common"
+ # The single quotes are exceedingly important for later. The dir path inside
+ # the single quotes should be relative to make browser maximally happy; we use
+ # a symlink later to make that possible but there's probably better ways to get
+ # after this same goal
+ local BROWSER_COMMON
+ BROWSER_COMMON=$(printf "'%s/'" "$COMMON_DIR")
+
+ local DOC_SRCDIR="$DATA_DIR/kf5/kdoctools"
+ XSLT="$DOC_SRCDIR/customization/${XSLT}"
+
+ mkdir -p "${DEST_DIR}"
+
+ # Check for obvious errors
+ if [ ! -e "${PATH_TO_DOCBOOK}" ]; then
+ echo "Unable to find Docbook file. Try running from the documentation directory!" >&2
+ exit 1
+ fi
+
+ if [ ! -e "${XSLT}" ]; then
+ echo "Unable to find documentation style template. Is kdoctools installed?" >&2
+ exit 1
+ fi
+
+ # We need to run this from right directory, i.e. the directory we want
+ # generated output to go to. Ensure meinproc will find common files in this
+ # directory.
+
+ if [ ! -e "${DEST_DIR}/$COMMON_DIR" ]; then
+ ln -s "$DATA_DIR/doc/HTML/$LANG_ISO3166_2/$COMMON_DIR" "${DEST_DIR}"
+ fi
+
+ local CUR_DIR
+ CUR_DIR="${PWD}"
+ cd "${DEST_DIR}"
+
+ rm -rf ./*.html ./*.1 # cleaning up, because different stylesheets could render to files with different names. ".1" - extension for man.
+
+ if [ "${SINGLE_FILE_OUTPUT}" == 1 ]; then
+ PAR_OUTPUT="--output"
+ PAR_OUTPUT_VAL="preview.html"
+ else
+ PAR_OUTPUT=""
+ PAR_OUTPUT_VAL=""
+ fi
+
+ # Run meinproc to generate our output
+ meinproc6 --srcdir "$DOC_SRCDIR" \
+ --param kde.common="$BROWSER_COMMON" \
+ --param chunker.output.encoding="UTF-8" \
+ --param chunker.output.indent="yes" \
+ --stylesheet "$XSLT" \
+ "$PATH_TO_DOCBOOK" ${PAR_OUTPUT} ${PAR_OUTPUT_VAL}
+
+ cd "$CUR_DIR" # to set the correct starting folder when invoking this function for next docbooks
+ echo "Rendered $1 to $2 using $3"
+}
+
+#STYLE=kde-chunk-common.xsl
+STYLE=kde-chunk-online.xsl # the official one, used in docs.kde.org website.
+#STYLE=kde-chunk.xsl
+#STYLE=kde-include-common.xsl # renders with broken characters?
+#STYLE=kde-include-man.xsl # renders to man format, not html.
+#STYLE=kde-navig-online.xsl
+#STYLE=kde-navig.xsl
+#STYLE=kde-nochunk.xsl # still renders to several files?
+#STYLE=kde-style.xsl
+#STYLE=kde-ttlpg-online.xsl
+#STYLE=kde-ttlpg.xsl
+#STYLE=kde-web-navig.xsl
+#STYLE=kde-web.xsl # looks pretty similar to kde-chunk-online.xsl
+
+DOCBOOK_DIR="../doc"
+RENDER_DIR="../doc"
+
+# render_docbook usage: $1 = docbook_file, $2 = folder for rendered html files, $3 - stylesheet_file
+render_docbook "${DOCBOOK_DIR}/index.docbook" "${RENDER_DIR}/preview_doc_html" "$STYLE"
+render_docbook "${DOCBOOK_DIR}/man-kdesrc-build.1.docbook" "${RENDER_DIR}/preview_man_html" "$STYLE"
More information about the kde-doc-english
mailing list