[libvirt PATCH 349/351] meson: adjust our documentation to mention meson instead of autoconf
Pavel Hrdina
phrdina at redhat.com
Thu Jul 16 09:59:45 UTC 2020
Signed-off-by: Pavel Hrdina <phrdina at redhat.com>
---
CONTRIBUTING.rst | 9 ++++----
docs/advanced-tests.rst | 14 ++++++------
docs/best-practices.rst | 2 +-
docs/committer-guidelines.rst | 6 +++---
docs/compiling.html.in | 40 ++++++++++++++++-------------------
docs/hacking.rst | 4 ++--
docs/strategy.html.in | 27 ++++++-----------------
docs/windows.html.in | 18 +++++++---------
8 files changed, 50 insertions(+), 70 deletions(-)
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 972b1898736..bda5cae6270 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -12,13 +12,12 @@ your git clone run:
::
- $ mkdir build && cd build
- $ ../autogen.sh
- $ make
+ $ meson build
+ $ ninja -C build
You'll find the freshly-built document in ``docs/contribute.html``.
-If ``configure`` fails because of missing dependencies, you can set
+If ``meson setup`` fails because of missing dependencies, you can set
up your system by calling
::
@@ -39,7 +38,7 @@ to run
::
- $ sudo dnf install gcc make libtool autoconf automake rpm-build
+ $ sudo dnf install gcc make ninja-build rpm-build
You might still be missing some dependencies if your distribution is
shipping an old libvirt version, but that will get you much closer to
diff --git a/docs/advanced-tests.rst b/docs/advanced-tests.rst
index d2d29d976d9..c8c02eabe06 100644
--- a/docs/advanced-tests.rst
+++ b/docs/advanced-tests.rst
@@ -6,8 +6,8 @@ The basic requirement before submitting changes to libvirt is that
::
- $ make check
- $ make syntax-check
+ $ ninja test
+ $ ninja syntax-check
succeed after each commit.
@@ -17,7 +17,7 @@ by running
::
- $ make -C tests valgrind
+ $ meson test --setup valgrind
`Valgrind <http://valgrind.org/>`__ is a test that checks for
memory management issues, such as leaks or use of uninitialized
@@ -27,13 +27,13 @@ Some tests are skipped by default in a development environment,
based on the time they take in comparison to the likelihood
that those tests will turn up problems during incremental
builds. These tests default to being run when building from a
-tarball or with the configure option --enable-expensive-tests;
+tarball or with the configure option -Dexpensive_tests=enabled;
you can also force a one-time toggle of these tests by setting
VIR_TEST_EXPENSIVE to 0 or 1 at make time, as in:
::
- $ make check VIR_TEST_EXPENSIVE=1
+ $ VIR_TEST_EXPENSIVE=1 ninja test
If you encounter any failing tests, the VIR_TEST_DEBUG
environment variable may provide extra information to debug the
@@ -42,8 +42,8 @@ amounts of information:
::
- $ VIR_TEST_DEBUG=1 make check (or)
- $ VIR_TEST_DEBUG=2 make check
+ $ VIR_TEST_DEBUG=1 ninja test (or)
+ $ VIR_TEST_DEBUG=2 ninja test
When debugging failures during development, it is possible to
focus in on just the failing subtests by using VIR_TEST_RANGE.
diff --git a/docs/best-practices.rst b/docs/best-practices.rst
index 4a28b03b652..b2572c81100 100644
--- a/docs/best-practices.rst
+++ b/docs/best-practices.rst
@@ -26,7 +26,7 @@ with minimal back-and-forth.
and an explanation of how the sequence of patches fits
together. Moreover, please keep in mind that it's required to
be able to compile cleanly (**including**
- ``make check`` and ``make syntax-check``) after each
+ ``ninja test`` and ``ninja syntax-check``) after each
patch. A feature does not have to work until the end of a
series, but intermediate patches must compile and not cause
test-suite failures (this is to preserve the usefulness of
diff --git a/docs/committer-guidelines.rst b/docs/committer-guidelines.rst
index 3be08e6fed3..1f879ddf934 100644
--- a/docs/committer-guidelines.rst
+++ b/docs/committer-guidelines.rst
@@ -12,7 +12,7 @@ objection on the list it should be good to go. If the patch
touches a part of the code where you're not the main maintainer,
or where you do not have a very clear idea of how things work,
it's better to wait for a more authoritative feedback though.
-Before committing, please also rebuild locally, run 'make check
+Before committing, please also rebuild locally, run 'ninja test
syntax-check', and make sure you don't raise errors.
An exception to 'review and approval on the list first' is fixing
@@ -21,10 +21,10 @@ failures to build:
- if a recently committed patch breaks compilation on a platform
or for a given driver, then it's fine to commit a minimal fix
directly without getting the review feedback first
-- if make check or make syntax-check breaks, if there is an
+- if ninja test or ninja syntax-check breaks, if there is an
obvious fix, it's fine to commit immediately. The patch should
still be sent to the list (or tell what the fix was if
- trivial), and 'make check syntax-check' should pass too, before
+ trivial), and 'ninja test syntax-check' should pass too, before
committing anything
- fixes for documentation and code comments can be managed in the
same way, but still make sure they get reviewed if non-trivial.
diff --git a/docs/compiling.html.in b/docs/compiling.html.in
index 0e12a9218e3..2a65fa7b8b0 100644
--- a/docs/compiling.html.in
+++ b/docs/compiling.html.in
@@ -9,28 +9,26 @@
<h2><a id="compiling">Compiling a release tarball</a></h2>
<p>
- libvirt uses the standard configure/make/install steps and mandates
+ libvirt uses the standard setup/build/install steps and mandates
that the build directory is different that the source directory:
</p>
<pre>
$ xz -c libvirt-x.x.x.tar.xz | tar xvf -
$ cd libvirt-x.x.x
-$ mkdir build && cd build
-$ ../configure</pre>
+$ meson build</pre>
<p>
- The <i>configure</i> script can be given options to change its default
+ The <i>meson</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:
+ To get the complete list of the options run the following command:
</p>
<pre>
-$ ../configure <i>--help</i></pre>
+$ meson configure</pre>
<p>
When you have determined which options you want to use (if any),
@@ -38,7 +36,7 @@ $ ../configure <i>--help</i></pre>
</p>
<p>
- Note the use of <b>sudo</b> with the <i>make install</i> command
+ 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.
@@ -46,14 +44,14 @@ $ ../configure <i>--help</i></pre>
<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
+ access to, then you can instead run the <i>ninja install</i> command
without putting <b>sudo</b> before it.
</p>
<pre>
-$ ../configure <i>[possible options]</i>
-$ make
-$ <b>sudo</b> <i>make install</i></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
@@ -63,12 +61,10 @@ $ <b>sudo</b> <i>make install</i></pre>
<h2><a id="building">Building from a GIT checkout</a></h2>
<p>
- The libvirt build process uses GNU autotools, so after obtaining a
- checkout it is necessary to generate the configure script and Makefile.in
- templates using the <code>autogen.sh</code> command. By default when
- the <code>configure</code> script is run from within a GIT checkout, it
+ 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
- --disable-werror, but this is not recommended.
+ --werror=false, but this is not recommended.
</p>
<p>To build & install libvirt to your home
@@ -76,9 +72,9 @@ $ <b>sudo</b> <i>make install</i></pre>
</p>
<pre>
-$ ./autogen.sh --prefix=$HOME/usr
-$ make
-$ <b>sudo</b> make install</pre>
+$ meson build --prefix=$HOME/usr
+$ ninja -C build
+$ ninja -C build install</pre>
<p>
Be aware though, that binaries built with a custom prefix will not
@@ -88,8 +84,8 @@ $ <b>sudo</b> make install</pre>
</p>
<pre>
-$ ./autogen.sh --system
-$ make
+$ meson build -Dsystem=true
+$ ninja -C build
</pre>
<p>
diff --git a/docs/hacking.rst b/docs/hacking.rst
index ccc94010b3a..4a9a1e19565 100644
--- a/docs/hacking.rst
+++ b/docs/hacking.rst
@@ -30,8 +30,8 @@ changes. That is:
::
- $ make check
- $ make syntax-check
+ $ ninja test
+ $ ninja syntax-check
These tests help making sure that your changes don't introduce
regressions in libvirt, as well as validating that any new code
diff --git a/docs/strategy.html.in b/docs/strategy.html.in
index 42c285d9f6a..0d845d006af 100644
--- a/docs/strategy.html.in
+++ b/docs/strategy.html.in
@@ -22,13 +22,12 @@
in the C language.</dd>
<dt>Python</dt>
<dd>Various supporting build/test scripts are written in Python, with
- compatibility for Python 2 and 3.</dd>
+ compatibility for Python 3.</dd>
<dt>Perl</dt>
<dd>Various supporting build/test scripts are written in Perl. It is
also used for many syntax-check inline rules</dd>
<dt>Shell</dt>
- <dd><code>configure</code>, generated by autoconf, is a shell script.
- Shell is also used for some simple build/test scripts. At runtime
+ <dd>Shell is used for some simple build/test scripts. At runtime
libvirt avoids shell except when using SSH tunnels to a remote
host</dd>
<dt>XSLT</dt>
@@ -38,14 +37,10 @@
<dt>HTML</dt>
<dd>The website documentation is all written in plain HTML. Some HTML
is also auto-generated for API documentation</dd>
- <dt>M4</dt>
- <dd>The autoconf <code>configure</code> script uses a large number of
- M4 macros to generate its content</dd>
+ <dt>Meson</dt>
+ <dd>The core build system uses the new Meson build system</dd>
<dt>make</dt>
- <dd>The core build system uses the traditional GNU make recipes</dd>
- <dt>automake</dt>
- <dd>The make recipes use automake's language extensions which are
- then turned into regular make rules</dd>
+ <dd>The syntax-check uses make recipes</dd>
<dt>awk/sed</dt>
<dd>A number of the syntax-check inline rules involve use of awk/sed
scripts</dd>
@@ -58,8 +53,8 @@
The wide range of languages used present a knowledge burden for
developers involved in libvirt, especially when there are multiple
languages all used in the same problem spaces. This is most notable
- in the build system which uses a combination of shell, M4, make,
- automake, awk, sed, Perl and Python, with debugging requiring
+ in the build system which uses a combination of Meson, shell, awk,
+ sed, Perl and Python, with debugging requiring
understanding of the interactions between many languages. The
popularity of Perl has declined, while Python has become
more popular. This directly influences the amount and quality of
@@ -119,14 +114,6 @@
code.
</p>
- <p>
- The Meson build system is written in Python 3. This directly informs the
- choice of Python 3 as the language for all supporting build scripts,
- re-inforcing the other benefits of Python over Perl, Shell, M4,
- automake, etc. There is no intention to support Python 2 given Meson's
- requirement for Python 3.
- </p>
-
<p>
Using the RST format for documentation allows for the use of XSLT to be
eliminated from the build process. RST and the Sphinx toolkit are widely
diff --git a/docs/windows.html.in b/docs/windows.html.in
index a0ff525e1ad..13dab1f6a40 100644
--- a/docs/windows.html.in
+++ b/docs/windows.html.in
@@ -180,16 +180,14 @@
</p>
<pre>
-mkdir build && cd build
-../configure \
- --without-sasl \
- --without-polkit \
- --without-python \
- --without-libxl \
- --without-qemu \
- --without-lxc \
- --without-openvz \
- --without-libvirtd
+meson build \
+ -Dsasl=disabled \
+ -Dpolkit=disabled \
+ -Ddriver_libxl=disabled \
+ -Ddriver_qemu=disabled \
+ -Ddriver_lxc=disabled \
+ -Ddriver_openvz=disabled \
+ -Ddriver_libvirtd=disabled
</pre>
</body>
--
2.26.2
More information about the libvir-list
mailing list