[libvirt] [PATCH 0/4] docs: Ship and install a few more files
Our handling of documentation is far from perfect, and a few issues in particular are causing me quite a bit of grief on the Debian packaging side of things. This series takes care of the more pressing matters; I have further cleanups planned for later. Andrea Bolognani (4): docs: Introduce $(modules) docs: Introduce $(devhelphtml_generated) docs: Install documentation under $(docdir) examples: Install under $(docdir) configure.ac | 13 ------------- docs/Makefile.am | 38 ++++++++++++++++++++++++-------------- examples/Makefile.am | 11 +++++++++++ libvirt.spec.in | 14 +------------- 4 files changed, 36 insertions(+), 40 deletions(-) -- 2.20.1
This variable contains a lists of documentation modules, in a neutral format. Right now is only used to define $(apihtml_generated), but later on we're gonna reuse it. Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- docs/Makefile.am | 31 ++++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/docs/Makefile.am b/docs/Makefile.am index 29b0761a2b..3a729f909c 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -18,24 +18,29 @@ DEVHELP_DIR=$(datadir)/gtk-doc/html/libvirt +modules = \ + libvirt-common \ + libvirt-domain \ + libvirt-domain-snapshot \ + libvirt-event \ + libvirt-host \ + libvirt-interface \ + libvirt-network \ + libvirt-nodedev \ + libvirt-nwfilter \ + libvirt-secret \ + libvirt-storage \ + libvirt-stream \ + virterror \ + $(NULL) + apihtml = \ html/index.html \ $(apihtml_generated) apihtml_generated = \ - html/libvirt-libvirt-common.html \ - html/libvirt-libvirt-domain.html \ - html/libvirt-libvirt-domain-snapshot.html \ - html/libvirt-libvirt-event.html \ - html/libvirt-libvirt-host.html \ - html/libvirt-libvirt-interface.html \ - html/libvirt-libvirt-network.html \ - html/libvirt-libvirt-nodedev.html \ - html/libvirt-libvirt-nwfilter.html \ - html/libvirt-libvirt-secret.html \ - html/libvirt-libvirt-storage.html \ - html/libvirt-libvirt-stream.html \ - html/libvirt-virterror.html + $(addprefix html/libvirt-,$(addsuffix .html,$(modules))) \ + $(NULL) apipng = \ html/left.png \ -- 2.20.1
Our XSLT magic generates one Devhelp-compatible HTML file per documentation module, but so far we have only shipped and installed documentation for virterror. Now that we have $(modules), however, we can generate the list of files the same way we do for regular documentation and make sure we always ship and install everything. Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- docs/Makefile.am | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/Makefile.am b/docs/Makefile.am index 3a729f909c..559ea2d01b 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -52,7 +52,11 @@ devhelphtml = \ devhelp/libvirt.devhelp \ devhelp/index.html \ devhelp/general.html \ - devhelp/libvirt-virterror.html + $(devhelphtml_generated) + +devhelphtml_generated = \ + $(addprefix devhelp/libvirt-,$(addsuffix .html,$(modules))) \ + $(NULL) css = \ generic.css \ -- 2.20.1
At the moment we allow the user to specify exactly where they want the HTML documentation to be installed with an extreme level of precision through the --with-html-dir and --with-html-subdir configure options. Most of the time, of course, the user will stick with the default, that is $(datadir)/doc/$(PACKAGE)-$(VERSION)/html. So close to $(docdir)! Including the version number in the path, specifically, seems entirely unnecessary since different releases of libvirt are not going to be able to coexist on the same system anyway. Drop all these custom flexibilty for flexibilty's sake shenaningans in favor of the standard, well understood $(docdir). Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- configure.ac | 13 ------------- docs/Makefile.am | 1 + libvirt.spec.in | 2 +- 3 files changed, 2 insertions(+), 14 deletions(-) diff --git a/configure.ac b/configure.ac index fabec815db..7e01b77fc0 100644 --- a/configure.ac +++ b/configure.ac @@ -414,19 +414,6 @@ dnl LIBVIRT_CHECK_EXTERNAL_PROGRAMS - -dnl Specific dir for HTML output ? -LIBVIRT_ARG_WITH([HTML_DIR], [path to base html directory], - ['$(datadir)/doc']) -LIBVIRT_ARG_WITH([HTML_SUBDIR], [directory used under html-dir], - ['$(PACKAGE)-$(VERSION)/html']) -if test "x$with_html_subdir" != "x" ; then - HTML_DIR="$with_html_dir/$with_html_subdir" -else - HTML_DIR="$with_html_dir" -fi -AC_SUBST([HTML_DIR]) - dnl if --prefix is /usr, don't use /usr/var for localstatedir dnl or /usr/etc for sysconfdir dnl as this makes a lot of things break in testing situations diff --git a/docs/Makefile.am b/docs/Makefile.am index 559ea2d01b..0c899f9580 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -16,6 +16,7 @@ ## License along with this library. If not, see ## <http://www.gnu.org/licenses/>. +HTML_DIR = $(docdir)/html DEVHELP_DIR=$(datadir)/gtk-doc/html/libvirt modules = \ diff --git a/libvirt.spec.in b/libvirt.spec.in index e07041c0b9..ea6a04c02a 100644 --- a/libvirt.spec.in +++ b/libvirt.spec.in @@ -1300,7 +1300,7 @@ rm -f $RPM_BUILD_ROOT%{_datadir}/augeas/lenses/tests/test_libvirtd_libxl.aug %endif # Copied into libvirt-docs subpackage eventually -mv $RPM_BUILD_ROOT%{_datadir}/doc/libvirt-%{version} libvirt-docs +mv $RPM_BUILD_ROOT%{_datadir}/doc/libvirt libvirt-docs %ifarch %{power64} s390x x86_64 ia64 alpha sparc64 mv $RPM_BUILD_ROOT%{_datadir}/systemtap/tapset/libvirt_probes.stp \ -- 2.20.1
Our build system doesn't currently install the various example programs provided along libvirt; however, both the upstream .spec file and the Debian packaging go out of their way to make sure these useful demos are included in the respective documentation packages. Moreover, doing so without help from the upstream build system is easy to get wrong: the libvirt-docs RPM package, for example, ends up missing one of the examples and including a bunch of empty .deps/ directories. Install the examples in $(docdir) as part of our regular procedure, so that users and downstreams don't have to do anything special about them. Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- examples/Makefile.am | 11 +++++++++++ libvirt.spec.in | 12 ------------ 2 files changed, 11 insertions(+), 12 deletions(-) diff --git a/examples/Makefile.am b/examples/Makefile.am index ee7d3e6b2c..c7688c7c3d 100644 --- a/examples/Makefile.am +++ b/examples/Makefile.am @@ -84,6 +84,17 @@ INSTALL_DATA_LOCAL += install-nwfilter-local UNINSTALL_LOCAL += uninstall-nwfilter-local endif WITH_NWFILTER +examplesdir = $(docdir)/examples + install-data-local: $(INSTALL_DATA_LOCAL) + $(mkinstalldirs) $(DESTDIR)$(examplesdir) + for p in $(noinst_PROGRAMS); do \ + d=$$(dirname $$p); \ + $(mkinstalldirs) $(DESTDIR)$(examplesdir)/$$d; \ + $(INSTALL_DATA) $(srcdir)/$${p}.c $(DESTDIR)$(examplesdir)/$$d/; \ + done uninstall-local: $(UNINSTALL_LOCAL) + for p in $(noinst_PROGRAMS); do \ + rm -f $(DESTDIR)$(examplesdir)/$${p}.c; \ + done diff --git a/libvirt.spec.in b/libvirt.spec.in index ea6a04c02a..5c27a44fc5 100644 --- a/libvirt.spec.in +++ b/libvirt.spec.in @@ -1232,8 +1232,6 @@ export SOURCE_DATE_EPOCH=$(stat --printf='%Y' %{_specdir}/%{name}.spec) %make_install %{?_smp_mflags} SYSTEMD_UNIT_DIR=%{_unitdir} V=1 -make %{?_smp_mflags} -C examples distclean V=1 - rm -f $RPM_BUILD_ROOT%{_libdir}/*.la rm -f $RPM_BUILD_ROOT%{_libdir}/*.a rm -f $RPM_BUILD_ROOT%{_libdir}/libvirt/lock-driver/*.la @@ -1510,16 +1508,6 @@ exit 0 %doc %{_datadir}/gtk-doc/html/libvirt/*.html %doc %{_datadir}/gtk-doc/html/libvirt/*.png %doc %{_datadir}/gtk-doc/html/libvirt/*.css -%doc examples/hellolibvirt -%doc examples/object-events -%doc examples/dominfo -%doc examples/domsuspend -%doc examples/dommigrate -%doc examples/openauth -%doc examples/xml -%doc examples/rename -%doc examples/systemtap -%doc examples/admin %files daemon -- 2.20.1
On Fri, May 10, 2019 at 08:51:20PM +0200, Andrea Bolognani wrote:
Our build system doesn't currently install the various example programs provided along libvirt; however, both the upstream .spec file and the Debian packaging go out of their way to make sure these useful demos are included in the respective documentation packages.
Moreover, doing so without help from the upstream build system is easy to get wrong: the libvirt-docs RPM package, for example, ends up missing one of the examples and including a bunch of empty .deps/ directories.
Install the examples in $(docdir) as part of our regular procedure, so that users and downstreams don't have to do anything special about them.
Signed-off-by: Andrea Bolognani <abologna@redhat.com> --- examples/Makefile.am | 11 +++++++++++ libvirt.spec.in | 12 ------------ 2 files changed, 11 insertions(+), 12 deletions(-)
diff --git a/examples/Makefile.am b/examples/Makefile.am index ee7d3e6b2c..c7688c7c3d 100644 --- a/examples/Makefile.am +++ b/examples/Makefile.am @@ -84,6 +84,17 @@ INSTALL_DATA_LOCAL += install-nwfilter-local UNINSTALL_LOCAL += uninstall-nwfilter-local endif WITH_NWFILTER
+examplesdir = $(docdir)/examples + install-data-local: $(INSTALL_DATA_LOCAL) + $(mkinstalldirs) $(DESTDIR)$(examplesdir) + for p in $(noinst_PROGRAMS); do \ + d=$$(dirname $$p); \ + $(mkinstalldirs) $(DESTDIR)$(examplesdir)/$$d; \ + $(INSTALL_DATA) $(srcdir)/$${p}.c $(DESTDIR)$(examplesdir)/$$d/; \ + done
uninstall-local: $(UNINSTALL_LOCAL) + for p in $(noinst_PROGRAMS); do \ + rm -f $(DESTDIR)$(examplesdir)/$${p}.c; \ + done
This breaks Windows builds, because the program names includes '.exe' suffix. Instead of copying/deleting example.c, we try to copy/delete example.exe.c Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
On Mon, 2019-05-13 at 12:03 +0100, Daniel P. Berrangé wrote:
On Fri, May 10, 2019 at 08:51:20PM +0200, Andrea Bolognani wrote:
install-data-local: $(INSTALL_DATA_LOCAL) + $(mkinstalldirs) $(DESTDIR)$(examplesdir) + for p in $(noinst_PROGRAMS); do \ + d=$$(dirname $$p); \ + $(mkinstalldirs) $(DESTDIR)$(examplesdir)/$$d; \ + $(INSTALL_DATA) $(srcdir)/$${p}.c $(DESTDIR)$(examplesdir)/$$d/; \ + done
uninstall-local: $(UNINSTALL_LOCAL) + for p in $(noinst_PROGRAMS); do \ + rm -f $(DESTDIR)$(examplesdir)/$${p}.c; \ + done
This breaks Windows builds, because the program names includes '.exe' suffix. Instead of copying/deleting example.c, we try to copy/delete example.exe.c
I guess automake is changing $(noinst_PROGRAMS) behind our back, since the code above would work otherwise. Pretty gross, but that's the kind of nasty meddling you have to accept if you want portability to work (mostly) out of the box (almost) all of the time, I suppose. Anyway, thanks for bringing this to my attention. I'll take care of it momentarily, and test it on MinGW before posting this time ;) -- Andrea Bolognani / Red Hat / Virtualization
On 5/10/19 8:51 PM, Andrea Bolognani wrote:
Our handling of documentation is far from perfect, and a few issues in particular are causing me quite a bit of grief on the Debian packaging side of things.
This series takes care of the more pressing matters; I have further cleanups planned for later.
Andrea Bolognani (4): docs: Introduce $(modules) docs: Introduce $(devhelphtml_generated) docs: Install documentation under $(docdir) examples: Install under $(docdir)
configure.ac | 13 ------------- docs/Makefile.am | 38 ++++++++++++++++++++++++-------------- examples/Makefile.am | 11 +++++++++++ libvirt.spec.in | 14 +------------- 4 files changed, 36 insertions(+), 40 deletions(-)
ACK Michal
participants (3)
-
Andrea Bolognani -
Daniel P. Berrangé -
Michal Privoznik