[Buildroot] [PATCH 0/2] Manual updates

[Buildroot] [PATCH 0/2] Manual updates

[Fiona Klute via buildroot]

From: "Fiona Klute (WIWA)" <fiona.klute@gmx.de>

These two patches integrate points that Arnout Vandecappelle clarified
on the mailing list in replies to me into the manual. I hope I didn't
add any errors in rephrasing them, please let me know if anything
needs to be changed.

Best regards,
Fiona

Fiona Klute (WIWA) (2):
  docs/manual: describe relying on default options
  docs/manual: allow sponsor mention in author name

 docs/manual/contribute.adoc             |  4 ++++
 docs/manual/integration-principles.adoc | 18 ++++++++++++++++++
 docs/manual/integration.adoc            |  2 ++
 3 files changed, 24 insertions(+)
 create mode 100644 docs/manual/integration-principles.adoc

--
2.45.2

_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot

[Buildroot] [PATCH 1/2] docs/manual: describe relying on default options

[Fiona Klute via buildroot]

From: "Fiona Klute (WIWA)" <fiona.klute@gmx.de>

People can assume that e.g. Busybox options enabled in the package are
enabled when writing code for Buildroot. Anyone who uses custom
configurations that disable default options needs to make sure
relevant scripts etc. still work for themselves.

Signed-off-by: Fiona Klute (WIWA) <fiona.klute@gmx.de>
---
 docs/manual/integration-principles.adoc | 18 ++++++++++++++++++
 docs/manual/integration.adoc            |  2 ++
 2 files changed, 20 insertions(+)
 create mode 100644 docs/manual/integration-principles.adoc

diff --git a/docs/manual/integration-principles.adoc b/docs/manual/integration-principles.adoc
new file mode 100644
index 0000000000..9e2f43a18a
--- /dev/null
+++ b/docs/manual/integration-principles.adoc
@@ -0,0 +1,18 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[integration-principles]]
+=== Integration Principles
+
+Some foundational packages like Busybox can be configured with or
+without certain features. When writing Buildroot code that uses such
+packages, contributors may assume that the options enabled in the
+Buildroot-provided configurations are enabled. For example,
++package/busybox/busybox.config+ sets
++CONFIG_FEATURE_START_STOP_DAEMON_LONG_OPTIONS=y+, so init scripts
+meant for use with Busybox init may use +start-stop-daemon+ with long
+form options.
+
+People who use custom configurations that disable such default options
+are responsible for making sure that all relevant scripts still work,
+and if not, adapting them accordingly (in an overlay).
diff --git a/docs/manual/integration.adoc b/docs/manual/integration.adoc
index 1626dd75dd..5f408dca29 100644
--- a/docs/manual/integration.adoc
+++ b/docs/manual/integration.adoc
@@ -9,6 +9,8 @@ level. Buildroot is highly configurable, almost everything discussed
 here can be changed or overridden by xref:rootfs-custom[rootfs overlay
 or custom skeleton] configuration.

+include::integration-principles.adoc[]
+
 include::integration-systemd.adoc[]

 include::integration-selinux-support.adoc[]
--
2.45.2

_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot

Re: [Buildroot] [PATCH 1/2] docs/manual: describe relying on default options

[Thomas Petazzoni via buildroot]

On Fri,  5 Jul 2024 11:44:48 +0200
Fiona Klute via buildroot <buildroot@buildroot.org> wrote:

> From: "Fiona Klute (WIWA)" <fiona.klute@gmx.de>
> 
> People can assume that e.g. Busybox options enabled in the package are
> enabled when writing code for Buildroot. Anyone who uses custom
> configurations that disable default options needs to make sure
> relevant scripts etc. still work for themselves.
> 
> Signed-off-by: Fiona Klute (WIWA) <fiona.klute@gmx.de>
> ---
>  docs/manual/integration-principles.adoc | 18 ++++++++++++++++++
>  docs/manual/integration.adoc            |  2 ++
>  2 files changed, 20 insertions(+)
>  create mode 100644 docs/manual/integration-principles.adoc
> 
> diff --git a/docs/manual/integration-principles.adoc b/docs/manual/integration-principles.adoc
> new file mode 100644
> index 0000000000..9e2f43a18a
> --- /dev/null
> +++ b/docs/manual/integration-principles.adoc
> @@ -0,0 +1,18 @@
> +// -*- mode:doc; -*-
> +// vim: set syntax=asciidoc:
> +
> +[[integration-principles]]
> +=== Integration Principles
> +
> +Some foundational packages like Busybox can be configured with or
> +without certain features. When writing Buildroot code that uses such
> +packages, contributors may assume that the options enabled in the
> +Buildroot-provided configurations are enabled. For example,
> ++package/busybox/busybox.config+ sets
> ++CONFIG_FEATURE_START_STOP_DAEMON_LONG_OPTIONS=y+, so init scripts
> +meant for use with Busybox init may use +start-stop-daemon+ with long
> +form options.
> +
> +People who use custom configurations that disable such default options
> +are responsible for making sure that all relevant scripts still work,
> +and if not, adapting them accordingly (in an overlay).

