[PATCH 0/2] kernel-dev manual fixes, V2

[PATCH 0/2] kernel-dev manual fixes, V2

[Tom Zanussi]

This is a fix for Yocto bug 9124, against yocto-docs/master.

V2: Fix a typo in the commit message and update README update, as the
cc: to the maintainer listed there bounced.

The following changes since commit 0b9ee8da66ff81e0724465f18b0323f1216cb9fa:

  ref-manual: Added GObject Introspection to 2.1 migration section. (2016-04-20 07:27:43 -0700)

are available in the git repository at:

  git://git.yoctoproject.org/poky-contrib tzanussi/kernel-dev-manual-fixes
  http://git.yoctoproject.org/cgit/cgit.cgi/poky-contrib/log/?h=tzanussi/kernel-dev-manual-fixes

Tom Zanussi (2):
  kernel-dev: Fix the locations of .config and source directory
  README: Add correct email for Yocto documentation maintainer

 README                                         |  2 +-
 documentation/kernel-dev/kernel-dev-common.xml | 20 +++++++++++++++-----
 2 files changed, 16 insertions(+), 6 deletions(-)

-- 
1.9.3

[PATCH v2 1/2] kernel-dev: Fix the locations of .config and source directory

[Tom Zanussi]

The locations of the kernel .config file and source directory moved a
couple releases ago; update the documentation accordingly.

Also, add a note explaining how to expand variables, which serves a
couple of purposes:

  * For curious readers, shows them how to demystify where these
    variables come from and how they're used.
  * For suspicious readers, shows them how they can verify that the
    variables in the documentation are actually correct.

Fixes [YOCTO #9124].

Signed-off-by: Tom Zanussi <tom.zanussi@linux.intel.com>
---
 documentation/kernel-dev/kernel-dev-common.xml | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index 261471c..5bd12be 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -384,9 +384,7 @@
 
             <para>
                 The resulting <filename>.config</filename> file is
-                located in
-                <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> under the
-                <filename>linux-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink><filename>}-${<ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>}-build</filename> directory.
+                located in the build directory,  <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}</filename>, which expands to <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename><filename>/linux-</filename><filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink><filename>}-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink><filename>}-build</filename>.
                 You can use the entire <filename>.config</filename> file as the
                 <filename>defconfig</filename> file as described in the
                 "<link linkend='changing-the-configuration'>Changing the Configuration</link>" section.
@@ -396,6 +394,19 @@
                 section in the Yocto Project Development Manual.
             </para>
 
+            <note>
+              If you're ever confused about what a variable expands
+              to, you can determine that unequivocally by looking at
+              the output of the <filename>bitbake -e</filename> command:
+
+	      <literallayout class='monospaced'>
+     $ bitbake -e virtual/kernel
+              </literallayout>
+
+	      Search the output for the variable you're interested in
+	      and you can see exactly how it's expanded and used.
+            </note>
+
             <para>
                 A better method is to create a configuration fragment using the
                 differences between two configuration files: one previously
@@ -512,8 +523,7 @@
                 </literallayout>
                 Taking this step ensures you have the sources prepared
                 and the configuration completed.
-                You can find the sources in the
-                <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/linux</filename> directory.
+                You can find the sources in the symlinked <filename>source/</filename> directory just off the build directory, in other words <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}/source</filename>, which expands to <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename><filename>/linux-</filename><filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink><filename>}-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink><filename>}-build/source</filename>.  The directory pointed to by the <filename>source/</filename> symlink is also known as <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink><filename>}</filename>
             </para>
 
             <para>
-- 
1.9.3

[PATCH v2 2/2] README: Add correct email for Yocto documentation maintainer

[Tom Zanussi]

The e-mail address the top-level README says to cc: is no longer
valid; replace it with the same e-mail address found elsewhere in the
repo.

Signed-off-by: Tom Zanussi <tom.zanussi@linux.intel.com>
---
 README | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README b/README
index 4c3b257..bcd68c1 100644
--- a/README
+++ b/README
@@ -12,4 +12,4 @@ Where to Send Patches
 
 Git repository: http://git.yoctoproject.org/cgit/cgit.cgi/yocto-docs/
 Mailing list: yocto@yoctoproject.org
-Please cc: Scott Rifenbark <scott.m.rifenbark@intel.com> on changes.
+Please cc: Scott Rifenbark <srifenbark@gmail.com> on changes.
-- 
1.9.3

Re: [PATCH v2 1/2] kernel-dev: Fix the locations of .config and source directory

[Tom Zanussi]

ping

On 05/03/2016 11:28 AM, Tom Zanussi wrote:
> The locations of the kernel .config file and source directory moved a
> couple releases ago; update the documentation accordingly.
>
> Also, add a note explaining how to expand variables, which serves a
> couple of purposes:
>
>    * For curious readers, shows them how to demystify where these
>      variables come from and how they're used.
>    * For suspicious readers, shows them how they can verify that the
>      variables in the documentation are actually correct.
>
> Fixes [YOCTO #9124].
>
> Signed-off-by: Tom Zanussi <tom.zanussi@linux.intel.com>
> ---
>   documentation/kernel-dev/kernel-dev-common.xml | 20 +++++++++++++++-----
>   1 file changed, 15 insertions(+), 5 deletions(-)
>
> diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
> index 261471c..5bd12be 100644
> --- a/documentation/kernel-dev/kernel-dev-common.xml
> +++ b/documentation/kernel-dev/kernel-dev-common.xml
> @@ -384,9 +384,7 @@
>
>               <para>
>                   The resulting <filename>.config</filename> file is
> -                located in
> -                <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> under the
> -                <filename>linux-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink><filename>}-${<ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>}-build</filename> directory.
> +                located in the build directory,  <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}</filename>, which expands to <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename><filename>/linux-</filename><filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink><filename>}-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink><filename>}-build</filename>.
>                   You can use the entire <filename>.config</filename> file as the
>                   <filename>defconfig</filename> file as described in the
>                   "<link linkend='changing-the-configuration'>Changing the Configuration</link>" section.
> @@ -396,6 +394,19 @@
>                   section in the Yocto Project Development Manual.
>               </para>
>
> +            <note>
> +              If you're ever confused about what a variable expands
> +              to, you can determine that unequivocally by looking at
> +              the output of the <filename>bitbake -e</filename> command:
> +
> +	      <literallayout class='monospaced'>
> +     $ bitbake -e virtual/kernel
> +              </literallayout>
> +
> +	      Search the output for the variable you're interested in
> +	      and you can see exactly how it's expanded and used.
> +            </note>
> +
>               <para>
>                   A better method is to create a configuration fragment using the
>                   differences between two configuration files: one previously
> @@ -512,8 +523,7 @@
>                   </literallayout>
>                   Taking this step ensures you have the sources prepared
>                   and the configuration completed.
> -                You can find the sources in the
> -                <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/linux</filename> directory.
> +                You can find the sources in the symlinked <filename>source/</filename> directory just off the build directory, in other words <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink><filename>}/source</filename>, which expands to <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename><filename>/linux-</filename><filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink><filename>}-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink><filename>}-build/source</filename>.  The directory pointed to by the <filename>source/</filename> symlink is also known as <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink><filename>}</filename>
>               </para>
>
>               <para>
>