From patchwork Thu Oct 31 16:56:16 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Julien Stephan X-Patchwork-Id: 51624 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 1C89CD767EE for ; Thu, 31 Oct 2024 16:56:39 +0000 (UTC) Received: from mail-wm1-f46.google.com (mail-wm1-f46.google.com [209.85.128.46]) by mx.groups.io with SMTP id smtpd.web11.17357.1730393792727672345 for ; Thu, 31 Oct 2024 09:56:33 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@baylibre-com.20230601.gappssmtp.com header.s=20230601 header.b=etP5s1TI; spf=pass (domain: baylibre.com, ip: 209.85.128.46, mailfrom: jstephan@baylibre.com) Received: by mail-wm1-f46.google.com with SMTP id 5b1f17b1804b1-43158625112so9660645e9.3 for ; Thu, 31 Oct 2024 09:56:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=baylibre-com.20230601.gappssmtp.com; s=20230601; t=1730393791; x=1730998591; darn=lists.yoctoproject.org; h=to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:from:to:cc:subject:date:message-id :reply-to; bh=1o4G8h3x5SaYs0gPXX1YI/0UiKbBxnmoxTFZP1kdGuY=; b=etP5s1TIQFfA522dZuSphl/jXM6ekHLR4J3GCBefOenGklzAVRskA0/icbss4Qbbs2 z3QAiq6//Li66j+MhN8c0NaXBgURzYKcE7b9C0bmNBW7NoaLhaOQHAKpqdZEGMLDPNXb falozo82w13BCTOfn42z9w9ovILO9Wkc7bY1+pt2T3P7ASxVNkJHh/XQeQm5xokMv/VO MzJkpHaoGdsWtzEXy8IcTCB/04uSxEW+dyaa3m2CaSpD98EimkJ8l2Rqo+uAO6h9JaiY Y5OUPm/ct1mwhjctUsfrK3Q3mM9Ii/V8Eto2uQ8SbC+T9KD64IX7tbw01hOVM+xwy2B4 /Pbg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1730393791; x=1730998591; h=to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=1o4G8h3x5SaYs0gPXX1YI/0UiKbBxnmoxTFZP1kdGuY=; b=GIa6Px5QVXEnneknmh1TalHcgwROoUAa3NjAv3iRbgzXuNhbYL6vCIZ5dRbYckyhyu 5pLe4/s+/43tL3Fjs5yL/IraXgLcfNKJIWtabG0KQjwq9RKLIm549V+d91w/nGL/zS3T KJ4LFU/lwziX/9KWejhXY+0wTgU6Dd6xau8p/L4tUQfmVXSvMeQ0g539+WZuiwoqSkh2 4jJOYTkpp7VdyWAoLBDKf6DN8Bxnar1BMFNLt0UrQK8i12wQ+0sT9mzYbXWRF8t1WZKq W2kIbNL71CULBwldimw7fVvwhO4GD8jY4SzM3h/BG9aFedIewHvomtlumAaQsmoiWIiU xyTg== X-Gm-Message-State: AOJu0YwYiRG2/aAiYDbFoS49EZYRg7WYHv5wXahvPGV+jDkaKgIJ3KJ8 tP7O9TE6UfQtNw1FWjozLVSRFulT4u141cutvrf6D5pBPhtLqG+WWc/gY603b01h/RSI6iUyrCt ou94= X-Google-Smtp-Source: AGHT+IFBQOiMcfpK4hIbGzZ+uvEQKu1UxpugD8rYvtvt5/jE9oGFgE2FW67chhhs8xQqYz3H+XGxnA== X-Received: by 2002:a05:600c:4f14:b0:42b:a7c7:5667 with SMTP id 5b1f17b1804b1-4328327ec52mr4895605e9.25.1730393790391; Thu, 31 Oct 2024 09:56:30 -0700 (PDT) Received: from [192.168.1.64] (2a02-8428-e55b-1101-1e41-304e-170b-482f.rev.sfr.net. [2a02:8428:e55b:1101:1e41:304e:170b:482f]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-381c10e747csm2660525f8f.64.2024.10.31.09.56.30 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 31 Oct 2024 09:56:30 -0700 (PDT) From: Julien Stephan Date: Thu, 31 Oct 2024 17:56:16 +0100 Subject: [PATCH 1/5] README: add instruction to run Vale on a subset MIME-Version: 1.0 Message-Id: <20241031-add-bblock-documentation-v1-1-32b89093bbda@baylibre.com> References: <20241031-add-bblock-documentation-v1-0-32b89093bbda@baylibre.com> In-Reply-To: <20241031-add-bblock-documentation-v1-0-32b89093bbda@baylibre.com> To: docs@lists.yoctoproject.org, Julien Stephan X-Mailer: b4 0.14.2 List-Id: X-Webhook-Received: from li982-79.members.linode.com [45.33.32.79] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Thu, 31 Oct 2024 16:56:39 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/5638 make stylecheck runs Vale on the whole documentation which can be long and reports a lot of errors/warnings. We can run Vale on a subset using the VALEDOCS variable, so update documentation to highlight it. Signed-off-by: Julien Stephan --- documentation/README | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/documentation/README b/documentation/README index c888b666a8632a1d6f576c68e4f9ca966d79f134..6a4db97d65b9c23828163d8b548485b2e302bc97 100644 --- a/documentation/README +++ b/documentation/README @@ -142,6 +142,13 @@ To run Vale: $ make stylecheck +Style checking the whole documentation might take some time and generate a +lot of warnings/errors, thus one can run Vale on a subset: + + $ make stylecheck VALEDOCS= + $ make stylecheck VALEDOCS=" " + $ make stylecheck VALEDOCS= + Link checking the Yocto Project documentation ============================================= From patchwork Thu Oct 31 16:56:17 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Julien Stephan X-Patchwork-Id: 51625 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 2EB07D767F0 for ; Thu, 31 Oct 2024 16:56:39 +0000 (UTC) Received: from mail-wr1-f50.google.com (mail-wr1-f50.google.com [209.85.221.50]) by mx.groups.io with SMTP id smtpd.web10.17506.1730393792352467157 for ; Thu, 31 Oct 2024 09:56:32 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@baylibre-com.20230601.gappssmtp.com header.s=20230601 header.b=ginfM/S4; spf=pass (domain: baylibre.com, ip: 209.85.221.50, mailfrom: jstephan@baylibre.com) Received: by mail-wr1-f50.google.com with SMTP id ffacd0b85a97d-37ec4e349f4so728204f8f.0 for ; Thu, 31 Oct 2024 09:56:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=baylibre-com.20230601.gappssmtp.com; s=20230601; t=1730393791; x=1730998591; darn=lists.yoctoproject.org; h=to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:from:to:cc:subject:date:message-id :reply-to; bh=1Dfe6GLjTSwPpbVGINLkfSatO1Q/SF9CvceQ+FJ70Vc=; b=ginfM/S4tWlAT80vu91t/KvsN6XdvvswGDC//bmL0t3bMvZISvfBQ5hZOPm0MfIbRj 7aZ2LMu7MQtwuK6/2Q2akbGyf5DGEpNa+WD1J+G5VfKy4GX150Zb+jm885ZcRsROQJhx iRs+bSPxaYeC6bwnzrwUHFHTvKxKGgfyb+4jnFQ0Cm5qfa/FnV1QJ3OtRPn7fEj+o/+5 PX2UWJRjqpTQsRY+WCkkFEDt1E+cLyz+sskps9fW8ZqZ88MczdO+tUx62csaJJoAO5sx ZkSlHLdqKeWZ0O+pblpTfnFR2gK3CtXIO4JobOwwIBvAF5sQVnSCEC0fq5NYLKTJPBVZ jE7w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1730393791; x=1730998591; h=to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=1Dfe6GLjTSwPpbVGINLkfSatO1Q/SF9CvceQ+FJ70Vc=; b=xE4h94pUY/RZD5/nxl3gosqiVAY87pKyc4mC/vL4sZurugVfNPlz7u+bQIeh39fjDN wMUUUB+hpWhUwa0az6pQavdKf9pydTH06T1i9jhMJo2hE4VGtQCsSCVd7Ym13bC6FUfr +Q+WHBSGHFpEv/a7+Q9GUAGh6qgVul8QmCDOG9CGbzKOyMmYN3KvoXMPB0ZHBCKyakFD G8Wt5gfxo7GPWjbfHDiYabiDSztXX0qLR8MaDNHgOoAEJySu5EkynT1INfLGv7nkiMun i6uIE1KcGl/jT+0aYcdhD8Wems8Q/XOrSxbw0jWQ6J35lGR9m7B9xY7g0+P99HZLnKH4 brLw== X-Gm-Message-State: AOJu0YyFdKqfs/tU+kWNytSPtHajAPPV5yuoPD8+RVh/ETw5sxJrf/n2 f9AHWpR1J+ixMxuLUJCzSwdfslPdRPUknElH8rxjJYD9t63BDAw5Te/SPbRw9Bx03y1ywxbU7pL u1J0= X-Google-Smtp-Source: AGHT+IEH55vyOVo/gDZZl0Qaj4jwnK4UbUU6kWBEgD9dFGBLv+sxWYgo1Eo8WQJ/IIiXARAoGLD5JA== X-Received: by 2002:a05:6000:1fa1:b0:37c:c842:a16e with SMTP id ffacd0b85a97d-381c7a47818mr445497f8f.5.1730393790774; Thu, 31 Oct 2024 09:56:30 -0700 (PDT) Received: from [192.168.1.64] (2a02-8428-e55b-1101-1e41-304e-170b-482f.rev.sfr.net. [2a02:8428:e55b:1101:1e41:304e:170b:482f]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-381c10e747csm2660525f8f.64.2024.10.31.09.56.30 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 31 Oct 2024 09:56:30 -0700 (PDT) From: Julien Stephan Date: Thu, 31 Oct 2024 17:56:17 +0100 Subject: [PATCH 2/5] documentation: Makefile: add SPHINXLINTDOCS to specify subset to sphinx-lint MIME-Version: 1.0 Message-Id: <20241031-add-bblock-documentation-v1-2-32b89093bbda@baylibre.com> References: <20241031-add-bblock-documentation-v1-0-32b89093bbda@baylibre.com> In-Reply-To: <20241031-add-bblock-documentation-v1-0-32b89093bbda@baylibre.com> To: docs@lists.yoctoproject.org, Julien Stephan X-Mailer: b4 0.14.2 List-Id: X-Webhook-Received: from li982-79.members.linode.com [45.33.32.79] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Thu, 31 Oct 2024 16:56:39 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/5637 make sphinx-lint runs sphinx-lint on the whole documentation which can be long and reports a lot or errors/warnings. Let's add a new SHPINXLINTDOCS variable to allow specifying a subset, just as VALEDOCS does. Keep variable assignment aligned and also use $(SOURCEDIR) by default for SPHINXLINTDOCS and VALEDOCS variables. Also update the README file and fix a typo in Link checking section title. Signed-off-by: Julien Stephan --- documentation/Makefile | 23 ++++++++++++----------- documentation/README | 9 ++++++++- 2 files changed, 20 insertions(+), 12 deletions(-) diff --git a/documentation/Makefile b/documentation/Makefile index 189bd1dfac69d3b3185aa3a2ff7c212084ae280b..0bd9db5eaeb9122f9f396cda61631c403a1325a0 100644 --- a/documentation/Makefile +++ b/documentation/Makefile @@ -3,17 +3,18 @@ # You can set these variables from the command line, and also # from the environment for the first two. -SPHINXOPTS ?= -W --keep-going -j auto -SPHINXBUILD ?= sphinx-build +SPHINXOPTS ?= -W --keep-going -j auto +SPHINXBUILD ?= sphinx-build # Release notes are excluded because they contain contributor names and commit messages which can't be modified -VALEOPTS ?= --no-wrap --glob '!migration-guides/release-notes-*.rst' -VALEDOCS ?= . -SOURCEDIR = . -IMAGEDIRS = */svg -BUILDDIR = _build -DESTDIR = final -SVG2PNG = inkscape -SVG2PDF = inkscape +VALEOPTS ?= --no-wrap --glob '!migration-guides/release-notes-*.rst' +SOURCEDIR = . +VALEDOCS ?= $(SOURCEDIR) +SPHINXLINTDOCS ?= $(SOURCEDIR) +IMAGEDIRS = */svg +BUILDDIR = _build +DESTDIR = final +SVG2PNG = inkscape +SVG2PDF = inkscape ifeq ($(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi),0) $(error "The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed") @@ -54,7 +55,7 @@ stylecheck: vale $(VALEOPTS) $(VALEDOCS) sphinx-lint: - sphinx-lint $(SOURCEDIR) + sphinx-lint $(SPHINXLINTDOCS) epub: $(PNGs) $(SOURCEDIR)/set_versions.py diff --git a/documentation/README b/documentation/README index 6a4db97d65b9c23828163d8b548485b2e302bc97..d2676ae2de9cb9c2dbe4191c0e38f8847cd8603b 100644 --- a/documentation/README +++ b/documentation/README @@ -149,7 +149,7 @@ lot of warnings/errors, thus one can run Vale on a subset: $ make stylecheck VALEDOCS=" " $ make stylecheck VALEDOCS= -Link checking the Yocto Project documentation +Lint checking the Yocto Project documentation ============================================= To fix errors which are not reported by Sphinx itself, @@ -163,6 +163,13 @@ To run sphinx-lint: $ make sphinx-lint +Lint checking the whole documentation might take some time and generate a +lot of warnings/errors, thus one can run sphinx-lint on a specific file: + + $ make sphinx-lint SPHINXLINTDOCS= + $ make sphinx-lint SPHINXLINTDOCS=" " + $ make sphinx-lint SPHINXLINTDOCS= + Sphinx theme and CSS customization ================================== From patchwork Thu Oct 31 16:56:18 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Julien Stephan X-Patchwork-Id: 51622 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 1B8D1D767EB for ; Thu, 31 Oct 2024 16:56:39 +0000 (UTC) Received: from mail-wr1-f43.google.com (mail-wr1-f43.google.com [209.85.221.43]) by mx.groups.io with SMTP id smtpd.web11.17358.1730393792741937816 for ; Thu, 31 Oct 2024 09:56:33 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@baylibre-com.20230601.gappssmtp.com header.s=20230601 header.b=jUxODVub; spf=pass (domain: baylibre.com, ip: 209.85.221.43, mailfrom: jstephan@baylibre.com) Received: by mail-wr1-f43.google.com with SMTP id ffacd0b85a97d-37d49a7207cso835569f8f.0 for ; Thu, 31 Oct 2024 09:56:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=baylibre-com.20230601.gappssmtp.com; s=20230601; t=1730393791; x=1730998591; darn=lists.yoctoproject.org; h=to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:from:to:cc:subject:date:message-id :reply-to; bh=yjc+cCaSrTj6YRBRbSTWLWixNioSKrrMjhlnx2xBkBo=; b=jUxODVubHT/OBLQzEAlRFmdtgKvtNQdpnkRGk+KapDD18i2uK+VXjteQUAYqy0zGlV +IRuT9kGf5f4lxA9Sh2F/G1tBakVthE+StIaGDzNkaxP4HLczWkKy2bVZr7Ev/VyT8sH uP0D2tYPAhWUp8umitYZF8XHTj2nm8gTP6RSc5lrLQ7K1WrUyps1ucFtBDHR1oPlDZwW XZZdHdDmGjod0miQsqOk1qNniU8V/F5AWfQtEMm1QZX1fxdQWubhPioxxwi/I3jEg14C dsLV/UDFTkisulNGJwAx6RDG5h2J5RwUrqo/+VQgNm0o4vBdvBktAt0Me8yAoVUnWNxK zK9g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1730393791; x=1730998591; h=to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=yjc+cCaSrTj6YRBRbSTWLWixNioSKrrMjhlnx2xBkBo=; b=oS60j4E9VY+z35zSZh7OtHUTlfg4N+aGzbnweCA9ix86l1KKZEG1S2LZlLnR3E1J7o WeS62Uirrx+voM3NMbiK6AxA+iglwDE6cqpYQgOrL7ODT6v9mWgJTjotL6IJEPEIaHZw JmgeFuxOPxpqefxtoiujoiffEq80EvZ5VuGuYZUa8D4d0VB0Ly3voy26ktk5bSwtMqD+ METobFEvsieVK+gIA+6i2L5byVsMGSmZ8Buo5DCcKu5ipFMe5xMpkgV/QIme1of4ZtuD DoC+NMCfw0vryOh9mboy3ANwXN5vazSWzH7Uy9bhH9H1EhhrQunJ7YPbMLRdZuu7aSd7 JJAw== X-Gm-Message-State: AOJu0YyIJ/XVTaXKtiJY+kudFGEAJh3mciPWmDbKc136YoxPacvP1lWT T7vVnLb2pS4YiPUdYh+PhANK41BxHt/cM0ptXVP7puSGqoCHxLBvG0fnT6gDIfDhLut3svMUIuA Yboo= X-Google-Smtp-Source: AGHT+IHjzoKf7V91hX9rC3JBH7vd4QQVLIg1gLmuUr4OzQWn1dtFedmFGM1M3VsgtDIPch7PG0WbAQ== X-Received: by 2002:a05:6000:1faf:b0:37d:43f1:57fd with SMTP id ffacd0b85a97d-381c7a3a6a8mr564457f8f.6.1730393791195; Thu, 31 Oct 2024 09:56:31 -0700 (PDT) Received: from [192.168.1.64] (2a02-8428-e55b-1101-1e41-304e-170b-482f.rev.sfr.net. [2a02:8428:e55b:1101:1e41:304e:170b:482f]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-381c10e747csm2660525f8f.64.2024.10.31.09.56.30 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 31 Oct 2024 09:56:30 -0700 (PDT) From: Julien Stephan Date: Thu, 31 Oct 2024 17:56:18 +0100 Subject: [PATCH 3/5] styles: vocabularies: Yocto: add sstate MIME-Version: 1.0 Message-Id: <20241031-add-bblock-documentation-v1-3-32b89093bbda@baylibre.com> References: <20241031-add-bblock-documentation-v1-0-32b89093bbda@baylibre.com> In-Reply-To: <20241031-add-bblock-documentation-v1-0-32b89093bbda@baylibre.com> To: docs@lists.yoctoproject.org, Julien Stephan X-Mailer: b4 0.14.2 List-Id: X-Webhook-Received: from li982-79.members.linode.com [45.33.32.79] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Thu, 31 Oct 2024 16:56:39 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/5639 Add sstate as an accepted word to avoid errors when runnign make stylecheck. Signed-off-by: Julien Stephan --- documentation/styles/config/vocabularies/Yocto/accept.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/documentation/styles/config/vocabularies/Yocto/accept.txt b/documentation/styles/config/vocabularies/Yocto/accept.txt index ca622ba41274c892f1fc1e16d8332a02f07a3531..7fedda8ae23c22f3660292faa0a1c3df23da353e 100644 --- a/documentation/styles/config/vocabularies/Yocto/accept.txt +++ b/documentation/styles/config/vocabularies/Yocto/accept.txt @@ -2,4 +2,5 @@ BitBake BSP crosstap OpenEmbedded +sstate Yocto From patchwork Thu Oct 31 16:56:19 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Julien Stephan X-Patchwork-Id: 51623 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 0AF20D767E9 for ; Thu, 31 Oct 2024 16:56:39 +0000 (UTC) Received: from mail-wm1-f44.google.com (mail-wm1-f44.google.com [209.85.128.44]) by mx.groups.io with SMTP id smtpd.web10.17508.1730393793170098224 for ; Thu, 31 Oct 2024 09:56:33 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@baylibre-com.20230601.gappssmtp.com header.s=20230601 header.b=XGwAb7MJ; spf=pass (domain: baylibre.com, ip: 209.85.128.44, mailfrom: jstephan@baylibre.com) Received: by mail-wm1-f44.google.com with SMTP id 5b1f17b1804b1-43155afca99so14339195e9.1 for ; Thu, 31 Oct 2024 09:56:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=baylibre-com.20230601.gappssmtp.com; s=20230601; t=1730393791; x=1730998591; darn=lists.yoctoproject.org; h=to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:from:to:cc:subject:date:message-id :reply-to; bh=4n/Gg1JnuXBIk4IMJplrznWJqonQXXzJTzd0kzIUh0E=; b=XGwAb7MJUonIIIZmBxKUEMlfO3KZTsMz/8pmBJKH5UDw5qIQVtXfw/6tJ2Zn4zXnBZ XamlnTPeKUFdE+UomI3WlI4GIbQUpyq5gsLXnDF31+rZ7n04CaunhBIzCEFMhn8U42ew hiXTzNAs36Z2GIdxURX58Jk99vRMvB8fkjTCpwvrNFqU/4tcnp8O4biYihFNf2hJMzYw RJ6AmBrwPyST0vqsqOYzVmvecpA2fvJwXkipowWLeg73M3P0SdpeFY2H+WHSXE1Bzldz gRreVurcFFDfxK+kG4Gb4HvpgKWjVAWmmqOucsqsDwDCxd8yTpRJcY532rqmGxIQmiVD CBZQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1730393791; x=1730998591; h=to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=4n/Gg1JnuXBIk4IMJplrznWJqonQXXzJTzd0kzIUh0E=; b=uVslV9RtjrGxddQ+4TPSc95L9mW0AcaV37loTqlbH6vNycK3/Gq2kdcEugc1l5Lslh Vz1Wxs7EIg2Po61jh30I9RUtNA6hB2+j5vkTNZTr+uSrSd0UANHiS1pamcqLw/yMSQaO 7klmlMb0YYePdyMQMkGwKAcAuFJ04GfKzJRJOcJ43yj6940Uw9rN6aEDq0J/U/1GjR9e V2myNh5gcoTgqkvkoQR1pAseMVjeU/4yJ8J2Ob1nKn/3/BeAPM4qe5Di7EUbIneY8vnS E9AeWXVTVejUZfMMde+/qBkavE7GZxKCUOZ+GHjv33xekFWSdmRFh9XI5SHV/s1sX5w1 ZuwQ== X-Gm-Message-State: AOJu0YyHcbfQC6hHSWzBENdiMu0hJMmChWozzNkQyf8hcGAl1nXVTQOI HbuBufH+6QbtV/ksNsdtQLq0akGm32N8CpvzOvHxbuJ0NIo9niloM/Qbij2oJOowjSxqjslxXzY RByc= X-Google-Smtp-Source: AGHT+IGXgAXs4Beanu48Q7ZnKxOoBWmYY/jDMzpQ7JR8Ix9EGGhSF1qbCOu/MuibrX4Q+vgx64MvyA== X-Received: by 2002:a05:6000:2a2:b0:378:8b56:4665 with SMTP id ffacd0b85a97d-381c14d495cmr2654311f8f.24.1730393791592; Thu, 31 Oct 2024 09:56:31 -0700 (PDT) Received: from [192.168.1.64] (2a02-8428-e55b-1101-1e41-304e-170b-482f.rev.sfr.net. [2a02:8428:e55b:1101:1e41:304e:170b:482f]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-381c10e747csm2660525f8f.64.2024.10.31.09.56.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 31 Oct 2024 09:56:31 -0700 (PDT) From: Julien Stephan Date: Thu, 31 Oct 2024 17:56:19 +0100 Subject: [PATCH 4/5] ref-manual: variables: add SIGGEN_LOCKEDSIGS* variables MIME-Version: 1.0 Message-Id: <20241031-add-bblock-documentation-v1-4-32b89093bbda@baylibre.com> References: <20241031-add-bblock-documentation-v1-0-32b89093bbda@baylibre.com> In-Reply-To: <20241031-add-bblock-documentation-v1-0-32b89093bbda@baylibre.com> To: docs@lists.yoctoproject.org, Julien Stephan X-Mailer: b4 0.14.2 List-Id: X-Webhook-Received: from li982-79.members.linode.com [45.33.32.79] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Thu, 31 Oct 2024 16:56:39 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/5640 Variables SIGGEN_LOCKEDSIGS, SIGGEN_LOCKEDSIGS_TASKSIG_CHECK and SIGGEN_LOCKEDSIGS_TYPES are used to lock specific tasks to specific signatures. They are used by bitbake -S and bblock, so add documentation for them. Signed-off-by: Julien Stephan --- documentation/ref-manual/variables.rst | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index 07ed143ac5606617c720301ac6621355a341f90a..8cfb978e795e43e3ef25f3e18e11baf7c2a28d54 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -7880,6 +7880,39 @@ system and gives an overview of their function and contents. might break at runtime if the interface of the recipe was changed after the other had been built. + :term:`SIGGEN_LOCKEDSIGS` + The list of locked taks, with the form:: + + SIGGEN_LOCKEDSIGS += "::" + + If ```` exists for the specified ```` and ```` + in sstate, BitBake will use the cached output instead of rebuilding the + ````. If it does not exist, BitBake will build the ```` and + the sstate will be used next time. + + :term:`SIGGEN_LOCKEDSIGS_TASKSIG_CHECK` + Specifies the debug level of task signature check. 3 levels are supported: + + * info: displays a "Note" message to remind user that a task is locked + and current signature matches the locked one. + * warn: displays a "Warning" message if a task is locked and current + signature does not match the locked one. + * error: same as warn but displays an “Error” message and abort. + + :term:`SIGGEN_LOCKEDSIGS_TYPES` + Allowed overrides for :term:`SIGGEN_LOCKEDSIGS`. This is mainly used + for achitecture specific lock. A common value for :term:`SIGGEN_LOCKEDSIGS_TYPES` + is ``${PACKAGE_ARCHS}``:: + + SIGGEN_LOCKEDSIGS_TYPES += "${PACKAGE_ARCHS}" + + SIGGEN_LOCKEDSIGS_core2-64 += "bc:do_compile:abcd" + SIGGEN_LOCKEDSIGS_cortexa57 += "bc:do_compile:efgh" + + Here, the ``do_compile`` task from ``bc`` will be locked only for + ``x86-64`` and ``arm64`` but not for other architectures such as + ``qemumips``. + :term:`SITEINFO_BITS` Specifies the number of bits for the target system CPU. The value should be either "32" or "64". From patchwork Thu Oct 31 16:56:20 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Julien Stephan X-Patchwork-Id: 51621 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 0EA8AD767EA for ; Thu, 31 Oct 2024 16:56:39 +0000 (UTC) Received: from mail-wr1-f41.google.com (mail-wr1-f41.google.com [209.85.221.41]) by mx.groups.io with SMTP id smtpd.web11.17363.1730393794412022404 for ; Thu, 31 Oct 2024 09:56:34 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@baylibre-com.20230601.gappssmtp.com header.s=20230601 header.b=SO1XJ0+s; spf=pass (domain: baylibre.com, ip: 209.85.221.41, mailfrom: jstephan@baylibre.com) Received: by mail-wr1-f41.google.com with SMTP id ffacd0b85a97d-37d4b0943c7so684991f8f.1 for ; Thu, 31 Oct 2024 09:56:34 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=baylibre-com.20230601.gappssmtp.com; s=20230601; t=1730393793; x=1730998593; darn=lists.yoctoproject.org; h=to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:from:to:cc:subject:date:message-id :reply-to; bh=k2bmk2W1jR1mc81TNupqjZ2musUGBv8KQurM6E5a/8Y=; b=SO1XJ0+s5IErHly2z/IO5IY1PDilRQTvFEltAuo5gnIm0L5mSLt5/8VyYMQAeajyu+ RxjkTWQ4BxSqAKzFC7zaLLItF2Uze7TY3+jMuhFPUV5uBJ+Rasf098NeMeUDsxxJ8jGE l33gHXNKl5K0ft6UfEkyspbTOTI+KiptRcSBxhpCRCMT/HXVRE1ZbRTA8IbLrI2NBNc6 C+TjpCAtz0TpqNm9r8cdTOiL8ZviM8u425UP+3EKfGyiSDgukIdOEKWRr6XX3GRAs1g1 f/z5WNOsUuCXuW48ahp/+5MO+jP24pLhbSjzpZqMWd0mLMLKls+xkBZGCfJm06Az/wLP srrw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1730393793; x=1730998593; h=to:in-reply-to:references:message-id:content-transfer-encoding :mime-version:subject:date:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=k2bmk2W1jR1mc81TNupqjZ2musUGBv8KQurM6E5a/8Y=; b=ro74rYIhcETeAPDthTR9xBADfUPL2SpquvCtNfp4ifDjpxysfnTotDFNZzUKFOBEeR sEl2NMDfyJnomRS2qsR9GBTfgvfGlgtow6YTfLs71mlnkT52V6U1/MmtFk6oaYEJEQCJ 0Ben9VjEh4xLDuLxFJAlmwVsc9EYjz10Q9H6tqphY4Ayxth+XzBqqJjtRqErBGbpYxLy q4sDn+m4o7l1fRncyLBxM2o5xvc5TFcPN4e/+/jQdl9Wtv2WRXrOL9Erpf/SswhKX4WD ZPhps3eY5RvNQqRDBi07xlef70yAz4T3majoC5Ea+ZOX5wkMjUzHDawoC/6er4bLK/KF lk4g== X-Gm-Message-State: AOJu0YxuDes1f1FigwbQn521DNDkszTWMmQlDuEzZHY8I9Q/2+AjrXga 9BAwEQKQksoaq0z0jaxk/aAwQHgyB64MDqJauFd+W9XCfa7pIuG/e6o4KNXVoca73fLGcVil8Ps b0/0= X-Google-Smtp-Source: AGHT+IEk/RSUJNaY3ZC3BZNgAMt0qP5ek73EsToSIm753lKDC2jZVi+KyJjXLMETVWsqc4CAHNdxfw== X-Received: by 2002:adf:a2d2:0:b0:37d:4647:154e with SMTP id ffacd0b85a97d-380610f264fmr13788988f8f.9.1730393792707; Thu, 31 Oct 2024 09:56:32 -0700 (PDT) Received: from [192.168.1.64] (2a02-8428-e55b-1101-1e41-304e-170b-482f.rev.sfr.net. [2a02:8428:e55b:1101:1e41:304e:170b:482f]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-381c10e747csm2660525f8f.64.2024.10.31.09.56.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 31 Oct 2024 09:56:31 -0700 (PDT) From: Julien Stephan Date: Thu, 31 Oct 2024 17:56:20 +0100 Subject: [PATCH 5/5] dev-manual: add bblock documentation MIME-Version: 1.0 Message-Id: <20241031-add-bblock-documentation-v1-5-32b89093bbda@baylibre.com> References: <20241031-add-bblock-documentation-v1-0-32b89093bbda@baylibre.com> In-Reply-To: <20241031-add-bblock-documentation-v1-0-32b89093bbda@baylibre.com> To: docs@lists.yoctoproject.org, Julien Stephan X-Mailer: b4 0.14.2 List-Id: X-Webhook-Received: from li982-79.members.linode.com [45.33.32.79] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Thu, 31 Oct 2024 16:56:39 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/5641 bblock is a helper tool to lock/unlock tasks and recipes to specific signatures. Add a documentation page for it. Signed-off-by: Julien Stephan --- documentation/dev-manual/bblock.rst | 129 ++++++++++++++++++++++++++++++++++++ documentation/dev-manual/index.rst | 1 + 2 files changed, 130 insertions(+) diff --git a/documentation/dev-manual/bblock.rst b/documentation/dev-manual/bblock.rst new file mode 100644 index 0000000000000000000000000000000000000000..3df75799aa638d173764607df191bd99612034cf --- /dev/null +++ b/documentation/dev-manual/bblock.rst @@ -0,0 +1,129 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +Locking and Unlocking Recipes Using ``bblock`` +********************************************** + +By design, the OpenEmbedded build system builds everything from scratch +unless BitBake determines that specific parts do not require rebuilding. +At startup, it computes a signature for each tasks, based on the task's input. +Then, it compares these signatures with the ones from sstate (if exist). Any +changes cause the task to rerun. + +During development, changes might trigger BitBake to rebuild certain +recipes, even when we know they do not require rebuilding at that stage. +For example, modifying a recipe can lead to the rebuilding of its native +counterpart, which might proves unnecessary. Editing the ``python3`` recipe, +for instance, can prompt BitBake to rebuild ``python3-native`` along with any +recipes that depend on it. + +To prevent this, use ``bblock`` to lock specific tasks or recipes to +specific signatures, forcing BitBake to use the sstate cache for them. + +.. attention:: + + Use ``bblock`` only during the development phase. + + Forcing BitBake to use sstate cache, regardless of input changes, means + the recipe metadata no longer directly reflect the output. Use this feature + with caution. If you do not understand why signatures change, see the section + on `understanding what changed `__. + + +Locking tasks and recipes +------------------------- + +To lock a recipe, use:: + + $ bblock recipe + +You can also use a space-separated list of recipes to lock many recipes:: + + $ bblock recipe1 recipe2 + +Locking a recipe, means locking all tasks of the recipe. If you need to +lock only particular tasks use the `-t` switch with a comma-separated +list of tasks:: + + $ bblock -t task1,task2 recipe + + +Unlocking tasks and recipes +--------------------------- + +To unlock a recipe, use:: + + $ bblock -r recipe + +You can also use a space-separated list of recipes to unlock many recipes:: + + $ bblock -r recipe1 recipe2 + +Unlocking a recipe, means unlocking all tasks of the recipe. If you need to +unlock only particular tasks use the `-t` switch with a comma-separated +list of tasks:: + + $ bblock -r -t task1,task2 recipe + +To unlock all recipes, do not specify any recipe:: + + $ bblock -r + + +Configuration file +------------------ + +``bblock`` will dump the signatures in the ``build/conf/bblock.conf`` file, +included by default in ``poky/meta/conf/bitbake.conf``. + +To dump it, use:: + + $ bblock -d + + +Locking mechanism +----------------- + +``bblock`` computes the signature(s) of the task(s) then uses the 3 following +variables: :term:`SIGGEN_LOCKEDSIGS`, :term:`SIGGEN_LOCKEDSIGS_TYPES` +and :term:`SIGGEN_LOCKEDSIGS_TASKSIG_CHECK`. + +In particular, ``bblock`` sets:: + + SIGGEN_LOCKEDSIGS_TASKSIG_CHECK = "info" + SIGGEN_LOCKEDSIGS_TYPES += "${PACKAGE_ARCHS}" + + SIGGEN_LOCKEDSIGS_ += "::" + +This produces architecture specific locks and reminds user that some tasks +have locked signatures. + +Example +------- + +When working on ``python3`` recipe, we can lock ``pyton3-native`` with the +following:: + + $ bblock python3-native + $ bblock -d + # Generated by bblock + SIGGEN_LOCKEDSIGS_TASKSIG_CHECK = "info" + SIGGEN_LOCKEDSIGS_TYPES += "${PACKAGE_ARCHS}" + + SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_patch:865859c27e603ba42025b7bb766c3cd4c0f477e4962cfd39128c0619d695fce7" + SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_populate_sysroot:f8fa5d3194cef638416000252b959e86d0a19f6b7898e1f56b643c588cdd8605" + SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_prepare_recipe_sysroot:fe295ac505d9d1143313424b201c6f3f2a0a90da40a13a905b86b874705f226a" + SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_fetch:1b6e4728fee631bc7a8a7006855c5b8182a8224579e32e3d0a2db77c26459f25" + SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_unpack:2ad74d6f865ef75c35c0e6bbe3f9a90923a6b2c62c18a3ddef514ea31fbc588f" + SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_deploy_source_date_epoch:15f89b8483c1ad7507480f337619bb98c26e231227785eb3543db163593e7b42" + SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_configure:7960c13d23270fdb12b3a7c426ce1da0d2f5c7cf5e5d3f5bdce5fa330eb7d482" + SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_compile:012e1d4a63f1a78fc2143bd90d704dbcf5865c5257d6272aa7540ec1cd3063d9" + SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_install:d3401cc2afa4c996beb154beaad3e45fa0272b9c56fb86e9db14ec3544c68f9d" + SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_build:fa88bb7afb9046c0417c24a3fa98a058653805a8b00eda2c2d7fea68fc42f882" + SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_collect_spdx_deps:cc9c53ba7c495567e9a38ec4801830c425c0d1f895aa2fc66930a2edd510d9b4" + SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_create_spdx:766a1d09368438b7b5a1a8e2a8f823b2b731db44b57e67d8b3196de91966f9c5" + SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_create_package_spdx:46f80faeab25575e9977ba3bf14c819489c3d489432ae5145255635108c21020" + SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_recipe_qa:cb960cdb074e7944e894958db58f3dc2a0436ecf87c247feb3e095e214fec0e4" + SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_populate_lic:15657441621ee83f15c2e650e7edbb036870b56f55e72e046c6142da3c5783fd" + SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_create_manifest:24f0abbec221d27bbb2909b6e846288b12cab419f1faf9f5006ed80423d37e28" + SIGGEN_LOCKEDSIGS_x86_64 += "python3-native:do_addto_recipe_sysroot:bcb6a1905f113128de3f88d702b706befd6a786267c045ee82532759a7c214d7" + diff --git a/documentation/dev-manual/index.rst b/documentation/dev-manual/index.rst index 9ccf60f7012ea344612298e77ebabed84ad6de3e..7afd0d820e94d56cb2145962b9b1a976c7951936 100644 --- a/documentation/dev-manual/index.rst +++ b/documentation/dev-manual/index.rst @@ -48,5 +48,6 @@ Yocto Project Development Tasks Manual error-reporting-tool wayland qemu + bblock .. include:: /boilerplate.rst