I understand the wish to document this, but I'm not sure an
"Integration principles" is the right place. Shouldn't we document that
in a section where we document the expectations in terms of init
scripts instead?

Best regards,

Thomas
-- 
Thomas Petazzoni, co-owner and CEO, Bootlin
Embedded Linux and Kernel engineering and training
https://bootlin.com
_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot

Re: [Buildroot] [PATCH 1/2] docs/manual: describe relying on default options

[Fiona Klute via buildroot]

Am 08.07.24 um 23:11 schrieb Thomas Petazzoni:
> On Fri,  5 Jul 2024 11:44:48 +0200
> Fiona Klute via buildroot <buildroot@buildroot.org> wrote:
>
>> From: "Fiona Klute (WIWA)" <fiona.klute@gmx.de>
>>
>> People can assume that e.g. Busybox options enabled in the package are
>> enabled when writing code for Buildroot. Anyone who uses custom
>> configurations that disable default options needs to make sure
>> relevant scripts etc. still work for themselves.
>>
>> Signed-off-by: Fiona Klute (WIWA) <fiona.klute@gmx.de>
>> ---
>>   docs/manual/integration-principles.adoc | 18 ++++++++++++++++++
>>   docs/manual/integration.adoc            |  2 ++
>>   2 files changed, 20 insertions(+)
>>   create mode 100644 docs/manual/integration-principles.adoc
>>
>> diff --git a/docs/manual/integration-principles.adoc b/docs/manual/integration-principles.adoc
>> new file mode 100644
>> index 0000000000..9e2f43a18a
>> --- /dev/null
>> +++ b/docs/manual/integration-principles.adoc
>> @@ -0,0 +1,18 @@
>> +// -*- mode:doc; -*-
>> +// vim: set syntax=asciidoc:
>> +
>> +[[integration-principles]]
>> +=== Integration Principles
>> +
>> +Some foundational packages like Busybox can be configured with or
>> +without certain features. When writing Buildroot code that uses such
>> +packages, contributors may assume that the options enabled in the
>> +Buildroot-provided configurations are enabled. For example,
>> ++package/busybox/busybox.config+ sets
>> ++CONFIG_FEATURE_START_STOP_DAEMON_LONG_OPTIONS=y+, so init scripts
>> +meant for use with Busybox init may use +start-stop-daemon+ with long
>> +form options.
>> +
>> +People who use custom configurations that disable such default options
>> +are responsible for making sure that all relevant scripts still work,
>> +and if not, adapting them accordingly (in an overlay).
>
> I understand the wish to document this, but I'm not sure an
> "Integration principles" is the right place. Shouldn't we document that
> in a section where we document the expectations in terms of init
> scripts instead?

Arnout explicitly requested I put it there in this mail:
https://lore.kernel.org/buildroot/6d02d2d5-e71e-45b3-a447-e81521085e7a@mind.be/

I'm happy to respin and put it elsewhere, but I'd like to avoid a back
and forth between two maintainers telling me different things, so I'd
appreciate if you could find an agreement before I do.

Best regards,
Fiona

_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot

Re: [Buildroot] [PATCH 1/2] docs/manual: describe relying on default options

[Thomas Petazzoni via buildroot]

On Tue, 9 Jul 2024 10:38:13 +0200
Fiona Klute <fiona.klute@gmx.de> wrote:

> > I understand the wish to document this, but I'm not sure an
> > "Integration principles" is the right place. Shouldn't we document that
> > in a section where we document the expectations in terms of init
> > scripts instead?  
> 
> Arnout explicitly requested I put it there in this mail:
> https://lore.kernel.org/buildroot/6d02d2d5-e71e-45b3-a447-e81521085e7a@mind.be/

Ah crap :-)

> I'm happy to respin and put it elsewhere, but I'd like to avoid a back
> and forth between two maintainers telling me different things, so I'd
> appreciate if you could find an agreement before I do.

You're absolutely right obviously.

I don't have a strong opinion, but I think
section https://buildroot.org/downloads/manual/manual.html#adding-packages-start-script
makes more sense, as it's actually close to where it matters. Arnout?

Thomas
-- 
Thomas Petazzoni, co-owner and CEO, Bootlin
Embedded Linux and Kernel engineering and training
https://bootlin.com
_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot

Re: [Buildroot] [PATCH 1/2] docs/manual: describe relying on default options

[Arnout Vandecappelle via buildroot]

On 09/07/2024 11:37, Thomas Petazzoni wrote:
> On Tue, 9 Jul 2024 10:38:13 +0200
> Fiona Klute <fiona.klute@gmx.de> wrote:
> 
>>> I understand the wish to document this, but I'm not sure an
>>> "Integration principles" is the right place. Shouldn't we document that
>>> in a section where we document the expectations in terms of init
>>> scripts instead?
>>
>> Arnout explicitly requested I put it there in this mail:
>> https://lore.kernel.org/buildroot/6d02d2d5-e71e-45b3-a447-e81521085e7a@mind.be/
> 
> Ah crap :-)
> 
>> I'm happy to respin and put it elsewhere, but I'd like to avoid a back
>> and forth between two maintainers telling me different things, so I'd
>> appreciate if you could find an agreement before I do.
> 
> You're absolutely right obviously.
> 
> I don't have a strong opinion, but I think
> section https://buildroot.org/downloads/manual/manual.html#adding-packages-start-script
> makes more sense, as it's actually close to where it matters. Arnout?

  The init scripts are just an example here, the principle applies more in 
