2 files changed, 81 insertions, 300 deletions
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.
+                interactively examine and configure all the kernel configuration parameters.
-                Once you have made your changes, simply exit the tool and save your changes to 
+                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
+                Consider an example that configures the <filename>linux-yocto-3.4</filename>
-                using <filename>menuconfig</filename>, see the 
+                kernel.
-                "<link linkend='changing-the-config-smp-configuration-using-menuconfig'>Changing
+                The OpenEmbedded build system recognizes this kernel as 
-                the <filename>CONFIG_SMP</filename> Configuration Using <filename>menuconfig</filename></link>" 
+                <filename>linux-yocto</filename>.
-                section.
+                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>
diff --git a/documentation/dev-manual/dev-manual-kernel-appendix.xml b/documentation/dev-manual/dev-manual-kernel-appendix.xml
index 9070fcb561..6ea77d030c 100644
--- a/documentation/dev-manual/dev-manual-kernel-appendix.xml
+++ b/documentation/dev-manual/dev-manual-kernel-appendix.xml
@@ -546,299 +546,6 @@
            </para>
        </section>
    </section>
-    <section id='changing-the-kernel-configuration'>
-        <title>Changing the Kernel Configuration</title>
-        <para>
-            This example changes the default behavior, which is "on", of the Symmetric 
-            Multi-processing Support (<filename>CONFIG_SMP</filename>) to "off".  
-            It is a simple example that demonstrates how to reconfigure the kernel.
-        </para>
-        <section id='getting-set-up-to-run-this-example'>
-            <title>Getting Set Up to Run this Example</title>
-            <para>
-                If you took the time to work through the example that modifies the kernel source code 
-                in "<link linkend='modifying-the-kernel-source-code'>Modifying the Kernel Source
-                Code</link>" you should already have the Source Directory set up on your 
-                host machine.
-                If this is the case, go to the next section, which is titled
-                "<link linkend='examining-the-default-config-smp-behavior'>Examining the Default
-                <filename>CONFIG_SMP</filename> Behavior</link>", and continue with the 
-                example.
-            </para>
-            <para>
-                If you don't have the Source Directory established on your system, 
-                you can get them through tarball extraction or by 
-                cloning the <filename>poky</filename> Git repository.  
-                This example uses <filename>poky</filename> as the root directory of the 
-                <link linkend='source-directory'>Source Directory</link>.
-                See the bulleted item
-                "<link linkend='local-yp-release'>Yocto Project Release</link>"
-                for information on how to get these files.
-            </para>
-            <para>
-                Once you have the local copy of the repository set up, 
-                you have many development branches from which you can work. 
-                From inside the repository you can see the branch names and the tag names used 
-                in the upstream Git repository using either of the following commands:
-                <literallayout class='monospaced'>
-     $ cd poky
-     $ git branch -a
-     $ git tag -l
-                </literallayout> 
-                This example uses the Yocto Project &DISTRO; Release code named "&DISTRO_NAME;", 
-                which maps to the <filename>&DISTRO_NAME;</filename> branch in the repository. 
-                The following commands create and checkout the local <filename>&DISTRO_NAME;</filename>
-                branch:
-                <literallayout class='monospaced'>
-     $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
-     Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin.
-     Switched to a new branch '&DISTRO_NAME;'
-                </literallayout>
-            </para>
-            <para>
-                Next, you need to build the default <filename>qemux86</filename> image that you 
-                can boot using QEMU.
-                <note>
-                    Because a full build can take hours, you should check two variables in the 
-                    <filename>build</filename> directory that is created after you source the 
-                    <filename>&OE_INIT_FILE;</filename> script.
-                    You can find these variables
-                    <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>
-                    in the <filename>build/conf</filename> directory in the 
-                    <filename>local.conf</filename> configuration file.
-                    By default, these variables are commented out.
-                    If your host development system supports multi-core and multi-thread capabilities,
-                    you can uncomment these statements and set the variables to significantly shorten
-                    the full build time.
-                    As a guideline, set both the <filename>BB_NUMBER_THREADS</filename> and the 
-                    <filename>PARALLEL_MAKE</filename> variables to twice the number 
-                    of cores your machine supports.
-                </note>
-                The following two commands <filename>source</filename> the build environment setup script
-                and build the default <filename>qemux86</filename> image.
-                If necessary, the script creates the build directory:
-                <literallayout class='monospaced'>
-     $ cd ~/poky
-     $ source &OE_INIT_FILE;
-          ### Shell environment set up for builds. ###
-     You can now run 'bitbake &lt;target&gt;'
-     Common targets are:
-         core-image-minimal
-         core-image-sato
-         meta-toolchain
-         meta-toolchain-sdk
-         adt-installer
-         meta-ide-support
-     You can also run generated qemu images with a command like 'runqemu qemux86'
-                </literallayout>
-            </para>
-            <para>
-                The following <filename>bitbake</filename> command starts the build:
-                <literallayout class='monospaced'>
-     $ bitbake -k core-image-minimal
-                </literallayout>
-                <note>Be sure to check the settings in the <filename>local.conf</filename>
-                before starting the build.</note>
-            </para>
-        </section>
-        <section id='examining-the-default-config-smp-behavior'>
-            <title>Examining the Default&nbsp;&nbsp;<filename>CONFIG_SMP</filename> Behavior</title>
-            <para>
-                By default, <filename>CONFIG_SMP</filename> supports multiple processor machines.
-                To see this default setting from within the QEMU emulator, boot your image using 
-                the emulator as follows:
-                <literallayout class='monospaced'>
-     $ runqemu qemux86 qemuparams="-smp 4"
-                </literallayout>
-            </para>
-            <para>
-                Login to the machine using <filename>root</filename> with no password.
-                After logging in, enter the following command to see how many processors are 
-                being supported in the emulator.
-                The emulator reports support for the number of processors you specified using 
-                the <filename>-smp</filename> option, four in this case:
-                <literallayout class='monospaced'>
-     # cat /proc/cpuinfo | grep processor 
-     processor       : 0
-     processor       : 1
-     processor       : 2
-     processor       : 3
-     #
-                </literallayout>
-                To check the setting for <filename>CONFIG_SMP</filename>, you can use the 
-                following command:
-                <literallayout class='monospaced'>
-     zcat /proc/config.gz | grep CONFIG_SMP
-                </literallayout>
-                The console returns the following showing that multi-processor machine support
-                is set:
-                <literallayout class='monospaced'>
-     CONFIG_SMP=y
-                </literallayout>
-                Logout of the emulator using the <filename>exit</filename> command and 
-                then close it down.
-            </para>
-        </section>
-        <section id='changing-the-config-smp-configuration-using-menuconfig'>
-            <title>Changing the&nbsp;&nbsp;<filename>CONFIG_SMP</filename> Configuration Using&nbsp;&nbsp;<filename>menuconfig</filename></title>
-            <para>
-                The <filename>menuconfig</filename> tool provides an interactive method with which
-                to set kernel configurations.
-                You need to run <filename>menuconfig</filename> inside the Yocto BitBake environment.
-                Thus, the environment must be set up using the <filename>&OE_INIT_FILE;</filename>
-                script found in the build directory.
-                If you have not sourced this script do so with the following commands:
-                <literallayout class='monospaced'>
-     $ cd ~/poky
-     $ source &OE_INIT_FILE;
-                </literallayout>
-            </para>
-            <para>
-                After setting up the environment to run <filename>menuconfig</filename>, you are ready 
-                to use the tool to interactively change the kernel configuration.
-                In this example, we are basing our changes on 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, navigate through the user interface
-                to find the <filename>CONFIG_SMP</filename> configuration setting.
-                You can find it at <filename>Processor Type and Features</filename>.
-                The configuration selection is 
-                <filename>Symmetric Multi-processing Support</filename>.
-                After using the arrow keys to highlight this selection, press "n" to turn it off.
-                Then, exit out and save your selections.
-            </para>
-            <para>
-                Once you save the selection, the <filename>.config</filename> configuration file
-                is updated. 
-                This is the file that the build system uses to configure the Yocto Project kernel
-                when it is built. 
-                You can find and examine this file in the build directory. 
-                This example uses the following:
-                <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 might differ 
-                    slightly.
-                </note>
-            </para>
-            <para>
-                Within the <filename>.config</filename> file, you can see the following setting:
-                <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>
-        <section id='recompiling-the-kernel-and-testing-the-new-configuration'>
-            <title>Recompiling the Kernel and Testing the New Configuration</title>
-            <para>
-                At this point, you are ready to recompile your kernel image with 
-                the new setting in effect using the BitBake command below:
-                <literallayout class='monospaced'>
-     $ bitbake linux-yocto
-                </literallayout>
-            </para>
- 
-            <para>
-                Now run the QEMU emulator and pass it the same multi-processor option as before:
-                <literallayout class='monospaced'>
-     $ runqemu qemux86 qemuparams="-smp 4"
-                </literallayout>
-            </para>
-            <para>
-                Login to the machine using <filename>root</filename> with no password
-                and test for the number of processors the kernel supports:
-                <literallayout class='monospaced'>
-     # cat /proc/cpuinfo | grep processor 
-     processor       : 0
-     #
-                </literallayout>
-            </para>
-            <para>
-                From the output, you can see that the kernel no longer supports multi-processor systems.
-                The output indicates support for a single processor.  You can verify the 
-                <filename>CONFIG_SMP</filename> setting by using this command:
-                <literallayout class='monospaced'>
-     zcat /proc/config.gz | grep CONFIG_SMP
-                </literallayout>
-                The console returns the following output:
-                <literallayout class='monospaced'>
-     # CONFIG_SMP is not set
-                </literallayout>
-                You have successfully reconfigured the kernel.
-            </para>
-        </section>
-    </section>
-    <section id='adding-kernel-recipes'>
-        <title>Adding Kernel Recipes</title>
-        <para>
-            A future release of this manual will present an example that adds kernel recipes, which provide 
-            new functionality to the kernel.
-        </para>
-        <para>
-            <imagedata fileref="figures/wip.png" 
-                width="2in" depth="3in" align="center" scalefit="1" />
-        </para> 
-    </section> 
 </appendix>
 <!--

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 @@
1352	<para>	1352	<para>
1353	The easiest way to define kernel configurations is to set them through the	1353	The easiest way to define kernel configurations is to set them through the
1354	<filename>menuconfig</filename> tool.	1354	<filename>menuconfig</filename> tool.
		1355	This tool provides an interactive method with which
		1356	to set kernel configurations.
