Re: [yocto] [PATCH v2] yocto-docs: kernel-dev, Aesthetic/formatting/clarification fixes

[Hart, Darren]

> -Original Message-
> From: Robert P. J. Day [mailto:rpj...@crashcourse.ca]
> Sent: Thursday, February 23, 2017 9:45 AM
> To: Yocto discussion list 
> Cc: Hart, Darren 
> Subject: [PATCH v2] yocto-docs: kernel-dev,
> Aesthetic/formatting/clarification fixes
> 
> 
> A variety of tweaks to kernel-dev manual, section
> kernel-dev-common.xml, which include:
> 
> * adding extra text in places to clarify possibly ambiguous content
> * some formatting changes related to font and overly long lines
> * update some old version numbers that don't even exist anymore
> 
> Signed-off-by: Robert P. J. Day 

Thanks Robert!

Reviewed-by: Darren Hart 

--
Darren Hart
Intel Open Source Technology Center

> 
> ---
> 
> 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
>  BitBake
>  append files
> -(.bbappend) and provides a convenient
> +(.bbappend) and would provide a
> convenient
>  mechanism to create your own recipe files
>  (.bb).
>  For details on how to create and work with layers, see the
> following
> @@ -59,9 +59,9 @@
>  
>  Modifying an existing recipe can consist of the following:
>  
> -Creating the append file
> -Applying patches
> -Changing the configuration
> +Creating an append file
> +Applying some local
> patches
> +Changing the kernel
> configuration
>  
>  
> 
> @@ -81,14 +81,14 @@
> 
>  
>  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
> -meta/recipes-kernel/linux/linux-
> yocto_3.19.bb
> -recipe, the append file will typically be located as follows
> -within your custom layer:
> +meta/recipes-kernel/linux/linux-
> yocto_4.4.bb
> +recipe, the corresponding append file will typically be 
> located
> +as follows within your custom layer:
>  
> - your-layer/recipes-kernel/linux/linux-
> yocto_3.19.bbappend
> + your-layer/recipes-kernel/linux/linux-
> yocto_4.4.bbappend
>  
>  The append file should initially extend the
>  FILESPATH
> @@ -133,12 +133,14 @@
> 
>  
>  For example, you can apply a three-patch series by adding the
> -following lines to your linux-yocto
> -.bbappend file in your layer:
> +following lines to the linux-yocto
> +.bbappend file in your custom layer:
>  
> - 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 \
> +"
>  
>  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 @@
>  
>  You can make wholesale or incremental changes to the final
>  .config file used for the eventual
> -Linux kernel configuration by including a
> -defconfig file and by specifying
> +Linux kernel configuration by including a local
> +defconfig file, as well as by specifying
>  configuration fragments in the
>  SRC_URI
> -to be applied to that file.
> +to be applied to the configuration defined by that
> +defconfig file.
>  
> 
>  
> @@ -204,10 +207,10 @@
> 
>  
>  Generally speaking, the preferred approach is to determine 
> the
> -incremental change you want to make and add that as a
> -

[yocto] [PATCH v2] yocto-docs: kernel-dev, Aesthetic/formatting/clarification fixes

[Robert P. J. Day]

A variety of tweaks to kernel-dev manual, section
kernel-dev-common.xml, which include:

* adding extra text in places to clarify possibly ambiguous content
* some formatting changes related to font and overly long lines
* update some old version numbers that don't even exist anymore

Signed-off-by: Robert P. J. Day 

---

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
 BitBake
 append files
-(.bbappend) and provides a convenient
+(.bbappend) and would provide a convenient
 mechanism to create your own recipe files
 (.bb).
 For details on how to create and work with layers, see the 
following
@@ -59,9 +59,9 @@
 
 Modifying an existing recipe can consist of the following:
 
-Creating the append file
-Applying patches
-Changing the configuration
+Creating an append file
+Applying some local patches
+Changing the kernel 
configuration
 
 

@@ -81,14 +81,14 @@

 
 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
-
meta/recipes-kernel/linux/linux-yocto_3.19.bb
-recipe, the append file will typically be located as follows
-within your custom layer:
+
meta/recipes-kernel/linux/linux-yocto_4.4.bb
+recipe, the corresponding append file will typically be located
+as follows within your custom layer:
 
- 
your-layer/recipes-kernel/linux/linux-yocto_3.19.bbappend
+ 
your-layer/recipes-kernel/linux/linux-yocto_4.4.bbappend
 
 The append file should initially extend the
 FILESPATH
@@ -133,12 +133,14 @@

 
 For example, you can apply a three-patch series by adding the
-following lines to your linux-yocto
-.bbappend file in your layer:
+following lines to the linux-yocto
+.bbappend file in your custom layer:
 
- 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 \
+"
 
 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 @@
 
 You can make wholesale or incremental changes to the final
 .config file used for the eventual
-Linux kernel configuration by including a
-defconfig file and by specifying
+Linux kernel configuration by including a local
+defconfig file, as well as by specifying
 configuration fragments in the
 SRC_URI
-to be applied to that file.
+to be applied to the configuration defined by that
+defconfig file.
 

 
@@ -204,10 +207,10 @@

 
 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 8250.cfg 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, 
8250.cfg in
 the ${PN} directory with the following
 content (without indentation):
 
@@ -219,7 +222,7 @@
  CONFIG_SERIAL_CORE=y
  CONFIG_SERIAL_CORE_CONSOLE=y