The qemu-ga documentation is currently in qemu-ga.texi in
Texinfo format, which we present to the user as:
* a qemu-ga manpage
* a section of the main qemu-doc HTML documentation
Convert the documentation to rST format, and present it to
the user as:
* a qemu-ga manpage
* part of the interop/ Sphinx manual
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com>
Tested-by: Michael Roth <mdroth@linux.vnet.ibm.com>
Message-id: 20190905131040.8350-1-peter.maydell@linaro.org
---
Makefile | 24 ++++---
MAINTAINERS | 2 +-
docs/conf.py | 18 ++---
docs/interop/conf.py | 7 ++
docs/interop/index.rst | 1 +
docs/interop/qemu-ga.rst | 133 +++++++++++++++++++++++++++++++++++++
qemu-doc.texi | 5 --
qemu-ga.texi | 137 ---------------------------------------
8 files changed, 166 insertions(+), 161 deletions(-)
create mode 100644 docs/interop/qemu-ga.rst
delete mode 100644 qemu-ga.texi
diff --git a/Makefile b/Makefile
index b3528617e48..111082ce545 100644
--- a/Makefile
+++ b/Makefile
@@ -325,7 +325,7 @@ endif
endif
ifdef BUILD_DOCS
-DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8 qemu-ga.8
+DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8 docs/interop/qemu-ga.8
DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7
DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/interop/qemu-ga-ref.7
DOCS+=docs/qemu-block-drivers.7
@@ -783,10 +783,11 @@ DESCS=
endif
# Note that we manually filter-out the non-Sphinx documentation which
-# is currently built into the docs/interop directory in the build tree.
+# is currently built into the docs/interop directory in the build tree,
+# and also any sphinx-built manpages.
define install-manual =
for d in $$(cd $(MANUAL_BUILDDIR) && find $1 -type d); do $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)/$$d"; done
-for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' '(' -name 'qemu-*-qapi.*' -o -name 'qemu-*-ref.*' ')' ); do $(INSTALL_DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done
+for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' '(' -name '*.[0-9]' -o -name 'qemu-*-qapi.*' -o -name 'qemu-*-ref.*' ')' ); do $(INSTALL_DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done
endef
# Note that we deliberately do not install the "devel" manual: it is
@@ -818,7 +819,7 @@ ifdef CONFIG_TRACE_SYSTEMTAP
$(INSTALL_DATA) scripts/qemu-trace-stap.1 "$(DESTDIR)$(mandir)/man1"
endif
ifneq (,$(findstring qemu-ga,$(TOOLS)))
- $(INSTALL_DATA) qemu-ga.8 "$(DESTDIR)$(mandir)/man8"
+ $(INSTALL_DATA) docs/interop/qemu-ga.8 "$(DESTDIR)$(mandir)/man8"
$(INSTALL_DATA) docs/interop/qemu-ga-ref.html "$(DESTDIR)$(qemu_docdir)"
$(INSTALL_DATA) docs/interop/qemu-ga-ref.txt "$(DESTDIR)$(qemu_docdir)"
$(INSTALL_DATA) docs/interop/qemu-ga-ref.7 "$(DESTDIR)$(mandir)/man7"
@@ -977,18 +978,22 @@ docs/version.texi: $(SRC_PATH)/VERSION config-host.mak
sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html $(MANUAL_BUILDDIR)/interop/index.html $(MANUAL_BUILDDIR)/specs/index.html
# Canned command to build a single manual
-build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -W -n -b html -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1")
+# Arguments: $1 = manual name, $2 = Sphinx builder ('html' or 'man')
+build-manual = $(call quiet-command,CONFDIR="$(qemu_confdir)" sphinx-build $(if $(V),,-q) -W -n -b $2 -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1")
# We assume all RST files in the manual's directory are used in it
manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py
$(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel)
- $(call build-manual,devel)
+ $(call build-manual,devel,html)
$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop)
- $(call build-manual,interop)
+ $(call build-manual,interop,html)
$(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)
- $(call build-manual,specs)
+ $(call build-manual,specs,html)
+
+$(MANUAL_BUILDDIR)/interop/qemu-ga.8: $(call manual-deps,interop)
+ $(call build-manual,interop,man)
qemu-options.texi: $(SRC_PATH)/qemu-options.hx $(SRC_PATH)/scripts/hxtool
$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@")
@@ -1013,7 +1018,6 @@ qemu.1: qemu-option-trace.texi
qemu-img.1: qemu-img.texi qemu-option-trace.texi qemu-img-cmds.texi
fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi
qemu-nbd.8: qemu-nbd.texi qemu-option-trace.texi
-qemu-ga.8: qemu-ga.texi
docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi
docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi
scripts/qemu-trace-stap.1: scripts/qemu-trace-stap.texi
@@ -1026,7 +1030,7 @@ txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt
qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \
qemu-img.texi qemu-nbd.texi qemu-options.texi \
qemu-tech.texi qemu-option-trace.texi \
- qemu-deprecated.texi qemu-monitor.texi qemu-img-cmds.texi qemu-ga.texi \
+ qemu-deprecated.texi qemu-monitor.texi qemu-img-cmds.texi \
qemu-monitor-info.texi docs/qemu-block-drivers.texi \
docs/qemu-cpu-models.texi docs/security.texi
diff --git a/MAINTAINERS b/MAINTAINERS
index 50eaf005f40..f0e30b5248c 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2040,7 +2040,7 @@ QEMU Guest Agent
M: Michael Roth <mdroth@linux.vnet.ibm.com>
S: Maintained
F: qga/
-F: qemu-ga.texi
+F: docs/interop/qemu-ga.rst
F: scripts/qemu-guest-agent/
F: tests/test-qga.c
F: docs/interop/qemu-ga-ref.texi
diff --git a/docs/conf.py b/docs/conf.py
index e46b299b71f..b7edb0666b5 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -115,6 +115,14 @@ todo_include_todos = False
# with "option::" in the document being processed. Turn that off.
suppress_warnings = ["ref.option"]
+# The rst_epilog fragment is effectively included in every rST file.
+# We use it to define substitutions based on build config that
+# can then be used in the documentation. The fallback if the
+# environment variable is not set is for the benefit of readthedocs
+# style document building; our Makefile always sets the variable.
+confdir = os.getenv('CONFDIR', "/etc/qemu")
+rst_epilog = ".. |CONFDIR| replace:: ``" + confdir + "``\n"
+
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
@@ -192,14 +200,8 @@ latex_documents = [
# -- Options for manual page output ---------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-man_pages = [
- (master_doc, 'qemu', u'QEMU Documentation',
- [author], 1)
-]
-
+# Individual manual/conf.py can override this to create man pages
+man_pages = []
# -- Options for Texinfo output -------------------------------------------
diff --git a/docs/interop/conf.py b/docs/interop/conf.py
index cf3c69d4a7e..e87b8c22bec 100644
--- a/docs/interop/conf.py
+++ b/docs/interop/conf.py
@@ -13,3 +13,10 @@ exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))
# This slightly misuses the 'description', but is the best way to get
# the manual title to appear in the sidebar.
html_theme_options['description'] = u'System Emulation Management and Interoperability Guide'
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('qemu-ga', 'qemu-ga', u'QEMU Guest Agent',
+ ['Michael Roth <mdroth@linux.vnet.ibm.com>'], 8)
+]
diff --git a/docs/interop/index.rst b/docs/interop/index.rst
index b4bfcab4171..3e33fb59332 100644
--- a/docs/interop/index.rst
+++ b/docs/interop/index.rst
@@ -15,5 +15,6 @@ Contents:
bitmaps
live-block-operations
pr-helper
+ qemu-ga
vhost-user
vhost-user-gpu
diff --git a/docs/interop/qemu-ga.rst b/docs/interop/qemu-ga.rst
new file mode 100644
index 00000000000..1313a4ae1c9
--- /dev/null
+++ b/docs/interop/qemu-ga.rst
@@ -0,0 +1,133 @@
+QEMU Guest Agent
+================
+
+Synopsis
+--------
+
+**qemu-ga** [*OPTIONS*]
+
+Description
+-----------
+
+The QEMU Guest Agent is a daemon intended to be run within virtual
+machines. It allows the hypervisor host to perform various operations
+in the guest, such as:
+
+- get information from the guest
+- set the guest's system time
+- read/write a file
+- sync and freeze the filesystems
+- suspend the guest
+- reconfigure guest local processors
+- set user's password
+- ...
+
+qemu-ga will read a system configuration file on startup (located at
+|CONFDIR|\ ``/qemu-ga.conf`` by default), then parse remaining
+configuration options on the command line. For the same key, the last
+option wins, but the lists accumulate (see below for configuration
+file format).
+
+Options
+-------
+
+.. program:: qemu-ga
+
+.. option:: -m, --method=METHOD
+
+ Transport method: one of ``unix-listen``, ``virtio-serial``, or
+ ``isa-serial`` (``virtio-serial`` is the default).
+
+.. option:: -p, --path=PATH
+
+ Device/socket path (the default for virtio-serial is
+ ``/dev/virtio-ports/org.qemu.guest_agent.0``,
+ the default for isa-serial is ``/dev/ttyS0``)
+
+.. option:: -l, --logfile=PATH
+
+ Set log file path (default is stderr).
+
+.. option:: -f, --pidfile=PATH
+
+ Specify pid file (default is ``/var/run/qemu-ga.pid``).
+
+.. option:: -F, --fsfreeze-hook=PATH
+
+ Enable fsfreeze hook. Accepts an optional argument that specifies
+ script to run on freeze/thaw. Script will be called with
+ 'freeze'/'thaw' arguments accordingly (default is
+ |CONFDIR|\ ``/fsfreeze-hook``). If using -F with an argument, do
+ not follow -F with a space (for example:
+ ``-F/var/run/fsfreezehook.sh``).
+
+.. option:: -t, --statedir=PATH
+
+ Specify the directory to store state information (absolute paths only,
+ default is ``/var/run``).
+
+.. option:: -v, --verbose
+
+ Log extra debugging information.
+
+.. option:: -V, --version
+
+ Print version information and exit.
+
+.. option:: -d, --daemon
+
+ Daemonize after startup (detach from terminal).
+
+.. option:: -b, --blacklist=LIST
+
+ Comma-separated list of RPCs to disable (no spaces, ``?`` to list
+ available RPCs).
+
+.. option:: -D, --dump-conf
+
+ Dump the configuration in a format compatible with ``qemu-ga.conf``
+ and exit.
+
+.. option:: -h, --help
+
+ Display this help and exit.
+
+Files
+-----
+
+
+The syntax of the ``qemu-ga.conf`` configuration file follows the
+Desktop Entry Specification, here is a quick summary: it consists of
+groups of key-value pairs, interspersed with comments.
+
+::
+
+ # qemu-ga configuration sample
+ [general]
+ daemonize = 0
+ pidfile = /var/run/qemu-ga.pid
+ verbose = 0
+ method = virtio-serial
+ path = /dev/virtio-ports/org.qemu.guest_agent.0
+ statedir = /var/run
+
+The list of keys follows the command line options:
+
+============= ===========
+Key Key type
+============= ===========
+daemon boolean
+method string
+path string
+logfile string
+pidfile string
+fsfreeze-hook string
+statedir string
+verbose boolean
+blacklist string list
+============= ===========
+
+See also
+--------
+
+:manpage:`qemu(1)`
diff --git a/qemu-doc.texi b/qemu-doc.texi
index b47e89cfca6..2ba6c90c083 100644
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -2535,11 +2535,6 @@ so should only be used with trusted guest OS.
@c man end
-@node QEMU Guest Agent
-@chapter QEMU Guest Agent invocation
-
-@include qemu-ga.texi
-
@node QEMU User space emulator
@chapter QEMU User space emulator
diff --git a/qemu-ga.texi b/qemu-ga.texi
deleted file mode 100644
index f00ad830f28..00000000000
--- a/qemu-ga.texi
+++ /dev/null
@@ -1,137 +0,0 @@
-@example
-@c man begin SYNOPSIS
-@command{qemu-ga} [@var{OPTIONS}]
-@c man end
-@end example
-
-@c man begin DESCRIPTION
-
-The QEMU Guest Agent is a daemon intended to be run within virtual
-machines. It allows the hypervisor host to perform various operations
-in the guest, such as:
-
-@itemize
-@item
-get information from the guest
-@item
-set the guest's system time
-@item
-read/write a file
-@item
-sync and freeze the filesystems
-@item
-suspend the guest
-@item
-reconfigure guest local processors
-@item
-set user's password
-@item
-...
-@end itemize
-
-qemu-ga will read a system configuration file on startup (located at
-@file{@value{CONFDIR}/qemu-ga.conf} by default), then parse remaining
-configuration options on the command line. For the same key, the last
-option wins, but the lists accumulate (see below for configuration
-file format).
-
-@c man end
-
-@c man begin OPTIONS
-@table @option
-@item -m, --method=@var{method}
- Transport method: one of @samp{unix-listen}, @samp{virtio-serial}, or
- @samp{isa-serial} (@samp{virtio-serial} is the default).
-
-@item -p, --path=@var{path}
- Device/socket path (the default for virtio-serial is
- @samp{/dev/virtio-ports/org.qemu.guest_agent.0},
- the default for isa-serial is @samp{/dev/ttyS0})
-
-@item -l, --logfile=@var{path}
- Set log file path (default is stderr).
-
-@item -f, --pidfile=@var{path}
- Specify pid file (default is @samp{/var/run/qemu-ga.pid}).
-
-@item -F, --fsfreeze-hook=@var{path}
- Enable fsfreeze hook. Accepts an optional argument that specifies
- script to run on freeze/thaw. Script will be called with
- 'freeze'/'thaw' arguments accordingly (default is
- @samp{@value{CONFDIR}/fsfreeze-hook}). If using -F with an argument, do
- not follow -F with a space (for example:
- @samp{-F/var/run/fsfreezehook.sh}).
-
-@item -t, --statedir=@var{path}
- Specify the directory to store state information (absolute paths only,
- default is @samp{/var/run}).
-
-@item -v, --verbose
- Log extra debugging information.
-
-@item -V, --version
- Print version information and exit.
-
-@item -d, --daemon
- Daemonize after startup (detach from terminal).
-
-@item -b, --blacklist=@var{list}
- Comma-separated list of RPCs to disable (no spaces, @samp{?} to list
- available RPCs).
-
-@item -D, --dump-conf
- Dump the configuration in a format compatible with @file{qemu-ga.conf}
- and exit.
-
-@item -h, --help
- Display this help and exit.
-@end table
-
-@c man end
-
-@c man begin FILES
-
-The syntax of the @file{qemu-ga.conf} configuration file follows the
-Desktop Entry Specification, here is a quick summary: it consists of
-groups of key-value pairs, interspersed with comments.
-
-@example
-# qemu-ga configuration sample
-[general]
-daemonize = 0
-pidfile = /var/run/qemu-ga.pid
-verbose = 0
-method = virtio-serial
-path = /dev/virtio-ports/org.qemu.guest_agent.0
-statedir = /var/run
-@end example
-
-The list of keys follows the command line options:
-@table @option
-@item daemon= boolean
-@item method= string
-@item path= string
-@item logfile= string
-@item pidfile= string
-@item fsfreeze-hook= string
-@item statedir= string
-@item verbose= boolean
-@item blacklist= string list
-@end table
-
-@c man end
-
-@ignore
-
-@setfilename qemu-ga
-@settitle QEMU Guest Agent
-
-@c man begin AUTHOR
-Michael Roth <mdroth@linux.vnet.ibm.com>
-@c man end
-
-@c man begin SEEALSO
-qemu(1)
-@c man end
-
-@end ignore
--
2.20.1
On 9/13/19 10:49 AM, Peter Maydell wrote: > The qemu-ga documentation is currently in qemu-ga.texi in > Texinfo format, which we present to the user as: > * a qemu-ga manpage > * a section of the main qemu-doc HTML documentation > > Convert the documentation to rST format, and present it to > the user as: > * a qemu-ga manpage > * part of the interop/ Sphinx manual > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> > Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com> > Tested-by: Michael Roth <mdroth@linux.vnet.ibm.com> > Message-id: 20190905131040.8350-1-peter.maydell@linaro.org > --- In an incremental build on Fedora 30, I'm now seeing: CHK version_gen.h GEN docs/interop/qemu-ga.8 No filename or title make: *** [/home/eblake/qemu/rules.mak:394: docs/interop/qemu-ga.8] Error 255 and suspect this patch introduced it. It may be that I just need to nuke intermediate artifacts rather than an actual problem with the patch, but I'd welcome help in identifying the problem. -- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3226 Virtualization: qemu.org | libvirt.org
Eric Blake <eblake@redhat.com> writes: > On 9/13/19 10:49 AM, Peter Maydell wrote: >> The qemu-ga documentation is currently in qemu-ga.texi in >> Texinfo format, which we present to the user as: >> * a qemu-ga manpage >> * a section of the main qemu-doc HTML documentation >> >> Convert the documentation to rST format, and present it to >> the user as: >> * a qemu-ga manpage >> * part of the interop/ Sphinx manual >> >> Signed-off-by: Peter Maydell <peter.maydell@linaro.org> >> Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com> >> Tested-by: Michael Roth <mdroth@linux.vnet.ibm.com> >> Message-id: 20190905131040.8350-1-peter.maydell@linaro.org >> --- > > In an incremental build on Fedora 30, I'm now seeing: > > CHK version_gen.h > GEN docs/interop/qemu-ga.8 > No filename or title > make: *** [/home/eblake/qemu/rules.mak:394: docs/interop/qemu-ga.8] > Error 255 > > and suspect this patch introduced it. It may be that I just need to > nuke intermediate artifacts rather than an actual problem with the > patch, but I'd welcome help in identifying the problem. It did - it's also the commit that has broken shippable builds. Once I reverted they started working again. However I'm finding it hard to trigger in the same containers on my setup so I'm confused as to how it breaks. -- Alex Bennée
On Thu, 19 Sep 2019 at 02:25, Eric Blake <eblake@redhat.com> wrote: > > On 9/13/19 10:49 AM, Peter Maydell wrote: > > The qemu-ga documentation is currently in qemu-ga.texi in > > Texinfo format, which we present to the user as: > > * a qemu-ga manpage > > * a section of the main qemu-doc HTML documentation > > > > Convert the documentation to rST format, and present it to > > the user as: > > * a qemu-ga manpage > > * part of the interop/ Sphinx manual > > > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> > > Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com> > > Tested-by: Michael Roth <mdroth@linux.vnet.ibm.com> > > Message-id: 20190905131040.8350-1-peter.maydell@linaro.org > > --- > > In an incremental build on Fedora 30, I'm now seeing: > > CHK version_gen.h > GEN docs/interop/qemu-ga.8 > No filename or title > make: *** [/home/eblake/qemu/rules.mak:394: docs/interop/qemu-ga.8] > Error 255 > > and suspect this patch introduced it. It may be that I just need to > nuke intermediate artifacts rather than an actual problem with the > patch, but I'd welcome help in identifying the problem. If you build with V=1 what does it say it's doing? thanks -- PMM
On 9/19/19 7:00 AM, Peter Maydell wrote: >> In an incremental build on Fedora 30, I'm now seeing: >> >> CHK version_gen.h >> GEN docs/interop/qemu-ga.8 >> No filename or title >> make: *** [/home/eblake/qemu/rules.mak:394: docs/interop/qemu-ga.8] >> Error 255 >> >> and suspect this patch introduced it. It may be that I just need to >> nuke intermediate artifacts rather than an actual problem with the >> patch, but I'd welcome help in identifying the problem. > > If you build with V=1 what does it say it's doing? make[1]: Leaving directory '/home/eblake/qemu/dtc' perl -Ww -- /home/eblake/qemu/scripts/texi2pod.pl -I docs -I scripts -I docs/interop -DVERSION="4.1.50" -DCONFDIR="/usr/local/etc/qemu" scripts/texi2pod.pl docs/interop/qemu-ga.8.pod && pod2man --utf8 --section=8 --center=" " --release=" " docs/interop/qemu-ga.8.pod > docs/interop/qemu-ga.8 No filename or title make: *** [/home/eblake/qemu/rules.mak:394: docs/interop/qemu-ga.8] Error 255 -- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3226 Virtualization: qemu.org | libvirt.org
On Thu, 19 Sep 2019 at 14:27, Eric Blake <eblake@redhat.com> wrote: > > On 9/19/19 7:00 AM, Peter Maydell wrote: > > >> In an incremental build on Fedora 30, I'm now seeing: > >> > >> CHK version_gen.h > >> GEN docs/interop/qemu-ga.8 > >> No filename or title > >> make: *** [/home/eblake/qemu/rules.mak:394: docs/interop/qemu-ga.8] > >> Error 255 > >> > >> and suspect this patch introduced it. It may be that I just need to > >> nuke intermediate artifacts rather than an actual problem with the > >> patch, but I'd welcome help in identifying the problem. > > > > If you build with V=1 what does it say it's doing? > > make[1]: Leaving directory '/home/eblake/qemu/dtc' > perl -Ww -- /home/eblake/qemu/scripts/texi2pod.pl -I docs -I scripts -I > docs/interop -DVERSION="4.1.50" -DCONFDIR="/usr/local/etc/qemu" > scripts/texi2pod.pl docs/interop/qemu-ga.8.pod && pod2man --utf8 > --section=8 --center=" " --release=" " docs/interop/qemu-ga.8.pod > > docs/interop/qemu-ga.8 > No filename or title > make: *** [/home/eblake/qemu/rules.mak:394: docs/interop/qemu-ga.8] > Error 255 Do you have sphinx installed on this machine? I'm wondering if the problem here is that we have disabled the sphinx build runes but are then falling back to the "try to make any %.8 via the TEXI2MAN rule in rules.mak" [*]. On the other hand docs/interop/qemu-ga.8 is only put into DOCS if BUILD_DOCS is set, which should only happen if sphinx is available. [*] these rules are a bit bogus, because I think they will apply even if there's no other rule saying 'foo.8 depends on something.texi', and then as you can see in your command line we end up running texi2pod with an empty "$<" rather than passing it a texi file. thanks -- PMM
On 9/19/19 8:35 AM, Peter Maydell wrote: > On Thu, 19 Sep 2019 at 14:27, Eric Blake <eblake@redhat.com> wrote: >> >> On 9/19/19 7:00 AM, Peter Maydell wrote: >> >>>> In an incremental build on Fedora 30, I'm now seeing: >>>> >>>> CHK version_gen.h >>>> GEN docs/interop/qemu-ga.8 >>>> No filename or title >>>> make: *** [/home/eblake/qemu/rules.mak:394: docs/interop/qemu-ga.8] >>>> Error 255 >>>> >>>> and suspect this patch introduced it. It may be that I just need to >>>> nuke intermediate artifacts rather than an actual problem with the >>>> patch, but I'd welcome help in identifying the problem. >>> >>> If you build with V=1 what does it say it's doing? >> >> make[1]: Leaving directory '/home/eblake/qemu/dtc' >> perl -Ww -- /home/eblake/qemu/scripts/texi2pod.pl -I docs -I scripts -I >> docs/interop -DVERSION="4.1.50" -DCONFDIR="/usr/local/etc/qemu" >> scripts/texi2pod.pl docs/interop/qemu-ga.8.pod && pod2man --utf8 >> --section=8 --center=" " --release=" " docs/interop/qemu-ga.8.pod > >> docs/interop/qemu-ga.8 >> No filename or title >> make: *** [/home/eblake/qemu/rules.mak:394: docs/interop/qemu-ga.8] >> Error 255 > > Do you have sphinx installed on this machine? Not yet. /me goes and installs sphinx-2.2.11-12.fc30.x86_64 Nope, problem is still happening even after rerunning ./configure > I'm wondering > if the problem here is that we have disabled the sphinx build > runes but are then falling back to the "try to make any %.8 > via the TEXI2MAN rule in rules.mak" [*]. On the other hand > docs/interop/qemu-ga.8 is only put into DOCS if BUILD_DOCS is > set, which should only happen if sphinx is available. > > [*] these rules are a bit bogus, because I think they will apply even > if there's no other rule saying 'foo.8 depends on something.texi', > and then as you can see in your command line we end up running > texi2pod with an empty "$<" rather than passing it a texi file. Okay, that's something to play with. -- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3226 Virtualization: qemu.org | libvirt.org
On Thu, 19 Sep 2019 at 14:54, Eric Blake <eblake@redhat.com> wrote:
>
> On 9/19/19 8:35 AM, Peter Maydell wrote:
> > On Thu, 19 Sep 2019 at 14:27, Eric Blake <eblake@redhat.com> wrote:
> >>
> >> On 9/19/19 7:00 AM, Peter Maydell wrote:
> >>
> >>>> In an incremental build on Fedora 30, I'm now seeing:
> >>>>
> >>>> CHK version_gen.h
> >>>> GEN docs/interop/qemu-ga.8
> >>>> No filename or title
> >>>> make: *** [/home/eblake/qemu/rules.mak:394: docs/interop/qemu-ga.8]
> >>>> Error 255
> >>>>
> >>>> and suspect this patch introduced it. It may be that I just need to
> >>>> nuke intermediate artifacts rather than an actual problem with the
> >>>> patch, but I'd welcome help in identifying the problem.
> >>>
> >>> If you build with V=1 what does it say it's doing?
> >>
> >> make[1]: Leaving directory '/home/eblake/qemu/dtc'
> >> perl -Ww -- /home/eblake/qemu/scripts/texi2pod.pl -I docs -I scripts -I
> >> docs/interop -DVERSION="4.1.50" -DCONFDIR="/usr/local/etc/qemu"
> >> scripts/texi2pod.pl docs/interop/qemu-ga.8.pod && pod2man --utf8
> >> --section=8 --center=" " --release=" " docs/interop/qemu-ga.8.pod >
> >> docs/interop/qemu-ga.8
> >> No filename or title
> >> make: *** [/home/eblake/qemu/rules.mak:394: docs/interop/qemu-ga.8]
> >> Error 255
> >
> > Do you have sphinx installed on this machine?
>
> Not yet.
>
> /me goes and installs sphinx-2.2.11-12.fc30.x86_64
>
> Nope, problem is still happening even after rerunning ./configure
Alex looked at this and suggests the problem is probably because
you're doing an in-tree build. Sphinx insists that it can't build
output files into the source tree, so we have a thing where we
set MANUAL_BUILDDIR to docs/built if we're doing an in-tree build.
But the filename we add to DOCS is just "docs/interop/qemu-ga.8"
so for an in-tree build the sphinx rule won't match it, and
the install rune won't find it either.
If that's the cause I think this untested fix should help:
diff --git a/Makefile b/Makefile
index 111082ce545..8d9dcb3aa4a 100644
--- a/Makefile
+++ b/Makefile
@@ -325,7 +325,7 @@ endif
endif
ifdef BUILD_DOCS
-DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8
docs/interop/qemu-ga.8
+DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8
$(MANUAL_BUILDDIR)/interop/qemu-ga.8
DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt
docs/interop/qemu-qmp-ref.7
DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt
docs/interop/qemu-ga-ref.7
DOCS+=docs/qemu-block-drivers.7
@@ -819,7 +819,7 @@ ifdef CONFIG_TRACE_SYSTEMTAP
$(INSTALL_DATA) scripts/qemu-trace-stap.1 "$(DESTDIR)$(mandir)/man1"
endif
ifneq (,$(findstring qemu-ga,$(TOOLS)))
- $(INSTALL_DATA) docs/interop/qemu-ga.8 "$(DESTDIR)$(mandir)/man8"
+ $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-ga.8
"$(DESTDIR)$(mandir)/man8"
$(INSTALL_DATA) docs/interop/qemu-ga-ref.html "$(DESTDIR)$(qemu_docdir)"
$(INSTALL_DATA) docs/interop/qemu-ga-ref.txt "$(DESTDIR)$(qemu_docdir)"
$(INSTALL_DATA) docs/interop/qemu-ga-ref.7 "$(DESTDIR)$(mandir)/man7"
thanks
-- PMM
On 9/19/19 10:22 AM, Peter Maydell wrote: > Alex looked at this and suggests the problem is probably because > you're doing an in-tree build. Bingo. I thought we wanted to get rid of that, though. What's the status on forcing out-of-tree builds? (I'll adapt, but only once patches are in that force me to). > Sphinx insists that it can't build > output files into the source tree, so we have a thing where we > set MANUAL_BUILDDIR to docs/built if we're doing an in-tree build. > But the filename we add to DOCS is just "docs/interop/qemu-ga.8" > so for an in-tree build the sphinx rule won't match it, and > the install rune won't find it either. > > If that's the cause I think this untested fix should help: > > diff --git a/Makefile b/Makefile > index 111082ce545..8d9dcb3aa4a 100644 > --- a/Makefile > +++ b/Makefile > @@ -325,7 +325,7 @@ endif > endif > [1] > ifdef BUILD_DOCS > -DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8 > docs/interop/qemu-ga.8 > +DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8 > $(MANUAL_BUILDDIR)/interop/qemu-ga.8 Not quite. This occurs prior to the line defining MANUAL_BUILDDIR, resulting in: GEN /interop/qemu-ga.8 opening "/interop": No such file or directory But hoisting the following text up to point [1] makes the build complete with sphinx installed. Progress! > # Sphinx does not allow building manuals into the same directory as > # the source files, so if we're doing an in-tree QEMU build we must > # build the manuals into a subdirectory (and then install them from > # there for 'make install'). For an out-of-tree build we can just > # use the docs/ subdirectory in the build tree as normal. > ifeq ($(realpath $(SRC_PATH)),$(realpath .)) > MANUAL_BUILDDIR := docs/built > else > MANUAL_BUILDDIR := docs > endif -- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3226 Virtualization: qemu.org | libvirt.org
On Thu, 19 Sep 2019 at 16:37, Eric Blake <eblake@redhat.com> wrote: > > On 9/19/19 10:22 AM, Peter Maydell wrote: > > > Alex looked at this and suggests the problem is probably because > > you're doing an in-tree build. > > Bingo. I thought we wanted to get rid of that, though. What's the > status on forcing out-of-tree builds? (I'll adapt, but only once > patches are in that force me to). I think the general consensus was that it would probably be a good idea, but nobody's actually written any code :-) (Among other things, various bits of CI infra, probably the tests/vm code, etc, need updating to not try to do an in-tree build.) thanks -- PMM
On Thu, Sep 19, 2019 at 04:39:00PM +0100, Peter Maydell wrote: > On Thu, 19 Sep 2019 at 16:37, Eric Blake <eblake@redhat.com> wrote: > > > > On 9/19/19 10:22 AM, Peter Maydell wrote: > > > > > Alex looked at this and suggests the problem is probably because > > > you're doing an in-tree build. > > > > Bingo. I thought we wanted to get rid of that, though. What's the > > status on forcing out-of-tree builds? (I'll adapt, but only once > > patches are in that force me to). > > I think the general consensus was that it would probably > be a good idea, but nobody's actually written any code :-) > (Among other things, various bits of CI infra, probably > the tests/vm code, etc, need updating to not try to do > an in-tree build.) We have another issue introduced by this patch and not fixed yet, caused by this sphinx-build bug: https://github.com/sphinx-doc/sphinx/issues/2946 We're triggering that bug because the interop/index.html and interop/qemu-ga.8 rules are using the same doctree cache directory. -- Eduardo
Peter Maydell <peter.maydell@linaro.org> writes: > On Thu, 19 Sep 2019 at 02:25, Eric Blake <eblake@redhat.com> wrote: >> >> On 9/13/19 10:49 AM, Peter Maydell wrote: >> > The qemu-ga documentation is currently in qemu-ga.texi in >> > Texinfo format, which we present to the user as: >> > * a qemu-ga manpage >> > * a section of the main qemu-doc HTML documentation >> > >> > Convert the documentation to rST format, and present it to >> > the user as: >> > * a qemu-ga manpage >> > * part of the interop/ Sphinx manual >> > >> > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> >> > Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com> >> > Tested-by: Michael Roth <mdroth@linux.vnet.ibm.com> >> > Message-id: 20190905131040.8350-1-peter.maydell@linaro.org >> > --- >> >> In an incremental build on Fedora 30, I'm now seeing: >> >> CHK version_gen.h >> GEN docs/interop/qemu-ga.8 >> No filename or title >> make: *** [/home/eblake/qemu/rules.mak:394: docs/interop/qemu-ga.8] >> Error 255 >> >> and suspect this patch introduced it. It may be that I just need to >> nuke intermediate artifacts rather than an actual problem with the >> patch, but I'd welcome help in identifying the problem. > > If you build with V=1 what does it say it's doing? This is what shippable shows: make -I/root/src/github.com/stsquad/qemu/dtc VPATH=/root/src/github.com/stsquad/qemu/dtc -C dtc V="1" LIBFDT_srcdir=/root/src/github.com/stsquad/qemu/dtc/libfdt CPPFLAGS="-I/root/src/github.com/stsquad/qemu/dtc -I/root/src/github.com/stsquad/qemu/dtc -I/root/src/github.com/stsquad/qemu/dtc/libfdt" CFLAGS="-O2 -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=2 -g -I/usr/include/pixman-1 -I/root/src/github.com/stsquad/qemu/dtc/libfdt -Werror -pthread -I/usr/include/glib-2.0 -I/usr/lib/x86_64-linux-gnu/glib-2.0/include -fPIE -DPIE -m64 -mcx16 -D_GNU_SOURCE -D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE -Wstrict-prototypes -Wredundant-decls -Wall -Wundef -Wwrite-strings -Wmissing-prototypes -fno-strict-aliasing -fno-common -fwrapv -std=gnu99 -Wendif-labels -Wno-shift-negative-value -Wno-missing-include-dirs -Wempty-body -Wnested-externs -Wformat-security -Wformat-y2k -Winit-self -Wignored-qualifiers -Wold-style-declaration -Wold-style-definition -Wtype-limits -fstack-protector-strong -I/usr/include/p11-kit-1 -I/usr/include/libpng16 -I/usr/include/spice-server -I/usr/include/spice-1 -I/root/src/github.com/stsquad/qemu/capstone/include -I/root/src/github.com/stsquad/qemu/tests" LDFLAGS="-Wl,--warn-common -Wl,-z,relro -Wl,-z,now -pie -m64 -g " ARFLAGS="rv" CC="cc" AR="ar" LD="ld" BUILD_DIR=/root/src/github.com/stsquad/qemu libfdt/libfdt.a if ! cmp -s qemu-version.h qemu-version.h.tmp; then mv qemu-version.h.tmp qemu-version.h; else rm qemu-version.h.tmp; fi make[1]: Entering directory '/root/src/github.com/stsquad/qemu/dtc' make[1]: Entering directory '/root/src/github.com/stsquad/qemu/slirp' make -C /root/src/github.com/stsquad/qemu/capstone CAPSTONE_SHARED=no BUILDDIR="/root/src/github.com/stsquad/qemu/capstone" CC="cc" AR="ar" LD="ld" RANLIB="ranlib" CFLAGS="-O2 -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=2 -g -I/usr/include/pixman-1 -I/root/src/github.com/stsquad/qemu/dtc/libfdt -pthread -I/usr/include/glib-2.0 -I/usr/lib/x86_64-linux-gnu/glib-2.0/include -fPIE -DPIE -m64 -mcx16 -D_GNU_SOURCE -D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE -fno-strict-aliasing -fno-common -fwrapv -std=gnu99 -fstack-protector-strong -I/usr/include/p11-kit-1 -I/usr/include/libpng16 -I/usr/include/spice-server -I/usr/include/spice-1 -I/root/src/github.com/stsquad/qemu/capstone/include -I/root/src/github.com/stsquad/qemu/tests -DCAPSTONE_USE_SYS_DYN_MEM -DCAPSTONE_HAS_ARM -DCAPSTONE_HAS_ARM64 -DCAPSTONE_HAS_POWERPC -DCAPSTONE_HAS_X86" BUILD_DIR=/root/src/github.com/stsquad/qemu /root/src/github.com/stsquad/qemu/capstone/libcapstone.a make[1]: Nothing to be done for 'all'. make[1]: Leaving directory '/root/src/github.com/stsquad/qemu/slirp' make[1]: Entering directory '/root/src/github.com/stsquad/qemu/capstone' set -e; echo ' CHK version_gen.h'; mkdir -p ./; (echo "#define DTC_VERSION \"DTC 1.4.7\""; ) < Makefile > version_gen.h.tmp; if [ -r version_gen.h ] && cmp -s version_gen.h version_gen.h.tmp; then rm -f version_gen.h.tmp; else echo ' UPD version_gen.h'; mv -f version_gen.h.tmp version_gen.h; fi; CHK version_gen.h make[1]: '/root/src/github.com/stsquad/qemu/capstone/libcapstone.a' is up to date. make[1]: Leaving directory '/root/src/github.com/stsquad/qemu/capstone' make[1]: 'libfdt/libfdt.a' is up to date. make[1]: Leaving directory '/root/src/github.com/stsquad/qemu/dtc' cc -iquote /root/src/github.com/stsquad/qemu/tests/qemu-iotests -iquote tests/qemu-iotests -iquote /root/src/github.com/stsquad/qemu/tcg -iquote /root/src/github.com/stsquad/qemu/tcg/i386 -I/root/src/github.com/stsquad/qemu/linux-headers -I/root/src/github.com/stsquad/qemu/linux-headers -iquote . -iquote /root/src/github.com/stsquad/qemu -iquote /root/src/github.com/stsquad/qemu/accel/tcg -iquote /root/src/github.com/stsquad/qemu/include -I/usr/include/pixman-1 -I/root/src/github.com/stsquad/qemu/dtc/libfdt -Werror -pthread -I/usr/include/glib-2.0 -I/usr/lib/x86_64-linux-gnu/glib-2.0/include -fPIE -DPIE -m64 -mcx16 -D_GNU_SOURCE -D_FILE_OFFSET_BITS=64 -D_LARGEFILE_SOURCE -Wstrict-prototypes -Wredundant-decls -Wall -Wundef -Wwrite-strings -Wmissing-prototypes -fno-strict-aliasing -fno-common -fwrapv -std=gnu99 -Wendif-labels -Wno-shift-negative-value -Wno-missing-include-dirs -Wempty-body -Wnested-externs -Wformat-security -Wformat-y2k -Winit-self -Wignored-qualifiers -Wold-style-declaration -Wold-style-definition -Wtype-limits -fstack-protector-strong -I/usr/include/p11-kit-1 -I/usr/include/libpng16 -I/usr/include/spice-server -I/usr/include/spice-1 -I/root/src/github.com/stsquad/qemu/capstone/include -I/root/src/github.com/stsquad/qemu/tests -MMD -MP -MT tests/qemu-iotests/socket_scm_helper.o -MF tests/qemu-iotests/socket_scm_helper.d -O2 -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=2 -g -c -o tests/qemu-iotests/socket_scm_helper.o tests/qemu-iotests/socket_scm_helper.c ( echo "@set VERSION 4.1.50" && echo "@set CONFDIR /usr/local/etc/qemu" )> docs/version.texi sh /root/src/github.com/stsquad/qemu/scripts/hxtool -t < /root/src/github.com/stsquad/qemu/qemu-options.hx > qemu-options.texi sh /root/src/github.com/stsquad/qemu/scripts/hxtool -t < /root/src/github.com/stsquad/qemu/hmp-commands.hx > qemu-monitor.texi sh /root/src/github.com/stsquad/qemu/scripts/hxtool -t < /root/src/github.com/stsquad/qemu/qemu-img-cmds.hx > qemu-img-cmds.texi sh /root/src/github.com/stsquad/qemu/scripts/hxtool -t < /root/src/github.com/stsquad/qemu/hmp-commands-info.hx > qemu-monitor-info.texi perl -Ww -- /root/src/github.com/stsquad/qemu/scripts/texi2pod.pl -I docs -I . -I . -DVERSION="4.1.50" -DCONFDIR="/usr/local/etc/qemu" qemu-img.texi qemu-img.1.pod && pod2man --utf8 --section=1 --center=" " --release=" " qemu-img.1.pod > qemu-img.1 perl -Ww -- /root/src/github.com/stsquad/qemu/scripts/texi2pod.pl -I docs -I . -I . -DVERSION="4.1.50" -DCONFDIR="/usr/local/etc/qemu" qemu-nbd.texi qemu-nbd.8.pod && pod2man --utf8 --section=8 --center=" " --release=" " qemu-nbd.8.pod > qemu-nbd.8 perl -Ww -- /root/src/github.com/stsquad/qemu/scripts/texi2pod.pl -I docs -I scripts -I docs/interop -DVERSION="4.1.50" -DCONFDIR="/usr/local/etc/qemu" scripts/texi2pod.pl docs/interop/qemu-ga.8.pod && pod2man --utf8 --section=8 --center=" " --release=" " docs/interop/qemu-ga.8.pod > docs/interop/qemu-ga.8 python3 -B /root/src/github.com/stsquad/qemu/scripts/qapi-gen.py -o qga/qapi-generated -p "qga-" /root/src/github.com/stsquad/qemu/qga/qapi-schema.json No filename or title /root/src/github.com/stsquad/qemu/rules.mak:394: recipe for target 'docs/interop/qemu-ga.8' failed make: *** [docs/interop/qemu-ga.8] Error 255 make: *** Waiting for unfinished jobs.... -- Alex Bennée
© 2016 - 2025 Red Hat, Inc.