Patchwork [1/2] docs/manual: enhance doc for BR2_TOOLCHAIN_HEADERS_AT_LEAST_X_Y

login
register
mail settings
Submitter Yann E. MORIN
Date July 25, 2014, 9:28 p.m.
Message ID <f8aa686b6618867afc2725a276beb75a63e8ca12.1406323367.git.yann.morin.1998@free.fr>
Download mbox | patch
Permalink /patch/373813/
State Accepted
Headers show

Comments

Yann E. MORIN - July 25, 2014, 9:28 p.m.
The BR2_TOOLCHAIN_HEADERS_AT_LEAST_X_Y symbols can be used to denote the
lowest required kernel headers version, but also the highest supported
version. Document that.

Use the `...` construct instead of +...+ used eveywhere else, otherwise
asciidoc would render +<=+ to the ⇐ arrow, while `...` does no rendering
at all.

Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
---
 docs/manual/adding-packages-directory.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Thomas De Schampheleire - July 26, 2014, 6:25 p.m.
On Fri, Jul 25, 2014 at 11:28 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> The BR2_TOOLCHAIN_HEADERS_AT_LEAST_X_Y symbols can be used to denote the
> lowest required kernel headers version, but also the highest supported
> version. Document that.
>
> Use the `...` construct instead of +...+ used eveywhere else, otherwise
> asciidoc would render +<=+ to the ⇐ arrow, while `...` does no rendering
> at all.
>
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> ---
>  docs/manual/adding-packages-directory.txt | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
> index c2f0a1a..93e6a3e 100644
> --- a/docs/manual/adding-packages-directory.txt
> +++ b/docs/manual/adding-packages-directory.txt
> @@ -222,8 +222,8 @@ use in the comment.
>  * Kernel headers
>  ** Dependency symbol: +BR2_TOOLCHAIN_HEADERS_AT_LEAST_X_Y+, (replace
>     +X_Y+ with the proper version, see +toolchain/toolchain-common.in+)
> -** Comment string: +headers >= X.Y+ (replace +X.Y+ with the
> -   proper version)
> +** Comment string: +headers >= X.Y+ and/or `headers <= X.Y` (replace
> +   +X.Y+ with the proper version)
>
>  * C library
>  ** Dependency symbol: +BR2_TOOLCHAIN_USES_GLIBC+,

Acked-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Thomas Petazzoni - July 27, 2014, 12:34 p.m.
Dear Yann E. MORIN,

On Fri, 25 Jul 2014 23:28:14 +0200, Yann E. MORIN wrote:
> The BR2_TOOLCHAIN_HEADERS_AT_LEAST_X_Y symbols can be used to denote the
> lowest required kernel headers version, but also the highest supported
> version. Document that.

I'm honestly really unsure about this. Kernel headers expose the kernel
to userspace API, and this API is supposed to be backward compatible.
Therefore, I don't see why we should document the idea of expressing on
dependency on a highest kernel header version.

The v4l2 example we had on freescale seems like an API that shouldn't
have been part of the kernel to userspace API, and therefore shouldn't
be used by userspace libraries/applications.

Therefore, I'm tempted to say no to this patch, but I'm interested to
be convince otherwise :)

Thomas
Yann E. MORIN - July 27, 2014, 12:49 p.m.
Thomas, All,

On 2014-07-27 14:34 +0200, Thomas Petazzoni spake thusly:
> On Fri, 25 Jul 2014 23:28:14 +0200, Yann E. MORIN wrote:
> > The BR2_TOOLCHAIN_HEADERS_AT_LEAST_X_Y symbols can be used to denote the
> > lowest required kernel headers version, but also the highest supported
> > version. Document that.
> 
> I'm honestly really unsure about this. Kernel headers expose the kernel
> to userspace API, and this API is supposed to be backward compatible.
> Therefore, I don't see why we should document the idea of expressing on
> dependency on a highest kernel header version.
> 
> The v4l2 example we had on freescale seems like an API that shouldn't
> have been part of the kernel to userspace API, and therefore shouldn't
> be used by userspace libraries/applications.
> 
> Therefore, I'm tempted to say no to this patch, but I'm interested to
> be convince otherwise :)

Well, APIs can get deprecated over time, and eventually removed. For
example, the status of interfaces is described in Documentation/ABI in
your favourite kernel source tree.

So, yes, I still think this patch is valid.

Regards,
Yann E. MORIN.
Thomas Petazzoni - July 27, 2014, 1:04 p.m.
Dear Yann E. MORIN,

On Sun, 27 Jul 2014 14:49:00 +0200, Yann E. MORIN wrote:

> > Therefore, I'm tempted to say no to this patch, but I'm interested to
> > be convince otherwise :)
> 
> Well, APIs can get deprecated over time, and eventually removed. For
> example, the status of interfaces is described in Documentation/ABI in
> your favourite kernel source tree.

Yeah, well, that's true. Even though that tends to happen very rarely
and generally for very rarely used interfaces.

> So, yes, I still think this patch is valid.

Ok, fair enough :)

Thomas
Thomas Petazzoni - July 27, 2014, 1:08 p.m.
Dear Yann E. MORIN,

On Fri, 25 Jul 2014 23:28:14 +0200, Yann E. MORIN wrote:
> The BR2_TOOLCHAIN_HEADERS_AT_LEAST_X_Y symbols can be used to denote the
> lowest required kernel headers version, but also the highest supported
> version. Document that.
> 
> Use the `...` construct instead of +...+ used eveywhere else, otherwise
> asciidoc would render +<=+ to the ⇐ arrow, while `...` does no rendering
> at all.
> 
> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
> ---
>  docs/manual/adding-packages-directory.txt | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)

Applied, thanks.

Thomas

Patch

diff --git a/docs/manual/adding-packages-directory.txt b/docs/manual/adding-packages-directory.txt
index c2f0a1a..93e6a3e 100644
--- a/docs/manual/adding-packages-directory.txt
+++ b/docs/manual/adding-packages-directory.txt
@@ -222,8 +222,8 @@  use in the comment.
 * Kernel headers
 ** Dependency symbol: +BR2_TOOLCHAIN_HEADERS_AT_LEAST_X_Y+, (replace
    +X_Y+ with the proper version, see +toolchain/toolchain-common.in+)
-** Comment string: +headers >= X.Y+ (replace +X.Y+ with the
-   proper version)
+** Comment string: +headers >= X.Y+ and/or `headers <= X.Y` (replace
+   +X.Y+ with the proper version)
 
 * C library
 ** Dependency symbol: +BR2_TOOLCHAIN_USES_GLIBC+,