Users should be encouraged to install libvirt from the distro's repos in the first place. Also encourage distro-specific ways to get newer versions, rather than building from source manually. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/compiling.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/compiling.rst b/docs/compiling.rst index 7746f20bed..25dd0f4265 100644 --- a/docs/compiling.rst +++ b/docs/compiling.rst @@ -4,6 +4,26 @@ libvirt Installation .. contents:: +Installing from distribution repositories +----------------------------------------- + +This is the recommended option to install libvirt. Libvirt is present in the +package repositories of all major distributions. Installing a package from the +package manager ensures that it's properly compiled, installed, and updated +during the lifecycle of the distribution. + +For users who wish to use the most recent version, certain distributions also +allow installing the most recent versions of virtualization packages: + + **Fedora** + + Refer to https://fedoraproject.org/wiki/Virtualization_Preview_Repository + + **Gentoo** + + The ``app-emulation/libvirt`` is regularly updated, but newest versions are + usually marked as testing by the ``~*`` keyword. + Compiling a release tarball --------------------------- -- 2.37.1

Create a section for instructions on how to install the built binaries rather than mentioning it multiple times. Add a note that installing over your distro-provided packages will most likely break your instalation. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/compiling.rst | 44 +++++++++++++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 13 deletions(-) diff --git a/docs/compiling.rst b/docs/compiling.rst index fc5556738d..c167fd238f 100644 --- a/docs/compiling.rst +++ b/docs/compiling.rst @@ -52,23 +52,12 @@ To get the complete list of the options run the following command: When you have determined which options you want to use (if any), continue the process. -Note the use of **sudo** with the *ninja install* command below. Using -sudo is only required when installing to a location your user does not -have write access to. Installing to a system location is a good example -of this. - -If you are installing to a location that your user *does* have write -access to, then you can instead run the *ninja install* command without -putting **sudo** before it. - :: $ meson build [possible options] $ ninja -C build - $ sudo ninja -C build install -At this point you **may** have to run ldconfig or a similar utility to -update your list of installed shared libs. +The ``build`` directory now contains the built binaries. Building from a GIT checkout ---------------------------- @@ -85,7 +74,6 @@ can be run: $ meson build --prefix=$HOME/usr $ ninja -C build - $ sudo ninja -C build install Be aware though, that binaries built with a custom prefix will not interoperate with OS vendor provided binaries, since the UNIX socket @@ -97,6 +85,7 @@ normal OS vendor prefixes, use $ meson build -Dsystem=true $ ninja -C build +The ``build`` directory now contains the built binaries. Running compiled binaries from build directory ---------------------------------------------- @@ -120,3 +109,32 @@ It is also possible to run virsh directly from the build tree using the $ pwd /home/to/your/checkout/build $ ./run ./tools/virsh .... + +Installing compiled binaries +---------------------------- + +**Important:** Manual installation of libvirt is generally not recommended and +you should prefer installation from package repository or from manually build +packages which are then installed using the package manager. Overwriting an +installation of libvirt from the package manager by a manually compilled +installation may not work properly. + +Installing of the compiled binaries into the appropriate location (based on +how the build was configured) is done by the following command: + +:: + + $ sudo ninja -C build install + +Note the use of **sudo** with the *ninja install* comman. Using +sudo is only required when installing to a location your user does not +have write access to. Installing to a system location is a good example +of this. + +If you are installing to a location that your user *does* have write +access to, then you can instead run the *ninja install* command without +putting **sudo** before it. + +After installation you you **may** have to run ``ldconfig`` or a similar +utility to update your list of installed shared libs, or adjust the paths where +the system looks for binaries and shared libraries. -- 2.37.1

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> --- 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

To prevent surprises when a build doesn't in fact contain the required functionality suggest that users force-enable required modules. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/compiling.rst | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/docs/compiling.rst b/docs/compiling.rst index 1969b9b0b0..1d06136ca6 100644 --- a/docs/compiling.rst +++ b/docs/compiling.rst @@ -81,11 +81,30 @@ normal OS vendor prefixes, use $ meson build -Dsystem=true +Explicitly enabling required functionality +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default each module of functionality of libvirtd is optionally enabled, +meaning it will be enabled if the build environment contains the required +dependencies. + +To ensure that your build contains the required functionality it's recommended +to explicitly enable given modules, in which case the configure step will end +with an error if dependencies are not present. **Example:** to build the +libvirt project with support for the **qemu** driver use the following options: + +:: + + $ meson build -Dsystem=true -Ddriver_qemu=enabled + +Notes: +~~~~~~ + 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 +Please also 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. -- 2.37.1