dev-manual: Added new section on "defconfig" files.

The "Configuring the Kernel" section did not address "defconfig"
files.  In my opinion, this is a hole in the docs for this section.
I added a new section titled "Creating a defconfig File" that is a
sub-section of the "Configuring the Kernel" section.

Additionally, I added a brief sentence in the introductory paragraph
to include the fact that this new information exists.

Finally, I included the bitbake command that ensures that the
proper configuration steps are minimally run before a user attempts
to use bitbake to get into menuconfig.

Fixes [#YOCTO 7474]

(From yocto-docs rev: 13c0c7dddca59474ef65dacc12f0bfaa38933887)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 92 insertions, 14 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 362fce1916..a929481633 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -4624,13 +4624,22 @@
         <title>Configuring the Kernel</title>
 
         <para>
-            Configuring the Yocto Project kernel consists of making sure the <filename>.config</filename>
-            file has all the right information in it for the image you are building.
-            You can use the <filename>menuconfig</filename> tool and configuration fragments to
-            make sure your <filename>.config</filename> file is just how you need it.
-            This section describes how to use <filename>menuconfig</filename>, create and use
-            configuration fragments, and how to interactively modify your <filename>.config</filename>
-            file to create the leanest kernel configuration file possible.
+            Configuring the Yocto Project kernel consists of making sure the
+            <filename>.config</filename> file has all the right information
+            in it for the image you are building.
+            You can use the <filename>menuconfig</filename> tool and
+            configuration fragments to make sure your
+            <filename>.config</filename> file is just how you need it.
+            You can also save known configurations in a
+            <filename>defconfig</filename> file that the build system can use
+            for kernel configuration.
+        </para>
+
+        <para>
+            This section describes how to use <filename>menuconfig</filename>,
+            create and use configuration fragments, and how to interactively
+            modify your <filename>.config</filename> file to create the
+            leanest kernel configuration file possible.
         </para>
 
         <para>
@@ -4660,18 +4669,23 @@
                 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
                 script found in the
                 <link linkend='build-directory'>Build Directory</link>.
-                The following commands run <filename>menuconfig</filename> assuming the
-                <link linkend='source-directory'>Source Directory</link>
-                top-level folder is <filename>~/poky</filename>:
+                You must also be sure of the state of your build in the
+                <link linkend='source-directory'>Source Directory</link>.
+                The following commands run <filename>menuconfig</filename>
+                assuming the Source Directory's top-level folder is
+                <filename>~/poky</filename>:
                 <literallayout class='monospaced'>
      $ cd poky
      $ source oe-init-build-env
+     $ bitbake linux-yocto -c kernel_configme -f
      $ bitbake linux-yocto -c menuconfig
                 </literallayout>
-                Once <filename>menuconfig</filename> comes up, its standard interface allows you to
-                interactively examine and configure all the kernel configuration parameters.
-                After making your changes, simply exit the tool and save your changes to
-                create an updated version of the <filename>.config</filename> configuration file.
+                Once <filename>menuconfig</filename> comes up, its standard
+                interface allows you to interactively examine and configure
+                all the kernel configuration parameters.
+                After making your changes, simply exit the tool and save your
+                changes to create an updated version of the
+                <filename>.config</filename> configuration file.
             </para>
 
             <para>
@@ -4752,6 +4766,70 @@
             </para>
         </section>
 
+        <section id='creating-a-defconfig-file'>
+            <title>Creating a&nbsp;&nbsp;<filename>defconfig</filename> File</title>
+
+            <para>
+                A <filename>defconfig</filename> file is simply a
+                <filename>.config</filename> renamed to "defconfig".
+                You can use a <filename>defconfig</filename> file
+                to retain a known set of kernel configurations from which the
+                OpenEmbedded build system can draw to create the final
+                <filename>.config</filename> file.
+                <note>
+                    Out-of-the-box, the Yocto Project never ships a
+                    <filename>defconfig</filename> or
+                    <filename>.config</filename> file.
+                    The OpenEmbedded build system creates the final
+                    <filename>.config</filename> file used to configure the
+                    kernel.
+                </note>
+            </para>
+
+            <para>
+                To create a <filename>defconfig</filename>, start with a
+                complete, working Linux kernel <filename>.config</filename>
+                file.
+                Copy that file to the appropriate
+                <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
+                directory in your layer's
+                <filename>recipes-kernel/linux</filename> directory, and rename
+                the copied file to "defconfig".
+                Then, add the following lines to the linux-yocto
+                <filename>.bbappend</filename> file in your layer:
+                <literallayout class='monospaced'>
+     FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
+     SRC_URI += "file://defconfig"
+                </literallayout>
+                The
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                tells the build system how to search for the file, while the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
+                extends the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
+                variable (search directories) to include the
+                <filename>${PN}</filename> directory you created to hold the
+                configuration changes.
+                <note>
+                    The build system applies the configurations from the
+                    <filename>defconfig</filename> file before applying any
+                    subsequent configuration fragments.
+                    The final kernel configuration is a combination of the
+                    configurations in the <filename>defconfig</filename>
+                    file and any configuration fragments you provide.
+                    You need to realize that if you have any configuration
+                    fragments, the build system applies these on top of and
+                    after applying the existing defconfig file configurations.
+                </note>
+                For more information on configuring the kernel, see the
+                "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#changing-the-configuration'>Changing the Configuration</ulink>"
+                and
+                "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>"
+                sections, both in the Yocto Project Linux Kernel Development
+                Manual.
+            </para>
+        </section>
+
         <section id='creating-config-fragments'>
             <title>Creating Configuration Fragments</title>