* [PATCH v2 1/8] docs: give the root prompts a preamble
2026-09-22 18:32 [PATCH v2 0/8] docs: editorial repairs to the examples Trevor Woerner
@ 2026-09-22 18:32 ` Trevor Woerner
2026-09-23 10:17 ` [docs] " Quentin Schulz
2026-09-22 18:32 ` [PATCH v2 2/8] docs: copy only the command from a console block Trevor Woerner
` (6 subsequent siblings)
7 siblings, 1 reply; 23+ messages in thread
From: Trevor Woerner @ 2026-09-22 18:32 UTC (permalink / raw)
To: docs
A bare "#" starting a line is a root prompt, a comment and a line of
program output all at once, and nothing can tell them apart. Most root
prompts in the manuals already carry a preamble naming the machine, and
the stragglers are what make the distinction unreliable.
Add the preamble the others already use: the machine the surrounding
steps name, or a generic "machine" where they name none.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
changes in v2:
- rebased on master-next
- the SystemTap example uses a generic root@machine prompt; the two
kernel-dev ones keep qemux86, which the surrounding steps name
---
documentation/kernel-dev/common.rst | 4 ++--
documentation/profile-manual/usage.rst | 2 +-
2 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst
index 2a65055e2a44..fe2e42265f9f 100644
--- a/documentation/kernel-dev/common.rst
+++ b/documentation/kernel-dev/common.rst
@@ -722,7 +722,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using ``devtool```" Sectio
.. code-block:: none
- # dmesg | less
+ root@qemux86:~# dmesg | less
You should see
the results of your ``printk`` statements as part of the output
@@ -878,7 +878,7 @@ Section.
.. code-block:: none
- # dmesg | less
+ root@qemux86:~# dmesg | less
You should see the results of your
``printk`` statements as part of the output when you scroll down the
diff --git a/documentation/profile-manual/usage.rst b/documentation/profile-manual/usage.rst
index dc34fa36c487..4efaa6d10fce 100644
--- a/documentation/profile-manual/usage.rst
+++ b/documentation/profile-manual/usage.rst
@@ -1801,7 +1801,7 @@ probe, you'd just install SystemTap on the system you want to probe,
and directly run the probe on that system e.g. assuming the name of the
file containing the above text is ``trace_open.stp``::
- # stap trace_open.stp
+ root@machine:~# stap trace_open.stp
What SystemTap does under the covers to run this probe is 1) parse and
convert the probe to an equivalent "C" form, 2) compile the "C" form
--
2.50.0.173.g8b6f19ccfc3a
^ permalink raw reply related [flat|nested] 23+ messages in thread* Re: [docs] [PATCH v2 1/8] docs: give the root prompts a preamble
2026-09-22 18:32 ` [PATCH v2 1/8] docs: give the root prompts a preamble Trevor Woerner
@ 2026-09-23 10:17 ` Quentin Schulz
2026-09-24 16:00 ` Trevor Woerner
0 siblings, 1 reply; 23+ messages in thread
From: Quentin Schulz @ 2026-09-23 10:17 UTC (permalink / raw)
To: twoerner, docs
Hi Trevor,
On 9/22/26 8:32 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> A bare "#" starting a line is a root prompt, a comment and a line of
> program output all at once, and nothing can tell them apart. Most root
> prompts in the manuals already carry a preamble naming the machine, and
> the stragglers are what make the distinction unreliable.
>
> Add the preamble the others already use: the machine the surrounding
> steps name, or a generic "machine" where they name none.
>
> AI-Generated: codex/claude-opus 5 (xhigh)
> Signed-off-by: Trevor Woerner <twoerner@gmail.com>
> ---
> changes in v2:
> - rebased on master-next
> - the SystemTap example uses a generic root@machine prompt; the two
> kernel-dev ones keep qemux86, which the surrounding steps name
> ---
> documentation/kernel-dev/common.rst | 4 ++--
> documentation/profile-manual/usage.rst | 2 +-
> 2 files changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst
> index 2a65055e2a44..fe2e42265f9f 100644
> --- a/documentation/kernel-dev/common.rst
> +++ b/documentation/kernel-dev/common.rst
> @@ -722,7 +722,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using ``devtool```" Sectio
>
> .. code-block:: none
>
> - # dmesg | less
> + root@qemux86:~# dmesg | less
>
> You should see
> the results of your ``printk`` statements as part of the output
> @@ -878,7 +878,7 @@ Section.
>
> .. code-block:: none
>
> - # dmesg | less
> + root@qemux86:~# dmesg | less
>
This file is also missing a
root@machine:~# cd /usr/src/kernel
root@machine:/usr/src/kernel# make scripts
I'm assuming.
In any case,
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
Thanks!
Quentin
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [docs] [PATCH v2 1/8] docs: give the root prompts a preamble
2026-09-23 10:17 ` [docs] " Quentin Schulz
@ 2026-09-24 16:00 ` Trevor Woerner
0 siblings, 0 replies; 23+ messages in thread
From: Trevor Woerner @ 2026-09-24 16:00 UTC (permalink / raw)
To: Quentin Schulz; +Cc: docs
On Wed 2026-09-23 @ 12:17:36 PM, Quentin Schulz wrote:
> Hi Trevor,
>
> On 9/22/26 8:32 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> > A bare "#" starting a line is a root prompt, a comment and a line of
> > program output all at once, and nothing can tell them apart. Most root
> > prompts in the manuals already carry a preamble naming the machine, and
> > the stragglers are what make the distinction unreliable.
> >
> > Add the preamble the others already use: the machine the surrounding
> > steps name, or a generic "machine" where they name none.
> >
> > AI-Generated: codex/claude-opus 5 (xhigh)
> > Signed-off-by: Trevor Woerner <twoerner@gmail.com>
> > ---
> > changes in v2:
> > - rebased on master-next
> > - the SystemTap example uses a generic root@machine prompt; the two
> > kernel-dev ones keep qemux86, which the surrounding steps name
> > ---
> > documentation/kernel-dev/common.rst | 4 ++--
> > documentation/profile-manual/usage.rst | 2 +-
> > 2 files changed, 3 insertions(+), 3 deletions(-)
> >
> > diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst
> > index 2a65055e2a44..fe2e42265f9f 100644
> > --- a/documentation/kernel-dev/common.rst
> > +++ b/documentation/kernel-dev/common.rst
> > @@ -722,7 +722,7 @@ the ":ref:`kernel-dev/common:getting ready to develop using ``devtool```" Sectio
> > .. code-block:: none
> > - # dmesg | less
> > + root@qemux86:~# dmesg | less
> > You should see
> > the results of your ``printk`` statements as part of the output
> > @@ -878,7 +878,7 @@ Section.
> > .. code-block:: none
> > - # dmesg | less
> > + root@qemux86:~# dmesg | less
>
> This file is also missing a
>
> root@machine:~# cd /usr/src/kernel
> root@machine:/usr/src/kernel# make scripts
>
> I'm assuming.
Good catch, thanks.
> In any case,
>
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
>
> Thanks!
> Quentin
^ permalink raw reply [flat|nested] 23+ messages in thread
* [PATCH v2 2/8] docs: copy only the command from a console block
2026-09-22 18:32 [PATCH v2 0/8] docs: editorial repairs to the examples Trevor Woerner
2026-09-22 18:32 ` [PATCH v2 1/8] docs: give the root prompts a preamble Trevor Woerner
@ 2026-09-22 18:32 ` Trevor Woerner
2026-09-23 10:41 ` [docs] " Quentin Schulz
2026-09-22 18:32 ` [PATCH v2 3/8] docs: show a prompt on commands the reader is meant to type Trevor Woerner
` (5 subsequent siblings)
7 siblings, 1 reply; 23+ messages in thread
From: Trevor Woerner @ 2026-09-22 18:32 UTC (permalink / raw)
To: docs
The copy button matches the literal "$ " prompt, so on a block prompted
any other way it matches nothing and falls back to copying every line,
prompt and output included. Match a pattern covering each prompt shape
the manuals use instead, so the button gives the command alone whatever
the prompt looks like.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
changes in v2:
- dropped the stylesheet change, so a mouse selection keeps the output
- the comment now says this governs the copy button only, and only
reaches a block the console lexer has read
---
documentation/conf.py | 28 +++++++++++++++++++++++++++-
1 file changed, 27 insertions(+), 1 deletion(-)
diff --git a/documentation/conf.py b/documentation/conf.py
index 48d28a686807..313cabec05bb 100644
--- a/documentation/conf.py
+++ b/documentation/conf.py
@@ -242,4 +242,30 @@ intersphinx_mapping = {
# -- sphinx_copybutton configuration -----------------------------------------
# sphinx-copybutton configuration
-copybutton_prompt_text = "$ "
+# This governs the copy button only. A mouse selection is a separate
+# mechanism and takes whatever the theme leaves selectable, which is the
+# command and its output; Sphinx already excludes the prompt itself.
+#
+# It also only reaches a block the console lexer read, since that is what
+# marks a prompt as a prompt.
+#
+# Strip the prompt from a copied line wherever the prompt cannot be
+# confused with content. The pattern is not scoped to console blocks, so
+# every alternative has to stay safe inside a BitBake or configuration
+# example as well; measured over the built manuals, each one matches only
+# lines the lexer itself marks as a prompt.
+#
+# A bare "#" is deliberately absent. It opens a root prompt, a comment and
+# a line of program output alike, and nothing distinguishes them - which is
+# why the root prompts are given a preamble before this is switched on.
+copybutton_prompt_text = "|".join((
+ r"^(?:\S+[@:]\S*)?\$\s+", # "$ ", and "user@host:~$ "
+ r"^\S+[@:]\S*#\s+", # "root@qemux86-64:~# ", a root prompt
+ r"^[A-Za-z]:\\[^>]*>\s*", # "C:\WINDOWS\system32>", cmd.exe
+ r"^DISKPART>\s*", # diskpart prints a prompt of its own
+ r"^pydevshell>\s+", # bitbake -c pydevshell
+))
+copybutton_prompt_is_regexp = True
+copybutton_only_copy_prompt_lines = True
+copybutton_remove_prompts = True
+copybutton_line_continuation_character = "\\"
--
2.50.0.173.g8b6f19ccfc3a
^ permalink raw reply related [flat|nested] 23+ messages in thread* Re: [docs] [PATCH v2 2/8] docs: copy only the command from a console block
2026-09-22 18:32 ` [PATCH v2 2/8] docs: copy only the command from a console block Trevor Woerner
@ 2026-09-23 10:41 ` Quentin Schulz
2026-09-23 10:43 ` Quentin Schulz
0 siblings, 1 reply; 23+ messages in thread
From: Quentin Schulz @ 2026-09-23 10:41 UTC (permalink / raw)
To: twoerner, docs
Hi Trevor,
On 9/22/26 8:32 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> The copy button matches the literal "$ " prompt, so on a block prompted
> any other way it matches nothing and falls back to copying every line,
> prompt and output included. Match a pattern covering each prompt shape
> the manuals use instead, so the button gives the command alone whatever
> the prompt looks like.
>
> AI-Generated: codex/claude-opus 5 (xhigh)
> Signed-off-by: Trevor Woerner <twoerner@gmail.com>
> ---
> changes in v2:
> - dropped the stylesheet change, so a mouse selection keeps the output
> - the comment now says this governs the copy button only, and only
> reaches a block the console lexer has read
> ---
> documentation/conf.py | 28 +++++++++++++++++++++++++++-
> 1 file changed, 27 insertions(+), 1 deletion(-)
>
> diff --git a/documentation/conf.py b/documentation/conf.py
> index 48d28a686807..313cabec05bb 100644
> --- a/documentation/conf.py
> +++ b/documentation/conf.py
> @@ -242,4 +242,30 @@ intersphinx_mapping = {
> # -- sphinx_copybutton configuration -----------------------------------------
>
> # sphinx-copybutton configuration
> -copybutton_prompt_text = "$ "
> +# This governs the copy button only. A mouse selection is a separate
> +# mechanism and takes whatever the theme leaves selectable, which is the
> +# command and its output; Sphinx already excludes the prompt itself.
> +#
> +# It also only reaches a block the console lexer read, since that is what
> +# marks a prompt as a prompt.
> +#
> +# Strip the prompt from a copied line wherever the prompt cannot be
> +# confused with content. The pattern is not scoped to console blocks, so
You say above that it only reaches blocks the console lexer reads and
now you say it's not scoped to console blocks, this is confusing.
> +# every alternative has to stay safe inside a BitBake or configuration
> +# example as well; measured over the built manuals, each one matches only
> +# lines the lexer itself marks as a prompt.
> +#
> +# A bare "#" is deliberately absent. It opens a root prompt, a comment and
> +# a line of program output alike, and nothing distinguishes them - which is
> +# why the root prompts are given a preamble before this is switched on.
Ask your AI to be less verbose please, or edit the comments by hand.
In 10s I could come up with:
# Only applies to the copybutton. Mouse selection is not impacted.
# <insert whatever is correct for the pattern scope>
# No rule for # as it can denote a comment, root prompt or command output.
> +copybutton_prompt_text = "|".join((
> + r"^(?:\S+[@:]\S*)?\$\s+", # "$ ", and "user@host:~$ "
Am I right that (?:) is just to say "do not capture the content" (c.f.
https://docs.python.org/3/library/re.html#regular-expression-syntax). Is
it *really* necessary, I find that it adds unnecessary complexity for a
human to maintain this regexp.
EDIT: sigh... copybutton is parsing with Javascript according to
https://sphinx-copybutton.readthedocs.io/en/latest/use.html#using-regexp-prompt-identifiers
but regex101.com says the same (non-capturing group).
> + r"^\S+[@:]\S*#\s+", # "root@qemux86-64:~# ", a root prompt
And then you could simply merge the two first regexp into one:
r"^\S+[@:]\S*[#\$]\s+"
> + r"^[A-Za-z]:\\[^>]*>\s*", # "C:\WINDOWS\system32>", cmd.exe
Have not used Windows in 15 years so cannot say whether this is
appropriate. In any case, I'm not sure we'll have more examples than we
have today for Windows as only the WSL part would use that, so fine with me.
> + r"^DISKPART>\s*", # diskpart prints a prompt of its own
> + r"^pydevshell>\s+", # bitbake -c pydevshell
question: what happens to the one and only example we have of commands
to run in a python interpreter? (remove the leading #, it's just so mail
clients don't interpret this as a quote of a quote of a quote)
# >>> from gi.repository import GLib
# >>> GLib.get_host_name()
> +))
> +copybutton_prompt_is_regexp = True
> +copybutton_only_copy_prompt_lines = True
This is the default, but I'm guessing it doesn't hurt to make it explicit.
> +copybutton_remove_prompts = True
This is the default, but I'm guessing it doesn't hurt to make it explicit.
Cheers,
Quentin
^ permalink raw reply [flat|nested] 23+ messages in thread* Re: [docs] [PATCH v2 2/8] docs: copy only the command from a console block
2026-09-23 10:41 ` [docs] " Quentin Schulz
@ 2026-09-23 10:43 ` Quentin Schulz
0 siblings, 0 replies; 23+ messages in thread
From: Quentin Schulz @ 2026-09-23 10:43 UTC (permalink / raw)
To: twoerner, docs
On 9/23/26 12:41 PM, Quentin Schulz via lists.yoctoproject.org wrote:
> Hi Trevor,
>
> On 9/22/26 8:32 PM, Trevor Woerner via lists.yoctoproject.org wrote:
>> The copy button matches the literal "$ " prompt, so on a block prompted
>> any other way it matches nothing and falls back to copying every line,
>> prompt and output included. Match a pattern covering each prompt shape
>> the manuals use instead, so the button gives the command alone whatever
>> the prompt looks like.
>>
>> AI-Generated: codex/claude-opus 5 (xhigh)
>> Signed-off-by: Trevor Woerner <twoerner@gmail.com>
>> ---
>> changes in v2:
>> - dropped the stylesheet change, so a mouse selection keeps the output
>> - the comment now says this governs the copy button only, and only
>> reaches a block the console lexer has read
>> ---
>> documentation/conf.py | 28 +++++++++++++++++++++++++++-
>> 1 file changed, 27 insertions(+), 1 deletion(-)
>>
>> diff --git a/documentation/conf.py b/documentation/conf.py
>> index 48d28a686807..313cabec05bb 100644
>> --- a/documentation/conf.py
>> +++ b/documentation/conf.py
>> @@ -242,4 +242,30 @@ intersphinx_mapping = {
>> # -- sphinx_copybutton configuration
>> -----------------------------------------
>> # sphinx-copybutton configuration
>> -copybutton_prompt_text = "$ "
>> +# This governs the copy button only. A mouse selection is a separate
>> +# mechanism and takes whatever the theme leaves selectable, which is the
>> +# command and its output; Sphinx already excludes the prompt itself.
>> +#
>> +# It also only reaches a block the console lexer read, since that is
>> what
>> +# marks a prompt as a prompt.
>> +#
>> +# Strip the prompt from a copied line wherever the prompt cannot be
>> +# confused with content. The pattern is not scoped to console blocks, so
>
> You say above that it only reaches blocks the console lexer reads and
> now you say it's not scoped to console blocks, this is confusing.
>
>> +# every alternative has to stay safe inside a BitBake or configuration
>> +# example as well; measured over the built manuals, each one matches
>> only
>> +# lines the lexer itself marks as a prompt.
>> +#
>> +# A bare "#" is deliberately absent. It opens a root prompt, a
>> comment and
>> +# a line of program output alike, and nothing distinguishes them -
>> which is
>> +# why the root prompts are given a preamble before this is switched on.
>
> Ask your AI to be less verbose please, or edit the comments by hand.
>
> In 10s I could come up with:
>
> # Only applies to the copybutton. Mouse selection is not impacted.
> # <insert whatever is correct for the pattern scope>
> # No rule for # as it can denote a comment, root prompt or command output.
>
>> +copybutton_prompt_text = "|".join((
>> + r"^(?:\S+[@:]\S*)?\$\s+", # "$ ", and "user@host:~$ "
>
> Am I right that (?:) is just to say "do not capture the content" (c.f.
> https://eur02.safelinks.protection.outlook.com/?
> url=https%3A%2F%2Fdocs.python.org%2F3%2Flibrary%2Fre.html%23regular-
> expression-
> syntax&data=05%7C02%7Cquentin.schulz%40cherry.de%7Cb7040e79d7cc4140b6d908df195f3dfa%7C5e0e1b5221b54e7b83bb514ec460677e%7C0%7C0%7C639257569068945587%7CUnknown%7CTWFpbGZsb3d8eyJFbXB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWFpbCIsIldUIjoyfQ%3D%3D%7C0%7C%7C%7C&sdata=ep8uCE%2BFE3tcdhzUT3Xt0wc4KdQytvOjxMP%2FUkvXtmk%3D&reserved=0). Is it *really* necessary, I find that it adds unnecessary complexity for a human to maintain this regexp.
>
> EDIT: sigh... copybutton is parsing with Javascript according to
> https://eur02.safelinks.protection.outlook.com/?
> url=https%3A%2F%2Fsphinx-
> copybutton.readthedocs.io%2Fen%2Flatest%2Fuse.html%23using-regexp-
> prompt-
> identifiers&data=05%7C02%7Cquentin.schulz%40cherry.de%7Cb7040e79d7cc4140b6d908df195f3dfa%7C5e0e1b5221b54e7b83bb514ec460677e%7C0%7C0%7C639257569068971255%7CUnknown%7CTWFpbGZsb3d8eyJFbXB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWFpbCIsIldUIjoyfQ%3D%3D%7C0%7C%7C%7C&sdata=lo7H8RTXJ%2FjVWkfjWeOk7xuIapQowSevjLwFHmWwukM%3D&reserved=0 but regex101.com says the same (non-capturing group).
>
>> + r"^\S+[@:]\S*#\s+", # "root@qemux86-64:~# ", a root prompt
>
> And then you could simply merge the two first regexp into one:
>
> r"^\S+[@:]\S*[#\$]\s+"
>
OK this isn't what you want, because this here will match not match a
line starting with $ and if we reuse the regexp from above, then it
would match a line starting with #, which we don't want. So having them
split is fine. Ignore this comment.
>> + r"^[A-Za-z]:\\[^>]*>\s*", # "C:\WINDOWS\system32>", cmd.exe
>
> Have not used Windows in 15 years so cannot say whether this is
> appropriate. In any case, I'm not sure we'll have more examples than we
> have today for Windows as only the WSL part would use that, so fine with
> me.
>
>> + r"^DISKPART>\s*", # diskpart prints a prompt of its own
>> + r"^pydevshell>\s+", # bitbake -c pydevshell
>
> question: what happens to the one and only example we have of commands
> to run in a python interpreter? (remove the leading #, it's just so mail
> clients don't interpret this as a quote of a quote of a quote)
>
> # >>> from gi.repository import GLib
> # >>> GLib.get_host_name()
>
>> +))
>> +copybutton_prompt_is_regexp = True
>> +copybutton_only_copy_prompt_lines = True
>
> This is the default, but I'm guessing it doesn't hurt to make it explicit.
>
>> +copybutton_remove_prompts = True
>
> This is the default, but I'm guessing it doesn't hurt to make it explicit.
>
> Cheers,
> Quentin
>
>
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#10602): https://lists.yoctoproject.org/g/docs/message/10602
> Mute This Topic: https://lists.yoctoproject.org/mt/121380214/6293953
> Group Owner: docs+owner@lists.yoctoproject.org
> Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [quentin.schulz@cherry.de]
> -=-=-=-=-=-=-=-=-=-=-=-
>
^ permalink raw reply [flat|nested] 23+ messages in thread
* [PATCH v2 3/8] docs: show a prompt on commands the reader is meant to type
2026-09-22 18:32 [PATCH v2 0/8] docs: editorial repairs to the examples Trevor Woerner
2026-09-22 18:32 ` [PATCH v2 1/8] docs: give the root prompts a preamble Trevor Woerner
2026-09-22 18:32 ` [PATCH v2 2/8] docs: copy only the command from a console block Trevor Woerner
@ 2026-09-22 18:32 ` Trevor Woerner
2026-09-23 10:49 ` [docs] " Quentin Schulz
2026-09-22 18:32 ` [PATCH v2 4/8] docs: write an elided passage as a comment Trevor Woerner
` (4 subsequent siblings)
7 siblings, 1 reply; 23+ messages in thread
From: Trevor Woerner @ 2026-09-22 18:32 UTC (permalink / raw)
To: docs
Most command blocks in the manuals start their lines with "$", but a
scattering of them do not, and those read as a file listing rather than
as something to run. Give them the prompt the surrounding pages already
use.
Transcripts take a prompt on their opening line alone. Two things that
matter only once a line is a command go with that: a bare "$" at the end,
the prompt returning after the command finished, and a trailing "\" on a
Windows path, which a shell reads as a continuation into the output.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
changes in v2:
- rebased on master-next; no other change
---
documentation/brief-yoctoprojectqs/index.rst | 2 +-
.../contributor-guide/recipe-style-guide.rst | 2 +-
.../contributor-guide/submit-changes.rst | 60 +++++++++----------
.../dev-manual/creating-fragments.rst | 4 +-
documentation/dev-manual/debugging.rst | 1 -
documentation/dev-manual/devtool.rst | 8 +--
documentation/dev-manual/disk-space.rst | 4 +-
documentation/dev-manual/hashequivserver.rst | 2 +-
.../dev-manual/limiting-resources.rst | 2 +-
documentation/dev-manual/new-recipe.rst | 6 +-
documentation/dev-manual/packages.rst | 2 +-
.../dev-manual/python-development-shell.rst | 1 -
documentation/dev-manual/qemu.rst | 8 +--
documentation/dev-manual/start.rst | 2 +-
documentation/dev-manual/wayland.rst | 6 +-
documentation/kernel-dev/common.rst | 3 -
.../migration-guides/migration-2.1.rst | 4 +-
.../migration-guides/migration-2.5.rst | 4 +-
.../migration-guides/migration-4.0.rst | 2 +-
.../migration-guides/migration-5.3.rst | 10 ++--
.../migration-guides/release-notes-4.2.rst | 2 +-
.../migration-guides/release-notes-5.3.rst | 2 +-
documentation/ref-manual/classes.rst | 8 +--
.../ref-manual/devtool-reference.rst | 2 -
documentation/ref-manual/fragments.rst | 16 ++---
documentation/ref-manual/qa-checks.rst | 4 +-
documentation/ref-manual/variables.rst | 6 +-
.../test-manual/reproducible-builds.rst | 2 +-
documentation/test-manual/runtime-testing.rst | 4 +-
29 files changed, 86 insertions(+), 93 deletions(-)
diff --git a/documentation/brief-yoctoprojectqs/index.rst b/documentation/brief-yoctoprojectqs/index.rst
index f7e4606f1f7b..e138df6c9351 100644
--- a/documentation/brief-yoctoprojectqs/index.rst
+++ b/documentation/brief-yoctoprojectqs/index.rst
@@ -373,7 +373,7 @@ layer>`:
First, clone the layer next to the other layers::
- git clone -b &DISTRO_NAME_NO_CAP; https://git.yoctoproject.org/meta-raspberrypi ../layers/meta-raspberrypi
+ $ git clone -b &DISTRO_NAME_NO_CAP; https://git.yoctoproject.org/meta-raspberrypi ../layers/meta-raspberrypi
#. **Add Your Layer to the Layer Configuration File:** Before you can use
it, you must add the layer and its dependencies to your :ref:`structure-build-conf-bblayers.conf`
diff --git a/documentation/contributor-guide/recipe-style-guide.rst b/documentation/contributor-guide/recipe-style-guide.rst
index 84c6bb14e8b0..fe12a8e6d826 100644
--- a/documentation/contributor-guide/recipe-style-guide.rst
+++ b/documentation/contributor-guide/recipe-style-guide.rst
@@ -436,7 +436,7 @@ By default, patches created with ``git format-patch`` have a `Git` version signa
To avoid having a `Git` signature at the end of generated or updated patches,
you can use `Git` configuration settings::
- git config --global format.signature ""
+ $ git config --global format.signature ""
.. note::
Patches generated or updated by ``devtool`` are created with no signature.
diff --git a/documentation/contributor-guide/submit-changes.rst b/documentation/contributor-guide/submit-changes.rst
index 574a92cd3465..e60f8ca7ace3 100644
--- a/documentation/contributor-guide/submit-changes.rst
+++ b/documentation/contributor-guide/submit-changes.rst
@@ -57,20 +57,20 @@ Set up Git
The first thing to do is to install Git packages. Here is an example
on Debian and Ubuntu::
- sudo apt install git-core git-email
+ $ sudo apt install git-core git-email
Then, you need to set a name and e-mail address that Git will
use to identify your commits::
- git config --global user.name "Ada Lovelace"
- git config --global user.email "ada.lovelace@gmail.com"
+ $ git config --global user.name "Ada Lovelace"
+ $ git config --global user.email "ada.lovelace@gmail.com"
By default, Git adds a signature line at the end of patches containing the Git
version. We suggest to remove it as it doesn't add useful information.
Remove it with the following command::
- git config --global format.signature ""
+ $ git config --global format.signature ""
Clone the Git repository for the component to modify
----------------------------------------------------
@@ -79,8 +79,8 @@ After identifying the component to modify as described in the
":doc:`/contributor-guide/identify-component`" section, clone the
corresponding Git repository. Here is an example for OpenEmbedded-Core::
- git clone https://git.openembedded.org/openembedded-core
- cd openembedded-core
+ $ git clone https://git.openembedded.org/openembedded-core
+ $ cd openembedded-core
Create a new branch
-------------------
@@ -177,7 +177,7 @@ to add the upgraded version.
is to look for prefixes used in previous commits touching the
same files or directories::
- git log --oneline <paths>
+ $ git log --oneline <paths>
#. For the commit description, provide detailed information
that describes what you changed, why you made the change, and the
@@ -278,7 +278,7 @@ Here is the general procedure on how to create patches to be sent through email:
For this purpose, a good solution is to store the cover letter contents
in the branch itself::
- git branch --edit-description
+ $ git branch --edit-description
This will open a text editor to fill in the description for your
changes. This description can be updated when necessary and will
@@ -334,19 +334,19 @@ functional testing of the changes will be performed by ``patchtest``. Currently,
it only supports testing patches for ``openembedded-core`` branches. To setup,
perform the following::
- pip install -r meta/lib/patchtest/requirements.txt
- source oe-init-build-env
- bitbake-layers add-layer ../meta-selftest
+ $ pip install -r meta/lib/patchtest/requirements.txt
+ $ source oe-init-build-env
+ $ bitbake-layers add-layer ../meta-selftest
Once these steps are complete and you have generated your patch files,
you can run ``patchtest`` like so::
- patchtest --patch <patch_name>
+ $ patchtest --patch <patch_name>
Alternatively, if you want ``patchtest`` to iterate over and test
multiple patches stored in a directory, you can use::
- patchtest --directory <directory_name>
+ $ patchtest --directory <directory_name>
By default, ``patchtest`` uses its own modules' file paths to determine what
repository and test suite to check patches against. If you wish to test
@@ -354,7 +354,7 @@ patches against a repository other than ``openembedded-core`` and/or use
a different set of tests, you can use the ``--repodir`` and ``--testdir``
flags::
- patchtest --patch <patch_name> --repodir <path/to/repo> --testdir <path/to/testdir>
+ $ patchtest --patch <patch_name> --repodir <path/to/repo> --testdir <path/to/testdir>
Finally, note that ``patchtest`` is designed to test patches in a standalone
way, so if your patches are meant to apply on top of changes made by
@@ -396,11 +396,11 @@ through a direct SMTP configuration in your Git ``~/.gitconfig`` file.
Here are the settings for letting ``git send-email`` send e-mail through your
regular STMP server, using a Google Mail account as an example::
- git config --global sendemail.smtpserver smtp.gmail.com
- git config --global sendemail.smtpserverport 587
- git config --global sendemail.smtpencryption tls
- git config --global sendemail.smtpuser ada.lovelace@gmail.com
- git config --global sendemail.smtppass = XXXXXXXX
+ $ git config --global sendemail.smtpserver smtp.gmail.com
+ $ git config --global sendemail.smtpserverport 587
+ $ git config --global sendemail.smtpencryption tls
+ $ git config --global sendemail.smtpuser ada.lovelace@gmail.com
+ $ git config --global sendemail.smtppass = XXXXXXXX
These settings will appear in the ``.gitconfig`` file in your home directory.
@@ -463,7 +463,7 @@ Sending Patches via Email
At this stage, you are ready to send your patches via email. Here's the
typical usage of ``git send-email``::
- git send-email --to <mailing-list-address> *.patch
+ $ git send-email --to <mailing-list-address> *.patch
Then, review each subject line and list of recipients carefully, and then
allow the command to send each message.
@@ -476,7 +476,7 @@ or any layer other than :oe_git:`openembedded-core </openembedded-core/>`,
please add the appropriate prefix so that it is clear which layer the patch is intended
to be applied to::
- git format-patch --subject-prefix="meta-oe][PATCH" ...
+ $ git format-patch --subject-prefix="meta-oe][PATCH" ...
.. note::
@@ -488,13 +488,13 @@ to be applied to::
Here's a command you can use if you just have one patch in your
branch::
- git send-email --to <mailing-list-address> -1
+ $ git send-email --to <mailing-list-address> -1
If you have multiple patches and a cover letter, you can send
patches for all the commits between the reference branch
and the tip of your branch::
- git send-email --cover-letter --cover-from-description=auto --to <mailing-list-address> -M <ref-branch>
+ $ git send-email --cover-letter --cover-from-description=auto --to <mailing-list-address> -M <ref-branch>
See the `git send-email manual page <https://git-scm.com/docs/git-send-email>`__
for details.
@@ -517,7 +517,7 @@ author name. The following will ensure that your e-mails have an additional
maintainers accepting your patches don't have to fix commit author information
manually::
- git config --global sendemail.from "linus.torvalds@kernel.org"
+ $ git config --global sendemail.from "linus.torvalds@kernel.org"
The ``sendemail.from`` should match your ``user.email`` setting,
which appears in the ``Signed-off-by`` line of your commits.
@@ -530,12 +530,12 @@ with ``git send-email``, you can use Git configuration settings.
- To set the right mailing list address for a given repository::
- git config --local sendemail.to openembedded-devel@lists.openembedded.org
+ $ git config --local sendemail.to openembedded-devel@lists.openembedded.org
- If the mailing list requires a subject prefix for the layer
(this only works when the repository only contains one layer)::
- git config --local format.subjectprefix "meta-something][PATCH"
+ $ git config --local format.subjectprefix "meta-something][PATCH"
Using Scripts to Push a Change Upstream and Request a Pull
==========================================================
@@ -597,7 +597,7 @@ have been followed:
enter the following command to bring up a short list of all
commits against a specific file::
- git shortlog -- filename
+ $ git shortlog -- filename
Just provide the name of the file for which you are interested. The
information returned is not ordered by history but does include a
@@ -719,7 +719,7 @@ follows:
``git format-patch``, for example to submit a patch to the
"&DISTRO_NAME_NO_CAP_MINUS_ONE;" branch use::
- git format-patch --subject-prefix='&DISTRO_NAME_NO_CAP_MINUS_ONE;][PATCH' ...
+ $ git format-patch --subject-prefix='&DISTRO_NAME_NO_CAP_MINUS_ONE;][PATCH' ...
Taking Patch Review into Account
================================
@@ -745,7 +745,7 @@ without the reported issues.
A single patch can be amended using ``git commit --amend``, and multiple
patches can be easily reworked and reordered through an interactive Git rebase::
- git rebase -i <ref-branch>
+ $ git rebase -i <ref-branch>
See `this tutorial <https://hackernoon.com/beginners-guide-to-interactive-rebasing-346a3f9c3a6d>`__
for practical guidance about using Git interactive rebasing.
@@ -755,7 +755,7 @@ sending the revised patch to mark the new iteration as ``[PATCH v2]``,
``[PATCH v3]``, etc as appropriate. This can be done by passing the ``-v``
argument to ``git format-patch`` with a version number::
- git format-patch -v2 <ref-branch>
+ $ git format-patch -v2 <ref-branch>
After generating updated patches (v2, v3, and so on) via ``git
diff --git a/documentation/dev-manual/creating-fragments.rst b/documentation/dev-manual/creating-fragments.rst
index 8dabd599f13f..cd87341e9a51 100644
--- a/documentation/dev-manual/creating-fragments.rst
+++ b/documentation/dev-manual/creating-fragments.rst
@@ -86,7 +86,7 @@ For now, our fragment exists and is listed by the
enable this fragment, use the :ref:`ref-bitbake-config-build-enable-fragment`
command::
- bitbake-config-build enable-fragment meta-custom/custom-fragment
+ $ bitbake-config-build enable-fragment meta-custom/custom-fragment
.. note::
@@ -143,4 +143,4 @@ configuration file:
You can then use the :ref:`ref-bitbake-config-build-enable-fragment` command to
set a value to the ``CUSTOM_VARIABLE`` variable::
- bitbake-config-build enable-fragment custom-builtin-fragment/somevalue
+ $ bitbake-config-build enable-fragment custom-builtin-fragment/somevalue
diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst
index 4995ba73f06b..0f6e9d1d7e85 100644
--- a/documentation/dev-manual/debugging.rst
+++ b/documentation/dev-manual/debugging.rst
@@ -821,7 +821,6 @@ missing dependency clearly visible at the end::
^
compilation terminated.
make: *** [tools/snep-send.o] Error 1
- $
Creating a Patch for the Fix
diff --git a/documentation/dev-manual/devtool.rst b/documentation/dev-manual/devtool.rst
index 242ea9dd9942..471134da8629 100644
--- a/documentation/dev-manual/devtool.rst
+++ b/documentation/dev-manual/devtool.rst
@@ -548,7 +548,7 @@ the two modes:
- To work on the source code of a recipe another instance of VSCode is
started in the recipe's workspace. Example::
- code build/workspace/sources/my-recipe
+ $ code build/workspace/sources/my-recipe
This instance of VSCode uses plugins that are useful for the development
of the application. ``devtool ide-sdk`` generates the necessary
@@ -720,9 +720,9 @@ the two modes:
VSCode. First of all we need a folder containing a CMake project.
For this example, let's create a CMake project and start VSCode::
- mkdir kit-test
- echo "project(foo VERSION 1.0)" > kit-test/CMakeLists.txt
- code kit-test
+ $ mkdir kit-test
+ $ echo "project(foo VERSION 1.0)" > kit-test/CMakeLists.txt
+ $ code kit-test
If there is a CMake project in the workspace, cross-compilation is
supported:
diff --git a/documentation/dev-manual/disk-space.rst b/documentation/dev-manual/disk-space.rst
index 5516f793e301..ee02b267081c 100644
--- a/documentation/dev-manual/disk-space.rst
+++ b/documentation/dev-manual/disk-space.rst
@@ -33,7 +33,7 @@ disk space. However, only the most recent ones are likely to be reused.
The following command is a quick way to purge all the cache files which
haven't been used for a least a specified number of days::
- find build/sstate-cache -type f -mtime +$DAYS -delete
+ $ find build/sstate-cache -type f -mtime +$DAYS -delete
The above command relies on the fact that BitBake touches the sstate cache
files as it accesses them, when it has write access to the cache.
@@ -49,7 +49,7 @@ requires a full build environment to be available and doesn't work well
covering multiple releases. It won't work either on limited environments
such as BSD based NAS::
- sstate-cache-management.py --remove-duplicated --cache-dir=sstate-cache
+ $ sstate-cache-management.py --remove-duplicated --cache-dir=sstate-cache
This command will ask you to confirm the deletions it identifies.
Run ``sstate-cache-management.py`` for more details about this script.
diff --git a/documentation/dev-manual/hashequivserver.rst b/documentation/dev-manual/hashequivserver.rst
index 75b77c30b944..0a67e79b66bc 100644
--- a/documentation/dev-manual/hashequivserver.rst
+++ b/documentation/dev-manual/hashequivserver.rst
@@ -22,7 +22,7 @@ the :term:`BitBake` repository, which can be found :oe_git:`here </bitbake>`.
To start a basic Hash Equivalence server, one could simply run::
- ./bin/bitbake-hashserv
+ $ ./bin/bitbake-hashserv
This will take all of the default options of the script, which are already
sufficient to start a local server.
diff --git a/documentation/dev-manual/limiting-resources.rst b/documentation/dev-manual/limiting-resources.rst
index 892b0069accf..93c20c44c36e 100644
--- a/documentation/dev-manual/limiting-resources.rst
+++ b/documentation/dev-manual/limiting-resources.rst
@@ -104,7 +104,7 @@ details.
#. Then, start a heavy-load build, for example::
- bitbake virtual/kernel -c compile -f
+ $ bitbake virtual/kernel -c compile -f
You can stop the build at anytime with Control + C.
diff --git a/documentation/dev-manual/new-recipe.rst b/documentation/dev-manual/new-recipe.rst
index f43fc2be3f4c..a23a796f5a40 100644
--- a/documentation/dev-manual/new-recipe.rst
+++ b/documentation/dev-manual/new-recipe.rst
@@ -106,19 +106,19 @@ Here are some syntax examples:
- Use this syntax to generate a recipe based on source. Once generated,
the recipe resides in the existing source code layer::
- recipetool create -o OUTFILE source
+ $ recipetool create -o OUTFILE source
- Use this syntax to generate a recipe using code that
you extract from source. The extracted code is placed in its own layer
defined by :term:`EXTERNALSRC`::
- recipetool create -o OUTFILE -x EXTERNALSRC source
+ $ recipetool create -o OUTFILE -x EXTERNALSRC source
- Use this syntax to generate a recipe based on source. The options
direct ``recipetool`` to generate debugging information. Once generated,
the recipe resides in the existing source code layer::
- recipetool create -d -o OUTFILE source
+ $ recipetool create -d -o OUTFILE source
Locating and Using a Similar Recipe
-----------------------------------
diff --git a/documentation/dev-manual/packages.rst b/documentation/dev-manual/packages.rst
index 35a9a0a30913..380d806be041 100644
--- a/documentation/dev-manual/packages.rst
+++ b/documentation/dev-manual/packages.rst
@@ -176,7 +176,7 @@ work against a common, shared package feed, you have a single PR Service
running and it is connected to each building system. For this scenario,
you need to start the PR Service using the ``bitbake-prserv`` command::
- bitbake-prserv --host ip --port port --start
+ $ bitbake-prserv --host ip --port port --start
In addition to
hand-starting the service, you need to update the
diff --git a/documentation/dev-manual/python-development-shell.rst b/documentation/dev-manual/python-development-shell.rst
index 07563043232c..034100ae8799 100644
--- a/documentation/dev-manual/python-development-shell.rst
+++ b/documentation/dev-manual/python-development-shell.rst
@@ -25,7 +25,6 @@ functions::
pydevshell> d.delVar("FOO")
pydevshell> d.getVar("FOO")
pydevshell> bb.build.exec_func("do_unpack", d)
- pydevshell>
See the ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:functions you can call from within python`"
section in the BitBake User Manual for details about available functions.
diff --git a/documentation/dev-manual/qemu.rst b/documentation/dev-manual/qemu.rst
index 514a72fc528a..6d092b2d2034 100644
--- a/documentation/dev-manual/qemu.rst
+++ b/documentation/dev-manual/qemu.rst
@@ -65,7 +65,7 @@ available. Follow these general steps to run QEMU:
initializes the toolchain. For example, the following commands run
the initialization script from the default ``poky_sdk`` directory::
- . poky_sdk/environment-setup-core2-64-poky-linux
+ $ . poky_sdk/environment-setup-core2-64-poky-linux
#. *Ensure the Artifacts are in Place:* You need to be sure you have a
pre-built kernel that will boot in QEMU. You also need the target
@@ -227,15 +227,15 @@ using an NFS server.
- To start the NFS share::
- runqemu-export-rootfs start file-system-location
+ $ runqemu-export-rootfs start file-system-location
- To stop the NFS share::
- runqemu-export-rootfs stop file-system-location
+ $ runqemu-export-rootfs stop file-system-location
- To restart the NFS share::
- runqemu-export-rootfs restart file-system-location
+ $ runqemu-export-rootfs restart file-system-location
QEMU CPU Compatibility Under KVM
================================
diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst
index c7d0fe3dab8d..73b7d9501ae4 100644
--- a/documentation/dev-manual/start.rst
+++ b/documentation/dev-manual/start.rst
@@ -423,7 +423,7 @@ your Yocto Project build host:
replace the PackageFamilyName and your user on the following path
to find your VHDX file::
- ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\
+ C:\WINDOWS\system32> ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState
Mode LastWriteTime Length Name
-a---- 3/14/2020 9:52 PM 57418973184 ext4.vhdx
diff --git a/documentation/dev-manual/wayland.rst b/documentation/dev-manual/wayland.rst
index 5e333b6265f4..3e1280943bf9 100644
--- a/documentation/dev-manual/wayland.rst
+++ b/documentation/dev-manual/wayland.rst
@@ -80,9 +80,9 @@ the CLI, you need to do the following after your image is built:
#. Run these commands to export ``XDG_RUNTIME_DIR``::
- mkdir -p /tmp/$USER-weston
- chmod 0700 /tmp/$USER-weston
- export XDG_RUNTIME_DIR=/tmp/$USER-weston
+ $ mkdir -p /tmp/$USER-weston
+ $ chmod 0700 /tmp/$USER-weston
+ $ export XDG_RUNTIME_DIR=/tmp/$USER-weston
#. Launch Weston in the shell::
diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst
index fe2e42265f9f..17b7dbac928f 100644
--- a/documentation/kernel-dev/common.rst
+++ b/documentation/kernel-dev/common.rst
@@ -75,7 +75,6 @@ section:
$ bitbake-layers create-layer ../layers/meta-mylayer
NOTE: Starting bitbake server...
Add your new layer with 'bitbake-layers add-layer ../layers/meta-mylayer'
- $
.. note::
@@ -98,7 +97,6 @@ section:
$ cd bitbake-builds/build
$ bitbake-layers add-layer ../../meta-mylayer
NOTE: Starting bitbake server...
- $
#. *Build the Clean Image:* The final step in preparing to work on the
kernel is to build an initial image using ``bitbake``::
@@ -194,7 +192,6 @@ section:
$ cd bitbake-builds/build
$ bitbake-layers add-layer ../../meta-mylayer
NOTE: Starting bitbake server ...
- $
#. *Create a Local Copy of the Kernel Git Repository:* You can find Git
repositories of supported Yocto Project kernels organized under
diff --git a/documentation/migration-guides/migration-2.1.rst b/documentation/migration-guides/migration-2.1.rst
index 473dd10ff121..987464f4d77f 100644
--- a/documentation/migration-guides/migration-2.1.rst
+++ b/documentation/migration-guides/migration-2.1.rst
@@ -46,8 +46,8 @@ not specify the final expand parameter to calls that do specify the
parameter. You can run the following ``sed`` command at the base of a
layer to make this change::
- sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *`
- sed -e 's:\(\.getVarFlag([^,()]*,[^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *`
+ $ sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *`
+ $ sed -e 's:\(\.getVarFlag([^,()]*,[^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *`
.. note::
diff --git a/documentation/migration-guides/migration-2.5.rst b/documentation/migration-guides/migration-2.5.rst
index 8e182cd2bc4a..70946b5e11b4 100644
--- a/documentation/migration-guides/migration-2.5.rst
+++ b/documentation/migration-guides/migration-2.5.rst
@@ -138,11 +138,11 @@ BitBake Changes
:ref:`ref-classes-archiver` classes). There is a BitBake option to complete this for
any arbitrary task. For example::
- bitbake <target> -c fetchall
+ $ bitbake <target> -c fetchall
should now be replaced with::
- bitbake <target> --runall=fetch
+ $ bitbake <target> --runall=fetch
.. _migration-2.5-python-and-python3-changes:
diff --git a/documentation/migration-guides/migration-4.0.rst b/documentation/migration-guides/migration-4.0.rst
index c8c2b856d91c..31ce15a9cafc 100644
--- a/documentation/migration-guides/migration-4.0.rst
+++ b/documentation/migration-guides/migration-4.0.rst
@@ -256,7 +256,7 @@ Miscellaneous changes
- The Python development shell (previously known as ``devpyshell``) feature has been
renamed to ``pydevshell``. To start it you should now run::
- bitbake <target> -c pydevshell
+ $ bitbake <target> -c pydevshell
- The ``packagegroups-core-full-cmdline-libs`` packagegroup is no longer produced, as
libraries should normally be brought in via dependencies. If you have any references
diff --git a/documentation/migration-guides/migration-5.3.rst b/documentation/migration-guides/migration-5.3.rst
index 38c7d6771667..e5521d94b59f 100644
--- a/documentation/migration-guides/migration-5.3.rst
+++ b/documentation/migration-guides/migration-5.3.rst
@@ -83,16 +83,16 @@ How to make those adjustments without tedious manual editing
The following sed command can be used to remove S = "${WORKDIR}/git
across a whole layer::
- sed -i "/^S = \"\${WORKDIR}\/git\"/d" `find . -name '*.bb' -o -name '*.inc' -o -name '*.bbclass'`
+ $ sed -i "/^S = \"\${WORKDIR}\/git\"/d" `find . -name '*.bb' -o -name '*.inc' -o -name '*.bbclass'`
Then, the following command can tweak the remaining :term:`S` assignments to
refer to :term:`UNPACKDIR` instead of :term:`WORKDIR`::
- sed -i "s/^S = \"\${WORKDIR}\//S = \"\${UNPACKDIR}\//g" `find . -name '*.bb' -o -name '*.inc' -o -name '*.bbclass'`
+ $ sed -i "s/^S = \"\${WORKDIR}\//S = \"\${UNPACKDIR}\//g" `find . -name '*.bb' -o -name '*.inc' -o -name '*.bbclass'`
The first change can introduce a lot of consecutive empty lines, so those can be removed with::
- sed -i -z -E 's/([ \t\f\v\r]*\n){3,}/\n\n/g' `find . -name '*.bb' -o -name '*.inc'`
+ $ sed -i -z -E 's/([ \t\f\v\r]*\n){3,}/\n\n/g' `find . -name '*.bb' -o -name '*.inc'`
BitBake Git fetcher ``tag`` parameter
@@ -312,11 +312,11 @@ The following classes have been removed in this release:
#. Use the specific FIT image recipe rather than the base kernel recipe.
For example, instead of::
- bitbake linux-yocto
+ $ bitbake linux-yocto
the FIT image is now build by::
- bitbake linux-yocto-fitimage
+ $ bitbake linux-yocto-fitimage
For custom kernel recipes, creating a corresponding custom FIT image recipe
is usually a good approach.
diff --git a/documentation/migration-guides/release-notes-4.2.rst b/documentation/migration-guides/release-notes-4.2.rst
index f50ef180ac66..3586622edca9 100644
--- a/documentation/migration-guides/release-notes-4.2.rst
+++ b/documentation/migration-guides/release-notes-4.2.rst
@@ -173,7 +173,7 @@ New Features / Enhancements in 4.2
command, which allowed to spot and fix a regression in the
``quilt`` ptest::
- yocto_testresults_query.py regression-report 4.2_M1 4.2_M2
+ $ yocto_testresults_query.py regression-report 4.2_M1 4.2_M2
See this `blog post about regression detection
<https://bootlin.com/blog/continuous-integration-in-yocto-improving-the-regressions-detection/>`__.
diff --git a/documentation/migration-guides/release-notes-5.3.rst b/documentation/migration-guides/release-notes-5.3.rst
index 8a564716f319..311a9a94718a 100644
--- a/documentation/migration-guides/release-notes-5.3.rst
+++ b/documentation/migration-guides/release-notes-5.3.rst
@@ -466,7 +466,7 @@ New Features / Enhancements in |yocto-ver|
- The script can now run compressed images with snapshot mode. For
example, with :term:`IMAGE_FSTYPES` containing ``ext4.zst``, you can run::
- runqemu snapshot ext4.zst <image-recipe>
+ $ runqemu snapshot ext4.zst <image-recipe>
- Add support for the ``erofs`` filesystem.
diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index cbad93e8a38d..7b67ae8cc6b3 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -366,7 +366,7 @@ To do so, create a recipe for your program, for example using
make it inherit the :ref:`ref-classes-cargo` and
:ref:`ref-classes-cargo-update-recipe-crates` and run::
- bitbake -c update_crates recipe
+ $ bitbake -c update_crates recipe
This creates a ``recipe-crates.inc`` file that you can include in your
recipe::
@@ -1372,7 +1372,7 @@ The simplest example for building a FIT image is to add::
to the machine :term:`configuration file` and to execute::
- bitbake linux-yocto-fitimage
+ $ bitbake linux-yocto-fitimage
This results in a ``fitImage`` file deployed to the :term:`DEPLOY_DIR_IMAGE`
directory and a ``linux-yocto-fitimage`` package which can be installed.
@@ -1386,7 +1386,7 @@ lines to the machine configuration file::
The FIT image, this time including the RT kernel, is built again by calling::
- bitbake linux-yocto-fitimage
+ $ bitbake linux-yocto-fitimage
For other kernels provided by other layers, the same approach would work.
However, it is usually more intuitive to add a custom FIT image recipe next to
@@ -3864,7 +3864,7 @@ build.
Example usage::
- bitbake -c generate_vex openssl
+ $ bitbake -c generate_vex openssl
.. _ref-classes-waf:
diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst
index d2e80611a994..4aa95d8e0499 100644
--- a/documentation/ref-manual/devtool-reference.rst
+++ b/documentation/ref-manual/devtool-reference.rst
@@ -461,7 +461,6 @@ Here is an example that resets the workspace directory that contains the
$ devtool reset mtr
NOTE: Cleaning sysroot for recipe mtr...
NOTE: Leaving source tree /home/scottrif/bitbake-builds/build/workspace/sources/mtr as-is; if you no longer need it then please delete it manually
- $
.. _devtool-finish-working-on-a-recipe:
@@ -634,7 +633,6 @@ to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory::
$ devtool status
mtr:/home/scottrif/bitbake-builds/build/workspace/sources/mtr (/home/scottrif/bitbake-builds/build/workspace/recipes/mtr/mtr_0.86.bb)
- $
.. _devtool-search-for-available-target-recipes:
diff --git a/documentation/ref-manual/fragments.rst b/documentation/ref-manual/fragments.rst
index e5cd9fc436c1..c5640b826eae 100644
--- a/documentation/ref-manual/fragments.rst
+++ b/documentation/ref-manual/fragments.rst
@@ -72,25 +72,25 @@ command, you can determine which fragments can be enabled for your build.
For example, the following command would enable the
:ref:`ref-fragments-core-yocto-sstate-mirror-cdn` fragment::
- bitbake-config-build enable-fragment core/yocto/sstate-mirror-cdn
+ $ bitbake-config-build enable-fragment core/yocto/sstate-mirror-cdn
.. note::
Multiple fragments can be enabled at once with the same command::
- bitbake-config-build enable-fragment <fragment1> <fragment2> ...
+ $ bitbake-config-build enable-fragment <fragment1> <fragment2> ...
:term:`Built-in fragments <Built-in Fragment>` are enabled the same way, and
their values are defined from the command-line directly. For example, the
following command sets the ``qemuarm64`` :term:`MACHINE` through the
:ref:`ref-fragments-builtin-core-machine` fragment::
- bitbake-config-build enable-fragment machine/qemuarm64
+ $ bitbake-config-build enable-fragment machine/qemuarm64
This fragment can be overridden from the command-line by setting it to another
value, for example::
- bitbake-config-build enable-fragment machine/qemux86-64
+ $ bitbake-config-build enable-fragment machine/qemux86-64
In the above example, the new value of :term:`MACHINE` is now equal to
``qemux86-64``.
@@ -118,18 +118,18 @@ command. The list of enabled fragments can be obtained with
For example, the following command disables the
:ref:`ref-fragments-core-yocto-sstate-mirror-cdn` fragment::
- bitbake-config-build disable-fragment core/yocto/sstate-mirror-cdn
+ $ bitbake-config-build disable-fragment core/yocto/sstate-mirror-cdn
Likewise, :term:`Built-in Fragments <Built-in Fragment>` are disabled the
same way. For example, this would disable the ``machine/qemuarm64`` fragment::
- bitbake-config-build disable-fragment machine/qemuarm64
+ $ bitbake-config-build disable-fragment machine/qemuarm64
.. note::
Multiple fragments can be disabled at once with the same command::
- bitbake-config-build disable-fragment <fragment1> <fragment2>
+ $ bitbake-config-build disable-fragment <fragment1> <fragment2>
.. _ref-bitbake-config-build-disable-all-fragments:
@@ -142,7 +142,7 @@ currently enabled fragments. The list of enabled fragments can be obtained with
This command is run without arguments::
- bitbake-config-build disable-all-fragments
+ $ bitbake-config-build disable-all-fragments
Core Fragments
==============
diff --git a/documentation/ref-manual/qa-checks.rst b/documentation/ref-manual/qa-checks.rst
index 8e1ce4438c79..14e3632ce6b8 100644
--- a/documentation/ref-manual/qa-checks.rst
+++ b/documentation/ref-manual/qa-checks.rst
@@ -573,14 +573,14 @@ patched file to still compile without errors.
Use the ``devtool`` command as explained by the warning. First, unpack the
source into devtool workspace::
- devtool modify <recipe>
+ $ devtool modify <recipe>
This will apply all of the patches, and create new commits out of them in
the workspace --- with the patch context updated.
Then, replace the patches in the recipe layer::
- devtool finish --force-patch-refresh <recipe> <layer_path>
+ $ devtool finish --force-patch-refresh <recipe> <layer_path>
The patch updates then need be reviewed (preferably with a side-by-side diff
tool) to ensure they are indeed doing the right thing i.e.:
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 2d0f6bd3f8cf..3c921c3f8087 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -967,7 +967,7 @@ system and gives an overview of their function and contents.
Use the following format to export the variable to the BitBake
environment::
- export BBSERVER=localhost:$port
+ $ export BBSERVER=localhost:$port
By default, :term:`BBSERVER` also appears in :term:`BB_BASEHASH_IGNORE_VARS`.
Consequently, :term:`BBSERVER` is excluded from checksum and dependency
@@ -9357,7 +9357,7 @@ system and gives an overview of their function and contents.
You can obtain the signature of all the tasks for the recipe ``bc`` using::
- bitbake -S none bc
+ $ bitbake -S none bc
Then you can look at files in ``build/tmp/stamps/<arch>/bc`` and look for
files like: ``<PV>.do_compile.sigdata.09772aa4532512baf96d433484f27234d4b7c11dd9cda0d6f56fa1b7ce6f25f0``.
@@ -9514,7 +9514,7 @@ system and gives an overview of their function and contents.
This file requires permissions set to ``400`` or ``600`` to prevent
other users from reading the file::
- chmod 600 "$HOME/.netrc"
+ $ chmod 600 "$HOME/.netrc"
Another method to configure the username and password is from the URL
in :term:`SOURCE_MIRROR_URL` directly, with the ``user`` and ``pswd``
diff --git a/documentation/test-manual/reproducible-builds.rst b/documentation/test-manual/reproducible-builds.rst
index 892f7b9c8f0d..4e39cf3f79d8 100644
--- a/documentation/test-manual/reproducible-builds.rst
+++ b/documentation/test-manual/reproducible-builds.rst
@@ -89,7 +89,7 @@ it always depends upon the paths it is built in.
To run our automated selftest, as we use in our CI on the Autobuilder, you can
run::
- oe-selftest -r reproducible.ReproducibleTests.test_reproducible_builds
+ $ oe-selftest -r reproducible.ReproducibleTests.test_reproducible_builds
This defaults to including a ``world`` build so, if other layers are added, it
would also run the tests for recipes in the additional layers. Different build
diff --git a/documentation/test-manual/runtime-testing.rst b/documentation/test-manual/runtime-testing.rst
index 55c19900f439..5a7193f015b4 100644
--- a/documentation/test-manual/runtime-testing.rst
+++ b/documentation/test-manual/runtime-testing.rst
@@ -326,7 +326,7 @@ You can start the tests automatically or manually:
Next, build your image. If the image successfully builds, the
tests run::
- bitbake core-image-sato
+ $ bitbake core-image-sato
- *Manually running tests:* To manually run the tests, first globally
inherit the :ref:`ref-classes-testimage` class by editing your
@@ -336,7 +336,7 @@ You can start the tests automatically or manually:
Next, use BitBake to run the tests::
- bitbake -c testimage image
+ $ bitbake -c testimage image
All test files reside in ``meta/lib/oeqa/runtime/cases`` in
:term:`OpenEmbedded-Core (OE-Core)`. A test name maps
--
2.50.0.173.g8b6f19ccfc3a
^ permalink raw reply related [flat|nested] 23+ messages in thread* Re: [docs] [PATCH v2 3/8] docs: show a prompt on commands the reader is meant to type
2026-09-22 18:32 ` [PATCH v2 3/8] docs: show a prompt on commands the reader is meant to type Trevor Woerner
@ 2026-09-23 10:49 ` Quentin Schulz
2026-09-24 15:59 ` Trevor Woerner
0 siblings, 1 reply; 23+ messages in thread
From: Quentin Schulz @ 2026-09-23 10:49 UTC (permalink / raw)
To: twoerner, docs
Hi Trevor,
On 9/22/26 8:32 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> Most command blocks in the manuals start their lines with "$", but a
> scattering of them do not, and those read as a file listing rather than
> as something to run. Give them the prompt the surrounding pages already
> use.
>
> Transcripts take a prompt on their opening line alone. Two things that
> matter only once a line is a command go with that: a bare "$" at the end,
> the prompt returning after the command finished, and a trailing "\" on a
> Windows path, which a shell reads as a continuation into the output.
>
> AI-Generated: codex/claude-opus 5 (xhigh)
> Signed-off-by: Trevor Woerner <twoerner@gmail.com>
> ---
[...]
> diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst
> index c7d0fe3dab8d..73b7d9501ae4 100644
> --- a/documentation/dev-manual/start.rst
> +++ b/documentation/dev-manual/start.rst
> @@ -423,7 +423,7 @@ your Yocto Project build host:
> replace the PackageFamilyName and your user on the following path
> to find your VHDX file::
>
> - ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\
> + C:\WINDOWS\system32> ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState
> Mode LastWriteTime Length Name
> -a---- 3/14/2020 9:52 PM 57418973184 ext4.vhdx
>
> diff --git a/documentation/dev-manual/wayland.rst b/documentation/dev-manual/wayland.rst
> index 5e333b6265f4..3e1280943bf9 100644
> --- a/documentation/dev-manual/wayland.rst
> +++ b/documentation/dev-manual/wayland.rst
> @@ -80,9 +80,9 @@ the CLI, you need to do the following after your image is built:
>
> #. Run these commands to export ``XDG_RUNTIME_DIR``::
>
> - mkdir -p /tmp/$USER-weston
> - chmod 0700 /tmp/$USER-weston
> - export XDG_RUNTIME_DIR=/tmp/$USER-weston
> + $ mkdir -p /tmp/$USER-weston
> + $ chmod 0700 /tmp/$USER-weston
> + $ export XDG_RUNTIME_DIR=/tmp/$USER-weston
>
This is to be run on the target as far as I could tell, do we also plan
on using $ without a user@host:path$ for target commands as well as the
ones the user is supposed to run on the build machine?
> #. Launch Weston in the shell::
>
Right under this context, there's a command to run which doesn't have
the prompt and needs one.
Cheers,
Quentin
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [docs] [PATCH v2 3/8] docs: show a prompt on commands the reader is meant to type
2026-09-23 10:49 ` [docs] " Quentin Schulz
@ 2026-09-24 15:59 ` Trevor Woerner
0 siblings, 0 replies; 23+ messages in thread
From: Trevor Woerner @ 2026-09-24 15:59 UTC (permalink / raw)
To: Quentin Schulz; +Cc: docs
On Wed 2026-09-23 @ 12:49:12 PM, Quentin Schulz wrote:
> Hi Trevor,
>
> On 9/22/26 8:32 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> > Most command blocks in the manuals start their lines with "$", but a
> > scattering of them do not, and those read as a file listing rather than
> > as something to run. Give them the prompt the surrounding pages already
> > use.
> >
> > Transcripts take a prompt on their opening line alone. Two things that
> > matter only once a line is a command go with that: a bare "$" at the end,
> > the prompt returning after the command finished, and a trailing "\" on a
> > Windows path, which a shell reads as a continuation into the output.
> >
> > AI-Generated: codex/claude-opus 5 (xhigh)
> > Signed-off-by: Trevor Woerner <twoerner@gmail.com>
> > ---
> [...]
> > diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst
> > index c7d0fe3dab8d..73b7d9501ae4 100644
> > --- a/documentation/dev-manual/start.rst
> > +++ b/documentation/dev-manual/start.rst
> > @@ -423,7 +423,7 @@ your Yocto Project build host:
> > replace the PackageFamilyName and your user on the following path
> > to find your VHDX file::
> > - ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState\
> > + C:\WINDOWS\system32> ls C:\Users\myuser\AppData\Local\Packages\CanonicalGroupLimited.UbuntuonWindows_79abcdefgh\LocalState
> > Mode LastWriteTime Length Name
> > -a---- 3/14/2020 9:52 PM 57418973184 ext4.vhdx
> > diff --git a/documentation/dev-manual/wayland.rst b/documentation/dev-manual/wayland.rst
> > index 5e333b6265f4..3e1280943bf9 100644
> > --- a/documentation/dev-manual/wayland.rst
> > +++ b/documentation/dev-manual/wayland.rst
> > @@ -80,9 +80,9 @@ the CLI, you need to do the following after your image is built:
> > #. Run these commands to export ``XDG_RUNTIME_DIR``::
> > - mkdir -p /tmp/$USER-weston
> > - chmod 0700 /tmp/$USER-weston
> > - export XDG_RUNTIME_DIR=/tmp/$USER-weston
> > + $ mkdir -p /tmp/$USER-weston
> > + $ chmod 0700 /tmp/$USER-weston
> > + $ export XDG_RUNTIME_DIR=/tmp/$USER-weston
>
> This is to be run on the target as far as I could tell, do we also plan on
> using $ without a user@host:path$ for target commands as well as the ones
> the user is supposed to run on the build machine?
I like the preamble; i'll change it.
> > #. Launch Weston in the shell::
>
> Right under this context, there's a command to run which doesn't have the
> prompt and needs one.
Good catch, thanks.
> Cheers,
> Quentin
^ permalink raw reply [flat|nested] 23+ messages in thread
* [PATCH v2 4/8] docs: write an elided passage as a comment
2026-09-22 18:32 [PATCH v2 0/8] docs: editorial repairs to the examples Trevor Woerner
` (2 preceding siblings ...)
2026-09-22 18:32 ` [PATCH v2 3/8] docs: show a prompt on commands the reader is meant to type Trevor Woerner
@ 2026-09-22 18:32 ` Trevor Woerner
2026-09-23 10:50 ` [docs] " Quentin Schulz
2026-09-22 18:32 ` [PATCH v2 5/8] docs: mark the placeholders in examples Trevor Woerner
` (3 subsequent siblings)
7 siblings, 1 reply; 23+ messages in thread
From: Trevor Woerner @ 2026-09-22 18:32 UTC (permalink / raw)
To: docs
Several examples stand in for code they leave out with a bare "..." or a
column of dots on a line of their own. Neither is valid in the language
around it, so the example cannot say what language it is without also
saying something false about itself.
Use a comment instead, in whatever language the example is written in,
and say in it what was left out. The ellipsis on its own raises a
question - what is missing here, and does it matter? - that a few words
can answer at no cost to the reader.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
changes in v2:
- rebased on master-next; no other change
---
documentation/bsp-manual/bsp.rst | 4 +---
documentation/kernel-dev/common.rst | 14 +++++++-------
documentation/migration-guides/migration-3.2.rst | 2 +-
documentation/overview-manual/concepts.rst | 2 +-
4 files changed, 10 insertions(+), 12 deletions(-)
diff --git a/documentation/bsp-manual/bsp.rst b/documentation/bsp-manual/bsp.rst
index dd613326942a..93af13f789d1 100644
--- a/documentation/bsp-manual/bsp.rst
+++ b/documentation/bsp-manual/bsp.rst
@@ -561,9 +561,7 @@ statements from the Raspberry Pi ``conf/layer.conf`` file::
# Additional license directories.
LICENSE_PATH += "${LAYERDIR}/files/custom-licenses"
- .
- .
- .
+ # ... and so on for the rest of the file ...
This file simply makes :term:`BitBake` aware of the recipes and configuration
directories. The file must exist so that the OpenEmbedded build system can
diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst
index 17b7dbac928f..555aadc76a6c 100644
--- a/documentation/kernel-dev/common.rst
+++ b/documentation/kernel-dev/common.rst
@@ -681,9 +681,9 @@ the ":ref:`kernel-dev/common:getting ready to develop using ``devtool```" Sectio
printk("*************************************\n");
if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
- .
- .
- .
+ /*
+ * ... remaining code unchanged ...
+ */
#. *Build the Updated Kernel Source:* To build the updated kernel
source, use ``devtool``::
@@ -817,9 +817,9 @@ Section.
printk("*************************************\n");
if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
- .
- .
- .
+ /*
+ * ... remaining code unchanged ...
+ */
#. *Stage and Commit Your Changes:* Use standard Git commands to stage
and commit the changes you just made::
@@ -1598,7 +1598,7 @@ looks much like the one provided with the ``hello-mod`` template::
modules_install:
$(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
- ...
+ # ... remaining rules ...
The important point to note here is the :term:`KERNEL_SRC` variable. The
:ref:`ref-classes-module` class sets this variable and the :term:`KERNEL_PATH`
diff --git a/documentation/migration-guides/migration-3.2.rst b/documentation/migration-guides/migration-3.2.rst
index 5cb958e75047..a037e6f51c53 100644
--- a/documentation/migration-guides/migration-3.2.rst
+++ b/documentation/migration-guides/migration-3.2.rst
@@ -100,7 +100,7 @@ This also applies when conditionally adding packages to :term:`PACKAGES` where
those packages have dependencies, for example (from the ``alsa-plugins`` recipe)::
PACKAGES += "${@bb.utils.contains('PACKAGECONFIG', 'pulseaudio', 'alsa-plugins-pulseaudio-conf', '', d)}"
- ...
+ # ... elsewhere in the same recipe ...
RDEPENDS_${PN}-pulseaudio-conf += "\
${MLPREFIX}libasound-module-conf-pulse \
${MLPREFIX}libasound-module-ctl-pulse \
diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst
index 3bf672c78387..1e9c6d3a6f0b 100644
--- a/documentation/overview-manual/concepts.rst
+++ b/documentation/overview-manual/concepts.rst
@@ -2193,7 +2193,7 @@ accomplished using fakeroot.
``virtual/fakeroot-native:do_populate_sysroot``, giving the following::
fakeroot do_mytask () {
- ...
+ # ... steps to perform task here ...
}
do_mytask[depends] += "virtual/fakeroot-native:do_populate_sysroot"
--
2.50.0.173.g8b6f19ccfc3a
^ permalink raw reply related [flat|nested] 23+ messages in thread* Re: [docs] [PATCH v2 4/8] docs: write an elided passage as a comment
2026-09-22 18:32 ` [PATCH v2 4/8] docs: write an elided passage as a comment Trevor Woerner
@ 2026-09-23 10:50 ` Quentin Schulz
0 siblings, 0 replies; 23+ messages in thread
From: Quentin Schulz @ 2026-09-23 10:50 UTC (permalink / raw)
To: twoerner, docs
Hi Trevor,
On 9/22/26 8:32 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> Several examples stand in for code they leave out with a bare "..." or a
> column of dots on a line of their own. Neither is valid in the language
> around it, so the example cannot say what language it is without also
> saying something false about itself.
>
> Use a comment instead, in whatever language the example is written in,
> and say in it what was left out. The ellipsis on its own raises a
> question - what is missing here, and does it matter? - that a few words
> can answer at no cost to the reader.
>
> AI-Generated: codex/claude-opus 5 (xhigh)
> Signed-off-by: Trevor Woerner <twoerner@gmail.com>
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
Thanks!
Quentin
^ permalink raw reply [flat|nested] 23+ messages in thread
* [PATCH v2 5/8] docs: mark the placeholders in examples
2026-09-22 18:32 [PATCH v2 0/8] docs: editorial repairs to the examples Trevor Woerner
` (3 preceding siblings ...)
2026-09-22 18:32 ` [PATCH v2 4/8] docs: write an elided passage as a comment Trevor Woerner
@ 2026-09-22 18:32 ` Trevor Woerner
2026-09-23 10:57 ` [docs] " Quentin Schulz
2026-09-22 18:32 ` [PATCH v2 6/8] docs: remove real accounts from the examples Trevor Woerner
` (2 subsequent siblings)
7 siblings, 1 reply; 23+ messages in thread
From: Trevor Woerner @ 2026-09-22 18:32 UTC (permalink / raw)
To: docs
Values the reader is expected to replace are written as though they were
literal. "arch-gdb" reads like a command that exists, a Git SRC_URI
example reads like a URL and a pair of revisions worth copying, and the
git-config examples give an account name and address that are somebody
else's. Put them in the angle brackets the manuals already use for the
purpose.
Two corrections go with them: the directory placeholder in the GDB
example described itself at length rather than naming the thing, and the
smtppass example carried a stray "=". Since git config takes a name and
then a value, that "=" was the value, and the password behind it an
argument git config reads as a pattern.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
changes in v2:
- rebased on master-next; no other change
---
.../contributor-guide/submit-changes.rst | 12 ++++++------
documentation/dev-manual/debugging.rst | 8 ++++----
documentation/migration-guides/migration-5.2.rst | 16 ++++++++--------
documentation/ref-manual/devtool-reference.rst | 2 +-
documentation/ref-manual/variables.rst | 2 +-
5 files changed, 20 insertions(+), 20 deletions(-)
diff --git a/documentation/contributor-guide/submit-changes.rst b/documentation/contributor-guide/submit-changes.rst
index e60f8ca7ace3..a283eb734768 100644
--- a/documentation/contributor-guide/submit-changes.rst
+++ b/documentation/contributor-guide/submit-changes.rst
@@ -62,8 +62,8 @@ on Debian and Ubuntu::
Then, you need to set a name and e-mail address that Git will
use to identify your commits::
- $ git config --global user.name "Ada Lovelace"
- $ git config --global user.email "ada.lovelace@gmail.com"
+ $ git config --global user.name "<name>"
+ $ git config --global user.email "<email>"
By default, Git adds a signature line at the end of patches containing the Git
version. We suggest to remove it as it doesn't add useful information.
@@ -399,8 +399,8 @@ regular STMP server, using a Google Mail account as an example::
$ git config --global sendemail.smtpserver smtp.gmail.com
$ git config --global sendemail.smtpserverport 587
$ git config --global sendemail.smtpencryption tls
- $ git config --global sendemail.smtpuser ada.lovelace@gmail.com
- $ git config --global sendemail.smtppass = XXXXXXXX
+ $ git config --global sendemail.smtpuser <email>
+ $ git config --global sendemail.smtppass <password>
These settings will appear in the ``.gitconfig`` file in your home directory.
@@ -509,7 +509,7 @@ We have a frequent issue with contributors whose patches are received through
a ``From`` field which doesn't match the ``Signed-off-by`` information. Here is
a typical example for people sending from a domain name with :wikipedia:`DMARC`::
- From: "Linus Torvalds via lists.openembedded.org <linus.torvalds=kernel.org@lists.openembedded.org>"
+ From: "xxx via lists.openembedded.org <xxx@lists.openembedded.org>"
This ``From`` field is used by ``git am`` to recreate commits with the right
author name. The following will ensure that your e-mails have an additional
@@ -517,7 +517,7 @@ author name. The following will ensure that your e-mails have an additional
maintainers accepting your patches don't have to fix commit author information
manually::
- $ git config --global sendemail.from "linus.torvalds@kernel.org"
+ $ git config --global sendemail.from "<email>"
The ``sendemail.from`` should match your ``user.email`` setting,
which appears in the ``Signed-off-by`` line of your commits.
diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst
index 0f6e9d1d7e85..8412c997a51e 100644
--- a/documentation/dev-manual/debugging.rst
+++ b/documentation/dev-manual/debugging.rst
@@ -810,7 +810,7 @@ be visible. In this case, there is a missing dependency for the ``neard``
Makefile target. Here is some abbreviated, sample output with the
missing dependency clearly visible at the end::
- i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/scott-lenovo/......
+ i586-poky-linux-gcc -m32 -march=i586 --sysroot=<path/to/sysroot>
.
.
.
@@ -1114,11 +1114,11 @@ debugger.
After running gdbserver on the target, you need to run Gdb on the
host and configure it and connect to the target. Use these commands::
- $ cd directory-holding-the-debugfs-directory
- $ arch-gdb
+ $ cd <debugfs-directory>
+ $ <arch>-gdb
(gdb) set sysroot debugfs
(gdb) set substitute-path /usr/src/debug debugfs/usr/src/debug
- (gdb) target remote IP-of-target:1234
+ (gdb) target remote <IP-of-target>:1234
At this
point, everything should automatically load (i.e. matching binaries,
diff --git a/documentation/migration-guides/migration-5.2.rst b/documentation/migration-guides/migration-5.2.rst
index 77a11fe27047..48f9e7485d93 100644
--- a/documentation/migration-guides/migration-5.2.rst
+++ b/documentation/migration-guides/migration-5.2.rst
@@ -193,9 +193,9 @@ The support for having multiple Git revisions per URL in :term:`SRC_URI` was
removed from BitBake, which means the following syntax is not supported
anymore::
- SRC_URI = "git://some.host/somepath;bareclone=1;branch=branchX,branchY;name=nameX,nameY"
- SRCREV_nameX = "xxxxxxxxxxxxxxxxxxxx"
- SRCREV_nameY = "yyyyyyyyyyyyyyyyyyyy"
+ SRC_URI = "git://<some.host>/<somepath>;bareclone=1;branch=<branchX>,<branchY>;name=<nameX>,<nameY>"
+ SRCREV_<nameX> = "<revisionX>"
+ SRCREV_<nameY> = "<revisionY>"
This was rarely used in the core repositories because it would only ever make
sense for bare clones (the ``bareclone=1`` :term:`SRC_URI` option) where recipes
@@ -205,10 +205,10 @@ places.
If one of your recipes is using this mechanism, you can split the code source
fetching into two separate entries::
- SRC_URI = "git://some.host/somepath;bareclone=1;branch=branchX;name=nameX \
- git://some.host/somepath;bareclone=1;branch=branchY;name=nameY"
- SRCREV_nameX = "xxxxxxxxxxxxxxxxxxxx"
- SRCREV_nameY = "yyyyyyyyyyyyyyyyyyyy"
+ SRC_URI = "git://<some.host>/<somepath>;bareclone=1;branch=<branchX>;name=<nameX> \
+ git://<some.host>/<somepath>;bareclone=1;branch=<branchY>;name=<nameY>"
+ SRCREV_<nameX> = "<revisionX>"
+ SRCREV_<nameY> = "<revisionY>"
Git fetcher: Branch parameter now required in :term:`SRC_URI`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -216,7 +216,7 @@ Git fetcher: Branch parameter now required in :term:`SRC_URI`
The ``branch`` parameter is now required when specifying a Git repository in
:term:`SRC_URI`, for example::
- SRC_URI = "git://some.host/somepath;branch=branchX"
+ SRC_URI = "git://<some.host>/<somepath>;branch=<branchX>"
A missing ``branch`` parameter used to produce a warning, and will now produce
an error.
diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst
index 4aa95d8e0499..62c3b707b9ff 100644
--- a/documentation/ref-manual/devtool-reference.rst
+++ b/documentation/ref-manual/devtool-reference.rst
@@ -474,7 +474,7 @@ This is roughly equivalent to the ``devtool update-recipe`` command followed by
the ``devtool reset`` command. The changes must have been committed to the git
repository created by ``devtool``. Here is an example::
- $ devtool finish recipe /path/to/custom/layer
+ $ devtool finish <recipe> <path/to/custom/layer>
.. _devtool-building-your-recipe:
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 3c921c3f8087..0072992b8597 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -162,7 +162,7 @@ system and gives an overview of their function and contents.
ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is the default.
ARCHIVER_MODE[src] = "configured" # Uses configured source files.
ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and do_patch.
- ARCHIVER_MODE[diff-exclude] ?= "file file ..." # Lists files and directories to exclude from diff.
+ ARCHIVER_MODE[diff-exclude] ?= "<file> <file> ..." # Lists files and directories to exclude from diff.
ARCHIVER_MODE[dumpdata] = "1" # Uses environment data.
ARCHIVER_MODE[recipe] = "1" # Uses recipe and include files.
--
2.50.0.173.g8b6f19ccfc3a
^ permalink raw reply related [flat|nested] 23+ messages in thread* Re: [docs] [PATCH v2 5/8] docs: mark the placeholders in examples
2026-09-22 18:32 ` [PATCH v2 5/8] docs: mark the placeholders in examples Trevor Woerner
@ 2026-09-23 10:57 ` Quentin Schulz
2026-09-24 15:58 ` Trevor Woerner
0 siblings, 1 reply; 23+ messages in thread
From: Quentin Schulz @ 2026-09-23 10:57 UTC (permalink / raw)
To: twoerner, docs
Hi Trevor,
On 9/22/26 8:32 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> Values the reader is expected to replace are written as though they were
> literal. "arch-gdb" reads like a command that exists, a Git SRC_URI
> example reads like a URL and a pair of revisions worth copying, and the
> git-config examples give an account name and address that are somebody
> else's. Put them in the angle brackets the manuals already use for the
> purpose.
>
> Two corrections go with them: the directory placeholder in the GDB
> example described itself at length rather than naming the thing, and the
> smtppass example carried a stray "=". Since git config takes a name and
> then a value, that "=" was the value, and the password behind it an
> argument git config reads as a pattern.
>
> AI-Generated: codex/claude-opus 5 (xhigh)
> Signed-off-by: Trevor Woerner <twoerner@gmail.com>
> ---
> changes in v2:
> - rebased on master-next; no other change
> ---
> .../contributor-guide/submit-changes.rst | 12 ++++++------
> documentation/dev-manual/debugging.rst | 8 ++++----
> documentation/migration-guides/migration-5.2.rst | 16 ++++++++--------
> documentation/ref-manual/devtool-reference.rst | 2 +-
> documentation/ref-manual/variables.rst | 2 +-
> 5 files changed, 20 insertions(+), 20 deletions(-)
>
> diff --git a/documentation/contributor-guide/submit-changes.rst b/documentation/contributor-guide/submit-changes.rst
> index e60f8ca7ace3..a283eb734768 100644
> --- a/documentation/contributor-guide/submit-changes.rst
> +++ b/documentation/contributor-guide/submit-changes.rst
> @@ -62,8 +62,8 @@ on Debian and Ubuntu::
> Then, you need to set a name and e-mail address that Git will
> use to identify your commits::
>
> - $ git config --global user.name "Ada Lovelace"
> - $ git config --global user.email "ada.lovelace@gmail.com"
> + $ git config --global user.name "<name>"
<firstname> <lastname>
maybe? I'm guessing some cultures have other orders, I've seen
<lastname>, <firstname>
a few times.
> + $ git config --global user.email "<email>"
>
> By default, Git adds a signature line at the end of patches containing the Git
> version. We suggest to remove it as it doesn't add useful information.
> @@ -399,8 +399,8 @@ regular STMP server, using a Google Mail account as an example::
> $ git config --global sendemail.smtpserver smtp.gmail.com
Why is this not changed to a placeholder?
> $ git config --global sendemail.smtpserverport 587
> $ git config --global sendemail.smtpencryption tls
> - $ git config --global sendemail.smtpuser ada.lovelace@gmail.com
> - $ git config --global sendemail.smtppass = XXXXXXXX
> + $ git config --global sendemail.smtpuser <email>
> + $ git config --global sendemail.smtppass <password>
It's also optional, in which case you're prompted every time you send a
mail, which I kinda like :)
>
> These settings will appear in the ``.gitconfig`` file in your home directory.
>
> @@ -509,7 +509,7 @@ We have a frequent issue with contributors whose patches are received through
> a ``From`` field which doesn't match the ``Signed-off-by`` information. Here is
> a typical example for people sending from a domain name with :wikipedia:`DMARC`::
>
> - From: "Linus Torvalds via lists.openembedded.org <linus.torvalds=kernel.org@lists.openembedded.org>"
> + From: "xxx via lists.openembedded.org <xxx@lists.openembedded.org>"
Please keep this one (or use an example that exists in the wild, I don't
think Linus sent patches to OE-Core :)) as it is an actual example.
>
> This ``From`` field is used by ``git am`` to recreate commits with the right
> author name. The following will ensure that your e-mails have an additional
> @@ -517,7 +517,7 @@ author name. The following will ensure that your e-mails have an additional
> maintainers accepting your patches don't have to fix commit author information
> manually::
>
> - $ git config --global sendemail.from "linus.torvalds@kernel.org"
> + $ git config --global sendemail.from "<email>"
>
> The ``sendemail.from`` should match your ``user.email`` setting,
> which appears in the ``Signed-off-by`` line of your commits.
> diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst
> index 0f6e9d1d7e85..8412c997a51e 100644
> --- a/documentation/dev-manual/debugging.rst
> +++ b/documentation/dev-manual/debugging.rst
> @@ -810,7 +810,7 @@ be visible. In this case, there is a missing dependency for the ``neard``
> Makefile target. Here is some abbreviated, sample output with the
> missing dependency clearly visible at the end::
>
> - i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/scott-lenovo/......
> + i586-poky-linux-gcc -m32 -march=i586 --sysroot=<path/to/sysroot>
> .
> .
> .
> @@ -1114,11 +1114,11 @@ debugger.
> After running gdbserver on the target, you need to run Gdb on the
> host and configure it and connect to the target. Use these commands::
>
> - $ cd directory-holding-the-debugfs-directory
> - $ arch-gdb
> + $ cd <debugfs-directory>
> + $ <arch>-gdb
> (gdb) set sysroot debugfs
> (gdb) set substitute-path /usr/src/debug debugfs/usr/src/debug
> - (gdb) target remote IP-of-target:1234
> + (gdb) target remote <IP-of-target>:1234
Here's yet another prompt we should support that I don't think it's
supported in patch 2/8.
>
> At this
> point, everything should automatically load (i.e. matching binaries,
> diff --git a/documentation/migration-guides/migration-5.2.rst b/documentation/migration-guides/migration-5.2.rst
> index 77a11fe27047..48f9e7485d93 100644
> --- a/documentation/migration-guides/migration-5.2.rst
> +++ b/documentation/migration-guides/migration-5.2.rst
> @@ -193,9 +193,9 @@ The support for having multiple Git revisions per URL in :term:`SRC_URI` was
> removed from BitBake, which means the following syntax is not supported
> anymore::
>
> - SRC_URI = "git://some.host/somepath;bareclone=1;branch=branchX,branchY;name=nameX,nameY"
> - SRCREV_nameX = "xxxxxxxxxxxxxxxxxxxx"
> - SRCREV_nameY = "yyyyyyyyyyyyyyyyyyyy"
> + SRC_URI = "git://<some.host>/<somepath>;bareclone=1;branch=<branchX>,<branchY>;name=<nameX>,<nameY>"
> + SRCREV_<nameX> = "<revisionX>"
> + SRCREV_<nameY> = "<revisionY>"
We should say that this is the full sha of the commit.
>
> This was rarely used in the core repositories because it would only ever make
> sense for bare clones (the ``bareclone=1`` :term:`SRC_URI` option) where recipes
> @@ -205,10 +205,10 @@ places.
> If one of your recipes is using this mechanism, you can split the code source
> fetching into two separate entries::
>
> - SRC_URI = "git://some.host/somepath;bareclone=1;branch=branchX;name=nameX \
> - git://some.host/somepath;bareclone=1;branch=branchY;name=nameY"
> - SRCREV_nameX = "xxxxxxxxxxxxxxxxxxxx"
> - SRCREV_nameY = "yyyyyyyyyyyyyyyyyyyy"
> + SRC_URI = "git://<some.host>/<somepath>;bareclone=1;branch=<branchX>;name=<nameX> \
> + git://<some.host>/<somepath>;bareclone=1;branch=<branchY>;name=<nameY>"
> + SRCREV_<nameX> = "<revisionX>"
> + SRCREV_<nameY> = "<revisionY>"
>
Ditto.
Cheers,
Quentin
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [docs] [PATCH v2 5/8] docs: mark the placeholders in examples
2026-09-23 10:57 ` [docs] " Quentin Schulz
@ 2026-09-24 15:58 ` Trevor Woerner
0 siblings, 0 replies; 23+ messages in thread
From: Trevor Woerner @ 2026-09-24 15:58 UTC (permalink / raw)
To: Quentin Schulz; +Cc: docs
On Wed 2026-09-23 @ 12:57:39 PM, Quentin Schulz wrote:
> Hi Trevor,
>
> On 9/22/26 8:32 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> > Values the reader is expected to replace are written as though they were
> > literal. "arch-gdb" reads like a command that exists, a Git SRC_URI
> > example reads like a URL and a pair of revisions worth copying, and the
> > git-config examples give an account name and address that are somebody
> > else's. Put them in the angle brackets the manuals already use for the
> > purpose.
> >
> > Two corrections go with them: the directory placeholder in the GDB
> > example described itself at length rather than naming the thing, and the
> > smtppass example carried a stray "=". Since git config takes a name and
> > then a value, that "=" was the value, and the password behind it an
> > argument git config reads as a pattern.
> >
> > AI-Generated: codex/claude-opus 5 (xhigh)
> > Signed-off-by: Trevor Woerner <twoerner@gmail.com>
> > ---
> > changes in v2:
> > - rebased on master-next; no other change
> > ---
> > .../contributor-guide/submit-changes.rst | 12 ++++++------
> > documentation/dev-manual/debugging.rst | 8 ++++----
> > documentation/migration-guides/migration-5.2.rst | 16 ++++++++--------
> > documentation/ref-manual/devtool-reference.rst | 2 +-
> > documentation/ref-manual/variables.rst | 2 +-
> > 5 files changed, 20 insertions(+), 20 deletions(-)
> >
> > diff --git a/documentation/contributor-guide/submit-changes.rst b/documentation/contributor-guide/submit-changes.rst
> > index e60f8ca7ace3..a283eb734768 100644
> > --- a/documentation/contributor-guide/submit-changes.rst
> > +++ b/documentation/contributor-guide/submit-changes.rst
> > @@ -62,8 +62,8 @@ on Debian and Ubuntu::
> > Then, you need to set a name and e-mail address that Git will
> > use to identify your commits::
> > - $ git config --global user.name "Ada Lovelace"
> > - $ git config --global user.email "ada.lovelace@gmail.com"
> > + $ git config --global user.name "<name>"
>
> <firstname> <lastname>
Sounds good, i like the above one.
> maybe? I'm guessing some cultures have other orders, I've seen
>
> <lastname>, <firstname>
>
> a few times.
>
> > + $ git config --global user.email "<email>"
> > By default, Git adds a signature line at the end of patches containing the Git
> > version. We suggest to remove it as it doesn't add useful information.
> > @@ -399,8 +399,8 @@ regular STMP server, using a Google Mail account as an example::
> > $ git config --global sendemail.smtpserver smtp.gmail.com
>
> Why is this not changed to a placeholder?
Sounds good.
> > $ git config --global sendemail.smtpserverport 587
> > $ git config --global sendemail.smtpencryption tls
> > - $ git config --global sendemail.smtpuser ada.lovelace@gmail.com
> > - $ git config --global sendemail.smtppass = XXXXXXXX
> > + $ git config --global sendemail.smtpuser <email>
> > + $ git config --global sendemail.smtppass <password>
>
> It's also optional, in which case you're prompted every time you send a
> mail, which I kinda like :)
>
> > These settings will appear in the ``.gitconfig`` file in your home directory.
> > @@ -509,7 +509,7 @@ We have a frequent issue with contributors whose patches are received through
> > a ``From`` field which doesn't match the ``Signed-off-by`` information. Here is
> > a typical example for people sending from a domain name with :wikipedia:`DMARC`::
> > - From: "Linus Torvalds via lists.openembedded.org <linus.torvalds=kernel.org@lists.openembedded.org>"
> > + From: "xxx via lists.openembedded.org <xxx@lists.openembedded.org>"
>
> Please keep this one (or use an example that exists in the wild, I don't
> think Linus sent patches to OE-Core :)) as it is an actual example.
Okay.
> > This ``From`` field is used by ``git am`` to recreate commits with the right
> > author name. The following will ensure that your e-mails have an additional
> > @@ -517,7 +517,7 @@ author name. The following will ensure that your e-mails have an additional
> > maintainers accepting your patches don't have to fix commit author information
> > manually::
> > - $ git config --global sendemail.from "linus.torvalds@kernel.org"
> > + $ git config --global sendemail.from "<email>"
> > The ``sendemail.from`` should match your ``user.email`` setting,
> > which appears in the ``Signed-off-by`` line of your commits.
> > diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst
> > index 0f6e9d1d7e85..8412c997a51e 100644
> > --- a/documentation/dev-manual/debugging.rst
> > +++ b/documentation/dev-manual/debugging.rst
> > @@ -810,7 +810,7 @@ be visible. In this case, there is a missing dependency for the ``neard``
> > Makefile target. Here is some abbreviated, sample output with the
> > missing dependency clearly visible at the end::
> > - i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/scott-lenovo/......
> > + i586-poky-linux-gcc -m32 -march=i586 --sysroot=<path/to/sysroot>
> > .
> > .
> > .
> > @@ -1114,11 +1114,11 @@ debugger.
> > After running gdbserver on the target, you need to run Gdb on the
> > host and configure it and connect to the target. Use these commands::
> > - $ cd directory-holding-the-debugfs-directory
> > - $ arch-gdb
> > + $ cd <debugfs-directory>
> > + $ <arch>-gdb
> > (gdb) set sysroot debugfs
> > (gdb) set substitute-path /usr/src/debug debugfs/usr/src/debug
> > - (gdb) target remote IP-of-target:1234
> > + (gdb) target remote <IP-of-target>:1234
>
> Here's yet another prompt we should support that I don't think it's
> supported in patch 2/8.
Agreed! Good catch.
> > At this
> > point, everything should automatically load (i.e. matching binaries,
> > diff --git a/documentation/migration-guides/migration-5.2.rst b/documentation/migration-guides/migration-5.2.rst
> > index 77a11fe27047..48f9e7485d93 100644
> > --- a/documentation/migration-guides/migration-5.2.rst
> > +++ b/documentation/migration-guides/migration-5.2.rst
> > @@ -193,9 +193,9 @@ The support for having multiple Git revisions per URL in :term:`SRC_URI` was
> > removed from BitBake, which means the following syntax is not supported
> > anymore::
> > - SRC_URI = "git://some.host/somepath;bareclone=1;branch=branchX,branchY;name=nameX,nameY"
> > - SRCREV_nameX = "xxxxxxxxxxxxxxxxxxxx"
> > - SRCREV_nameY = "yyyyyyyyyyyyyyyyyyyy"
> > + SRC_URI = "git://<some.host>/<somepath>;bareclone=1;branch=<branchX>,<branchY>;name=<nameX>,<nameY>"
> > + SRCREV_<nameX> = "<revisionX>"
> > + SRCREV_<nameY> = "<revisionY>"
>
> We should say that this is the full sha of the commit.
Sounds good. I thought "revisionX" was better enough from "xxxx", but
SHA is better yet.
> > This was rarely used in the core repositories because it would only ever make
> > sense for bare clones (the ``bareclone=1`` :term:`SRC_URI` option) where recipes
> > @@ -205,10 +205,10 @@ places.
> > If one of your recipes is using this mechanism, you can split the code source
> > fetching into two separate entries::
> > - SRC_URI = "git://some.host/somepath;bareclone=1;branch=branchX;name=nameX \
> > - git://some.host/somepath;bareclone=1;branch=branchY;name=nameY"
> > - SRCREV_nameX = "xxxxxxxxxxxxxxxxxxxx"
> > - SRCREV_nameY = "yyyyyyyyyyyyyyyyyyyy"
> > + SRC_URI = "git://<some.host>/<somepath>;bareclone=1;branch=<branchX>;name=<nameX> \
> > + git://<some.host>/<somepath>;bareclone=1;branch=<branchY>;name=<nameY>"
> > + SRCREV_<nameX> = "<revisionX>"
> > + SRCREV_<nameY> = "<revisionY>"
>
> Ditto.
Got it.
> Cheers,
> Quentin
^ permalink raw reply [flat|nested] 23+ messages in thread
* [PATCH v2 6/8] docs: remove real accounts from the examples
2026-09-22 18:32 [PATCH v2 0/8] docs: editorial repairs to the examples Trevor Woerner
` (4 preceding siblings ...)
2026-09-22 18:32 ` [PATCH v2 5/8] docs: mark the placeholders in examples Trevor Woerner
@ 2026-09-22 18:32 ` Trevor Woerner
2026-09-23 11:02 ` [docs] " Quentin Schulz
2026-09-22 18:32 ` [PATCH v2 7/8] kernel-dev: give each example block one thing to hold Trevor Woerner
2026-09-22 18:32 ` [PATCH v2 8/8] ref-manual: put the ARCHIVER_MODE comments on their own lines Trevor Woerner
7 siblings, 1 reply; 23+ messages in thread
From: Trevor Woerner @ 2026-09-22 18:32 UTC (permalink / raw)
To: docs
Examples across the manuals carry the account names of the people who
wrote them, in home directory paths and in shell prompts that also
name a machine. Use "/home/user" and a bare "$", which is what the rest
of the manuals already do.
The autobuilder's own service account is left alone: the paths containing
it are about autobuilder output rather than about somebody's machine.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
changes in v2:
- rebased on master-next; no other change
---
documentation/dev-manual/debugging.rst | 4 +-
documentation/dev-manual/layers.rst | 12 ++---
documentation/dev-manual/qemu.rst | 2 +-
.../dev-manual/upgrading-recipes.rst | 18 ++++----
documentation/dev-manual/wic.rst | 44 +++++++++----------
documentation/kernel-dev/common.rst | 16 +++----
documentation/profile-manual/usage.rst | 2 +-
.../ref-manual/devtool-reference.rst | 6 +--
documentation/ref-manual/faq.rst | 6 +--
documentation/ref-manual/variables.rst | 8 ++--
documentation/sdk-manual/extensible.rst | 6 +--
11 files changed, 62 insertions(+), 62 deletions(-)
diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst
index 8412c997a51e..62e19a6c8a28 100644
--- a/documentation/dev-manual/debugging.rst
+++ b/documentation/dev-manual/debugging.rst
@@ -144,7 +144,7 @@ helpful during debugging.
Variables that are exported to the environment are preceded by
``export`` in the output of ``bitbake-getvar``. See the following example::
- export CC="i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/ulf/poky/build/tmp/sysroots/qemux86"
+ export CC="i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/user/poky/build/tmp/sysroots/qemux86"
Shell functions and tasks can also be inspected with the same mechanism::
@@ -522,7 +522,7 @@ task dependency mechanisms.
.. code-block:: none
- WARNING: /home/ulf/openembedded-core/meta/recipes-sato/matchbox-desktop/matchbox-desktop_2.1.bb.do_compile is tainted from a forced run
+ WARNING: /home/user/openembedded-core/meta/recipes-sato/matchbox-desktop/matchbox-desktop_2.1.bb.do_compile is tainted from a forced run
The purpose of the warning is to let you know that the work directory
diff --git a/documentation/dev-manual/layers.rst b/documentation/dev-manual/layers.rst
index 185a63feb700..a36f849a0c3f 100644
--- a/documentation/dev-manual/layers.rst
+++ b/documentation/dev-manual/layers.rst
@@ -916,11 +916,11 @@ shows the layers that are in your :ref:`structure-build-conf-bblayers.conf` file
NOTE: Starting bitbake server...
layer path priority
==============================================================================================
- meta /home/scottrif/bitbake-builds/layers/openembedded-core/meta 5
- meta-poky /home/scottrif/bitbake-builds/layers/meta-yocto/meta-poky 5
- meta-yocto-bsp /home/scottrif/bitbake-builds/layers/meta-yocto/meta-yocto-bsp 5
- workspace /home/scottrif/bitbake-builds/build/workspace 99
- meta-scottrif /home/scottrif/bitbake-builds/build/meta-scottrif 6
+ meta /home/user/bitbake-builds/layers/openembedded-core/meta 5
+ meta-poky /home/user/bitbake-builds/layers/meta-yocto/meta-poky 5
+ meta-yocto-bsp /home/user/bitbake-builds/layers/meta-yocto/meta-yocto-bsp 5
+ workspace /home/user/bitbake-builds/build/workspace 99
+ meta-scottrif /home/user/bitbake-builds/build/meta-scottrif 6
Adding the layer to this file
enables the build system to locate the layer during the build.
@@ -958,7 +958,7 @@ above:
#. Run the script directly with no options::
- alex@Zen2:/srv/work/alex/my-build$ meta-alex/setup-layers
+ $ meta-alex/setup-layers
Note: not checking out source meta-alex, use --force-bootstraplayer-checkout to override.
Setting up source meta-intel, revision 15.0-hardknott-3.3-310-g0a96edae, branch master
diff --git a/documentation/dev-manual/qemu.rst b/documentation/dev-manual/qemu.rst
index 6d092b2d2034..d7e0b2f2f44f 100644
--- a/documentation/dev-manual/qemu.rst
+++ b/documentation/dev-manual/qemu.rst
@@ -151,7 +151,7 @@ available. Follow these general steps to run QEMU:
determines the QEMU architecture (`MACHINE`) to be "qemux86-64" and
the root filesystem type to be "vmdk"::
- $ runqemu /home/scott-lenovo/vm/core-image-minimal-qemux86-64.wic.vmdk
+ $ runqemu /home/user/vm/core-image-minimal-qemux86-64.wic.vmdk
Switching Between Consoles
==========================
diff --git a/documentation/dev-manual/upgrading-recipes.rst b/documentation/dev-manual/upgrading-recipes.rst
index 0bdc1351ec7f..f4b9df241093 100644
--- a/documentation/dev-manual/upgrading-recipes.rst
+++ b/documentation/dev-manual/upgrading-recipes.rst
@@ -244,12 +244,12 @@ script. For example, suppose you use the ``nano.bb`` recipe from the
``meta-oe`` layer in the ``meta-openembedded`` repository. For this
example, assume that the layer has been cloned into following area::
- /home/scottrif/bitbake-builds/layers/meta-openembedded
+ /home/user/bitbake-builds/layers/meta-openembedded
The following command from your :term:`Build Directory` adds the layer to
your build configuration (i.e. ``${BUILDDIR}/conf/bblayers.conf``)::
- $ bitbake-layers add-layer /home/scottrif/bitbake-builds/layers/meta-openembedded/meta-oe
+ $ bitbake-layers add-layer /home/user/bitbake-builds/layers/meta-openembedded/meta-oe
NOTE: Starting bitbake server...
Parsing recipes: 100% |##########################################| Time: 0:00:55
Parsing of 1431 .bb files complete (0 cached, 1431 parsed). 2040 targets, 56 skipped, 0 masked, 0 errors.
@@ -265,7 +265,7 @@ directory automatically upgrades the recipe for you::
$ devtool upgrade nano -V 2.9.3
NOTE: Starting bitbake server...
- NOTE: Creating workspace layer in /home/scottrif/bitbake-builds/build/workspace
+ NOTE: Creating workspace layer in /home/user/bitbake-builds/build/workspace
Parsing recipes: 100% |##########################################| Time: 0:00:46
Parsing of 1431 .bb files complete (0 cached, 1431 parsed). 2040 targets, 56 skipped, 0 masked, 0 errors.
NOTE: Extracting current version source...
@@ -277,8 +277,8 @@ directory automatically upgrades the recipe for you::
NOTE: Executing RunQueue Tasks
NOTE: Tasks Summary: Attempted 74 tasks of which 72 didn't need to be rerun and all succeeded.
Adding changed files: 100% |#####################################| Time: 0:00:00
- NOTE: Upgraded source extracted to /home/scottrif/bitbake-builds/build/workspace/sources/nano
- NOTE: New recipe is /home/scottrif/bitbake-builds/build/workspace/recipes/nano/nano_2.9.3.bb
+ NOTE: Upgraded source extracted to /home/user/bitbake-builds/build/workspace/sources/nano
+ NOTE: New recipe is /home/user/bitbake-builds/build/workspace/recipes/nano/nano_2.9.3.bb
.. note::
@@ -300,7 +300,7 @@ newly upgraded recipe::
.
NOTE: Executing SetScene Tasks
NOTE: Executing RunQueue Tasks
- NOTE: nano: compiling from external source tree /home/scottrif/bitbake-builds/build/workspace/sources/nano
+ NOTE: nano: compiling from external source tree /home/user/bitbake-builds/build/workspace/sources/nano
NOTE: Tasks Summary: Attempted 520 tasks of which 304 didn't need to be rerun and all succeeded.
Within the ``devtool upgrade`` workflow, you can
@@ -321,9 +321,9 @@ directory::
Parsing of 1432 .bb files complete (1431 cached, 1 parsed). 2041 targets, 56 skipped, 0 masked, 0 errors.
NOTE: Adding new patch 0001-nano.bb-Stuff-I-changed-when-upgrading-nano.bb.patch
NOTE: Updating recipe nano_2.9.3.bb
- NOTE: Removing file /home/scottrif/bitbake-builds/layers/meta-openembedded/meta-oe/recipes-support/nano/nano_2.7.4.bb
- NOTE: Moving recipe file to /home/scottrif/bitbake-builds/layers/meta-openembedded/meta-oe/recipes-support/nano
- NOTE: Leaving source tree /home/scottrif/bitbake-builds/build/workspace/sources/nano as-is; if you no longer need it then please delete it manually
+ NOTE: Removing file /home/user/bitbake-builds/layers/meta-openembedded/meta-oe/recipes-support/nano/nano_2.7.4.bb
+ NOTE: Moving recipe file to /home/user/bitbake-builds/layers/meta-openembedded/meta-oe/recipes-support/nano
+ NOTE: Leaving source tree /home/user/bitbake-builds/build/workspace/sources/nano as-is; if you no longer need it then please delete it manually
Using the ``devtool finish`` command cleans up the workspace and creates a patch
diff --git a/documentation/dev-manual/wic.rst b/documentation/dev-manual/wic.rst
index c13655f8730a..9161122d3166 100644
--- a/documentation/dev-manual/wic.rst
+++ b/documentation/dev-manual/wic.rst
@@ -520,13 +520,13 @@ file:
./mkefidisk-201804191017-sda.direct
The following build artifacts were used to create the image(s):
- ROOTFS_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs
- BOOTIMG_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
- KERNEL_DIR: /home/stephano/yocto/build/tmp-glibc/deploy/images/qemux86
- NATIVE_SYSROOT: /home/stephano/yocto/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native
+ ROOTFS_DIR: /home/user/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs
+ BOOTIMG_DIR: /home/user/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
+ KERNEL_DIR: /home/user/yocto/build/tmp-glibc/deploy/images/qemux86
+ NATIVE_SYSROOT: /home/user/yocto/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native
INFO: The image(s) were created using OE kickstart file:
- /home/stephano/yocto/openembedded-core/files/wic/mkefidisk.wks
+ /home/user/yocto/openembedded-core/files/wic/mkefidisk.wks
The previous example shows the easiest way to create an image by running
in cooked mode and supplying a kickstart file and the "-e" option to
@@ -590,8 +590,8 @@ the lines that specify the target disk from which to boot:
.. code-block:: console
- $ cp /home/stephano/yocto/openembedded-core/files/wic/directdisk-gpt.wks \
- /home/stephano/yocto/openembedded-core/files/wic/directdisksdb-gpt.wks
+ $ cp /home/user/yocto/openembedded-core/files/wic/directdisk-gpt.wks \
+ /home/user/yocto/openembedded-core/files/wic/directdisksdb-gpt.wks
Next, the example modifies the ``directdisksdb-gpt.wks`` file and
changes all instances of "``--ondisk sda``" to "``--ondisk sdb``". The
@@ -625,13 +625,13 @@ Computing (nuc) :term:`MACHINE`:
./directdisksdb-gpt-201710090938-sdb.direct
The following build artifacts were used to create the image(s):
- ROOTFS_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs
- BOOTIMG_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
- KERNEL_DIR: /home/stephano/yocto/build/tmp-glibc/deploy/images/qemux86
- NATIVE_SYSROOT: /home/stephano/yocto/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native
+ ROOTFS_DIR: /home/user/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs
+ BOOTIMG_DIR: /home/user/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
+ KERNEL_DIR: /home/user/yocto/build/tmp-glibc/deploy/images/qemux86
+ NATIVE_SYSROOT: /home/user/yocto/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native
INFO: The image(s) were created using OE kickstart file:
- /home/stephano/yocto/openembedded-core/files/wic/directdisksdb-gpt.wks
+ /home/user/yocto/openembedded-core/files/wic/directdisksdb-gpt.wks
Continuing with the example, you can now directly ``dd`` the image to a
USB stick, or whatever media for which you built your image, and boot
@@ -655,22 +655,22 @@ default output directory, which is the current directory:
.. code-block:: console
- $ wic create test.wks -o /home/stephano/testwic \
- --rootfs-dir /home/stephano/yocto/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/rootfs \
- --bootimg-dir /home/stephano/yocto/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share \
- --kernel-dir /home/stephano/yocto/build/tmp/deploy/images/qemux86 \
- --native-sysroot /home/stephano/yocto/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native
+ $ wic create test.wks -o /home/user/testwic \
+ --rootfs-dir /home/user/yocto/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/rootfs \
+ --bootimg-dir /home/user/yocto/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share \
+ --kernel-dir /home/user/yocto/build/tmp/deploy/images/qemux86 \
+ --native-sysroot /home/user/yocto/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native
INFO: Creating image(s)...
INFO: The new image(s) can be found here:
- /home/stephano/testwic/test-201710091445-sdb.direct
+ /home/user/testwic/test-201710091445-sdb.direct
The following build artifacts were used to create the image(s):
- ROOTFS_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs
- BOOTIMG_DIR: /home/stephano/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
- KERNEL_DIR: /home/stephano/yocto/build/tmp-glibc/deploy/images/qemux86
- NATIVE_SYSROOT: /home/stephano/yocto/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native
+ ROOTFS_DIR: /home/user/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs
+ BOOTIMG_DIR: /home/user/yocto/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
+ KERNEL_DIR: /home/user/yocto/build/tmp-glibc/deploy/images/qemux86
+ NATIVE_SYSROOT: /home/user/yocto/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native
INFO: The image(s) were created using OE kickstart file:
test.wks
diff --git a/documentation/kernel-dev/common.rst b/documentation/kernel-dev/common.rst
index 555aadc76a6c..15c8429dbeb3 100644
--- a/documentation/kernel-dev/common.rst
+++ b/documentation/kernel-dev/common.rst
@@ -1250,32 +1250,32 @@ Here is sample output from the :ref:`ref-tasks-kernel_configcheck` task:
---------- CONFIG_X86_TSC -----------------
Config: CONFIG_X86_TSC
- From: /home/scottrif/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc-cpu.cfg
+ From: /home/user/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc-cpu.cfg
Requested value: CONFIG_X86_TSC=y
Actual value:
---------- CONFIG_X86_BIGSMP -----------------
Config: CONFIG_X86_BIGSMP
- From: /home/scottrif/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
- /home/scottrif/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
+ From: /home/user/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
+ /home/user/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
Requested value: # CONFIG_X86_BIGSMP is not set
Actual value:
---------- CONFIG_NR_CPUS -----------------
Config: CONFIG_NR_CPUS
- From: /home/scottrif/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
- /home/scottrif/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc.cfg
- /home/scottrif/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
+ From: /home/user/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
+ /home/user/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/bsp/common-pc/common-pc.cfg
+ /home/user/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
Requested value: CONFIG_NR_CPUS=8
Actual value: CONFIG_NR_CPUS=1
---------- CONFIG_SCHED_SMT -----------------
Config: CONFIG_SCHED_SMT
- From: /home/scottrif/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
- /home/scottrif/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
+ From: /home/user/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/cfg/smp.cfg
+ /home/user/bitbake-builds/build/tmp/work-shared/qemux86/kernel-source/.kernel-meta/configs/standard/defconfig
Requested value: CONFIG_SCHED_SMT=y
Actual value:
diff --git a/documentation/profile-manual/usage.rst b/documentation/profile-manual/usage.rst
index 4efaa6d10fce..7fdbe41da5e7 100644
--- a/documentation/profile-manual/usage.rst
+++ b/documentation/profile-manual/usage.rst
@@ -322,7 +322,7 @@ debug packages once built can be found in ``build/tmp/deploy/rpm/*``
on the host system. Find the ``busybox-dbg-...rpm`` file and copy it
to the target. For example::
- [trz@empanada core2]$ scp /home/trz/yocto/crownbay-tracing-dbg/build/tmp/deploy/rpm/core2_32/busybox-dbg-1.20.2-r2.core2_32.rpm root@192.168.1.31:
+ $ scp /home/user/yocto/crownbay-tracing-dbg/build/tmp/deploy/rpm/core2_32/busybox-dbg-1.20.2-r2.core2_32.rpm root@192.168.1.31:
busybox-dbg-1.20.2-r2.core2_32.rpm 100% 1826KB 1.8MB/s 00:01
Now install the debug RPM on the target::
diff --git a/documentation/ref-manual/devtool-reference.rst b/documentation/ref-manual/devtool-reference.rst
index 62c3b707b9ff..c8ca7bad8c9c 100644
--- a/documentation/ref-manual/devtool-reference.rst
+++ b/documentation/ref-manual/devtool-reference.rst
@@ -460,7 +460,7 @@ Here is an example that resets the workspace directory that contains the
$ devtool reset mtr
NOTE: Cleaning sysroot for recipe mtr...
- NOTE: Leaving source tree /home/scottrif/bitbake-builds/build/workspace/sources/mtr as-is; if you no longer need it then please delete it manually
+ NOTE: Leaving source tree /home/user/bitbake-builds/build/workspace/sources/mtr as-is; if you no longer need it then please delete it manually
.. _devtool-finish-working-on-a-recipe:
@@ -612,7 +612,7 @@ You can create a workspace layer anywhere by supplying a pathname with
the command. The following command creates a new workspace layer named
"new-workspace"::
- $ devtool create-workspace /home/scottrif/new-workspace
+ $ devtool create-workspace /home/user/new-workspace
.. _devtool-get-the-status-of-the-recipes-in-your-workspace:
@@ -632,7 +632,7 @@ Here is sample output after using
to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory::
$ devtool status
- mtr:/home/scottrif/bitbake-builds/build/workspace/sources/mtr (/home/scottrif/bitbake-builds/build/workspace/recipes/mtr/mtr_0.86.bb)
+ mtr:/home/user/bitbake-builds/build/workspace/sources/mtr (/home/user/bitbake-builds/build/workspace/recipes/mtr/mtr_0.86.bb)
.. _devtool-search-for-available-target-recipes:
diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst
index f8e047e27fed..3646286a6e0c 100644
--- a/documentation/ref-manual/faq.rst
+++ b/documentation/ref-manual/faq.rst
@@ -461,11 +461,11 @@ and related variables. To better understand this, consider the following
two paths (artificially broken across lines for readability) where the
first is relatively normal and the second is not::
- /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/
+ /home/user/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/
1.2.8-r0/sysroot-destdir/usr/bin
- /home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/
- zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/
+ /home/user/poky-bootchart2/build/tmp/work/x86_64-linux/
+ zlib-native/1.2.8-r0/sysroot-destdir/home/user/poky-bootchart2/
build/tmp/sysroots/x86_64-linux/usr/bin
Even if the paths look unusual, they both are correct --- the first for
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 0072992b8597..8a9bd9075843 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -888,10 +888,10 @@ system and gives an overview of their function and contents.
Here is an example::
BBLAYERS = " \
- /home/scottrif/bitbake-builds/layers/meta \
- /home/scottrif/bitbake-builds/layers/meta-poky \
- /home/scottrif/bitbake-builds/layers/meta-yocto-bsp \
- /home/scottrif/bitbake-builds/layers/meta-mykernel \
+ /home/user/bitbake-builds/layers/meta \
+ /home/user/bitbake-builds/layers/meta-poky \
+ /home/user/bitbake-builds/layers/meta-yocto-bsp \
+ /home/user/bitbake-builds/layers/meta-mykernel \
"
This example enables four layers, one of which is a custom,
diff --git a/documentation/sdk-manual/extensible.rst b/documentation/sdk-manual/extensible.rst
index 0eb9eda8d82a..8b8034707eab 100644
--- a/documentation/sdk-manual/extensible.rst
+++ b/documentation/sdk-manual/extensible.rst
@@ -149,7 +149,7 @@ architecture. The example assumes the SDK installer is located in
Poky (Yocto Project Reference Distro) Extensible SDK installer version 2.5
==========================================================================
Enter target directory for SDK (default: poky_sdk):
- You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed [Y/n]? Y
+ You are about to install the SDK to "/home/user/poky_sdk". Proceed [Y/n]? Y
Extracting SDK..............done
Setting it up...
Extracting buildtools...
@@ -162,7 +162,7 @@ architecture. The example assumes the SDK installer is located in
done
SDK has been successfully set up and is ready to be used.
Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
- $ . /home/scottrif/poky_sdk/environment-setup-core2-64-poky-linux
+ $ . /home/user/poky_sdk/environment-setup-core2-64-poky-linux
.. note::
@@ -197,7 +197,7 @@ script is for an IA-based target machine using i586 tuning:
.. code-block:: console
- $ cd /home/scottrif/poky_sdk
+ $ cd /home/user/poky_sdk
$ source environment-setup-core2-64-poky-linux
SDK environment now set up; additionally you may now run devtool to perform development tasks.
Run devtool --help for further details.
--
2.50.0.173.g8b6f19ccfc3a
^ permalink raw reply related [flat|nested] 23+ messages in thread* Re: [docs] [PATCH v2 6/8] docs: remove real accounts from the examples
2026-09-22 18:32 ` [PATCH v2 6/8] docs: remove real accounts from the examples Trevor Woerner
@ 2026-09-23 11:02 ` Quentin Schulz
2026-09-24 15:55 ` Trevor Woerner
0 siblings, 1 reply; 23+ messages in thread
From: Quentin Schulz @ 2026-09-23 11:02 UTC (permalink / raw)
To: twoerner, docs
Hi Trevor,
On 9/22/26 8:32 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> Examples across the manuals carry the account names of the people who
> wrote them, in home directory paths and in shell prompts that also
> name a machine. Use "/home/user" and a bare "$", which is what the rest
> of the manuals already do.
>
> The autobuilder's own service account is left alone: the paths containing
> it are about autobuilder output rather than about somebody's machine.
>
> AI-Generated: codex/claude-opus 5 (xhigh)
> Signed-off-by: Trevor Woerner <twoerner@gmail.com>
> ---
> changes in v2:
> - rebased on master-next; no other change
> ---
[...]
> diff --git a/documentation/dev-manual/layers.rst b/documentation/dev-manual/layers.rst
> index 185a63feb700..a36f849a0c3f 100644
> --- a/documentation/dev-manual/layers.rst
> +++ b/documentation/dev-manual/layers.rst
[...]
> @@ -958,7 +958,7 @@ above:
>
> #. Run the script directly with no options::
>
> - alex@Zen2:/srv/work/alex/my-build$ meta-alex/setup-layers
> + $ meta-alex/setup-layers
No, the path is known there and is important. If you prefer, you can
modify /srv/work/alex/meta-alex all over the file to something that
works better for you, but the path in the prompt is important.
Cheers,
Quentin
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [docs] [PATCH v2 6/8] docs: remove real accounts from the examples
2026-09-23 11:02 ` [docs] " Quentin Schulz
@ 2026-09-24 15:55 ` Trevor Woerner
0 siblings, 0 replies; 23+ messages in thread
From: Trevor Woerner @ 2026-09-24 15:55 UTC (permalink / raw)
To: Quentin Schulz; +Cc: docs
On Wed 2026-09-23 @ 01:02:05 PM, Quentin Schulz wrote:
> Hi Trevor,
>
> On 9/22/26 8:32 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> > Examples across the manuals carry the account names of the people who
> > wrote them, in home directory paths and in shell prompts that also
> > name a machine. Use "/home/user" and a bare "$", which is what the rest
> > of the manuals already do.
> >
> > The autobuilder's own service account is left alone: the paths containing
> > it are about autobuilder output rather than about somebody's machine.
> >
> > AI-Generated: codex/claude-opus 5 (xhigh)
> > Signed-off-by: Trevor Woerner <twoerner@gmail.com>
> > ---
> > changes in v2:
> > - rebased on master-next; no other change
> > ---
> [...]
> > diff --git a/documentation/dev-manual/layers.rst b/documentation/dev-manual/layers.rst
> > index 185a63feb700..a36f849a0c3f 100644
> > --- a/documentation/dev-manual/layers.rst
> > +++ b/documentation/dev-manual/layers.rst
> [...]
> > @@ -958,7 +958,7 @@ above:
> > #. Run the script directly with no options::
> > - alex@Zen2:/srv/work/alex/my-build$ meta-alex/setup-layers
> > + $ meta-alex/setup-layers
>
> No, the path is known there and is important. If you prefer, you can modify
> /srv/work/alex/meta-alex all over the file to something that works better
> for you, but the path in the prompt is important.
Okay.
> Cheers,
> Quentin
^ permalink raw reply [flat|nested] 23+ messages in thread
* [PATCH v2 7/8] kernel-dev: give each example block one thing to hold
2026-09-22 18:32 [PATCH v2 0/8] docs: editorial repairs to the examples Trevor Woerner
` (5 preceding siblings ...)
2026-09-22 18:32 ` [PATCH v2 6/8] docs: remove real accounts from the examples Trevor Woerner
@ 2026-09-22 18:32 ` Trevor Woerner
2026-09-23 11:05 ` [docs] " Quentin Schulz
2026-09-22 18:32 ` [PATCH v2 8/8] ref-manual: put the ARCHIVER_MODE comments on their own lines Trevor Woerner
7 siblings, 1 reply; 23+ messages in thread
From: Trevor Woerner @ 2026-09-22 18:32 UTC (permalink / raw)
To: docs
Several kernel metadata examples put a filename label inside the block,
and some go on to hold more than one file, in more than one language,
under a single "::". A block shaped that way is not any one language, so
it can only ever be shown unhighlighted.
Split them into a block each, dedent what is left, and move the
filename to the code-block caption, which keeps it attached to the block
it names and renders it inside the block's frame. The theme centres a
caption in italics, which reads as prose, so it is restyled to look like
the filename it is.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
changes in v2:
- the caption takes the theme's whole font stack; the shortened copy
dropped Liberation Mono, which is why it rendered in a different face
---
documentation/kernel-dev/advanced.rst | 139 ++++++++++--------
.../sphinx-static/theme_overrides.css | 28 ++++
2 files changed, 104 insertions(+), 63 deletions(-)
diff --git a/documentation/kernel-dev/advanced.rst b/documentation/kernel-dev/advanced.rst
index 321033b7bd49..ecd0137fa5fd 100644
--- a/documentation/kernel-dev/advanced.rst
+++ b/documentation/kernel-dev/advanced.rst
@@ -216,24 +216,28 @@ used with the ``linux-yocto-4.12`` kernel as defined outside of the
recipe space (i.e. ``yocto-kernel-cache``). This Metadata consists of
two files: ``smp.scc`` and ``smp.cfg``. You can find these files in the
``cfg`` directory of the ``yocto-4.12`` branch in the
-``yocto-kernel-cache`` Git repository::
+``yocto-kernel-cache`` Git repository.
+
+.. code-block::
+ :caption: cfg/smp.scc
+
+ define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds"
+ define KFEATURE_COMPATIBILITY all
- cfg/smp.scc:
- define KFEATURE_DESCRIPTION "Enable SMP for 32 bit builds"
- define KFEATURE_COMPATIBILITY all
+ kconf hardware smp.cfg
- kconf hardware smp.cfg
+.. code-block::
+ :caption: cfg/smp.cfg
- cfg/smp.cfg:
- CONFIG_SMP=y
- CONFIG_SCHED_SMT=y
- # Increase default NR_CPUS from 8 to 64 so that platform with
- # more than 8 processors can be all activated at boot time
- CONFIG_NR_CPUS=64
- # The following is needed when setting NR_CPUS to something
- # greater than 8 on x86 architectures, it should be automatically
- # disregarded by Kconfig when using a different arch
- CONFIG_X86_BIGSMP=y
+ CONFIG_SMP=y
+ CONFIG_SCHED_SMT=y
+ # Increase default NR_CPUS from 8 to 64 so that platform with
+ # more than 8 processors can be all activated at boot time
+ CONFIG_NR_CPUS=64
+ # The following is needed when setting NR_CPUS to something
+ # greater than 8 on x86 architectures, it should be automatically
+ # disregarded by Kconfig when using a different arch
+ CONFIG_X86_BIGSMP=y
You can find general information on configuration
fragment files in the ":ref:`kernel-dev/common:creating configuration fragments`" section.
@@ -278,36 +282,39 @@ kernel as defined outside of the recipe space (i.e.
in the ``patches/build`` directory of the ``yocto-4.12`` branch in the
``yocto-kernel-cache`` Git repository.
-The following listings show the ``build.scc`` file and part of the
-``modpost-mask-trivial-warnings.patch`` file::
+.. code-block::
+ :caption: patches/build/build.scc
- patches/build/build.scc:
- patch arm-serialize-build-targets.patch
- patch powerpc-serialize-image-targets.patch
- patch kbuild-exclude-meta-directory-from-distclean-processi.patch
+ patch arm-serialize-build-targets.patch
+ patch powerpc-serialize-image-targets.patch
+ patch kbuild-exclude-meta-directory-from-distclean-processi.patch
- # applied by kgit
- # patch kbuild-add-meta-files-to-the-ignore-li.patch
+ # applied by kgit
+ # patch kbuild-add-meta-files-to-the-ignore-li.patch
- patch modpost-mask-trivial-warnings.patch
- patch menuconfig-check-lxdiaglog.sh-Allow-specification-of.patch
+ patch modpost-mask-trivial-warnings.patch
+ patch menuconfig-check-lxdiaglog.sh-Allow-specification-of.patch
- patches/build/modpost-mask-trivial-warnings.patch:
- From bd48931bc142bdd104668f3a062a1f22600aae61 Mon Sep 17 00:00:00 2001
- From: Paul Gortmaker <paul.gortmaker@windriver.com>
- Date: Sun, 25 Jan 2009 17:58:09 -0500
- Subject: [PATCH] modpost: mask trivial warnings
+and part of the patch it names:
- Newer HOSTCC will complain about various stdio fcns because
- .
- .
- .
- char *dump_write = NULL, *files_source = NULL;
- int opt;
- --
- 2.10.1
+.. code-block::
+ :caption: patches/build/modpost-mask-trivial-warnings.patch
- generated by cgit v0.10.2 at 2017-09-28 15:23:23 (GMT)
+ From bd48931bc142bdd104668f3a062a1f22600aae61 Mon Sep 17 00:00:00 2001
+ From: Paul Gortmaker <paul.gortmaker@windriver.com>
+ Date: Sun, 25 Jan 2009 17:58:09 -0500
+ Subject: [PATCH] modpost: mask trivial warnings
+
+ Newer HOSTCC will complain about various stdio fcns because
+ .
+ .
+ .
+ char *dump_write = NULL, *files_source = NULL;
+ int opt;
+ --
+ 2.10.1
+
+ generated by cgit v0.10.2 at 2017-09-28 15:23:23 (GMT)
The description file can
include multiple patch statements where each statement handles a single
@@ -325,16 +332,18 @@ Features
Features are complex kernel Metadata types that consist of configuration
fragments, patches, and possibly other feature description files. As an
-example, consider the following generic listing::
+example, consider the following generic listing:
+
+.. code-block::
+ :caption: features/myfeature.scc
- features/myfeature.scc
- define KFEATURE_DESCRIPTION "Enable myfeature"
+ define KFEATURE_DESCRIPTION "Enable myfeature"
- patch 0001-myfeature-core.patch
- patch 0002-myfeature-interface.patch
+ patch 0001-myfeature-core.patch
+ patch 0002-myfeature-interface.patch
- include cfg/myfeature_dependency.scc
- kconf non-hardware myfeature.cfg
+ include cfg/myfeature_dependency.scc
+ kconf non-hardware myfeature.cfg
This example shows how the ``patch`` and ``kconf`` commands are used as well
as how an additional feature description file is included with the
@@ -873,17 +882,19 @@ new branch as the :term:`KBRANCH` to use for the board as follows::
KBRANCH = "mynewbranch"
Another method is to use the ``branch`` command in the BSP
-description::
+description:
- mybsp.scc:
- define KMACHINE mybsp
- define KTYPE standard
- define KARCH i386
- include standard.scc
+.. code-block::
+ :caption: mybsp.scc
- branch mynewbranch
+ define KMACHINE mybsp
+ define KTYPE standard
+ define KARCH i386
+ include standard.scc
+
+ branch mynewbranch
- include mybsp-hw.scc
+ include mybsp-hw.scc
If you find yourself with numerous branches, you might consider using a
hierarchical branching system similar to what the Yocto Linux Kernel Git
@@ -925,18 +936,20 @@ that have to be regularly updated. The Yocto Project Linux kernel tools
provide for this with the ``git merge`` command.
To merge a feature branch into a BSP, insert the ``git merge`` command
-after any ``branch`` commands::
+after any ``branch`` commands:
- mybsp.scc:
- define KMACHINE mybsp
- define KTYPE standard
- define KARCH i386
- include standard.scc
+.. code-block::
+ :caption: mybsp.scc
+
+ define KMACHINE mybsp
+ define KTYPE standard
+ define KARCH i386
+ include standard.scc
- branch mynewbranch
- git merge myfeature
+ branch mynewbranch
+ git merge myfeature
- include mybsp-hw.scc
+ include mybsp-hw.scc
SCC Description File Reference
==============================
diff --git a/documentation/sphinx-static/theme_overrides.css b/documentation/sphinx-static/theme_overrides.css
index f9e067239b8e..3912872e1890 100644
--- a/documentation/sphinx-static/theme_overrides.css
+++ b/documentation/sphinx-static/theme_overrides.css
@@ -107,6 +107,34 @@ section#welcome-to-the-yocto-project-documentation p.caption {
display: none;
}
+/* A code-block caption names the file the block came from, so it
+ should read as a filename rather than as prose, and sit on the block
+ it titles rather than floating above it. */
+.rst-content .literal-block-wrapper .code-block-caption {
+ font-style: normal;
+ font-family: SFMono-Regular, Menlo, Monaco, Consolas,
+ Liberation Mono, Courier New, Courier, monospace;
+ font-size: 80%;
+ text-align: left;
+ color: #e6edf3;
+ background: #2b3137;
+ padding: .45em .9em;
+ margin: 0;
+ line-height: 1.5;
+ border-radius: 4px 4px 0 0;
+}
+
+.rst-content .literal-block-wrapper .code-block-caption .headerlink {
+ color: #93a1ad;
+}
+
+/* No gap and no doubled border between a caption and its block. */
+.rst-content .literal-block-wrapper .code-block-caption + div[class^=highlight] {
+ margin-top: 0;
+ border-top: none;
+ border-radius: 0 0 4px 4px;
+}
+
@media screen {
.wy-nav-content {
max-width: 1000px;
--
2.50.0.173.g8b6f19ccfc3a
^ permalink raw reply related [flat|nested] 23+ messages in thread* Re: [docs] [PATCH v2 7/8] kernel-dev: give each example block one thing to hold
2026-09-22 18:32 ` [PATCH v2 7/8] kernel-dev: give each example block one thing to hold Trevor Woerner
@ 2026-09-23 11:05 ` Quentin Schulz
0 siblings, 0 replies; 23+ messages in thread
From: Quentin Schulz @ 2026-09-23 11:05 UTC (permalink / raw)
To: twoerner, docs
Hi Trevor,
On 9/22/26 8:32 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> Several kernel metadata examples put a filename label inside the block,
> and some go on to hold more than one file, in more than one language,
> under a single "::". A block shaped that way is not any one language, so
> it can only ever be shown unhighlighted.
>
> Split them into a block each, dedent what is left, and move the
> filename to the code-block caption, which keeps it attached to the block
> it names and renders it inside the block's frame. The theme centres a
> caption in italics, which reads as prose, so it is restyled to look like
> the filename it is.
>
> AI-Generated: codex/claude-opus 5 (xhigh)
> Signed-off-by: Trevor Woerner <twoerner@gmail.com>
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de> # rST
No clue about the CSS part. will let Antonin have a look as he's
reworked some CSS recently if I remember correctly.
Thanks!
Quentin
^ permalink raw reply [flat|nested] 23+ messages in thread
* [PATCH v2 8/8] ref-manual: put the ARCHIVER_MODE comments on their own lines
2026-09-22 18:32 [PATCH v2 0/8] docs: editorial repairs to the examples Trevor Woerner
` (6 preceding siblings ...)
2026-09-22 18:32 ` [PATCH v2 7/8] kernel-dev: give each example block one thing to hold Trevor Woerner
@ 2026-09-22 18:32 ` Trevor Woerner
2026-09-23 11:09 ` [docs] " Quentin Schulz
7 siblings, 1 reply; 23+ messages in thread
From: Trevor Woerner @ 2026-09-22 18:32 UTC (permalink / raw)
To: docs
BitBake has no inline comments. A "#" after a value is not stripped and
does not end the statement: the parser simply fails to match the line, so
each of these varflag examples would be rejected outright if copied into
a configuration file.
Move each explanation to the line above the setting it describes, which
parses and reads the same.
AI-Generated: codex/claude-opus 5 (xhigh)
Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
changes in v2:
- the srpm varflag is no longer in this block, having been removed
upstream in d5216e3fd4be
---
documentation/ref-manual/variables.rst | 21 ++++++++++++++-------
1 file changed, 14 insertions(+), 7 deletions(-)
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 8a9bd9075843..0d7069433bf2 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -158,13 +158,20 @@ system and gives an overview of their function and contents.
original source, configured source, and so forth by employing the
following variable flags (varflags)::
- ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source files.
- ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is the default.
- ARCHIVER_MODE[src] = "configured" # Uses configured source files.
- ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and do_patch.
- ARCHIVER_MODE[diff-exclude] ?= "<file> <file> ..." # Lists files and directories to exclude from diff.
- ARCHIVER_MODE[dumpdata] = "1" # Uses environment data.
- ARCHIVER_MODE[recipe] = "1" # Uses recipe and include files.
+ # Uses original (unpacked) source files.
+ ARCHIVER_MODE[src] = "original"
+ # Uses patched source files. This is the default.
+ ARCHIVER_MODE[src] = "patched"
+ # Uses configured source files.
+ ARCHIVER_MODE[src] = "configured"
+ # Uses patches between do_unpack and do_patch.
+ ARCHIVER_MODE[diff] = "1"
+ # Lists files and directories to exclude from diff.
+ ARCHIVER_MODE[diff-exclude] ?= "<file> <file> ..."
+ # Uses environment data.
+ ARCHIVER_MODE[dumpdata] = "1"
+ # Uses recipe and include files.
+ ARCHIVER_MODE[recipe] = "1"
For information on how the variable works, see the
``meta/classes/archiver.bbclass`` file in :term:`OpenEmbedded-Core
--
2.50.0.173.g8b6f19ccfc3a
^ permalink raw reply related [flat|nested] 23+ messages in thread* Re: [docs] [PATCH v2 8/8] ref-manual: put the ARCHIVER_MODE comments on their own lines
2026-09-22 18:32 ` [PATCH v2 8/8] ref-manual: put the ARCHIVER_MODE comments on their own lines Trevor Woerner
@ 2026-09-23 11:09 ` Quentin Schulz
2026-09-24 15:55 ` Trevor Woerner
0 siblings, 1 reply; 23+ messages in thread
From: Quentin Schulz @ 2026-09-23 11:09 UTC (permalink / raw)
To: twoerner, docs
Hi Trevor,
On 9/22/26 8:32 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> BitBake has no inline comments. A "#" after a value is not stripped and
> does not end the statement: the parser simply fails to match the line, so
> each of these varflag examples would be rejected outright if copied into
> a configuration file.
>
> Move each explanation to the line above the setting it describes, which
> parses and reads the same.
>
> AI-Generated: codex/claude-opus 5 (xhigh)
> Signed-off-by: Trevor Woerner <twoerner@gmail.com>
> ---
> changes in v2:
> - the srpm varflag is no longer in this block, having been removed
> upstream in d5216e3fd4be
> ---
> documentation/ref-manual/variables.rst | 21 ++++++++++++++-------
> 1 file changed, 14 insertions(+), 7 deletions(-)
>
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 8a9bd9075843..0d7069433bf2 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -158,13 +158,20 @@ system and gives an overview of their function and contents.
> original source, configured source, and so forth by employing the
> following variable flags (varflags)::
>
> - ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source files.
> - ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is the default.
> - ARCHIVER_MODE[src] = "configured" # Uses configured source files.
> - ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and do_patch.
> - ARCHIVER_MODE[diff-exclude] ?= "<file> <file> ..." # Lists files and directories to exclude from diff.
> - ARCHIVER_MODE[dumpdata] = "1" # Uses environment data.
> - ARCHIVER_MODE[recipe] = "1" # Uses recipe and include files.
> + # Uses original (unpacked) source files.
> + ARCHIVER_MODE[src] = "original"
> + # Uses patched source files. This is the default.
> + ARCHIVER_MODE[src] = "patched"
> + # Uses configured source files.
> + ARCHIVER_MODE[src] = "configured"
> + # Uses patches between do_unpack and do_patch.
> + ARCHIVER_MODE[diff] = "1"
> + # Lists files and directories to exclude from diff.
> + ARCHIVER_MODE[diff-exclude] ?= "<file> <file> ..."
> + # Uses environment data.
> + ARCHIVER_MODE[dumpdata] = "1"
> + # Uses recipe and include files.
> + ARCHIVER_MODE[recipe] = "1"
>
It probably is also for the best to avoid long lines wherever we can. I
personally would add a newline before each new comment so it is easier
on the eye but that's just a matter of taste.
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
Thanks!
Quentin
^ permalink raw reply [flat|nested] 23+ messages in thread
* Re: [docs] [PATCH v2 8/8] ref-manual: put the ARCHIVER_MODE comments on their own lines
2026-09-23 11:09 ` [docs] " Quentin Schulz
@ 2026-09-24 15:55 ` Trevor Woerner
0 siblings, 0 replies; 23+ messages in thread
From: Trevor Woerner @ 2026-09-24 15:55 UTC (permalink / raw)
To: Quentin Schulz; +Cc: docs
On Wed 2026-09-23 @ 01:09:11 PM, Quentin Schulz wrote:
> Hi Trevor,
>
> On 9/22/26 8:32 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> > BitBake has no inline comments. A "#" after a value is not stripped and
> > does not end the statement: the parser simply fails to match the line, so
> > each of these varflag examples would be rejected outright if copied into
> > a configuration file.
> >
> > Move each explanation to the line above the setting it describes, which
> > parses and reads the same.
> >
> > AI-Generated: codex/claude-opus 5 (xhigh)
> > Signed-off-by: Trevor Woerner <twoerner@gmail.com>
> > ---
> > changes in v2:
> > - the srpm varflag is no longer in this block, having been removed
> > upstream in d5216e3fd4be
> > ---
> > documentation/ref-manual/variables.rst | 21 ++++++++++++++-------
> > 1 file changed, 14 insertions(+), 7 deletions(-)
> >
> > diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> > index 8a9bd9075843..0d7069433bf2 100644
> > --- a/documentation/ref-manual/variables.rst
> > +++ b/documentation/ref-manual/variables.rst
> > @@ -158,13 +158,20 @@ system and gives an overview of their function and contents.
> > original source, configured source, and so forth by employing the
> > following variable flags (varflags)::
> > - ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source files.
> > - ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is the default.
> > - ARCHIVER_MODE[src] = "configured" # Uses configured source files.
> > - ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and do_patch.
> > - ARCHIVER_MODE[diff-exclude] ?= "<file> <file> ..." # Lists files and directories to exclude from diff.
> > - ARCHIVER_MODE[dumpdata] = "1" # Uses environment data.
> > - ARCHIVER_MODE[recipe] = "1" # Uses recipe and include files.
> > + # Uses original (unpacked) source files.
> > + ARCHIVER_MODE[src] = "original"
> > + # Uses patched source files. This is the default.
> > + ARCHIVER_MODE[src] = "patched"
> > + # Uses configured source files.
> > + ARCHIVER_MODE[src] = "configured"
> > + # Uses patches between do_unpack and do_patch.
> > + ARCHIVER_MODE[diff] = "1"
> > + # Lists files and directories to exclude from diff.
> > + ARCHIVER_MODE[diff-exclude] ?= "<file> <file> ..."
> > + # Uses environment data.
> > + ARCHIVER_MODE[dumpdata] = "1"
> > + # Uses recipe and include files.
> > + ARCHIVER_MODE[recipe] = "1"
>
> It probably is also for the best to avoid long lines wherever we can. I
> personally would add a newline before each new comment so it is easier on
> the eye but that's just a matter of taste.
I agree too. I was on the fence about it, but since you flagged it, i'm
happy to make the change.
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
>
> Thanks!
> Quentin
^ permalink raw reply [flat|nested] 23+ messages in thread