docs: html.in: Convert 'compiling' to rst

Signed-off-by: Erik Skultety <eskultet@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
This commit is contained in:
Erik Skultety 2021-03-12 08:34:15 +01:00
parent 5e7289e068
commit 9f8696d62f
3 changed files with 96 additions and 116 deletions

View File

@ -1,115 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<body>
<h1><a id="installation">libvirt Installation</a></h1>
<ul id="toc"></ul>
<h2><a id="compiling">Compiling a release tarball</a></h2>
<p>
libvirt uses the standard setup/build/install steps and mandates
that the build directory is different from the source directory:
</p>
<pre>
$ xz -dc libvirt-x.x.x.tar.xz | tar xvf -
$ cd libvirt-x.x.x
$ meson build</pre>
<p>
The <i>meson</i> script can be given options to change its default
behaviour.
</p>
<p>
To get the complete list of the options run the following command:
</p>
<pre>
$ meson configure</pre>
<p>
When you have determined which options you want to use (if any),
continue the process.
</p>
<p>
Note the use of <b>sudo</b> with the <i>ninja install</i> 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.
</p>
<p>
If you are installing to a location that your user <i>does</i> have write
access to, then you can instead run the <i>ninja install</i> command
without putting <b>sudo</b> before it.
</p>
<pre>
$ meson build <i>[possible options]</i>
$ ninja -C build
$ <b>sudo</b> <i>ninja -C build install</i></pre>
<p>
At this point you <b>may</b> have to run ldconfig or a similar utility
to update your list of installed shared libs.
</p>
<h2><a id="building">Building from a GIT checkout</a></h2>
<p>
The libvirt build process uses Meson build system. By default when
the <code>meson</code> 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.
</p>
<p>To build &amp; install libvirt to your home
directory the following commands can be run:
</p>
<pre>
$ meson build --prefix=$HOME/usr
$ ninja -C build
$ <b>sudo</b> ninja -C build install</pre>
<p>
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
</p>
<pre>
$ meson build -Dsystem=true
$ ninja -C build
</pre>
<p>
When doing this for day-to-day development purposes, it is recommended
not to install over the OS vendor provided binaries. Instead simply
run libvirt directly from the source tree. For example to run
a privileged libvirtd instance
</p>
<pre>
$ su -
# service libvirtd stop (or systemctl stop libvirtd.service)
# /home/to/your/checkout/build/src/libvirtd
</pre>
<p>
It is also possible to run virsh directly from the build tree
using the ./run script (which sets some environment variables):
</p>
<pre>
$ pwd
/home/to/your/checkout/build
$ ./run ./tools/virsh ....
</pre>
</body>
</html>

95
docs/compiling.rst Normal file
View File

@ -0,0 +1,95 @@
====================
libvirt Installation
====================
.. contents::
Compiling a release tarball
---------------------------
libvirt uses the standard setup/build/install steps and mandates that
the build directory is different from the source directory:
::
$ 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.
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.
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.
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.
To build & install libvirt to your home directory the following commands
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
paths will all be different. To produce a build that is compatible with
normal OS vendor prefixes, use
::
$ meson build -Dsystem=true
$ ninja -C build
When doing this for day-to-day development purposes, it is recommended
not to install over the OS vendor provided binaries. Instead simply run
libvirt directly from the source tree. For example to run a privileged
libvirtd instance
::
$ su -
# service libvirtd stop (or systemctl stop libvirtd.service)
# /home/to/your/checkout/build/src/libvirtd
It is also possible to run virsh directly from the build tree using the
./run script (which sets some environment variables):
::
$ pwd
/home/to/your/checkout/build
$ ./run ./tools/virsh ....

View File

@ -36,7 +36,6 @@ docs_html_in_files = [
'auth',
'bugs',
'cgroups',
'compiling',
'contact',
'contribute',
'csharp',
@ -111,6 +110,7 @@ docs_rst_files = [
'ci',
'coding-style',
'committer-guidelines',
'compiling',
'daemons',
'developer-tooling',
'formatbackup',