openkylin
/
libvirt
mirror of https://gitee.com/openkylin/libvirt.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity
libvirt/docs/compiling.html.in

141 lines
4.5 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 22:25:37 +08: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-27 01:01:25 +08: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 22:25:37 +08: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 17:38:37 +08: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 22:52:42 +08: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 17:38:37 +08: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 22:52:42 +08: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 17:38:37 +08:00
<p>
libvirt uses the standard configure/make/install steps:
</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-12 06:40:27 +08:00
$ xz -c libvirt-x.x.x.tar.xz | tar xvf -
$ cd libvirt-x.x.x
$ ./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 17:38:37 +08:00
<p>
The <i>configure</i> script can be given options to change its default
behaviour.
</p>
<p>
To get the complete list of the options it can take, pass it the
<i>--help</i> option like this:
</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-12 06:40:27 +08:00
$ ./configure <i>--help</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 17:38:37 +08:00
<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>make 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>make install</i> command
without putting <b>sudo</b> before it.
</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-12 06:40:27 +08:00
$ ./configure <i>[possible options]</i>
$ make
$ <b>sudo</b> <i>make 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 17:38:37 +08: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 22:52:42 +08: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 17:38:37 +08:00
<p>
The libvirt build process uses GNU autotools, so after obtaining a
checkout it is necessary to generate the configure script and Makefile.in
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 23:07:58 +08:00
templates using the <code>autogen.sh</code> command. By default when
the <code>configure</code> script 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-04 04:43:11 +08:00
will turn on -Werror for builds. This can be disabled with
--disable-werror, but this is not recommended.
</p>
<p>
Libvirt takes advantage of
the <a href="http://www.gnu.org/software/gnulib/">gnulib</a>
project to provide portability to a number of platforms. This
is normally done dynamically via a git submodule in
the <code>.gnulib</code> subdirectory, which is auto-updated as
needed when you do incremental builds. Setting the environment
variable <code>GNULIB_SRCDIR</code> to a local directory
containing a git checkout of gnulib will let you reduce local
disk space requirements and network download time, regardless of
which actual commit you have in that reference directory.
</p>
<p>
However, if you are developing on a platform where git is not
available, or are behind a firewall that does not allow for git
to easily obtain the gnulib submodule, it is possible to instead
use a static mode of operation where you are then responsible
for updating the git submodule yourself. In this mode, you must
track the exact gnulib commit needed by libvirt (usually not the
latest gnulib.git) via alternative means, such as a shared NFS
drive or manual download, and run this any time libvirt.git
updates the commit stored in the .gnulib submodule:</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-12 06:40:27 +08:00
$ GNULIB_SRCDIR=/path/to/gnulib ./autogen.sh --no-git
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-04 04:43:11 +08:00
</pre>
<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 23:07:58 +08: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 17:38:37 +08: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-12 06:40:27 +08:00
$ ./autogen.sh --prefix=$HOME/usr
$ make
$ <b>sudo</b> make 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 23:07:58 +08: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>
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-12 06:40:27 +08:00
$ ./autogen.sh --system
$ make
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 23:07:58 +08: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-12 06:40:27 +08: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 19:57:30 +08: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 23:07:58 +08: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 17:08:54 +08: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 23:07:58 +08: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-12 06:40:27 +08: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 23:07:58 +08: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 17:38:37 +08:00
</body>
</html>