1355	For general information on <filename>menuconfig</filename>, see	1357	For general information on <filename>menuconfig</filename>, see
1356	<ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.	1358	<ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.
1357	</para>	1359	</para>
@@ -1359,6 +1361,9 @@
1359	<para>	1361	<para>
1360	To use the <filename>menuconfig</filename> tool in the Yocto Project development	1362	To use the <filename>menuconfig</filename> tool in the Yocto Project development
1361	environment, you must build the tool using BitBake.	1363	environment, you must build the tool using BitBake.
		1364	Thus, the environment must be set up using the <filename>&OE_INIT_FILE;</filename>
		1365	script found in the
		1366	<link linkend='build-directory'>Build Directory</link>.
1362	The following commands build and invoke <filename>menuconfig</filename> assuming the	1367	The following commands build and invoke <filename>menuconfig</filename> assuming the
1363	source directory top-level folder is <filename>~/poky</filename>:	1368	source directory top-level folder is <filename>~/poky</filename>:
1364	<literallayout class='monospaced'>	1369	<literallayout class='monospaced'>
@@ -1367,17 +1372,86 @@
1367	$ bitbake linux-yocto -c menuconfig	1372	$ bitbake linux-yocto -c menuconfig
1368	</literallayout>	1373	</literallayout>
1369	Once <filename>menuconfig</filename> comes up, its standard interface allows you to	1374	Once <filename>menuconfig</filename> comes up, its standard interface allows you to
1370	examine and configure all the kernel configuration parameters.	1375	interactively examine and configure all the kernel configuration parameters.
1371	Once you have made your changes, simply exit the tool and save your changes to	1376	After making your changes, simply exit the tool and save your changes to
1372	create an updated version of the <filename>.config</filename> configuration file.	1377	create an updated version of the <filename>.config</filename> configuration file.
1373	</para>	1378	</para>
1374		1379
1375	<para>	1380	<para>
1376	For an example that shows how to change a specific kernel option	1381	Consider an example that configures the <filename>linux-yocto-3.4</filename>
1377	using <filename>menuconfig</filename>, see the	1382	kernel.
1378	"<link linkend='changing-the-config-smp-configuration-using-menuconfig'>Changing	1383	The OpenEmbedded build system recognizes this kernel as
1379	the <filename>CONFIG_SMP</filename> Configuration Using <filename>menuconfig</filename></link>"	1384	<filename>linux-yocto</filename>.
1380	section.	1385	Thus, the following commands from the shell in which you previously sourced the
		1386	environment initialization script cleans the shared state cache and the
		1387	<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
		1388	directory and then builds and launches <filename>menuconfig</filename>:
		1389	<literallayout class='monospaced'>
		1390	$ bitbake linux-yocto -c menuconfig
		1391	</literallayout>
		1392	</para>
		1393
		1394	<para>
		1395	Once <filename>menuconfig</filename> launches, you use the interface
		1396	to navigate through the selections to find the configuration settings in
		1397	which you are interested.
		1398	For example, consider the <filename>CONFIG_SMP</filename> configuration setting.
		1399	You can find it at <filename>Processor Type and Features</filename> under
		1400	the configuration selection <filename>Symmetric Multi-processing Support</filename>.
		1401	After highlighting the selection, you can use the arrow keys to select or deselect
		1402	the setting.
		1403	When you are finished with all your selections, exit out and save them.
		1404	</para>
		1405
		1406	<para>
		1407	Saving the selections updates the <filename>.config</filename> configuration file.
		1408	This is the file that the OpenEmbedded build system uses to configure the
		1409	kernel during the build.
		1410	You can find and examine this file in the build directory in
		1411	<filename>tmp/work/</filename>.
		1412	The actual <filename>.config</filename> is located in the area where the
		1413	specific kernel is built.
		1414	For example, if you were building a Linux Yocto kernel based on the
		1415	Linux 3.4 kernel and you were building a QEMU image targeted for
		1416	<filename>x86</filename> architecture, the
		1417	<filename>.config</filename> file would be located here:
		1418	<literallayout class='monospaced'>
		1419	~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+84f...
		1420	...656ed30-r1/linux-qemux86-standard-build
		1421	</literallayout>
		1422	<note>
		1423	The previous example directory is artificially split and many of the characters
		1424	in the actual filename are omitted in order to make it more readable.
		1425	Also, depending on the kernel you are using, the exact pathname
		1426	for <filename>linux-yocto-3.4...</filename> might differ.
		1427	</note>
		1428	</para>
		1429
		1430	<para>
		1431	Within the <filename>.config</filename> file, you can see the kernel settings.
		1432	For example, the following entry shows that symmetric multi-processor support
		1433	is not set:
		1434	<literallayout class='monospaced'>
		1435	# CONFIG_SMP is not set
		1436	</literallayout>
		1437	</para>
		1438
		1439	<para>
		1440	A good method to isolate changed configurations is to use a combination of the
		1441	<filename>menuconfig</filename> tool and simple shell commands.
		1442	Before changing configurations with <filename>menuconfig</filename>, copy the
		1443	existing <filename>.config</filename> and rename it to something else,
		1444	use <filename>menuconfig</filename> to make
		1445	as many changes an you want and save them, then compare the renamed configuration
		1446	file against the newly created file.
		1447	You can use the resulting differences as your base to create configuration fragments
		1448	to permanently save in your kernel layer.
		1449	<note>
		1450	Be sure to make a copy of the <filename>.config</filename> and don't just
		1451	rename it.
		1452	The build system needs an existing <filename>.config</filename>
		1453	from which to work.
		1454	</note>