general. It also applies to e.g. ifupdown scripts, or even systemd unit files 
(e.g. if a systemd unit file needs some ExecStartPre command). That's why I 
thought that the start script was not the most appropriate place.

  Regards,
  Arnout
_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot

Re: [Buildroot] [PATCH 1/2] docs/manual: describe relying on default options

[Thomas Petazzoni via buildroot]

On Tue, 9 Jul 2024 12:13:08 +0200
Arnout Vandecappelle <arnout@mind.be> wrote:

> > I don't have a strong opinion, but I think
> > section https://buildroot.org/downloads/manual/manual.html#adding-packages-start-script
> > makes more sense, as it's actually close to where it matters. Arnout?  
> 
>   The init scripts are just an example here, the principle applies more in 
> general. It also applies to e.g. ifupdown scripts, or even systemd unit files 
> (e.g. if a systemd unit file needs some ExecStartPre command). That's why I 
> thought that the start script was not the most appropriate place.

ACK. But then perhaps the discussion can be extended beyond Busybox.
For example for uClibc-ng, we also assume it is built with our default
configuration, and don't try to support the myriad of possible
uClibc-ng configurations.

Thomas
-- 
Thomas Petazzoni, co-owner and CEO, Bootlin
Embedded Linux and Kernel engineering and training
https://bootlin.com
_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot

Re: [Buildroot] [PATCH 1/2] docs/manual: describe relying on default options

[Fiona Klute via buildroot]

Am 09.07.24 um 13:57 schrieb Thomas Petazzoni:
> On Tue, 9 Jul 2024 12:13:08 +0200
> Arnout Vandecappelle <arnout@mind.be> wrote:
>
>>> I don't have a strong opinion, but I think
>>> section https://buildroot.org/downloads/manual/manual.html#adding-packages-start-script
>>> makes more sense, as it's actually close to where it matters. Arnout?
>>
>>    The init scripts are just an example here, the principle applies more in
>> general. It also applies to e.g. ifupdown scripts, or even systemd unit files
>> (e.g. if a systemd unit file needs some ExecStartPre command). That's why I
>> thought that the start script was not the most appropriate place.
>
> ACK. But then perhaps the discussion can be extended beyond Busybox.
> For example for uClibc-ng, we also assume it is built with our default
> configuration, and don't try to support the myriad of possible
> uClibc-ng configurations.

I've tried to make clearer that it's a general thing, with Busybox being
an example (patch 1 in the "Update init script style" series I just
sent). I hope that works.

Best regards,
Fiona

_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot

[Buildroot] [PATCH 2/2] docs/manual: allow sponsor mention in author name

[Fiona Klute via buildroot]

From: "Fiona Klute (WIWA)" <fiona.klute@gmx.de>

Unfortunately not all mail providers deliver mails with subaddressing,
mention people can acknowledge a sponsor in the author name instead.

Signed-off-by: Fiona Klute (WIWA) <fiona.klute@gmx.de>
---
 docs/manual/contribute.adoc | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/manual/contribute.adoc b/docs/manual/contribute.adoc
index c88035597e..078725ef56 100644
--- a/docs/manual/contribute.adoc
+++ b/docs/manual/contribute.adoc
@@ -264,6 +264,10 @@ separated from it by a plus `+` sign. E.g.:
 +
 `Your-Name Your-Surname <your-name.your-surname+their-name.their-surname@mail.com>`

+Alternatively, especially if your email server does not support
+subaddressing, you can include the sponsor in your author name in
+parentheses, e.g. "Your Name (Sponsor Name)".
+
 When adding new packages, you should submit every package in a
 separate patch. This patch should have the update to
 +package/Config.in+, the package +Config.in+ file, the +.mk+ file, the
--
2.45.2

_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot

Re: [Buildroot] [PATCH 2/2] docs/manual: allow sponsor mention in author name

[Thomas Petazzoni via buildroot]

On Fri,  5 Jul 2024 11:44:49 +0200
Fiona Klute via buildroot <buildroot@buildroot.org> wrote:

> From: "Fiona Klute (WIWA)" <fiona.klute@gmx.de>
> 
> Unfortunately not all mail providers deliver mails with subaddressing,
> mention people can acknowledge a sponsor in the author name instead.
> 
> Signed-off-by: Fiona Klute (WIWA) <fiona.klute@gmx.de>
> ---
>  docs/manual/contribute.adoc | 4 ++++
>  1 file changed, 4 insertions(+)

Applied to master, thanks.

Thomas
-- 
Thomas Petazzoni, CTO, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
_______________________________________________
buildroot mailing list
buildroot@buildroot.org
https://lists.buildroot.org/mailman/listinfo/buildroot