* [PATCH] yocto-docs: Some aesthetic changes to kernel-dev-common.xml
@ 2017-02-23 11:08 Robert P. J. Day
2017-02-23 17:36 ` Hart, Darren
0 siblings, 1 reply; 4+ messages in thread
From: Robert P. J. Day @ 2017-02-23 11:08 UTC (permalink / raw)
To: Yocto discussion list; +Cc: Darren Hart
Small number of aesthetic/visual changes to kernel-dev-common.xml.
Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
---
as darren is the author, i'll leave it in his hands to
accept/reject any of this. a lot of this is just subtle rewording
whenever i think there might be the slightest ambiguity, and some
aesthetic prettification. nothing significant.
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index a9aafd3..cb186c9 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -25,10 +25,10 @@
If you are going to be modifying kernel recipes, it is recommended
that you create and prepare your own layer in which to do your
work.
- Your layer contains its own
+ Your layer would typically contain its own
<ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
append files
- (<filename>.bbappend</filename>) and provides a convenient
+ (<filename>.bbappend</filename>) and would provide a convenient
mechanism to create your own recipe files
(<filename>.bb</filename>).
For details on how to create and work with layers, see the following
@@ -59,9 +59,9 @@
<para>
Modifying an existing recipe can consist of the following:
<itemizedlist>
- <listitem><para>Creating the append file</para></listitem>
- <listitem><para>Applying patches</para></listitem>
- <listitem><para>Changing the configuration</para></listitem>
+ <listitem><para>Creating an append file</para></listitem>
+ <listitem><para>Applying some local patches</para></listitem>
+ <listitem><para>Changing the kernel configuration</para></listitem>
</itemizedlist>
</para>
@@ -81,14 +81,14 @@
<para>
You create this file in your custom layer.
- You also name it accordingly based on the linux-yocto recipe
- you are using.
+ You also name it accordingly based on the version of the
+ linux-yocto recipe you are modifying.
For example, if you are modifying the
- <filename>meta/recipes-kernel/linux/linux-yocto_3.19.bb</filename>
- recipe, the append file will typically be located as follows
- within your custom layer:
+ <filename>meta/recipes-kernel/linux/linux-yocto_4.4.bb</filename>
+ recipe, the corresponding append file will typically be located
+ as follows within your custom layer:
<literallayout class='monospaced'>
- <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_3.19.bbappend
+ <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_4.4.bbappend
</literallayout>
The append file should initially extend the
<ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
@@ -133,12 +133,14 @@
<para>
For example, you can apply a three-patch series by adding the
- following lines to your linux-yocto
- <filename>.bbappend</filename> file in your layer:
+ following lines to the linux-yocto
+ <filename>.bbappend</filename> file in your custom layer:
<literallayout class='monospaced'>
- SRC_URI += "file://0001-first-change.patch"
- SRC_URI += "file://0002-second-change.patch"
- SRC_URI += "file://0003-third-change.patch"
+ SRC_URI += " \
+ file://0001-first-change.patch \
+ file://0002-second-change.patch \
+ file://0003-third-change.patch \
+ "
</literallayout>
The next time you run BitBake to build the Linux kernel,
BitBake detects the change in the recipe and fetches and
@@ -158,11 +160,12 @@
<para>
You can make wholesale or incremental changes to the final
<filename>.config</filename> file used for the eventual
- Linux kernel configuration by including a
- <filename>defconfig</filename> file and by specifying
+ Linux kernel configuration by including a local
+ <filename>defconfig</filename> file, as well as by specifying
configuration fragments in the
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- to be applied to that file.
+ to be applied to the configuration defined by that
+ <filename>defconfig</filename> file.
</para>
<para>
@@ -204,10 +207,10 @@
<para>
Generally speaking, the preferred approach is to determine the
- incremental change you want to make and add that as a
- configuration fragment.
- For example, if you want to add support for a basic serial
- console, create a file named <filename>8250.cfg</filename> in
+ incremental changes you want to make and add each of those changes
+ using a separate configuration fragment.
+ For example, if you want to add support for a basic (8250 UART-based) serial
+ console, create a file named, for example, <filename>8250.cfg</filename> in
the <filename>${PN}</filename> directory with the following
content (without indentation):
<literallayout class='monospaced'>
@@ -219,7 +222,7 @@
CONFIG_SERIAL_CORE=y
CONFIG_SERIAL_CORE_CONSOLE=y
</literallayout>
- Next, include this configuration fragment and extend the
+ Next, include this configuration fragment and (as before) extend the
<filename>FILESPATH</filename> variable in your
<filename>.bbappend</filename> file:
<literallayout class='monospaced'>
@@ -231,6 +234,17 @@
new configuration before building the kernel.
</para>
+ <note>
+ Depending on the kernel config fragment you are adding, it might not be
+ necessary to specify every single setting related to what you want.
+ For instance, in the above example, once you select
+ <varname>CONFIG_SERIAL_8250=y</varname>, some of the subsequent config
+ settings might be set based on default values in the kernel's
+ corresponding <varname>Kconfig</varname>
+ file. However, some developers prefer to list everything related to
+ the selected feature for the sake of completeness and clarity.
+ </note>
+
<para>
For a detailed example showing how to configure the kernel,
see the
@@ -270,7 +284,7 @@
edit the recipe that builds your kernel so that it has the
following command form:
<literallayout class='monospaced'>
- KBUILD_DEFCONFIG_KMACHINE ?= <replaceable>defconfig_file</replaceable>
+ KBUILD_DEFCONFIG_<replaceable>KMACHINE</replaceable> ?= <replaceable>defconfig_file</replaceable>
</literallayout>
You need to append the variable with
<ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>
--
========================================================================
Robert P. J. Day Ottawa, Ontario, CANADA
http://crashcourse.ca
Twitter: http://twitter.com/rpjday
LinkedIn: http://ca.linkedin.com/in/rpjday
========================================================================
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: [PATCH] yocto-docs: Some aesthetic changes to kernel-dev-common.xml
2017-02-23 11:08 [PATCH] yocto-docs: Some aesthetic changes to kernel-dev-common.xml Robert P. J. Day
@ 2017-02-23 17:36 ` Hart, Darren
2017-02-23 17:39 ` Robert P. J. Day
0 siblings, 1 reply; 4+ messages in thread
From: Hart, Darren @ 2017-02-23 17:36 UTC (permalink / raw)
To: Robert P. J. Day, Yocto discussion list
> -----Original Message-----
> From: Robert P. J. Day [mailto:rpjday@crashcourse.ca]
> Sent: Thursday, February 23, 2017 3:08 AM
> To: Yocto discussion list <yocto@yoctoproject.org>
> Cc: Hart, Darren <darren.hart@intel.com>
> Subject: [PATCH] yocto-docs: Some aesthetic changes to kernel-dev-
> common.xml
>
>
> Small number of aesthetic/visual changes to kernel-dev-common.xml.
>
Erm... that's not really what these are :-) These are a mix of grammatical fixes, format preferences, and clarifying commentary, which do amount to some functional changes in terms of what a reader may do or not do as a result of reading them. Please be explicit in your commit log.
That said, I have no objections to these changes, the majority of which I consider to be good improvements. Thanks for taking the time to improve the documentation.
> Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
Reviewed-by: Darren Hart <dvhart@linux.intel.com>
>
> ---
>
> as darren is the author, i'll leave it in his hands to
> accept/reject any of this. a lot of this is just subtle rewording
> whenever i think there might be the slightest ambiguity, and some
> aesthetic prettification. nothing significant.
>
> diff --git a/documentation/kernel-dev/kernel-dev-common.xml
> b/documentation/kernel-dev/kernel-dev-common.xml
> index a9aafd3..cb186c9 100644
> --- a/documentation/kernel-dev/kernel-dev-common.xml
> +++ b/documentation/kernel-dev/kernel-dev-common.xml
> @@ -25,10 +25,10 @@
> If you are going to be modifying kernel recipes, it is recommended
> that you create and prepare your own layer in which to do your
> work.
> - Your layer contains its own
> + Your layer would typically contain its own
> <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-
> term'>BitBake</ulink>
> append files
> - (<filename>.bbappend</filename>) and provides a convenient
> + (<filename>.bbappend</filename>) and would provide a
> convenient
> mechanism to create your own recipe files
> (<filename>.bb</filename>).
> For details on how to create and work with layers, see the
> following
> @@ -59,9 +59,9 @@
> <para>
> Modifying an existing recipe can consist of the following:
> <itemizedlist>
> - <listitem><para>Creating the append file</para></listitem>
> - <listitem><para>Applying patches</para></listitem>
> - <listitem><para>Changing the configuration</para></listitem>
> + <listitem><para>Creating an append file</para></listitem>
> + <listitem><para>Applying some local
> patches</para></listitem>
> + <listitem><para>Changing the kernel
> configuration</para></listitem>
> </itemizedlist>
> </para>
>
> @@ -81,14 +81,14 @@
>
> <para>
> You create this file in your custom layer.
> - You also name it accordingly based on the linux-yocto recipe
> - you are using.
> + You also name it accordingly based on the version of the
> + linux-yocto recipe you are modifying.
> For example, if you are modifying the
> - <filename>meta/recipes-kernel/linux/linux-
> yocto_3.19.bb</filename>
> - recipe, the append file will typically be located as follows
> - within your custom layer:
> + <filename>meta/recipes-kernel/linux/linux-
> yocto_4.4.bb</filename>
> + recipe, the corresponding append file will typically be located
> + as follows within your custom layer:
> <literallayout class='monospaced'>
> - <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-
> yocto_3.19.bbappend
> + <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-
> yocto_4.4.bbappend
> </literallayout>
> The append file should initially extend the
> <ulink url='&YOCTO_DOCS_REF_URL;#var-
> FILESPATH'><filename>FILESPATH</filename></ulink>
> @@ -133,12 +133,14 @@
>
> <para>
> For example, you can apply a three-patch series by adding the
> - following lines to your linux-yocto
> - <filename>.bbappend</filename> file in your layer:
> + following lines to the linux-yocto
> + <filename>.bbappend</filename> file in your custom layer:
> <literallayout class='monospaced'>
> - SRC_URI += "file://0001-first-change.patch"
> - SRC_URI += "file://0002-second-change.patch"
> - SRC_URI += "file://0003-third-change.patch"
> + SRC_URI += " \
> + file://0001-first-change.patch \
> + file://0002-second-change.patch \
> + file://0003-third-change.patch \
> + "
> </literallayout>
> The next time you run BitBake to build the Linux kernel,
> BitBake detects the change in the recipe and fetches and
> @@ -158,11 +160,12 @@
> <para>
> You can make wholesale or incremental changes to the final
> <filename>.config</filename> file used for the eventual
> - Linux kernel configuration by including a
> - <filename>defconfig</filename> file and by specifying
> + Linux kernel configuration by including a local
> + <filename>defconfig</filename> file, as well as by specifying
> configuration fragments in the
> <ulink url='&YOCTO_DOCS_REF_URL;#var-
> SRC_URI'><filename>SRC_URI</filename></ulink>
> - to be applied to that file.
> + to be applied to the configuration defined by that
> + <filename>defconfig</filename> file.
> </para>
>
> <para>
> @@ -204,10 +207,10 @@
>
> <para>
> Generally speaking, the preferred approach is to determine the
> - incremental change you want to make and add that as a
> - configuration fragment.
> - For example, if you want to add support for a basic serial
> - console, create a file named <filename>8250.cfg</filename> in
> + incremental changes you want to make and add each of those
> changes
> + using a separate configuration fragment.
> + For example, if you want to add support for a basic (8250 UART-
> based) serial
> + console, create a file named, for example,
> <filename>8250.cfg</filename> in
> the <filename>${PN}</filename> directory with the following
> content (without indentation):
> <literallayout class='monospaced'>
> @@ -219,7 +222,7 @@
> CONFIG_SERIAL_CORE=y
> CONFIG_SERIAL_CORE_CONSOLE=y
> </literallayout>
> - Next, include this configuration fragment and extend the
> + Next, include this configuration fragment and (as before)
> extend the
> <filename>FILESPATH</filename> variable in your
> <filename>.bbappend</filename> file:
> <literallayout class='monospaced'>
> @@ -231,6 +234,17 @@
> new configuration before building the kernel.
> </para>
>
> + <note>
> + Depending on the kernel config fragment you are adding, it
> might not be
> + necessary to specify every single setting related to what you
> want.
> + For instance, in the above example, once you select
> + <varname>CONFIG_SERIAL_8250=y</varname>, some of the
> subsequent config
> + settings might be set based on default values in the kernel's
> + corresponding <varname>Kconfig</varname>
> + file. However, some developers prefer to list everything related
> to
> + the selected feature for the sake of completeness and clarity.
> + </note>
> +
> <para>
> For a detailed example showing how to configure the kernel,
> see the
> @@ -270,7 +284,7 @@
> edit the recipe that builds your kernel so that it has the
> following command form:
> <literallayout class='monospaced'>
> - KBUILD_DEFCONFIG_KMACHINE ?=
> <replaceable>defconfig_file</replaceable>
> + KBUILD_DEFCONFIG_<replaceable>KMACHINE</replaceable> ?=
> <replaceable>defconfig_file</replaceable>
> </literallayout>
> You need to append the variable with
> <ulink url='&YOCTO_DOCS_REF_URL;#var-
> KMACHINE'><filename>KMACHINE</filename></ulink>
>
> --
>
> =======================================================
> =================
> Robert P. J. Day Ottawa, Ontario, CANADA
> http://crashcourse.ca
>
> Twitter: http://twitter.com/rpjday
> LinkedIn: http://ca.linkedin.com/in/rpjday
> =======================================================
> =================
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH] yocto-docs: Some aesthetic changes to kernel-dev-common.xml
2017-02-23 17:36 ` Hart, Darren
@ 2017-02-23 17:39 ` Robert P. J. Day
2017-02-23 17:44 ` Hart, Darren
0 siblings, 1 reply; 4+ messages in thread
From: Robert P. J. Day @ 2017-02-23 17:39 UTC (permalink / raw)
To: Hart, Darren; +Cc: Yocto discussion list
On Thu, 23 Feb 2017, Hart, Darren wrote:
> > -----Original Message-----
> > From: Robert P. J. Day [mailto:rpjday@crashcourse.ca]
> > Sent: Thursday, February 23, 2017 3:08 AM
> > To: Yocto discussion list <yocto@yoctoproject.org>
> > Cc: Hart, Darren <darren.hart@intel.com>
> > Subject: [PATCH] yocto-docs: Some aesthetic changes to kernel-dev-
> > common.xml
> >
> >
> > Small number of aesthetic/visual changes to kernel-dev-common.xml.
> >
>
> Erm... that's not really what these are :-) These are a mix of
> grammatical fixes, format preferences, and clarifying commentary,
> which do amount to some functional changes in terms of what a reader
> may do or not do as a result of reading them. Please be explicit in
> your commit log.
>
> That said, I have no objections to these changes, the majority of
> which I consider to be good improvements. Thanks for taking the time
> to improve the documentation.
so i should resubmit PATCH v2 with a more detailed commit msg? ok, i
can do that. stay tuned ...
rday
--
========================================================================
Robert P. J. Day Ottawa, Ontario, CANADA
http://crashcourse.ca
Twitter: http://twitter.com/rpjday
LinkedIn: http://ca.linkedin.com/in/rpjday
========================================================================
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: [PATCH] yocto-docs: Some aesthetic changes to kernel-dev-common.xml
2017-02-23 17:39 ` Robert P. J. Day
@ 2017-02-23 17:44 ` Hart, Darren
0 siblings, 0 replies; 4+ messages in thread
From: Hart, Darren @ 2017-02-23 17:44 UTC (permalink / raw)
To: Robert P. J. Day; +Cc: Yocto discussion list
> -----Original Message-----
> From: Robert P. J. Day [mailto:rpjday@crashcourse.ca]
> Sent: Thursday, February 23, 2017 9:40 AM
> To: Hart, Darren <darren.hart@intel.com>
> Cc: Yocto discussion list <yocto@yoctoproject.org>
> Subject: RE: [PATCH] yocto-docs: Some aesthetic changes to kernel-dev-
> common.xml
>
> On Thu, 23 Feb 2017, Hart, Darren wrote:
>
> > > -----Original Message-----
> > > From: Robert P. J. Day [mailto:rpjday@crashcourse.ca]
> > > Sent: Thursday, February 23, 2017 3:08 AM
> > > To: Yocto discussion list <yocto@yoctoproject.org>
> > > Cc: Hart, Darren <darren.hart@intel.com>
> > > Subject: [PATCH] yocto-docs: Some aesthetic changes to kernel-dev-
> > > common.xml
> > >
> > >
> > > Small number of aesthetic/visual changes to kernel-dev-
> common.xml.
> > >
> >
> > Erm... that's not really what these are :-) These are a mix of
> > grammatical fixes, format preferences, and clarifying commentary,
> > which do amount to some functional changes in terms of what a reader
> > may do or not do as a result of reading them. Please be explicit in
> > your commit log.
> >
> > That said, I have no objections to these changes, the majority of
> > which I consider to be good improvements. Thanks for taking the time
> > to improve the documentation.
>
> so i should resubmit PATCH v2 with a more detailed commit msg? ok, i
> can do that. stay tuned ...
That is ultimately up to the maintainer who could decide to update the message
themselves, or require a v2 from you. If it were me, I would just submit a v2
with an updated commit message as that is likely the fastest path to merging,
and you are sure to get your intent captured.
Thanks!
--
Darren Hart
Intel Open Source Technology Center
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2017-02-23 17:45 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-02-23 11:08 [PATCH] yocto-docs: Some aesthetic changes to kernel-dev-common.xml Robert P. J. Day
2017-02-23 17:36 ` Hart, Darren
2017-02-23 17:39 ` Robert P. J. Day
2017-02-23 17:44 ` Hart, Darren
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.