From 274095d4c21a8f617a41f85a364db78e96f7bf4d Mon Sep 17 00:00:00 2001
From: Scott Rifenbark <scott.m.rifenbark@intel.com>
Date: Mon, 8 Oct 2012 08:49:23 -0700
Subject: documentation: dev-manual - Updates to configuring Kernel section

Eliminated the section A.2, which had an example of how to use
menuconfig in the kerenl example appendix.  The information is
now merged into the similar section in Chapter 4 "Common
Tasks."  It was decided that the Appendix A examples in the
manual were too detailed for a general development guide.

(From yocto-docs rev: f88ec421b257657f02cc0f132ec2580c17f07cef)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
---
 .../dev-manual/dev-manual-common-tasks.xml         | 88 ++++++++++++++++++++--
 1 file changed, 81 insertions(+), 7 deletions(-)

(limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 824aac1236..918d884681 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1352,6 +1352,8 @@
             <para>
                 The easiest way to define kernel configurations is to set them through the
                 <filename>menuconfig</filename> tool.
+                This tool provides an interactive method with which
+                to set kernel configurations.
                 For general information on <filename>menuconfig</filename>, see
                 <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.
             </para>
@@ -1359,6 +1361,9 @@
             <para>
                 To use the <filename>menuconfig</filename> tool in the Yocto Project development
                 environment, you must build the tool using BitBake.
+                Thus, the environment must be set up using the <filename>&OE_INIT_FILE;</filename>
+                script found in the 
+                <link linkend='build-directory'>Build Directory</link>.
                 The following commands build and invoke <filename>menuconfig</filename> assuming the 
                 source directory top-level folder is <filename>~/poky</filename>:
                 <literallayout class='monospaced'>
@@ -1367,17 +1372,86 @@
      $ bitbake linux-yocto -c menuconfig
                 </literallayout>
                 Once <filename>menuconfig</filename> comes up, its standard interface allows you to 
-                examine and configure all the kernel configuration parameters.
-                Once you have made your changes, simply exit the tool and save your changes 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>
-                For an example that shows how to change a specific kernel option
-                using <filename>menuconfig</filename>, see the 
-                "<link linkend='changing-the-config-smp-configuration-using-menuconfig'>Changing
-                the <filename>CONFIG_SMP</filename> Configuration Using <filename>menuconfig</filename></link>" 
-                section.
+                Consider an example that configures the <filename>linux-yocto-3.4</filename>
+                kernel.
+                The OpenEmbedded build system recognizes this kernel as 
+                <filename>linux-yocto</filename>.
+                Thus, the following commands from the shell in which you previously sourced the 
+                environment initialization script cleans the shared state cache and the 
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
+                directory and then builds and launches <filename>menuconfig</filename>:
+                <literallayout class='monospaced'>
+     $ bitbake linux-yocto -c menuconfig
+                </literallayout>
+            </para>
+
+            <para>
+                Once <filename>menuconfig</filename> launches, you use the interface 
+                to navigate through the selections to find the configuration settings in
+                which you are interested.  
+                For example, consider the <filename>CONFIG_SMP</filename> configuration setting.
+                You can find it at <filename>Processor Type and Features</filename> under 
+                the configuration selection <filename>Symmetric Multi-processing Support</filename>.
+                After highlighting the selection, you can use the arrow keys to select or deselect
+                the setting.
+                When you are finished with all your selections, exit out and save them.
+            </para>
+
+            <para>
+                Saving the selections updates the <filename>.config</filename> configuration file.
+                This is the file that the OpenEmbedded build system uses to configure the 
+                kernel during the build. 
+                You can find and examine this file in the build directory in 
+                <filename>tmp/work/</filename>.
+                The actual <filename>.config</filename> is located in the area where the 
+                specific kernel is built.
+                For example, if you were building a Linux Yocto kernel based on the 
+                Linux 3.4 kernel and you were building a QEMU image targeted for 
+                <filename>x86</filename> architecture, the 
+                <filename>.config</filename> file would be located here:
+                <literallayout class='monospaced'>
+     ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+84f...
+        ...656ed30-r1/linux-qemux86-standard-build
+                </literallayout>
+                <note>
+                    The previous example directory is artificially split and many of the characters 
+                    in the actual filename are omitted in order to make it more readable.
+                    Also, depending on the kernel you are using, the exact pathname 
+                    for <filename>linux-yocto-3.4...</filename> might differ.
+                </note>
+            </para>
+
+            <para>
+                Within the <filename>.config</filename> file, you can see the kernel settings.
+                For example, the following entry shows that symmetric multi-processor support
+                is not set:
+                <literallayout class='monospaced'>
+     # CONFIG_SMP is not set
+                </literallayout>
+            </para>
+
+            <para>
+                A good method to isolate changed configurations is to use a combination of the 
+                <filename>menuconfig</filename> tool and simple shell commands.
+                Before changing configurations with <filename>menuconfig</filename>, copy the 
+                existing <filename>.config</filename> and rename it to something else,
+                use <filename>menuconfig</filename> to make 
+                as many changes an you want and save them, then compare the renamed configuration 
+                file against the newly created file.
+                You can use the resulting differences as your base to create configuration fragments
+                to permanently save in your kernel layer.
+                <note>
+                    Be sure to make a copy of the <filename>.config</filename> and don't just
+                    rename it. 
+                    The build system needs an existing <filename>.config</filename>
+                    from which to work.
+                </note>
             </para>
         </section>
 
-- 
cgit v1.2.3-54-g00ecf