1381	</para>	1455	</para>
1382	</section>	1456	</section>
1383		1457


diff --git a/documentation/dev-manual/dev-manual-kernel-appendix.xml b/documentation/dev-manual/dev-manual-kernel-appendix.xml index 9070fcb561..6ea77d030c 100644 --- a/documentation/dev-manual/dev-manual-kernel-appendix.xml +++ b/documentation/dev-manual/dev-manual-kernel-appendix.xml
@@ -546,299 +546,6 @@
546	</para>	546	</para>
547	</section>	547	</section>
548	</section>	548	</section>
549
550	<section id='changing-the-kernel-configuration'>
551	<title>Changing the Kernel Configuration</title>
552
553	<para>
554	This example changes the default behavior, which is "on", of the Symmetric
555	Multi-processing Support (<filename>CONFIG_SMP</filename>) to "off".
556	It is a simple example that demonstrates how to reconfigure the kernel.
557	</para>
558
559	<section id='getting-set-up-to-run-this-example'>
560	<title>Getting Set Up to Run this Example</title>
561
562	<para>
563	If you took the time to work through the example that modifies the kernel source code
564	in "<link linkend='modifying-the-kernel-source-code'>Modifying the Kernel Source
565	Code</link>" you should already have the Source Directory set up on your
566	host machine.
567	If this is the case, go to the next section, which is titled
568	"<link linkend='examining-the-default-config-smp-behavior'>Examining the Default
569	<filename>CONFIG_SMP</filename> Behavior</link>", and continue with the
570	example.
571	</para>
572
573	<para>
574	If you don't have the Source Directory established on your system,
575	you can get them through tarball extraction or by
576	cloning the <filename>poky</filename> Git repository.
577	This example uses <filename>poky</filename> as the root directory of the
578	<link linkend='source-directory'>Source Directory</link>.
579	See the bulleted item
580	"<link linkend='local-yp-release'>Yocto Project Release</link>"
581	for information on how to get these files.
582	</para>
583
584	<para>
585	Once you have the local copy of the repository set up,
586	you have many development branches from which you can work.
587	From inside the repository you can see the branch names and the tag names used
588	in the upstream Git repository using either of the following commands:
589	<literallayout class='monospaced'>
590	$ cd poky
591	$ git branch -a
592	$ git tag -l
593	</literallayout>
594	This example uses the Yocto Project &DISTRO; Release code named "&DISTRO_NAME;",
595	which maps to the <filename>&DISTRO_NAME;</filename> branch in the repository.
596	The following commands create and checkout the local <filename>&DISTRO_NAME;</filename>
597	branch:
598	<literallayout class='monospaced'>
599	$ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
600	Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin.
601	Switched to a new branch '&DISTRO_NAME;'
602	</literallayout>
603	</para>
604
605	<para>
606	Next, you need to build the default <filename>qemux86</filename> image that you
607	can boot using QEMU.
608	<note>
609	Because a full build can take hours, you should check two variables in the
610	<filename>build</filename> directory that is created after you source the
611	<filename>&OE_INIT_FILE;</filename> script.
612	You can find these variables
613	<filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>
614	in the <filename>build/conf</filename> directory in the
615	<filename>local.conf</filename> configuration file.
616	By default, these variables are commented out.
617	If your host development system supports multi-core and multi-thread capabilities,
618	you can uncomment these statements and set the variables to significantly shorten
619	the full build time.
620	As a guideline, set both the <filename>BB_NUMBER_THREADS</filename> and the
621	<filename>PARALLEL_MAKE</filename> variables to twice the number
622	of cores your machine supports.
623	</note>
624	The following two commands <filename>source</filename> the build environment setup script
625	and build the default <filename>qemux86</filename> image.
626	If necessary, the script creates the build directory:
627	<literallayout class='monospaced'>
628	$ cd ~/poky
629	$ source &OE_INIT_FILE;
630
631	### Shell environment set up for builds. ###
632
633	You can now run 'bitbake <target>'
634
635	Common targets are:
636	core-image-minimal
637	core-image-sato
638	meta-toolchain
639	meta-toolchain-sdk
640	adt-installer
641	meta-ide-support
642
643	You can also run generated qemu images with a command like 'runqemu qemux86'
644	</literallayout>
645	</para>
646
647	<para>
648	The following <filename>bitbake</filename> command starts the build:
649	<literallayout class='monospaced'>
650	$ bitbake -k core-image-minimal
651	</literallayout>
652	<note>Be sure to check the settings in the <filename>local.conf</filename>
653	before starting the build.</note>
654	</para>
655	</section>
656
657	<section id='examining-the-default-config-smp-behavior'>
658	<title>Examining the Default  <filename>CONFIG_SMP</filename> Behavior</title>
659
660	<para>
661	By default, <filename>CONFIG_SMP</filename> supports multiple processor machines.
662	To see this default setting from within the QEMU emulator, boot your image using
663	the emulator as follows:
664	<literallayout class='monospaced'>
665	$ runqemu qemux86 qemuparams="-smp 4"
666	</literallayout>
667	</para>
668
669	<para>
670	Login to the machine using <filename>root</filename> with no password.
671	After logging in, enter the following command to see how many processors are
672	being supported in the emulator.
673	The emulator reports support for the number of processors you specified using
674	the <filename>-smp</filename> option, four in this case:
675	<literallayout class='monospaced'>
676	# cat /proc/cpuinfo \| grep processor
677	processor : 0
678	processor : 1
679	processor : 2
680	processor : 3
681	#
682	</literallayout>
683	To check the setting for <filename>CONFIG_SMP</filename>, you can use the
684	following command:
685	<literallayout class='monospaced'>
686	zcat /proc/config.gz \| grep CONFIG_SMP
687	</literallayout>
688	The console returns the following showing that multi-processor machine support
689	is set:
690	<literallayout class='monospaced'>
691	CONFIG_SMP=y
692	</literallayout>
693	Logout of the emulator using the <filename>exit</filename> command and
694	then close it down.
695	</para>
696	</section>
697
698	<section id='changing-the-config-smp-configuration-using-menuconfig'>
699	<title>Changing the  <filename>CONFIG_SMP</filename> Configuration Using  <filename>menuconfig</filename></title>
700
701	<para>
702	The <filename>menuconfig</filename> tool provides an interactive method with which
703	to set kernel configurations.
704	You need to run <filename>menuconfig</filename> inside the Yocto BitBake environment.
705	Thus, the environment must be set up using the <filename>&OE_INIT_FILE;</filename>
706	script found in the build directory.
707	If you have not sourced this script do so with the following commands:
708	<literallayout class='monospaced'>
709	$ cd ~/poky
710	$ source &OE_INIT_FILE;
711	</literallayout>
712	</para>
713
714	<para>
715	After setting up the environment to run <filename>menuconfig</filename>, you are ready
716	to use the tool to interactively change the kernel configuration.
717	In this example, we are basing our changes on the <filename>linux-yocto-3.4</filename>
718	kernel.
719	The OpenEmbedded build system recognizes this kernel as
720	<filename>linux-yocto</filename>.
721	Thus, the following commands from the shell in which you previously sourced the
722	environment initialization script cleans the shared state cache and the
723	<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
724	directory and then builds and launches <filename>menuconfig</filename>:
725	<literallayout class='monospaced'>
726	$ bitbake linux-yocto -c menuconfig
727	</literallayout>
728	</para>
729
730	<para>
731	Once <filename>menuconfig</filename> launches, navigate through the user interface
732	to find the <filename>CONFIG_SMP</filename> configuration setting.
733	You can find it at <filename>Processor Type and Features</filename>.
734	The configuration selection is
735	<filename>Symmetric Multi-processing Support</filename>.
736	After using the arrow keys to highlight this selection, press "n" to turn it off.
737	Then, exit out and save your selections.
738	</para>
739
740	<para>
741	Once you save the selection, the <filename>.config</filename> configuration file
742	is updated.
743	This is the file that the build system uses to configure the Yocto Project kernel
744	when it is built.
745	You can find and examine this file in the build directory.
746	This example uses the following:
747	<literallayout class='monospaced'>
748	~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+84f...
749	...656ed30-r1/linux-qemux86-standard-build
750	</literallayout>
751	<note>
752	The previous example directory is artificially split and many of the characters
753	in the actual filename are omitted in order to make it more readable.
754	Also, depending on the kernel you are using, the exact pathname might differ
755	slightly.
756	</note>
757	</para>
758
759	<para>
760	Within the <filename>.config</filename> file, you can see the following setting:
761	<literallayout class='monospaced'>
762	# CONFIG_SMP is not set
763	</literallayout>
764	</para>
765
766	<para>
767	A good method to isolate changed configurations is to use a combination of the
768	<filename>menuconfig</filename> tool and simple shell commands.
769	Before changing configurations with <filename>menuconfig</filename>, copy the
770	existing <filename>.config</filename> and rename it to something else,
771	use <filename>menuconfig</filename> to make
772	as many changes an you want and save them, then compare the renamed configuration
773	file against the newly created file.
774	You can use the resulting differences as your base to create configuration fragments
775	to permanently save in your kernel layer.
776	<note>
777	Be sure to make a copy of the <filename>.config</filename> and don't just
778	rename it.
779	The build system needs an existing <filename>.config</filename>
780	from which to work.
781	</note>
782	</para>
783	</section>
784
785	<section id='recompiling-the-kernel-and-testing-the-new-configuration'>
786	<title>Recompiling the Kernel and Testing the New Configuration</title>
787
788	<para>
789	At this point, you are ready to recompile your kernel image with
790	the new setting in effect using the BitBake command below:
791	<literallayout class='monospaced'>
792	$ bitbake linux-yocto
793	</literallayout>
794	</para>
795
796	<para>
797	Now run the QEMU emulator and pass it the same multi-processor option as before:
798	<literallayout class='monospaced'>
799	$ runqemu qemux86 qemuparams="-smp 4"
800	</literallayout>
801	</para>
802
803	<para>
804	Login to the machine using <filename>root</filename> with no password
805	and test for the number of processors the kernel supports:
806	<literallayout class='monospaced'>
807	# cat /proc/cpuinfo \| grep processor
808	processor : 0
809	#
810	</literallayout>
811	</para>
812
813	<para>
814	From the output, you can see that the kernel no longer supports multi-processor systems.
815	The output indicates support for a single processor. You can verify the
816	<filename>CONFIG_SMP</filename> setting by using this command:
817	<literallayout class='monospaced'>
818	zcat /proc/config.gz \| grep CONFIG_SMP
819	</literallayout>
820	The console returns the following output:
821	<literallayout class='monospaced'>
822	# CONFIG_SMP is not set
823	</literallayout>
824	You have successfully reconfigured the kernel.
825	</para>
826	</section>
827	</section>
828
829	<section id='adding-kernel-recipes'>
830	<title>Adding Kernel Recipes</title>
831
832	<para>
833	A future release of this manual will present an example that adds kernel recipes, which provide
834	new functionality to the kernel.
835	</para>
836
837	<para>
838	<imagedata fileref="figures/wip.png"
839	width="2in" depth="3in" align="center" scalefit="1" />
840	</para>
841	</section>
842	</appendix>	549	</appendix>
843		550
844	<!--	551	<!--