diff mbox series

[meta-oe] lcov: Fix parallel build race in sphinx docs

Message ID 20261102065234.1804122-1-khem.raj@oss.qualcomm.com
State New
Headers show
Series [meta-oe] lcov: Fix parallel build race in sphinx docs | expand

Commit Message

Khem Raj Nov. 2, 2026, 6:52 a.m. UTC 
"make install" depends on a doc target which runs "make -C docs man html".
With -j both goals start their own sphinx-build sharing _build/doctrees,
which sphinx does not write atomically, so one can read a doctree the
other is rewriting. do_install then fails at random:

  AttributeError: 'dict' object has no attribute 'append'
  make: *** [Makefile:138: doc] Error 2

Add .NOTPARALLEL to docs/Makefile so that the goals run one after the
other. Running "make -j64 man html" on an oversubscribed host failed 71
out of 576 times without this change and never with it.

Signed-off-by: Khem Raj <khem.raj@oss.qualcomm.com>
AI-Generated: Uses Claude Code
---
 ...t-run-sphinx-build-goals-in-parallel.patch | 36 +++++++++++++++++++
 meta-oe/recipes-support/lcov/lcov_2.6.bb      |  4 ++-
 2 files changed, 39 insertions(+), 1 deletion(-)
 create mode 100644 meta-oe/recipes-support/lcov/lcov/0001-docs-Do-not-run-sphinx-build-goals-in-parallel.patch
diff mbox series

Patch

diff --git a/meta-oe/recipes-support/lcov/lcov/0001-docs-Do-not-run-sphinx-build-goals-in-parallel.patch b/meta-oe/recipes-support/lcov/lcov/0001-docs-Do-not-run-sphinx-build-goals-in-parallel.patch
new file mode 100644
index 0000000000..abc1539773
--- /dev/null
+++ b/meta-oe/recipes-support/lcov/lcov/0001-docs-Do-not-run-sphinx-build-goals-in-parallel.patch
@@ -0,0 +1,36 @@ 
+From: Khem Raj <khem.raj@oss.qualcomm.com>
+Date: Sun, 1 Nov 2026 20:00:00 -0700
+Subject: [PATCH] docs: Do not run sphinx-build goals in parallel
+
+The top-level "doc" target runs "make -C docs man html". With -j both
+goals match the catch-all rule at once and start two sphinx-build
+processes sharing _build/doctrees. One process can read a doctree the
+other is rewriting, so "make -j install" fails at random with unpickling
+errors such as:
+
+  AttributeError: 'dict' object has no attribute 'append'
+  EOFError: Ran out of input
+
+Mark the docs Makefile .NOTPARALLEL so the goals run one after the other.
+
+Upstream-Status: Pending
+Signed-off-by: Khem Raj <khem.raj@oss.qualcomm.com>
+---
+ docs/Makefile | 4 ++++
+ 1 file changed, 4 insertions(+)
+
+diff --git a/docs/Makefile b/docs/Makefile
+index f99b1df..c088ba8 100644
+--- a/docs/Makefile
++++ b/docs/Makefile
+@@ -14,6 +14,10 @@ BUILDDIR      = _build
+ help:
+ 	@LCOV_BUILD_DATE=$(BUILD_DATE) LCOV_RELEASE=$(RELEASE) TOOL_NAME=$(TOOL_NAME) $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
++# Each goal runs its own sphinx-build and they all share the doctrees in
++# $(BUILDDIR), which sphinx does not write atomically.
++.NOTPARALLEL:
++
+ .PHONY: clean help Makefile
+
+ # Catch-all target: route all unknown targets to Sphinx using the new
diff --git a/meta-oe/recipes-support/lcov/lcov_2.6.bb b/meta-oe/recipes-support/lcov/lcov_2.6.bb
index 3fb48e4501..cd37a6cce5 100755
--- a/meta-oe/recipes-support/lcov/lcov_2.6.bb
+++ b/meta-oe/recipes-support/lcov/lcov_2.6.bb
@@ -57,7 +57,9 @@  RDEPENDS:${PN}:append:class-target = " \
     gcov \
     gcov-symlinks \
 "
-SRC_URI = "https://github.com/linux-test-project/lcov/releases/download/v${PV}/lcov-${PV}.tar.gz"
+SRC_URI = "https://github.com/linux-test-project/lcov/releases/download/v${PV}/lcov-${PV}.tar.gz \
+           file://0001-docs-Do-not-run-sphinx-build-goals-in-parallel.patch \
+           "
 SRC_URI[sha256sum] = "67a45db99b8ef0260c3fac9a2e3749fd8fa350a15e235dd3c29b356d97755c75"

 UPSTREAM_CHECK_URI = "https://github.com/linux-test-project/lcov/releases"