docs/compiling.html.in

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html>
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4   <body>
   5     <h1><a id="installation">libvirt Installation</a></h1>
   6
   7     <ul id="toc"></ul>
   8
   9     <h2><a id="compiling">Compiling a release tarball</a></h2>
  10
  11     <p>
  12       libvirt uses the standard configure/make/install steps:
  13     </p>
  14
  15     <pre>
  16 $ xz -c libvirt-x.x.x.tar.xz | tar xvf -
  17 $ cd libvirt-x.x.x
  18 $ ./configure</pre>
  19
  20     <p>
  21       The <i>configure</i> script can be given options to change its default
  22       behaviour.
  23     </p>
  24
  25     <p>
  26       To get the complete list of the options it can take, pass it the
  27       <i>--help</i> option like this:
  28     </p>
  29
  30     <pre>
  31 $ ./configure <i>--help</i></pre>
  32
  33     <p>
  34       When you have determined which options you want to use (if any),
  35       continue the process.
  36     </p>
  37
  38     <p>
  39       Note the use of <b>sudo</b> with the <i>make install</i> command
  40       below.  Using sudo is only required when installing to a location your
  41       user does not have write access to.  Installing to a system location
  42       is a good example of this.
  43     </p>
  44
  45     <p>
  46       If you are installing to a location that your user <i>does</i> have write
  47       access to, then you can instead run the <i>make install</i> command
  48       without putting <b>sudo</b> before it.
  49     </p>
  50
  51     <pre>
  52 $ ./configure <i>[possible options]</i>
  53 $ make
  54 $ <b>sudo</b> <i>make install</i></pre>
  55
  56     <p>
  57       At this point you <b>may</b> have to run ldconfig or a similar utility
  58       to update your list of installed shared libs.
  59     </p>
  60
  61     <h2><a id="building">Building from a GIT checkout</a></h2>
  62
  63     <p>
  64       The libvirt build process uses GNU autotools, so after obtaining a
  65       checkout it is necessary to generate the configure script and Makefile.in
  66       templates using the <code>autogen.sh</code> command. By default when
  67       the <code>configure</code> script is run from within a GIT checkout, it
  68       will turn on -Werror for builds. This can be disabled with
  69       --disable-werror, but this is not recommended.
  70     </p>
  71     <p>
  72       Libvirt takes advantage of
  73       the <a href="http://www.gnu.org/software/gnulib/">gnulib</a>
  74       project to provide portability to a number of platforms.  This
  75       is normally done dynamically via a git submodule in
  76       the <code>.gnulib</code> subdirectory, which is auto-updated as
  77       needed when you do incremental builds.  Setting the environment
  78       variable <code>GNULIB_SRCDIR</code> to a local directory
  79       containing a git checkout of gnulib will let you reduce local
  80       disk space requirements and network download time, regardless of
  81       which actual commit you have in that reference directory.
  82     </p>
  83     <p>
  84       However, if you are developing on a platform where git is not
  85       available, or are behind a firewall that does not allow for git
  86       to easily obtain the gnulib submodule, it is possible to instead
  87       use a static mode of operation where you are then responsible
  88       for updating the git submodule yourself.  In this mode, you must
  89       track the exact gnulib commit needed by libvirt (usually not the
  90       latest gnulib.git) via alternative means, such as a shared NFS
  91       drive or manual download, and run this any time libvirt.git
  92       updates the commit stored in the .gnulib submodule:</p>
  93     <pre>
  94 $ GNULIB_SRCDIR=/path/to/gnulib ./autogen.sh --no-git
  95     </pre>
  96
  97     <p>To build &amp; install libvirt to your home
  98       directory the following commands can be run:
  99     </p>
 100
 101     <pre>
 102 $ ./autogen.sh --prefix=$HOME/usr
 103 $ make
 104 $ <b>sudo</b> make install</pre>
 105
 106     <p>
 107       Be aware though, that binaries built with a custom prefix will not
 108       interoperate with OS vendor provided binaries, since the UNIX socket
 109       paths will all be different. To produce a build that is compatible
 110       with normal OS vendor prefixes, use
 111     </p>
 112
 113     <pre>
 114 $ ./autogen.sh --system
 115 $ make
 116     </pre>
 117
 118     <p>
 119       When doing this for day-to-day development purposes, it is recommended
 120       not to install over the OS vendor provided binaries. Instead simply
 121       run libvirt directly from the source tree. For example to run
 122       a privileged libvirtd instance
 123     </p>
 124
 125     <pre>
 126 $ su -
 127 # service libvirtd stop  (or systemctl stop libvirtd.service)
 128 # /home/to/your/checkout/src/libvirtd
 129     </pre>
 130
 131     <p>
 132       It is also possible to run virsh directly from the source tree
 133       using the ./run script (which sets some environment variables):
 134     </p>
 135
 136     <pre>
 137 $ ./run ./tools/virsh ....
 138     </pre>
 139   </body>
 140 </html>