docs: compiling: Separate 'prepare', 'configure', and 'build' steps

Only the preparation of sources differs between a build from a git
checkout vs a build from tarball. Restructure the docs to outline the
difference and combine information on how to configure libvirt.

Most notably the suggestion to use '-Dsystem=true' was present only for
the steps to build a git checkout.

Suggest also running the testsuite as part of the build step.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>

1 files changed, 53 insertions, 32 deletions

diff --git a/docs/compiling.rst b/docs/compiling.rst
index 0a9b9d0833..e9d055914f 100644
--- a/docs/compiling.rst
+++ b/docs/compiling.rst
@@ -24,24 +24,47 @@ allow installing the most recent versions of virtualization packages:
    The ``app-emulation/libvirt`` is regularly updated, but newest versions are
    usually marked as testing by the ``~*`` keyword.
 
-Compiling a release tarball
----------------------------
+Preparing sources
+-----------------
 
-libvirt uses the standard setup/build/install steps and mandates that
-the build directory is different from the source directory:
+Libvirt can be built both from release tarballs and from a git checkout using
+the same steps once the source code is prepared. Note that the build system
+requires that the build directory is separate from the top level source
+directory.
+
+By default further steps will build libvirt inside a subdirectory of the source
+tree named ``build``.
+
+Refer to the `downloads page <downloads.html>`__ for official tarballs and the
+git repository.
+
+Unpacking a source tarball
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Download a source tarball of the version you want to compile and unpack it
+using the following commands:
 
 ::
 
    $ xz -dc libvirt-x.x.x.tar.xz | tar xvf -
    $ cd libvirt-x.x.x
-   $ meson build
 
-The *meson* script can be given options to change its default behaviour.
+Git checkout
+~~~~~~~~~~~~
+
+A git checkout/clone is already in correct state for next steps. Just change
+your working directory to the checkout.
+
+Configuring the project
+-----------------------
 
-**Note:** Please ensure that you have the appropriate minimal ``meson`` version
-installed in your build environment. The minimal version for a specific package
-can be checked in the top level ``meson.build`` file in the ``meson_version``
-field.
+The libvirt build process uses the **Meson** build system. To configure for a
+build use the following command. Note that the ``build`` argument is the name
+of the build directory which will be created.
+
+::
+
+   $ meson build [options]
 
 To get the complete list of the options run the following command:
 
@@ -49,43 +72,41 @@ To get the complete list of the options run the following command:
 
    $ meson configure
 
-When you have determined which options you want to use (if any),
-continue the process.
+Be aware that by default the build is configured with a local ``prefix`` path
+which will not interoperate with OS vendor provided binaries, since the UNIX
+socket paths will all be different. To produce a build that is compatible with
+normal OS vendor prefixes, use
 
 ::
 
-   $ meson build [possible options]
-   $ ninja -C build
+   $ meson build -Dsystem=true
 
-The ``build`` directory now contains the built binaries.
+By default when the ``meson`` is run from within a GIT checkout, it will turn
+on -Werror for builds. This can be disabled with --werror=false, but this is
+not recommended.
 
-Building from a GIT checkout
-----------------------------
+Please ensure that you have the appropriate minimal ``meson`` version installed
+in your build environment. The minimal version for a specific package can be
+checked in the top level ``meson.build`` file in the ``meson_version`` field.
 
-The libvirt build process uses Meson build system. By default when the
-``meson`` is run from within a GIT checkout, it will turn on -Werror for
-builds. This can be disabled with --werror=false, but this is not
-recommended.
 
-To build & install libvirt to your home directory the following commands
-can be run:
+Compiling the sources
+---------------------
+
+To build the configured project run (note that ``-C build`` is a path to the
+build directory):
 
 ::
 
-   $ meson build --prefix=$HOME/usr
    $ ninja -C build
 
-Be aware though, that binaries built with a custom prefix will not
-interoperate with OS vendor provided binaries, since the UNIX socket
-paths will all be different. To produce a build that is compatible with
-normal OS vendor prefixes, use
+The ``build`` directory now contains the built binaries.
 
-::
+Additionally you can also run the test suite:
 
-   $ meson build -Dsystem=true
-   $ ninja -C build
+::
 
-The ``build`` directory now contains the built binaries.
+   $ ninja -C build test
 
 Running compiled binaries from build directory
 ----------------------------------------------