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@xxxxxxxxxx>
---
docs/compiling.rst | 86 +++++++++++++++++++++++++++++-----------------
1 file changed, 54 insertions(+), 32 deletions(-)
diff --git a/docs/compiling.rst b/docs/compiling.rst
index c167fd238f..1969b9b0b0 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
+~~~~~~~~~~~~
-**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.
+A git checkout/clone is already in correct state for next steps. Just change
+your working directory to the checkout.
+
+Configuring the project
+-----------------------
+
+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,42 @@ 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.
+
+**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.
-Building from a GIT checkout
-----------------------------
-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.
+Compiling the sources
+---------------------
-To build & install libvirt to your home directory the following commands
-can be run:
+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
----------------------------------------------
--
2.37.1
