External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-10-31 02:13:27 +00:00
Code Issues Packages Projects Releases Wiki Activity
0e7549fe47
libvirt/docs/compiling.html.in

114 lines
3.1 KiB
HTML
Raw Normal View History

Fix multiple formatting problems in HTML docs The rule generating the HTML docs passing the --html flag to xsltproc. This makes it use the legacy HTML parser, which either ignores or tries to fix all sorts of broken XML tags. There's no reason why we should be writing broken XML in the first place, so removing --html and adding the XHTML doctype to all files forces us to create good XML. This adds the XHTML doc type and fixes many, many XML tag problems it exposes. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-05-03 14:25:37 +00:00
<?xml version="1.0" encoding="UTF-8"?>
docs: switch to using HTML5 doctype declaration The HTML5 doctype is simply <!DOCTYPE html> no DTD is present because HTML5 is no longer defined as an extension of SGML. XSL has no way to natively output a doctype without a public or system identifier, so we have to use an <xsl:text> hack instead. See also https://dev.w3.org/html5/html-author/#doctype-declaration Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 17:01:25 +00:00
<!DOCTYPE html>
Fix multiple formatting problems in HTML docs The rule generating the HTML docs passing the --html flag to xsltproc. This makes it use the legacy HTML parser, which either ignores or tries to fix all sorts of broken XML tags. There's no reason why we should be writing broken XML in the first place, so removing --html and adding the XHTML doctype to all files forces us to create good XML. This adds the XHTML doc type and fixes many, many XML tag problems it exposes. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-05-03 14:25:37 +00:00
<html xmlns="http://www.w3.org/1999/xhtml">
docs: added compiling page and significantly expanded windows page Also added an additional menu placement for the windows page, in order to attract further potential testers.
2010-12-21 09:38:37 +00:00
<body>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 14:52:42 +00:00
<h1><a id="installation">libvirt Installation</a></h1>
docs: added compiling page and significantly expanded windows page Also added an additional menu placement for the windows page, in order to attract further potential testers.
2010-12-21 09:38:37 +00:00
<ul id="toc"></ul>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 14:52:42 +00:00
<h2><a id="compiling">Compiling a release tarball</a></h2>
docs: added compiling page and significantly expanded windows page Also added an additional menu placement for the windows page, in order to attract further potential testers.
2010-12-21 09:38:37 +00:00
<p>
meson: adjust our documentation to mention meson instead of autoconf Signed-off-by: Pavel Hrdina <phrdina@redhat.com> Reviewed-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Neal Gompa <ngompa13@gmail.com>
2020-07-17 19:09:25 +00:00
libvirt uses the standard setup/build/install steps and mandates
Fix a typo in compiling.html.in: that -> from The original author intended to write "different than". "Different" is commonly followed by "from", "than", and "to". Globally, "from" is the most common. Signed-off-by: Matt Coleman <matt@datto.com> Reviewed-by: Neal Gompa <ngompa13@gmail.com> Reviewed-by: Erik Skultety <eskultet@redhat.com>
2020-09-08 20:43:52 +00:00
that the build directory is different from the source directory:
docs: added compiling page and significantly expanded windows page Also added an additional menu placement for the windows page, in order to attract further potential testers.
2010-12-21 09:38:37 +00:00
</p>
<pre>
docs: compiling.html: pass -d to xz to decompress tar on macOS recognizes XZ compression automatically, but that is not the case for GNU tar (1.32 at least). On Fedora 33 the current instructions result in the following error: $ xz -c libvirt-6.9.0.tar.xz | tar xvf - tar: Archive is compressed. Use -J option tar: Error is not recoverable: exiting now Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Signed-off-by: Jonathan Watt <jwatt@jwatt.org>
2020-11-13 13:30:45 +00:00
$ xz -dc libvirt-x.x.x.tar.xz | tar xvf -
compiling.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-11 22:40:27 +00:00
$ cd libvirt-x.x.x
meson: adjust our documentation to mention meson instead of autoconf Signed-off-by: Pavel Hrdina <phrdina@redhat.com> Reviewed-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Neal Gompa <ngompa13@gmail.com>
2020-07-17 19:09:25 +00:00
$ meson build</pre>
docs: added compiling page and significantly expanded windows page Also added an additional menu placement for the windows page, in order to attract further potential testers.
2010-12-21 09:38:37 +00:00
<p>
meson: adjust our documentation to mention meson instead of autoconf Signed-off-by: Pavel Hrdina <phrdina@redhat.com> Reviewed-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Neal Gompa <ngompa13@gmail.com>
2020-07-17 19:09:25 +00:00
The <i>meson</i> script can be given options to change its default
docs: added compiling page and significantly expanded windows page Also added an additional menu placement for the windows page, in order to attract further potential testers.
2010-12-21 09:38:37 +00:00
behaviour.
</p>
<p>
meson: adjust our documentation to mention meson instead of autoconf Signed-off-by: Pavel Hrdina <phrdina@redhat.com> Reviewed-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Neal Gompa <ngompa13@gmail.com>
2020-07-17 19:09:25 +00:00
To get the complete list of the options run the following command:
docs: added compiling page and significantly expanded windows page Also added an additional menu placement for the windows page, in order to attract further potential testers.
2010-12-21 09:38:37 +00:00
</p>
<pre>
meson: adjust our documentation to mention meson instead of autoconf Signed-off-by: Pavel Hrdina <phrdina@redhat.com> Reviewed-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Neal Gompa <ngompa13@gmail.com>
2020-07-17 19:09:25 +00:00
$ meson configure</pre>
docs: added compiling page and significantly expanded windows page Also added an additional menu placement for the windows page, in order to attract further potential testers.
2010-12-21 09:38:37 +00:00
<p>
When you have determined which options you want to use (if any),
continue the process.
</p>
<p>
meson: adjust our documentation to mention meson instead of autoconf Signed-off-by: Pavel Hrdina <phrdina@redhat.com> Reviewed-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Neal Gompa <ngompa13@gmail.com>
2020-07-17 19:09:25 +00:00
Note the use of <b>sudo</b> with the <i>ninja install</i> command
docs: added compiling page and significantly expanded windows page Also added an additional menu placement for the windows page, in order to attract further potential testers.
2010-12-21 09:38:37 +00:00
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
meson: adjust our documentation to mention meson instead of autoconf Signed-off-by: Pavel Hrdina <phrdina@redhat.com> Reviewed-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Neal Gompa <ngompa13@gmail.com>
2020-07-17 19:09:25 +00:00
access to, then you can instead run the <i>ninja install</i> command
docs: added compiling page and significantly expanded windows page Also added an additional menu placement for the windows page, in order to attract further potential testers.
2010-12-21 09:38:37 +00:00
without putting <b>sudo</b> before it.
</p>
<pre>
meson: adjust our documentation to mention meson instead of autoconf Signed-off-by: Pavel Hrdina <phrdina@redhat.com> Reviewed-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Neal Gompa <ngompa13@gmail.com>
2020-07-17 19:09:25 +00:00
$ meson build <i>[possible options]</i>
$ ninja -C build
$ <b>sudo</b> <i>ninja -C build install</i></pre>
docs: added compiling page and significantly expanded windows page Also added an additional menu placement for the windows page, in order to attract further potential testers.
2010-12-21 09:38:37 +00:00
<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>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 14:52:42 +00:00
<h2><a id="building">Building from a GIT checkout</a></h2>
docs: added compiling page and significantly expanded windows page Also added an additional menu placement for the windows page, in order to attract further potential testers.
2010-12-21 09:38:37 +00:00
<p>
meson: adjust our documentation to mention meson instead of autoconf Signed-off-by: Pavel Hrdina <phrdina@redhat.com> Reviewed-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Neal Gompa <ngompa13@gmail.com>
2020-07-17 19:09:25 +00:00
The libvirt build process uses Meson build system. By default when
the <code>meson</code> is run from within a GIT checkout, it
build: honor autogen.sh --no-git Based on a report by Chandrashekar Shastri, at https://bugzilla.redhat.com/show_bug.cgi?id=979360 On systems where git cannot access the outside world, a developer can instead arrange to get a copy of gnulib at the right commit via side channels (such as NFS share drives), set GNULIB_SRCDIR, then use ./autogen.sh --no-git. In this setup, we will now avoid direct use of git. Of course, this means no automatic gnulib updates when libvirt.git updates its submodule, but it is expected that any developer in such a situation is already prepared to deal with the fallout. * .gnulib: Update to latest, for bootstrap. * bootstrap: Synchronize from gnulib. * autogen.sh (no_git): Avoid git when requested. * cfg.mk (_update_required): Skip automatic rerun of bootstrap if we can't use git. * docs/compiling.html.in: Document this setup. * docs/hacking.html.in: Mention this. * HACKING: Regenerate. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-07-03 20:43:11 +00:00
will turn on -Werror for builds. This can be disabled with
meson: adjust our documentation to mention meson instead of autoconf Signed-off-by: Pavel Hrdina <phrdina@redhat.com> Reviewed-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Neal Gompa <ngompa13@gmail.com>
2020-07-17 19:09:25 +00:00
--werror=false, but this is not recommended.
build: honor autogen.sh --no-git Based on a report by Chandrashekar Shastri, at https://bugzilla.redhat.com/show_bug.cgi?id=979360 On systems where git cannot access the outside world, a developer can instead arrange to get a copy of gnulib at the right commit via side channels (such as NFS share drives), set GNULIB_SRCDIR, then use ./autogen.sh --no-git. In this setup, we will now avoid direct use of git. Of course, this means no automatic gnulib updates when libvirt.git updates its submodule, but it is expected that any developer in such a situation is already prepared to deal with the fallout. * .gnulib: Update to latest, for bootstrap. * bootstrap: Synchronize from gnulib. * autogen.sh (no_git): Avoid git when requested. * cfg.mk (_update_required): Skip automatic rerun of bootstrap if we can't use git. * docs/compiling.html.in: Document this setup. * docs/hacking.html.in: Mention this. * HACKING: Regenerate. Signed-off-by: Eric Blake <eblake@redhat.com>
2013-07-03 20:43:11 +00:00
</p>
<p>To build &amp; install libvirt to your home
Improve docs about compiling libvirt from GIT Add a note about setting the LIBVIRT_DRIVER_DIR env variable, explain --system and fix example to use --disable-werror
2012-05-24 15:07:58 +00:00
directory the following commands can be run:
docs: added compiling page and significantly expanded windows page Also added an additional menu placement for the windows page, in order to attract further potential testers.
2010-12-21 09:38:37 +00:00
</p>
<pre>
meson: adjust our documentation to mention meson instead of autoconf Signed-off-by: Pavel Hrdina <phrdina@redhat.com> Reviewed-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Neal Gompa <ngompa13@gmail.com>
2020-07-17 19:09:25 +00:00
$ meson build --prefix=$HOME/usr
$ ninja -C build
$ <b>sudo</b> ninja -C build install</pre>
Improve docs about compiling libvirt from GIT Add a note about setting the LIBVIRT_DRIVER_DIR env variable, explain --system and fix example to use --disable-werror
2012-05-24 15:07:58 +00:00
<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: adjust our documentation to mention meson instead of autoconf Signed-off-by: Pavel Hrdina <phrdina@redhat.com> Reviewed-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Neal Gompa <ngompa13@gmail.com>
2020-07-17 19:09:25 +00:00
$ meson build -Dsystem=true
$ ninja -C build
Improve docs about compiling libvirt from GIT Add a note about setting the LIBVIRT_DRIVER_DIR env variable, explain --system and fix example to use --disable-werror
2012-05-24 15:07:58 +00:00
</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>
compiling.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-11 22:40:27 +00:00
$ su -
# service libvirtd stop (or systemctl stop libvirtd.service)
Forget last daemon/ dir artefacts The most important part is LIBVIRTD_PATH env var fix. It is used in virFileFindResourceFull() from tests. The libvirtd no longer lives under daemon/. Then, libvirtd-fail test was still failing (as expected) but not because of missing config file but because it was trying to execute (nonexistent) top_builddir/daemon/libvirtd which fulfilled expected outcome and thus test did not fail. Thirdly, lcov was told to generate coverage for daemon/ dir too. Fourthly, our compiling documentation was still suggesting to run daemonn/libvirtd. And finally, some comments in a systemtap file and a probes file were still referring to daemon/libvirtd. Signed-off-by: Michal Privoznik <mprivozn@redhat.com> Reviewed-by: John Ferlan <jferlan@redhat.com>
2018-07-07 11:57:30 +00:00
# /home/to/your/checkout/src/libvirtd
Improve docs about compiling libvirt from GIT Add a note about setting the LIBVIRT_DRIVER_DIR env variable, explain --system and fix example to use --disable-werror
2012-05-24 15:07:58 +00:00
</pre>
<p>
It is also possible to run virsh directly from the source tree
Add a ./run script for running programs from the local directory. With this script you can run libvirt programs without needing to install them first. You just have to do for example: ./run ./tools/virsh [args ...] If you are already in the tools/ subdirectory, then the following command will also work: ../run ./virsh [...] You can also run the C programs under valgrind like this: ./run valgrind [valgrind opts...] ./program or under gdb: ./run gdb --args ./program This also works with sudo (eg. if you need root access for libvirt): sudo ./run ./tools/virsh list --all Derived from libguestfs and simplified. The ./run script in libguestfs is much more sophisticated: https://github.com/libguestfs/libguestfs/blob/master/run.in
2012-09-14 09:08:54 +00:00
using the ./run script (which sets some environment variables):
Improve docs about compiling libvirt from GIT Add a note about setting the LIBVIRT_DRIVER_DIR env variable, explain --system and fix example to use --disable-werror
2012-05-24 15:07:58 +00:00
</p>
<pre>
compiling.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-11 22:40:27 +00:00
$ ./run ./tools/virsh ....
Improve docs about compiling libvirt from GIT Add a note about setting the LIBVIRT_DRIVER_DIR env variable, explain --system and fix example to use --disable-werror
2012-05-24 15:07:58 +00:00
</pre>
docs: added compiling page and significantly expanded windows page Also added an additional menu placement for the windows page, in order to attract further potential testers.
2010-12-21 09:38:37 +00:00
</body>
</html>
Reference in New Issue Copy Permalink