harfbuzz: fix install of version.h

version.h is listed both in pkginclude_HEADERS (via $HBHEADERS) and
nodist_pkginclude_HEADERS. This double listing is likely cause of
the make install error:
/usr/bin/install: cannot create regular file `.../harfbuzz/0.9.10-r0/image/usr/include/harfbuzz/hb-version.h': File exists
Just remove the nodist_pkginclude_HEADERS entry. We're not creating
the tarball, and listing version.h here wouldn't prevent the other
listing from including it to tarball anyway.

(From OE-Core rev: 1489a69cecb1dcc3502a4c24beaea81e6ca6dacc)

Signed-off-by: Marko Lindqvist <cazfi74@gmail.com>
Signed-off-by: Saul Wold <sgw@linux.intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

.gitignore

@@ -1,4 +1,3 @@
-bitbake
 *.pyc
 *.pyo
 /*.patch
@@ -7,12 +6,18 @@ pyshtables.py
 pstage/
 scripts/oe-git-proxy-socks
 sources/
-meta-*
+meta-*/
 !meta-skeleton
-!meta-demoapps
+!meta-hob
+hob-image-*.bb
 *.swp
 *.orig
 *.rej
 *~
-
-
+!meta-yocto
+!meta-yocto-bsp
+bitbake/doc/manual/html/
+bitbake/doc/manual/pdf/
+bitbake/doc/manual/txt/
+bitbake/doc/manual/xhtml/
+pull-*/

bitbake/bin/bitbake

@@ -40,7 +40,7 @@ from bb import cooker
 from bb import ui
 from bb import server
 
-__version__ = "1.16.0"
+__version__ = "1.17.0"
 logger = logging.getLogger("BitBake")
 
 # Unbuffer stdout to avoid log truncation in the event
@@ -214,9 +214,10 @@ Default BBFILES are the .bb files in the current directory.""")
     if configuration.bind and configuration.servertype != "xmlrpc":
         sys.exit("FATAL: If '-B' or '--bind' is defined, we must set the servertype as 'xmlrpc'.\n")
 
-    # Save a logfile for cooker into the current working directory. When the
-    # server is daemonized this logfile will be truncated.
-    cooker_logfile = os.path.join(os.getcwd(), "cooker.log")
+    if "BBDEBUG" in os.environ:
+        level = int(os.environ["BBDEBUG"])
+        if level > configuration.debug:
+            configuration.debug = level
 
     bb.msg.init_msgconfig(configuration.verbose, configuration.debug,
                          configuration.debug_domains)
@@ -246,7 +247,7 @@ Default BBFILES are the .bb files in the current directory.""")
 
     server.addcooker(cooker)
     server.saveConnectionDetails()
-    server.detach(cooker_logfile)
+    server.detach()
 
     # Should no longer need to ever reference cooker
     del cooker

bitbake/bin/image-writer

@@ -28,8 +28,10 @@ import gtk
 import optparse
 import pygtk
 
-from bb.ui.crumbs.hig import DeployImageDialog, ImageSelectionDialog, CrumbsMessageDialog
 from bb.ui.crumbs.hobwidget import HobAltButton, HobButton
+from bb.ui.crumbs.hig.crumbsmessagedialog import CrumbsMessageDialog
+from bb.ui.crumbs.hig.deployimagedialog import DeployImageDialog
+from bb.ui.crumbs.hig.imageselectiondialog import ImageSelectionDialog
 
 # I put all the fs bitbake supported here. Need more test.
 DEPLOYABLE_IMAGE_TYPES = ["jffs2", "cramfs", "ext2", "ext3", "btrfs", "squashfs", "ubi", "vmdk"]

bitbake/contrib/vim/ftdetect/bitbake.vim

@@ -10,8 +10,8 @@ if &compatible || version < 600
     finish
 endif
 
-" .bb and .bbclass
-au BufNewFile,BufRead *.b{b,bclass}	set filetype=bitbake
+" .bb, .bbappend and .bbclass
+au BufNewFile,BufRead *.{bb,bbappend,bbclass}	set filetype=bitbake
 
 " .inc
 au BufNewFile,BufRead *.inc 		set filetype=bitbake

bitbake/lib/bb/__init__.py

@@ -21,7 +21,7 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
-__version__ = "1.16.0"
+__version__ = "1.17.0"
 
 import sys
 if sys.version_info < (2, 6, 0):
@@ -74,11 +74,6 @@ logger.setLevel(logging.DEBUG - 2)
 # can result in construction of the various loggers.
 import bb.msg
 
-if "BBDEBUG" in os.environ:
-    level = int(os.environ["BBDEBUG"])
-    if level:
-        bb.msg.set_debug_level(level)
-
 from bb import fetch2 as fetch
 sys.modules['bb.fetch'] = sys.modules['bb.fetch2']
 

bitbake/lib/bb/build.py

@@ -29,6 +29,7 @@ import os
 import sys
 import logging
 import shlex
+import glob
 import bb
 import bb.msg
 import bb.process
@@ -491,9 +492,11 @@ def stamp_cleanmask_internal(taskname, d, file_name):
         extrainfo = d.getVarFlag(taskflagname, 'stamp-extra-info', True) or ""
 
     if not stamp:
-        return
+        return []
 
-    return bb.parse.siggen.stampcleanmask(stamp, file_name, taskname, extrainfo)
+    cleanmask = bb.parse.siggen.stampcleanmask(stamp, file_name, taskname, extrainfo)
+
+    return [cleanmask, cleanmask.replace(taskflagname, taskflagname + "_setscene")]
 
 def make_stamp(task, d, file_name = None):
     """
@@ -501,9 +504,13 @@ def make_stamp(task, d, file_name = None):
     (d can be a data dict or dataCache)
     """
     cleanmask = stamp_cleanmask_internal(task, d, file_name)
-    if cleanmask:
-        bb.utils.remove(cleanmask)
-
+    for mask in cleanmask:
+        # Preserve sigdata files in the stamps directory
+        for name in glob.glob(mask):
+            if "sigdata" in name:
+                continue
+            os.unlink(name)
+    
     stamp = stamp_internal(task, d, file_name)
     # Remove the file and recreate to force timestamp
     # change on broken NFS filesystems
@@ -584,9 +591,10 @@ def add_tasks(tasklist, d):
         getTask('noexec')
         getTask('umask')
         task_deps['parents'][task] = []
-        for dep in flags['deps']:
-            dep = data.expand(dep, d)
-            task_deps['parents'][task].append(dep)
+        if 'deps' in flags:
+            for dep in flags['deps']:
+                dep = data.expand(dep, d)
+                task_deps['parents'][task].append(dep)
 
     # don't assume holding a reference
     data.setVar('_task_deps', task_deps, d)

bitbake/lib/bb/cache.py

@@ -405,12 +405,12 @@ class Cache(object):
         """Parse the specified filename, returning the recipe information"""
         infos = []
         datastores = cls.load_bbfile(filename, appends, configdata)
-        depends = set()
+        depends = []
         for variant, data in sorted(datastores.iteritems(),
                                     key=lambda i: i[0],
                                     reverse=True):
             virtualfn = cls.realfn2virtual(filename, variant)
-            depends |= (data.getVar("__depends", False) or set())
+            depends = depends + (data.getVar("__depends", False) or [])
             if depends and not variant:
                 data.setVar("__depends", depends)
 

bitbake/lib/bb/command.py

@@ -44,6 +44,9 @@ class CommandFailed(CommandExit):
         self.error = message
         CommandExit.__init__(self, 1)
 
+class CommandError(Exception):
+    pass
+
 class Command:
     """
     A queue of asynchronous commands for bitbake
@@ -57,21 +60,26 @@ class Command:
         self.currentAsyncCommand = None
 
     def runCommand(self, commandline):
-        try:
-            command = commandline.pop(0)
-            if command in CommandsSync.__dict__:
-                # Can run synchronous commands straight away
-                return getattr(CommandsSync, command)(self.cmds_sync, self, commandline)
-            if self.currentAsyncCommand is not None:
-                return "Busy (%s in progress)" % self.currentAsyncCommand[0]
-            if command not in CommandsAsync.__dict__:
-                return "No such command"
-            self.currentAsyncCommand = (command, commandline)
-            self.cooker.server_registration_cb(self.cooker.runCommands, self.cooker)
-            return True
-        except:
-            import traceback
-            return traceback.format_exc()
+        command = commandline.pop(0)
+        if hasattr(CommandsSync, command):
+            # Can run synchronous commands straight away
+            command_method = getattr(self.cmds_sync, command)
+            try:
+                result = command_method(self, commandline)
+            except CommandError as exc:
+                return None, exc.args[0]
+            except Exception:
+                import traceback
+                return None, traceback.format_exc()
+            else:
+                return result, None
+        if self.currentAsyncCommand is not None:
+            return None, "Busy (%s in progress)" % self.currentAsyncCommand[0]
+        if command not in CommandsAsync.__dict__:
+            return None, "No such command"
+        self.currentAsyncCommand = (command, commandline)
+        self.cooker.server_registration_cb(self.cooker.runCommands, self.cooker)
+        return True, None
 
     def runAsyncCommand(self):
         try:
@@ -139,7 +147,13 @@ class CommandsSync:
         """
         Get any command parsed from the commandline
         """
-        return command.cooker.commandlineAction
+        cmd_action = command.cooker.commandlineAction
+        if cmd_action is None:
+            return None
+        elif 'msg' in cmd_action and cmd_action['msg']:
+            raise CommandError(cmd_action['msg'])
+        else:
+            return cmd_action['action']
 
     def getVariable(self, command, params):
         """
@@ -186,6 +200,16 @@ class CommandsSync:
         filterfunc = params[0]
         bb.parse.parse_py.ConfHandler.confFilters.append(filterfunc)
 
+    def matchFile(self, command, params):
+        fMatch = params[0]
+        return command.cooker.matchFile(fMatch)
+
+    def generateNewImage(self, command, params):
+        image = params[0]
+        base_image = params[1]
+        package_queue = params[2]
+        return command.cooker.generateNewImage(image, base_image, package_queue)
+
 class CommandsAsync:
     """
     A class of asynchronous commands

bitbake/lib/bb/cooker.py

@@ -177,6 +177,8 @@ class BBCooker:
 
     def initConfigurationData(self):
         self.configuration.data = bb.data.init()
+        if self.configuration.show_environment:
+            self.configuration.data.enableTracking()
 
         if not self.server_registration_cb:
             self.configuration.data.setVar("BB_WORKERCONTEXT", "1")
@@ -185,13 +187,7 @@ class BBCooker:
         bb.data.inheritFromOS(self.configuration.data, self.savedenv, filtered_keys)
 
     def loadConfigurationData(self):
-        self.configuration.data = bb.data.init()
-
-        if not self.server_registration_cb:
-            self.configuration.data.setVar("BB_WORKERCONTEXT", "1")
-
-        filtered_keys = bb.utils.approved_variables()
-        bb.data.inheritFromOS(self.configuration.data, self.savedenv, filtered_keys)
+        self.initConfigurationData()
 
         try:
             self.parseConfigurationFiles(self.configuration.prefile,
@@ -239,8 +235,10 @@ class BBCooker:
                 self.commandlineAction['msg'] = "No target should be used with the --environment and --buildfile options."
             elif len(self.configuration.pkgs_to_build) > 0:
                 self.commandlineAction['action'] = ["showEnvironmentTarget", self.configuration.pkgs_to_build]
+                self.configuration.data.setVar("BB_CONSOLELOG", None)
             else:
                 self.commandlineAction['action'] = ["showEnvironment", self.configuration.buildfile]
+                self.configuration.data.setVar("BB_CONSOLELOG", None)
         elif self.configuration.buildfile is not None:
             self.commandlineAction['action'] = ["buildFile", self.configuration.buildfile, self.configuration.cmd]
         elif self.configuration.revisions_changed:
@@ -311,6 +309,10 @@ class BBCooker:
         elif len(pkgs_to_build) == 1:
             self.updateCache()
 
+            ignore = self.configuration.data.getVar("ASSUME_PROVIDED", True) or ""
+            if pkgs_to_build[0] in set(ignore.split()):
+                bb.fatal("%s is in ASSUME_PROVIDED" % pkgs_to_build[0])
+
             localdata = data.createCopy(self.configuration.data)
             bb.data.update_data(localdata)
             bb.data.expandKeys(localdata)
@@ -332,6 +334,11 @@ class BBCooker:
                 parselog.exception("Unable to read %s", fn)
                 raise
 
+        # Display history
+        with closing(StringIO()) as env:
+            self.configuration.data.inchistory.emit(env)
+            logger.plain(env.getvalue())
+
         # emit variables and shell functions
         data.update_data(envdata)
         with closing(StringIO()) as env:
@@ -690,8 +697,8 @@ class BBCooker:
         # Generate a list of parsed configuration files by searching the files
         # listed in the __depends and __base_depends variables with a .conf suffix.
         conffiles = []
-        dep_files = self.configuration.data.getVar('__depends') or set()
-        dep_files.union(self.configuration.data.getVar('__base_depends') or set())
+        dep_files = self.configuration.data.getVar('__base_depends') or []
+        dep_files = dep_files + (self.configuration.data.getVar('__depends') or [])
 
         for f in dep_files:
             if f[0].endswith(".conf"):
@@ -1182,6 +1189,25 @@ class BBCooker:
 
         self.server_registration_cb(buildTargetsIdle, rq)
 
+    def generateNewImage(self, image, base_image, package_queue):
+        '''
+        Create a new image with a "require" base_image statement
+        '''
+        image_name = os.path.splitext(image)[0]
+        timestr = time.strftime("-%Y%m%d-%H%M%S")
+        dest = image_name + str(timestr) + ".bb"
+
+        with open(dest, "w") as imagefile:
+            imagefile.write("require " + base_image + "\n")
+            package_install = "PACKAGE_INSTALL_forcevariable = \""
+            for package in package_queue:
+                package_install += str(package) + " "
+            package_install += "\"\n"
+            imagefile.write(package_install)
+
+        self.state = state.initial
+        return timestr
+
     def updateCache(self):
         if self.state == state.running:
             return

bitbake/lib/bb/data.py

@@ -158,7 +158,7 @@ def expandKeys(alterdata, readdata = None):
 
     for key in todolist:
         ekey = todolist[key]
-        renameVar(key, ekey, alterdata)
+        alterdata.renameVar(key, ekey)
 
 def inheritFromOS(d, savedenv, permitted):
     """Inherit variables from the initial environment."""
@@ -166,9 +166,9 @@ def inheritFromOS(d, savedenv, permitted):
     for s in savedenv.keys():
         if s in permitted:
             try:
-                setVar(s, getVar(s, savedenv, True), d)
+                d.setVar(s, getVar(s, savedenv, True), op = 'from env')
                 if s in exportlist:
-                    setVarFlag(s, "export", True, d)
+                    d.setVarFlag(s, "export", True, op = 'auto env export')
             except TypeError:
                 pass
 
@@ -194,8 +194,7 @@ def emit_var(var, o=sys.__stdout__, d = init(), all=False):
         return 0
 
     if all:
-        commentVal = re.sub('\n', '\n#', str(oval))
-        o.write('# %s=%s\n' % (var, commentVal))
+        d.varhistory.emit(var, oval, val, o)
 
     if (var.find("-") != -1 or var.find(".") != -1 or var.find('{') != -1 or var.find('}') != -1 or var.find('+') != -1) and not all:
         return 0
@@ -260,6 +259,7 @@ def emit_func(func, o=sys.__stdout__, d = init()):
 
     emit_var(func, o, d, False) and o.write('\n')
     newdeps = bb.codeparser.ShellParser(func, logger).parse_shell(d.getVar(func, True))
+    newdeps |= set((d.getVarFlag(func, "vardeps", True) or "").split())
     seen = set()
     while newdeps:
         deps = newdeps
@@ -273,7 +273,7 @@ def emit_func(func, o=sys.__stdout__, d = init()):
 
 def update_data(d):
     """Performs final steps upon the datastore, including application of overrides"""
-    d.finalize()
+    d.finalize(parent = True)
 
 def build_dependencies(key, keys, shelldeps, vardepvals, d):
     deps = set()
@@ -357,6 +357,8 @@ def generate_dependencies(d):
 
 def inherits_class(klass, d):
     val = getVar('__inherit_cache', d) or []
-    if os.path.join('classes', '%s.bbclass' % klass) in val:
-        return True
+    needle = os.path.join('classes', '%s.bbclass' % klass)
+    for v in val:
+        if v.endswith(needle):
+            return True
     return False

bitbake/lib/bb/data_smart.py

@@ -28,7 +28,7 @@ BitBake build tools.
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 # Based on functions from the base bb module, Copyright 2003 Holger Schurig
 
-import copy, re
+import copy, re, sys, traceback
 from collections import MutableMapping
 import logging
 import hashlib
@@ -43,6 +43,42 @@ __setvar_regexp__ = re.compile('(?P<base>.*?)(?P<keyword>_append|_prepend)(_(?P<
 __expand_var_regexp__ = re.compile(r"\${[^{}]+}")
 __expand_python_regexp__ = re.compile(r"\${@.+?}")
 
+def infer_caller_details(loginfo, parent = False, varval = True):
+    """Save the caller the trouble of specifying everything."""
+    # Save effort.
+    if 'ignore' in loginfo and loginfo['ignore']:
+        return
+    # If nothing was provided, mark this as possibly unneeded.
+    if not loginfo:
+        loginfo['ignore'] = True
+        return
+    # Infer caller's likely values for variable (var) and value (value), 
+    # to reduce clutter in the rest of the code.
+    if varval and ('variable' not in loginfo or 'detail' not in loginfo):
+        try:
+            raise Exception
+        except Exception:
+            tb = sys.exc_info()[2]
+            if parent:
+                above = tb.tb_frame.f_back.f_back
+            else:
+                above = tb.tb_frame.f_back
+            lcls = above.f_locals.items()
+        for k, v in lcls:
+            if k == 'value' and 'detail' not in loginfo:
+                loginfo['detail'] = v
+            if k == 'var' and 'variable' not in loginfo:
+                loginfo['variable'] = v
+    # Infer file/line/function from traceback
+    if 'file' not in loginfo:
+        depth = 3    
+        if parent:
+            depth = 4
+        file, line, func, text = traceback.extract_stack(limit = depth)[0]
+        loginfo['file'] = file
+        loginfo['line'] = line
+        if func not in loginfo:
+            loginfo['func'] = func
 
 class VariableParse:
     def __init__(self, varname, d, val = None):
@@ -114,16 +150,136 @@ class ExpansionError(Exception):
     def __str__(self):
         return self.msg
 
+class IncludeHistory(object):
+    def __init__(self, parent = None, filename = '[TOP LEVEL]'):
+        self.parent = parent
+        self.filename = filename
+        self.children = []
+        self.current = self
+
+    def copy(self):
+        new = IncludeHistory(self.parent, self.filename)
+        for c in self.children:
+            new.children.append(c)
+        return new
+
+    def include(self, filename):
+        newfile = IncludeHistory(self.current, filename)
+        self.current.children.append(newfile)
+        self.current = newfile
+        return self
+
+    def __enter__(self):
+        pass
+
+    def __exit__(self, a, b, c):
+        if self.current.parent:
+            self.current = self.current.parent
+        else:
+            bb.warn("Include log: Tried to finish '%s' at top level." % filename)
+        return False
+
+    def emit(self, o, level = 0):
+        """Emit an include history file, and its children."""
+        if level:
+            spaces = "  " * (level - 1)
+            o.write("# %s%s" % (spaces, self.filename))
+            if len(self.children) > 0:
+                o.write(" includes:")
+        else:
+            o.write("#\n# INCLUDE HISTORY:\n#")
+        level = level + 1
+        for child in self.children:
+            o.write("\n")
+            child.emit(o, level)
+
+class VariableHistory(object):
+    def __init__(self, dataroot):
+        self.dataroot = dataroot
+        self.variables = COWDictBase.copy()
+
+    def copy(self):
+        new = VariableHistory(self.dataroot)
+        new.variables = self.variables.copy()
+        return new
+
+    def record(self, *kwonly, **loginfo):
+        if not self.dataroot._tracking:
+            return
+        if len(kwonly) > 0:
+            raise TypeError
+        infer_caller_details(loginfo, parent = True)
+        if 'ignore' in loginfo and loginfo['ignore']:
+            return
+        if 'op' not in loginfo or not loginfo['op']:
+            loginfo['op'] = 'set'
+        if 'detail' in loginfo:
+            loginfo['detail'] = str(loginfo['detail'])
+        if 'variable' not in loginfo or 'file' not in loginfo:
+            raise ValueError("record() missing variable or file.")
+        var = loginfo['variable']
+
+        if var not in self.variables:
+            self.variables[var] = []
+        self.variables[var].append(loginfo.copy())
+
+    def variable(self, var):
+        if var in self.variables:
+            return self.variables[var]
+        else:
+            return []
+
+    def emit(self, var, oval, val, o):
+        history = self.variable(var)
+        commentVal = re.sub('\n', '\n#', str(oval))
+        if history:
+            if len(history) == 1:
+                o.write("#\n# $%s\n" % var)
+            else:
+                o.write("#\n# $%s [%d operations]\n" % (var, len(history)))
+            for event in history:
+                # o.write("# %s\n" % str(event))
+                if 'func' in event:
+                    # If we have a function listed, this is internal
+                    # code, not an operation in a config file, and the
+                    # full path is distracting.
+                    event['file'] = re.sub('.*/', '', event['file'])
+                    display_func = ' [%s]' % event['func']
+                else:
+                    display_func = ''
+                if 'flag' in event:
+                    flag = '[%s] ' % (event['flag'])
+                else:
+                    flag = ''
+                o.write("#   %s %s:%s%s\n#     %s\"%s\"\n" % (event['op'], event['file'], event['line'], display_func, flag, re.sub('\n', '\n#     ', event['detail'])))
+            if len(history) > 1:
+                o.write("# computed:\n")
+                o.write('#   "%s"\n' % (commentVal))
+        else:
+            o.write("#\n# $%s\n#   [no history recorded]\n#\n" % var)
+            o.write('#   "%s"\n' % (commentVal))
+
+
 class DataSmart(MutableMapping):
     def __init__(self, special = COWDictBase.copy(), seen = COWDictBase.copy() ):
         self.dict = {}
 
+        self.inchistory = IncludeHistory()
+        self.varhistory = VariableHistory(self)
+        self._tracking = False
+
         # cookie monster tribute
         self._special_values = special
         self._seen_overrides = seen
 
         self.expand_cache = {}
 
+    def enableTracking(self):
+        self._tracking = True
+
+    def disableTracking(self):
+        self._tracking = False
+
     def expandWithRefs(self, s, varname):
 
         if not isinstance(s, basestring): # sanity check
@@ -143,6 +299,8 @@ class DataSmart(MutableMapping):
                     break
             except ExpansionError:
                 raise
+            except bb.parse.SkipPackage:
+                raise
             except Exception as exc:
                 raise ExpansionError(varname, s, exc)
 
@@ -157,10 +315,14 @@ class DataSmart(MutableMapping):
         return self.expandWithRefs(s, varname).value
 
 
-    def finalize(self):
+    def finalize(self, parent = False):
         """Performs final steps upon the datastore, including application of overrides"""
 
         overrides = (self.getVar("OVERRIDES", True) or "").split(":") or []
+        finalize_caller = {
+            'op': 'finalize',
+        }
+        infer_caller_details(finalize_caller, parent = parent, varval = False)
 
         #
         # Well let us see what breaks here. We used to iterate
@@ -177,6 +339,9 @@ class DataSmart(MutableMapping):
         # Then  we will handle _append and _prepend
         #
 
+        # We only want to report finalization once per variable overridden.
+        finalizes_reported = {}
+
         for o in overrides:
             # calculate '_'+override
             l = len(o) + 1
@@ -189,7 +354,19 @@ class DataSmart(MutableMapping):
             for var in vars:
                 name = var[:-l]
                 try:
-                    self.setVar(name, self.getVar(var, False))
+                    # Report only once, even if multiple changes.
+                    if name not in finalizes_reported:
+                        finalizes_reported[name] = True
+                        finalize_caller['variable'] = name
+                        finalize_caller['detail'] = 'was: ' + str(self.getVar(name, False))
+                        self.varhistory.record(**finalize_caller)
+                    # Copy history of the override over.
+                    for event in self.varhistory.variable(var):
+                        loginfo = event.copy()
+                        loginfo['variable'] = name
+                        loginfo['op'] = 'override[%s]:%s' % (o, loginfo['op'])
+                        self.varhistory.record(**loginfo)
+                    self.setVar(name, self.getVar(var, False), op = 'finalize', file = 'override[%s]' % o, line = '')
                     self.delVar(var)
                 except Exception:
                     logger.info("Untracked delVar")
@@ -220,9 +397,9 @@ class DataSmart(MutableMapping):
 
                     # We save overrides that may be applied at some later stage
                     if keep:
-                        self.setVarFlag(append, op, keep)
+                        self.setVarFlag(append, op, keep, ignore=True)
                     else:
-                        self.delVarFlag(append, op)
+                        self.delVarFlag(append, op, ignore=True)
 
     def initVar(self, var):
         self.expand_cache = {}
@@ -250,7 +427,10 @@ class DataSmart(MutableMapping):
         else:
             self.initVar(var)
 
-    def setVar(self, var, value):
+
+    def setVar(self, var, value, **loginfo):
+        if 'op' not in loginfo:
+            loginfo['op'] = "set"
         self.expand_cache = {}
         match  = __setvar_regexp__.match(var)
         if match and match.group("keyword") in __setvar_keyword__:
@@ -259,15 +439,22 @@ class DataSmart(MutableMapping):
             override = match.group('add')
             l = self.getVarFlag(base, keyword) or []
             l.append([value, override])
-            self.setVarFlag(base, keyword, l)
-
+            self.setVarFlag(base, keyword, l, ignore=True)
+            # And cause that to be recorded:
+            loginfo['detail'] = value
+            loginfo['variable'] = base
+            if override:
+                loginfo['op'] = '%s[%s]' % (keyword, override)
+            else:
+                loginfo['op'] = keyword
+            self.varhistory.record(**loginfo)
             # todo make sure keyword is not __doc__ or __module__
             # pay the cookie monster
             try:
-                self._special_values[keyword].add( base )
+                self._special_values[keyword].add(base)
             except KeyError:
                 self._special_values[keyword] = set()
-                self._special_values[keyword].add( base )
+                self._special_values[keyword].add(base)
 
             return
 
@@ -284,6 +471,7 @@ class DataSmart(MutableMapping):
 
         # setting var
         self.dict[var]["_content"] = value
+        self.varhistory.record(**loginfo)
 
     def getVar(self, var, expand=False, noweakdefault=False):
         value = self.getVarFlag(var, "_content", False, noweakdefault)
@@ -293,13 +481,17 @@ class DataSmart(MutableMapping):
             return self.expand(value, var)
         return value
 
-    def renameVar(self, key, newkey):
+    def renameVar(self, key, newkey, **loginfo):
         """
         Rename the variable key to newkey
         """
         val = self.getVar(key, 0)
         if val is not None:
-            self.setVar(newkey, val)
+            loginfo['variable'] = newkey
+            loginfo['op'] = 'rename from %s' % key
+            loginfo['detail'] = val
+            self.varhistory.record(**loginfo)
+            self.setVar(newkey, val, ignore=True)
 
         for i in ('_append', '_prepend'):
             src = self.getVarFlag(key, i)
@@ -308,23 +500,34 @@ class DataSmart(MutableMapping):
 
             dest = self.getVarFlag(newkey, i) or []
             dest.extend(src)
-            self.setVarFlag(newkey, i, dest)
+            self.setVarFlag(newkey, i, dest, ignore=True)
 
             if i in self._special_values and key in self._special_values[i]:
                 self._special_values[i].remove(key)
                 self._special_values[i].add(newkey)
 
-        self.delVar(key)
+        loginfo['variable'] = key
+        loginfo['op'] = 'rename (to)'
+        loginfo['detail'] = newkey
+        self.varhistory.record(**loginfo)
+        self.delVar(key, ignore=True)
 
-    def appendVar(self, key, value):
-        value = (self.getVar(key, False) or "") + value
-        self.setVar(key, value)
+    def appendVar(self, var, value, **loginfo):
+        loginfo['op'] = 'append'
+        self.varhistory.record(**loginfo)
+        newvalue = (self.getVar(var, False) or "") + value
+        self.setVar(var, newvalue, ignore=True)
 
-    def prependVar(self, key, value):
-        value = value + (self.getVar(key, False) or "")
-        self.setVar(key, value)
+    def prependVar(self, var, value, **loginfo):
+        loginfo['op'] = 'prepend'
+        self.varhistory.record(**loginfo)
+        newvalue = value + (self.getVar(var, False) or "")
+        self.setVar(var, newvalue, ignore=True)
 
-    def delVar(self, var):
+    def delVar(self, var, **loginfo):
+        loginfo['detail'] = ""
+        loginfo['op'] = 'del'
+        self.varhistory.record(**loginfo)
         self.expand_cache = {}
         self.dict[var] = {}
         if '_' in var:
@@ -332,10 +535,14 @@ class DataSmart(MutableMapping):
             if override and override in self._seen_overrides and var in self._seen_overrides[override]:
                 self._seen_overrides[override].remove(var)
 
-    def setVarFlag(self, var, flag, flagvalue):
+    def setVarFlag(self, var, flag, value, **loginfo):
+        if 'op' not in loginfo:
+            loginfo['op'] = "set"
+        loginfo['flag'] = flag
+        self.varhistory.record(**loginfo)
         if not var in self.dict:
             self._makeShadowCopy(var)
-        self.dict[var][flag] = flagvalue
+        self.dict[var][flag] = value
 
     def getVarFlag(self, var, flag, expand=False, noweakdefault=False):
         local_var = self._findVar(var)
@@ -349,7 +556,7 @@ class DataSmart(MutableMapping):
             value = self.expand(value, None)
         return value
 
-    def delVarFlag(self, var, flag):
+    def delVarFlag(self, var, flag, **loginfo):
         local_var = self._findVar(var)
         if not local_var:
             return
@@ -357,23 +564,38 @@ class DataSmart(MutableMapping):
             self._makeShadowCopy(var)
 
         if var in self.dict and flag in self.dict[var]:
+            loginfo['detail'] = ""
+            loginfo['op'] = 'delFlag'
+            loginfo['flag'] = flag
+            self.varhistory.record(**loginfo)
+
             del self.dict[var][flag]
 
-    def appendVarFlag(self, key, flag, value):
-        value = (self.getVarFlag(key, flag, False) or "") + value
-        self.setVarFlag(key, flag, value)
+    def appendVarFlag(self, var, flag, value, **loginfo):
+        loginfo['op'] = 'append'
+        loginfo['flag'] = flag
+        self.varhistory.record(**loginfo)
+        newvalue = (self.getVarFlag(var, flag, False) or "") + value
+        self.setVarFlag(var, flag, newvalue, ignore=True)
 
-    def prependVarFlag(self, key, flag, value):
-        value = value + (self.getVarFlag(key, flag, False) or "")
-        self.setVarFlag(key, flag, value)
+    def prependVarFlag(self, var, flag, value, **loginfo):
+        loginfo['op'] = 'prepend'
+        loginfo['flag'] = flag
+        self.varhistory.record(**loginfo)
+        newvalue = value + (self.getVarFlag(var, flag, False) or "")
+        self.setVarFlag(var, flag, newvalue, ignore=True)
 
-    def setVarFlags(self, var, flags):
+    def setVarFlags(self, var, flags, **loginfo):
+        infer_caller_details(loginfo)
         if not var in self.dict:
             self._makeShadowCopy(var)
 
         for i in flags:
             if i == "_content":
                 continue
+            loginfo['flag'] = i
+            loginfo['detail'] = flags[i]
+            self.varhistory.record(**loginfo)
             self.dict[var][i] = flags[i]
 
     def getVarFlags(self, var):
@@ -391,13 +613,16 @@ class DataSmart(MutableMapping):
         return flags
 
 
-    def delVarFlags(self, var):
+    def delVarFlags(self, var, **loginfo):
         if not var in self.dict:
             self._makeShadowCopy(var)
 
         if var in self.dict:
             content = None
 
+            loginfo['op'] = 'delete flags'
+            self.varhistory.record(**loginfo)
+
             # try to save the content
             if "_content" in self.dict[var]:
                 content  = self.dict[var]["_content"]
@@ -414,6 +639,11 @@ class DataSmart(MutableMapping):
         # we really want this to be a DataSmart...
         data = DataSmart(seen=self._seen_overrides.copy(), special=self._special_values.copy())
         data.dict["_data"] = self.dict
+        data.varhistory = self.varhistory.copy()
+        data.varhistory.datasmart = data
+        data.inchistory = self.inchistory.copy()
+
+        data._tracking = self._tracking
 
         return data
 
@@ -474,12 +704,16 @@ class DataSmart(MutableMapping):
 
     def get_hash(self):
         data = {}
-        config_whitelist = set((self.getVar("BB_HASHCONFIG_WHITELIST", True) or "").split())
-        keys = set(key for key in iter(self) if not key.startswith("__"))
+        d = self.createCopy()
+        bb.data.expandKeys(d)
+        bb.data.update_data(d)
+
+        config_whitelist = set((d.getVar("BB_HASHCONFIG_WHITELIST", True) or "").split())
+        keys = set(key for key in iter(d) if not key.startswith("__"))
         for key in keys:
             if key in config_whitelist:
                 continue
-            value = self.getVar(key, False) or ""
+            value = d.getVar(key, False) or ""
             data.update({key:value})
 
         data_str = str([(k, data[k]) for k in sorted(data.keys())])

bitbake/lib/bb/event.py

@@ -566,3 +566,19 @@ class SanityCheckFailed(Event):
         Event.__init__(self)
         self._msg = msg
         self._network_error = network_error
+
+class NetworkTest(Event):
+    """
+    Event to start network test
+    """
+
+class NetworkTestPassed(Event):
+    """
+    Event to indicate network test has passed
+    """
+
+class NetworkTestFailed(Event):
+    """
+    Event to indicate network test has failed
+    """
+

bitbake/lib/bb/fetch2/__init__.py

@@ -30,6 +30,7 @@ from __future__ import print_function
 import os, re
 import logging
 import urllib
+import operator
 import bb.persist_data, bb.utils
 import bb.checksum
 from bb import data
@@ -422,10 +423,18 @@ def get_srcrev(d):
     if not format:
         raise FetchError("The SRCREV_FORMAT variable must be set when multiple SCMs are used.")
 
+    autoinc = False
+    autoinc_templ = 'AUTOINC+'
     for scm in scms:
         ud = urldata[scm]
         for name in ud.names:
             rev = ud.method.sortable_revision(scm, ud, d, name)
+            if rev.startswith(autoinc_templ):
+                if not autoinc:
+                    autoinc = True
+                    format = "%s%s" % (autoinc_templ, format)
+                rev = rev[len(autoinc_templ):]
+
             format = format.replace(name, rev)
 
     return format
@@ -721,7 +730,7 @@ def get_file_checksums(filelist, pn):
         if checksum:
             checksums.append((pth, checksum))
 
-    checksums.sort()
+    checksums.sort(key=operator.itemgetter(1))
     return checksums
 
 
@@ -963,15 +972,18 @@ class FetchMethod(object):
             dest = os.path.join(rootdir, os.path.basename(file))
             if (file != dest) and not (os.path.exists(dest) and os.path.samefile(file, dest)):
                 if os.path.isdir(file):
-                    filesdir = os.path.realpath(data.getVar("FILESDIR", True))
+                    # If for example we're asked to copy file://foo/bar, we need to unpack the result into foo/bar
+                    basepath = getattr(urldata, "basepath", None)
                     destdir = "."
-                    if file[0:len(filesdir)] == filesdir:
-                        destdir = file[len(filesdir):file.rfind('/')]
+                    if basepath and basepath.endswith("/"):
+                        basepath = basepath.rstrip("/")
+                    elif basepath:
+                        basepath = os.path.dirname(basepath)
+                    if basepath and basepath.find("/") != -1:
+                        destdir = basepath[:basepath.rfind('/')]
                         destdir = destdir.strip('/')
-                        if len(destdir) < 1:
-                            destdir = "."
-                        elif not os.access("%s/%s" % (rootdir, destdir), os.F_OK):
-                            os.makedirs("%s/%s" % (rootdir, destdir))
+                    if destdir != "." and not os.access("%s/%s" % (rootdir, destdir), os.F_OK):
+                        os.makedirs("%s/%s" % (rootdir, destdir))
                     cmd = 'cp -pPR %s %s/%s/' % (file, rootdir, destdir)
                     #cmd = 'tar -cf - -C "%d" -ps . | tar -xf - -C "%s/%s/"' % (file, rootdir, destdir)
                 else:
@@ -1033,23 +1045,6 @@ class FetchMethod(object):
         logger.info("URL %s could not be checked for status since no method exists.", url)
         return True
 
-    def localcount_internal_helper(ud, d, name):
-        """
-        Return:
-            a) a locked localcount if specified
-            b) None otherwise
-        """
-
-        localcount = None
-        if name != '':
-            pn = d.getVar("PN", True)
-            localcount = d.getVar("LOCALCOUNT_" + name, True)
-        if not localcount:
-            localcount = d.getVar("LOCALCOUNT", True)
-        return localcount
-
-    localcount_internal_helper = staticmethod(localcount_internal_helper)
-
     def latest_revision(self, url, ud, d, name):
         """
         Look in the cache for the latest revision, if not present ask the SCM.
@@ -1072,36 +1067,8 @@ class FetchMethod(object):
         if hasattr(self, "_sortable_revision"):
             return self._sortable_revision(url, ud, d)
 
-        localcounts = bb.persist_data.persist('BB_URI_LOCALCOUNT', d)
-        key = self.generate_revision_key(url, ud, d, name)
-
         latest_rev = self._build_revision(url, ud, d, name)
-        last_rev = localcounts.get(key + '_rev')
-        uselocalcount = d.getVar("BB_LOCALCOUNT_OVERRIDE", True) or False
-        count = None
-        if uselocalcount:
-            count = FetchMethod.localcount_internal_helper(ud, d, name)
-        if count is None:
-            count = localcounts.get(key + '_count') or "0"
-
-        if last_rev == latest_rev:
-            return str(count + "+" + latest_rev)
-
-        buildindex_provided = hasattr(self, "_sortable_buildindex")
-        if buildindex_provided:
-            count = self._sortable_buildindex(url, ud, d, latest_rev)
-
-        if count is None:
-            count = "0"
-        elif uselocalcount or buildindex_provided:
-            count = str(count)
-        else:
-            count = str(int(count) + 1)
-
-        localcounts[key + '_rev'] = latest_rev
-        localcounts[key + '_count'] = count
-
-        return str(count + "+" + latest_rev)
+        return 'AUTOINC+%s' % str(latest_rev)
 
     def generate_revision_key(self, url, ud, d, name):
         key = self._revision_key(url, ud, d, name)

bitbake/lib/bb/fetch2/git.py

@@ -11,8 +11,8 @@ Supported SRC_URI options are:
 - branch
    The git branch to retrieve from. The default is "master"
 
-   this option also support multiple branches fetching, branches
-   are seperated by comma. in multiple branches case, the name option
+   This option also supports multiple branch fetching, with branches
+   separated by commas.  In multiple branches case, the name option
    must have the same number of names to match the branches, which is
    used to specify the SRC_REV for the branch
    e.g:
@@ -25,13 +25,13 @@ Supported SRC_URI options are:
 
 - protocol
    The method to use to access the repository. Common options are "git",
-   "http", "file" and "rsync". The default is "git"
+   "http", "https", "file", "ssh" and "rsync". The default is "git".
 
 - rebaseable
    rebaseable indicates that the upstream git repo may rebase in the future,
    and current revision may disappear from upstream repo. This option will
-   reminder fetcher to preserve local cache carefully for future use.
-   The default value is "0", set rebaseable=1 for rebaseable git repo
+   remind fetcher to preserve local cache carefully for future use.
+   The default value is "0", set rebaseable=1 for rebaseable git repo.
 
 - nocheckout
    Don't checkout source code when unpacking. set this option for the recipe
@@ -71,11 +71,8 @@ from   bb.fetch2 import logger
 class Git(FetchMethod):
     """Class to fetch a module or modules from git repositories"""
     def init(self, d):
-        #
-        # Only enable _sortable revision if the key is set
-        #
-        if d.getVar("BB_GIT_CLONE_FOR_SRCREV", True):
-            self._sortable_buildindex = self._sortable_buildindex_disabled
+        pass
+
     def supports(self, url, ud, d):
         """
         Check to see if a given url can be fetched with git.
@@ -316,38 +313,6 @@ class Git(FetchMethod):
     def _build_revision(self, url, ud, d, name):
         return ud.revisions[name]
 
-    def _sortable_buildindex_disabled(self, url, ud, d, rev):
-        """
-        Return a suitable buildindex for the revision specified. This is done by counting revisions
-        using "git rev-list" which may or may not work in different circumstances.
-        """
-
-        cwd = os.getcwd()
-
-        # Check if we have the rev already
-
-        if not os.path.exists(ud.clonedir):
-            logger.debug(1, "GIT repository for %s does not exist in %s.  \
-                          Downloading.", url, ud.clonedir)
-            self.download(None, ud, d)
-            if not os.path.exists(ud.clonedir):
-                logger.error("GIT repository for %s does not exist in %s after \
-                             download. Cannot get sortable buildnumber, using \
-                             old value", url, ud.clonedir)
-                return None
-
-
-        os.chdir(ud.clonedir)
-        if not self._contains_ref(rev, d):
-            self.download(None, ud, d)
-
-        output = runfetchcmd("%s rev-list %s -- 2> /dev/null | wc -l" % (ud.basecmd, rev), d, quiet=True)
-        os.chdir(cwd)
-
-        buildindex = "%s" % output.split()[0]
-        logger.debug(1, "GIT repository for %s in %s is returning %s revisions in rev-list before %s", url, ud.clonedir, buildindex, rev)
-        return buildindex
-
     def checkstatus(self, uri, ud, d):
         fetchcmd = "%s ls-remote %s" % (ud.basecmd, uri)
         try:

bitbake/lib/bb/fetch2/hg.py

@@ -98,7 +98,12 @@ class Hg(FetchMethod):
             return "%s identify -i %s://%s/%s" % (basecmd, proto, hgroot, ud.module)
 
         options = [];
-        if ud.revision:
+
+        # Don't specify revision for the fetch; clone the entire repo.
+        # This avoids an issue if the specified revision is a tag, because
+        # the tag actually exists in the specified revision + 1, so it won't
+        # be available when used in any successive commands.
+        if ud.revision and command != "fetch":
             options.append("-r %s" % ud.revision)
 
         if command == "fetch":

bitbake/lib/bb/fetch2/local.py

@@ -44,6 +44,7 @@ class Local(FetchMethod):
         # We don't set localfile as for this fetcher the file is already local!
         ud.decodedurl = urllib.unquote(ud.url.split("://")[1].split(";")[0])
         ud.basename = os.path.basename(ud.decodedurl)
+        ud.basepath = ud.decodedurl
         return
 
     def localpath(self, url, urldata, d):
@@ -62,7 +63,12 @@ class Local(FetchMethod):
                 if filesdir:
                     logger.debug(2, "Searching for %s in path: %s" % (path, filesdir))
                     newpath = os.path.join(filesdir, path)
-            if not os.path.exists(newpath) and path.find("*") == -1:
+            if (not newpath or not os.path.exists(newpath)) and path.find("*") != -1:
+                # For expressions using '*', best we can do is take the first directory in FILESPATH that exists
+                newpath = bb.utils.which(filespath, ".")
+                logger.debug(2, "Searching for %s in path: %s" % (path, newpath))
+                return newpath
+            if not os.path.exists(newpath):
                 dldirfile = os.path.join(d.getVar("DL_DIR", True), path)
                 logger.debug(2, "Defaulting to %s for %s" % (dldirfile, path))
                 bb.utils.mkdirhier(os.path.dirname(dldirfile))

bitbake/lib/bb/fetch2/wget.py

@@ -69,10 +69,10 @@ class Wget(FetchMethod):
             basecmd += " -O ${DL_DIR}/" + ud.localfile
 
         if checkonly:
-            fetchcmd = d.getVar("CHECKCOMMAND_wget", True) or d.expand(basecmd + " -c -P ${DL_DIR} '${URI}'")
+            fetchcmd = d.getVar("CHECKCOMMAND_wget", True) or d.expand(basecmd + " --spider '${URI}'")
         elif os.path.exists(ud.localpath):
             # file exists, but we didnt complete it.. trying again..
-            fetchcmd = d.getVar("RESUMECOMMAND_wget", True) or d.expand(basecmd + " --spider -P ${DL_DIR} '${URI}'")
+            fetchcmd = d.getVar("RESUMECOMMAND_wget", True) or d.expand(basecmd + " -c -P ${DL_DIR} '${URI}'")
         else:
             fetchcmd = d.getVar("FETCHCOMMAND_wget", True) or d.expand(basecmd + " -P ${DL_DIR} '${URI}'")
 

bitbake/lib/bb/msg.py

@@ -23,6 +23,7 @@ Message handling infrastructure for bitbake
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
 import sys
+import copy
 import logging
 import collections
 from itertools import groupby
@@ -55,6 +56,25 @@ class BBLogFormatter(logging.Formatter):
         CRITICAL: 'ERROR',
     }
 
+    color_enabled = False
+    BASECOLOR, BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE = range(29,38)
+
+    COLORS = {
+        DEBUG3  : CYAN,
+        DEBUG2  : CYAN,
+        DEBUG   : CYAN,
+        VERBOSE : BASECOLOR,
+        NOTE    : BASECOLOR,
+        PLAIN   : BASECOLOR,
+        WARNING : YELLOW,
+        ERROR   : RED,
+        CRITICAL: RED,
+    }
+
+    BLD = '\033[1;%dm'
+    STD = '\033[%dm'
+    RST = '\033[0m'
+
     def getLevelName(self, levelno):
         try:
             return self.levelnames[levelno]
@@ -67,6 +87,8 @@ class BBLogFormatter(logging.Formatter):
         if record.levelno == self.PLAIN:
             msg = record.getMessage()
         else:
+            if self.color_enabled:
+                record = self.colorize(record)
             msg = logging.Formatter.format(self, record)
 
         if hasattr(record, 'bb_exc_info'):
@@ -75,6 +97,17 @@ class BBLogFormatter(logging.Formatter):
             msg += '\n' + ''.join(formatted)
         return msg
 
+    def colorize(self, record):
+        color = self.COLORS[record.levelno]
+        if self.color_enabled and color is not None:
+            record = copy.copy(record)
+            record.levelname = "".join([self.BLD % color, record.levelname, self.RST])
+            record.msg = "".join([self.STD % color, record.msg, self.RST])
+        return record
+
+    def enable_color(self):
+        self.color_enabled = True
+
 class BBLogFilter(object):
     def __init__(self, handler, level, debug_domains):
         self.stdlevel = level

bitbake/lib/bb/parse/__init__.py

@@ -73,8 +73,7 @@ def update_mtime(f):
 def mark_dependency(d, f):
     if f.startswith('./'):
         f = "%s/%s" % (os.getcwd(), f[2:])
-    deps = d.getVar('__depends') or set()
-    deps.update([(f, cached_mtime(f))])
+    deps = (d.getVar('__depends') or []) + [(f, cached_mtime(f))]
     d.setVar('__depends', deps)
 
 def supports(fn, data):
@@ -88,7 +87,8 @@ def handle(fn, data, include = 0):
     """Call the handler that is appropriate for this file"""
     for h in handlers:
         if h['supports'](fn, data):
-            return h['handle'](fn, data, include)
+            with data.inchistory.include(fn):
+                return h['handle'](fn, data, include)
     raise ParseError("not a BitBake file", fn)
 
 def init(fn, data):
@@ -134,8 +134,8 @@ def vars_from_file(mypkg, d):
 def get_file_depends(d):
     '''Return the dependent files'''
     dep_files = []
-    depends = d.getVar('__depends', True) or set()
-    depends = depends.union(d.getVar('__base_depends', True) or set())
+    depends = d.getVar('__base_depends', True) or []
+    depends = depends + (d.getVar('__depends', True) or [])
     for (fn, _) in depends:
         dep_files.append(os.path.abspath(fn))
     return " ".join(dep_files)

bitbake/lib/bb/parse/ast.py

@@ -68,7 +68,7 @@ class ExportNode(AstNode):
         self.var = var
 
     def eval(self, data):
-        data.setVarFlag(self.var, "export", 1)
+        data.setVarFlag(self.var, "export", 1, op = 'exported')
 
 class DataNode(AstNode):
     """
@@ -90,33 +90,53 @@ class DataNode(AstNode):
     def eval(self, data):
         groupd = self.groupd
         key = groupd["var"]
+        loginfo = {
+            'variable': key,
+            'file': self.filename,
+            'line': self.lineno,
+        }
         if "exp" in groupd and groupd["exp"] != None:
-            data.setVarFlag(key, "export", 1)
+            data.setVarFlag(key, "export", 1, op = 'exported', **loginfo)
+
+        op = "set"
         if "ques" in groupd and groupd["ques"] != None:
             val = self.getFunc(key, data)
+            op = "set?"
             if val == None:
                 val = groupd["value"]
         elif "colon" in groupd and groupd["colon"] != None:
             e = data.createCopy()
             bb.data.update_data(e)
+            op = "immediate"
             val = e.expand(groupd["value"], key + "[:=]")
         elif "append" in groupd and groupd["append"] != None:
+            op = "append"
             val = "%s %s" % ((self.getFunc(key, data) or ""), groupd["value"])
         elif "prepend" in groupd and groupd["prepend"] != None:
+            op = "prepend"
             val = "%s %s" % (groupd["value"], (self.getFunc(key, data) or ""))
         elif "postdot" in groupd and groupd["postdot"] != None:
+            op = "postdot"
             val = "%s%s" % ((self.getFunc(key, data) or ""), groupd["value"])
         elif "predot" in groupd and groupd["predot"] != None:
+            op = "predot"
             val = "%s%s" % (groupd["value"], (self.getFunc(key, data) or ""))
         else:
             val = groupd["value"]
 
+        flag = None
         if 'flag' in groupd and groupd['flag'] != None:
-            data.setVarFlag(key, groupd['flag'], val)
+            flag = groupd['flag']
         elif groupd["lazyques"]:
-            data.setVarFlag(key, "defaultval", val)
+            flag = "defaultval"
+
+        loginfo['op'] = op
+        loginfo['detail'] = groupd["value"]
+
+        if flag:
+            data.setVarFlag(key, flag, val, **loginfo)
         else:
-            data.setVar(key, val)
+            data.setVar(key, val, **loginfo)
 
 class MethodNode(AstNode):
     def __init__(self, filename, lineno, func_name, body):
@@ -179,44 +199,35 @@ class MethodFlagsNode(AstNode):
             data.delVarFlag(self.key, "fakeroot")
 
 class ExportFuncsNode(AstNode):
-    def __init__(self, filename, lineno, fns, classes):
+    def __init__(self, filename, lineno, fns, classname):
         AstNode.__init__(self, filename, lineno)
         self.n = fns.split()
-        self.classes = classes
+        self.classname = classname
 
     def eval(self, data):
-        for f in self.n:
-            allvars = []
-            allvars.append(f)
-            allvars.append(self.classes[-1] + "_" + f)
 
-            vars = [[ allvars[0], allvars[1] ]]
-            if len(self.classes) > 1 and self.classes[-2] is not None:
-                allvars.append(self.classes[-2] + "_" + f)
-                vars = []
-                vars.append([allvars[2], allvars[1]])
-                vars.append([allvars[0], allvars[2]])
+        for func in self.n:
+            calledfunc = self.classname + "_" + func
 
-            for (var, calledvar) in vars:
-                if data.getVar(var) and not data.getVarFlag(var, 'export_func'):
-                    continue
+            if data.getVar(func) and not data.getVarFlag(func, 'export_func'):
+                continue
 
-                if data.getVar(var):
-                    data.setVarFlag(var, 'python', None)
-                    data.setVarFlag(var, 'func', None)
+            if data.getVar(func):
+                data.setVarFlag(func, 'python', None)
+                data.setVarFlag(func, 'func', None)
 
-                for flag in [ "func", "python" ]:
-                    if data.getVarFlag(calledvar, flag):
-                        data.setVarFlag(var, flag, data.getVarFlag(calledvar, flag))
-                for flag in [ "dirs" ]:
-                    if data.getVarFlag(var, flag):
-                        data.setVarFlag(calledvar, flag, data.getVarFlag(var, flag))
+            for flag in [ "func", "python" ]:
+                if data.getVarFlag(calledfunc, flag):
+                    data.setVarFlag(func, flag, data.getVarFlag(calledfunc, flag))
+            for flag in [ "dirs" ]:
+                if data.getVarFlag(func, flag):
+                    data.setVarFlag(calledfunc, flag, data.getVarFlag(func, flag))
 
-                if data.getVarFlag(calledvar, "python"):
-                    data.setVar(var, "    bb.build.exec_func('" + calledvar + "', d)\n")
-                else:
-                    data.setVar(var, "    " + calledvar + "\n")
-                data.setVarFlag(var, 'export_func', '1')
+            if data.getVarFlag(calledfunc, "python"):
+                data.setVar(func, "    bb.build.exec_func('" + calledfunc + "', d)\n")
+            else:
+                data.setVar(func, "    " + calledfunc + "\n")
+            data.setVarFlag(func, 'export_func', '1')
 
 class AddTaskNode(AstNode):
     def __init__(self, filename, lineno, func, before, after):
@@ -288,8 +299,8 @@ def handlePythonMethod(statements, filename, lineno, funcname, modulename, body)
 def handleMethodFlags(statements, filename, lineno, key, m):
     statements.append(MethodFlagsNode(filename, lineno, key, m))
 
-def handleExportFuncs(statements, filename, lineno, m, classes):
-    statements.append(ExportFuncsNode(filename, lineno, m.group(1), classes))
+def handleExportFuncs(statements, filename, lineno, m, classname):
+    statements.append(ExportFuncsNode(filename, lineno, m.group(1), classname))
 
 def handleAddTask(statements, filename, lineno, m):
     func = m.group("func")

bitbake/lib/bb/parse/parse_py/BBHandler.py

@@ -51,7 +51,6 @@ __infunc__ = ""
 __inpython__ = False
 __body__   = []
 __classname__ = ""
-classes = [ None, ]
 
 cached_statements = {}
 
@@ -75,10 +74,17 @@ def inherit(files, fn, lineno, d):
         if not os.path.isabs(file) and not file.endswith(".bbclass"):
             file = os.path.join('classes', '%s.bbclass' % file)
 
+        if not os.path.isabs(file):
+            dname = os.path.dirname(fn)
+            bbpath = "%s:%s" % (dname, d.getVar("BBPATH", True))
+            abs_fn = bb.utils.which(bbpath, file)
+            if abs_fn:
+                file = abs_fn
+
         if not file in __inherit_cache:
             logger.log(logging.DEBUG -1, "BB %s:%d: inheriting %s", fn, lineno, file)
             __inherit_cache.append( file )
-            data.setVar('__inherit_cache', __inherit_cache, d)
+            d.setVar('__inherit_cache', __inherit_cache)
             include(fn, file, lineno, d, "inherit")
             __inherit_cache = d.getVar('__inherit_cache') or []
 
@@ -107,7 +113,7 @@ def get_statements(filename, absolute_filename, base_name):
         return statements
 
 def handle(fn, d, include):
-    global __func_start_regexp__, __inherit_regexp__, __export_func_regexp__, __addtask_regexp__, __addhandler_regexp__, __infunc__, __body__, __residue__
+    global __func_start_regexp__, __inherit_regexp__, __export_func_regexp__, __addtask_regexp__, __addhandler_regexp__, __infunc__, __body__, __residue__, __classname__
     __body__ = []
     __infunc__ = ""
     __classname__ = ""
@@ -125,11 +131,10 @@ def handle(fn, d, include):
 
     if ext == ".bbclass":
         __classname__ = root
-        classes.append(__classname__)
         __inherit_cache = d.getVar('__inherit_cache') or []
         if not fn in __inherit_cache:
             __inherit_cache.append(fn)
-            data.setVar('__inherit_cache', __inherit_cache, d)
+            d.setVar('__inherit_cache', __inherit_cache)
 
     if include != 0:
         oldfile = d.getVar('FILE')
@@ -146,15 +151,17 @@ def handle(fn, d, include):
 
     # DONE WITH PARSING... time to evaluate
     if ext != ".bbclass":
-        data.setVar('FILE', abs_fn, d)
+        d.setVar('FILE', abs_fn)
 
-    statements.eval(d)
-
-    if ext == ".bbclass":
-        classes.remove(__classname__)
-    else:
+    try:
+        statements.eval(d)
+    except bb.parse.SkipPackage:
+        bb.data.setVar("__SKIPPED", True, d)
         if include == 0:
-            return ast.multi_finalize(fn, d)
+            return { "" : d }
+
+    if ext != ".bbclass" and include == 0:
+        return ast.multi_finalize(fn, d)
 
     if oldfile:
         d.setVar("FILE", oldfile)
@@ -166,7 +173,7 @@ def handle(fn, d, include):
     return d
 
 def feeder(lineno, s, fn, root, statements):
-    global __func_start_regexp__, __inherit_regexp__, __export_func_regexp__, __addtask_regexp__, __addhandler_regexp__, __def_regexp__, __python_func_regexp__, __inpython__, __infunc__, __body__, classes, bb, __residue__
+    global __func_start_regexp__, __inherit_regexp__, __export_func_regexp__, __addtask_regexp__, __addhandler_regexp__, __def_regexp__, __python_func_regexp__, __inpython__, __infunc__, __body__, bb, __residue__, __classname__
     if __infunc__:
         if s == '}':
             __body__.append('')
@@ -193,7 +200,10 @@ def feeder(lineno, s, fn, root, statements):
 
     if s and s[0] == '#':
         if len(__residue__) != 0 and __residue__[0][0] != "#":
-            bb.error("There is a comment on line %s of file %s (%s) which is in the middle of a multiline expression.\nBitbake used to ignore these but no longer does so, please fix your metadata as errors are likely as a result of this change." % (lineno, fn, s))
+            bb.fatal("There is a comment on line %s of file %s (%s) which is in the middle of a multiline expression.\nBitbake used to ignore these but no longer does so, please fix your metadata as errors are likely as a result of this change." % (lineno, fn, s))
+
+    if len(__residue__) != 0 and __residue__[0][0] == "#" and (not s or s[0] != "#"):
+        bb.fatal("There is a confusing multiline, partially commented expression on line %s of file %s (%s).\nPlease clarify whether this is all a comment or should be parsed." % (lineno, fn, s))
 
     if s and s[-1] == '\\':
         __residue__.append(s[:-1])
@@ -225,7 +235,7 @@ def feeder(lineno, s, fn, root, statements):
 
     m = __export_func_regexp__.match(s)
     if m:
-        ast.handleExportFuncs(statements, fn, lineno, m, classes)
+        ast.handleExportFuncs(statements, fn, lineno, m, __classname__)
         return
 
     m = __addtask_regexp__.match(s)

bitbake/lib/bb/parse/parse_py/ConfHandler.py

@@ -29,7 +29,7 @@ import logging
 import bb.utils
 from bb.parse import ParseError, resolve_file, ast, logger
 
-__config_regexp__  = re.compile( r"(?P<exp>export\s*)?(?P<var>[a-zA-Z0-9\-_+.${}/]+)(\[(?P<flag>[a-zA-Z0-9\-_+.]+)\])?\s*((?P<colon>:=)|(?P<lazyques>\?\?=)|(?P<ques>\?=)|(?P<append>\+=)|(?P<prepend>=\+)|(?P<predot>=\.)|(?P<postdot>\.=)|=)\s*(?!'[^']*'[^']*'$)(?!\"[^\"]*\"[^\"]*\"$)(?P<apo>['\"])(?P<value>.*)(?P=apo)$")
+__config_regexp__  = re.compile( r"(?P<exp>export\s*)?(?P<var>[a-zA-Z0-9\-~_+.${}/]+)(\[(?P<flag>[a-zA-Z0-9\-_+.]+)\])?\s*((?P<colon>:=)|(?P<lazyques>\?\?=)|(?P<ques>\?=)|(?P<append>\+=)|(?P<prepend>=\+)|(?P<predot>=\.)|(?P<postdot>\.=)|=)\s*(?!'[^']*'[^']*'$)(?!\"[^\"]*\"[^\"]*\"$)(?P<apo>['\"])(?P<value>.*)(?P=apo)$")
 __include_regexp__ = re.compile( r"include\s+(.+)" )
 __require_regexp__ = re.compile( r"require\s+(.+)" )
 __export_regexp__ = re.compile( r"export\s+([a-zA-Z0-9\-_+.${}/]+)$" )
@@ -98,15 +98,22 @@ def handle(fn, data, include):
     while True:
         lineno = lineno + 1
         s = f.readline()
-        if not s: break
+        if not s:
+            break
         w = s.strip()
-        if not w: continue          # skip empty lines
+        # skip empty lines
+        if not w:
+            continue
         s = s.rstrip()
-        if s[0] == '#': continue    # skip comments
         while s[-1] == '\\':
             s2 = f.readline().strip()
             lineno = lineno + 1
+            if (not s2 or s2 and s2[0] != "#") and s[0] == "#" :
+                bb.fatal("There is a confusing multiline, partially commented expression on line %s of file %s (%s).\nPlease clarify whether this is all a comment or should be parsed." % (lineno, fn, s))
             s = s[:-1] + s2
+        # skip comments
+        if s[0] == '#':
+            continue
         feeder(lineno, s, fn, statements)
 
     # DONE WITH PARSING... time to evaluate

bitbake/lib/bb/persist_data.py

@@ -125,6 +125,11 @@ class SQLTable(collections.MutableMapping):
 
         return len(self) < len(other)
 
+    def get_by_pattern(self, pattern):
+        data = self._execute("SELECT * FROM %s WHERE key LIKE ?;" %
+                             self.table, [pattern])
+        return [row[1] for row in data]
+
     def values(self):
         return list(self.itervalues())
 

bitbake/lib/bb/runqueue.py

@@ -785,6 +785,7 @@ class RunQueue:
         self.stamppolicy = cfgData.getVar("BB_STAMP_POLICY", True) or "perfile"
         self.hashvalidate = cfgData.getVar("BB_HASHCHECK_FUNCTION", True) or None
         self.setsceneverify = cfgData.getVar("BB_SETSCENE_VERIFY_FUNCTION", True) or None
+        self.depvalidate = cfgData.getVar("BB_SETSCENE_DEPVALID", True) or None
 
         self.state = runQueuePrepare
 
@@ -1161,6 +1162,26 @@ class RunQueueExecute:
 
         return pid, pipein, pipeout
 
+    def check_dependencies(self, task, taskdeps, setscene = False):
+        if not self.rq.depvalidate:
+            return False
+
+        taskdata = {}
+        taskdeps.add(task)
+        for dep in taskdeps:
+            if setscene:
+                depid = self.rqdata.runq_setscene[dep]
+            else:
+                depid = dep
+            fn = self.rqdata.taskData.fn_index[self.rqdata.runq_fnid[depid]]
+            pn = self.rqdata.dataCache.pkg_fn[fn]
+            taskname = self.rqdata.runq_task[depid]
+            taskdata[dep] = [pn, taskname, fn]
+        call = self.rq.depvalidate + "(task, taskdata, notneeded, d)"
+        locs = { "task" : task, "taskdata" : taskdata, "notneeded" : self.scenequeue_notneeded, "d" : self.cooker.configuration.data }
+        valid = bb.utils.better_eval(call, locs)
+        return valid
+
 class RunQueueExecuteDummy(RunQueueExecute):
     def __init__(self, rq):
         self.rq = rq
@@ -1198,16 +1219,8 @@ class RunQueueExecuteTasks(RunQueueExecute):
                 logger.debug(1, 'Considering %s (%s): %s' % (task, self.rqdata.get_user_idstring(task), str(self.rqdata.runq_revdeps[task])))
 
                 if len(self.rqdata.runq_revdeps[task]) > 0 and self.rqdata.runq_revdeps[task].issubset(self.rq.scenequeue_covered) and task not in self.rq.scenequeue_notcovered:
-                    ok = True
-                    for revdep in self.rqdata.runq_revdeps[task]:
-                        if self.rqdata.runq_fnid[task] != self.rqdata.runq_fnid[revdep]:
-                            logger.debug(1, 'Found "bad" dep %s (%s) for %s (%s)' % (revdep, self.rqdata.get_user_idstring(revdep), task, self.rqdata.get_user_idstring(task)))
-
-                            ok = False
-                            break
-                    if ok:
-                        found = True
-                        self.rq.scenequeue_covered.add(task)
+                    found = True
+                    self.rq.scenequeue_covered.add(task)
 
         logger.debug(1, 'Skip list (pre setsceneverify) %s', sorted(self.rq.scenequeue_covered))
 
@@ -1408,6 +1421,7 @@ class RunQueueExecuteScenequeue(RunQueueExecute):
 
         self.scenequeue_covered = set()
         self.scenequeue_notcovered = set()
+        self.scenequeue_notneeded = set()
 
         # If we don't have any setscene functions, skip this step
         if len(self.rqdata.runq_setscene) == 0:
@@ -1417,7 +1431,6 @@ class RunQueueExecuteScenequeue(RunQueueExecute):
 
         self.stats = RunQueueStats(len(self.rqdata.runq_setscene))
 
-        endpoints = {}
         sq_revdeps = []
         sq_revdeps_new = []
         sq_revdeps_squash = []
@@ -1432,12 +1445,15 @@ class RunQueueExecuteScenequeue(RunQueueExecute):
             self.runq_complete.append(0)
             self.runq_buildable.append(0)
 
+        # First process the chains up to the first setscene task.
+        endpoints = {}
         for task in xrange(len(self.rqdata.runq_fnid)):
             sq_revdeps.append(copy.copy(self.rqdata.runq_revdeps[task]))
             sq_revdeps_new.append(set())
             if (len(self.rqdata.runq_revdeps[task]) == 0) and task not in self.rqdata.runq_setscene:
                 endpoints[task] = set()
 
+        # Secondly process the chains between setscene tasks.
         for task in self.rqdata.runq_setscene:
             for dep in self.rqdata.runq_depends[task]:
                     if dep not in endpoints:
@@ -1453,6 +1469,8 @@ class RunQueueExecuteScenequeue(RunQueueExecute):
                 if sq_revdeps_new[point]:
                     tasks |= sq_revdeps_new[point]
                 sq_revdeps_new[point] = set()
+                if point in self.rqdata.runq_setscene:
+                    sq_revdeps_new[point] = tasks
                 for dep in self.rqdata.runq_depends[point]:
                     if point in sq_revdeps[dep]:
                         sq_revdeps[dep].remove(point)
@@ -1465,6 +1483,42 @@ class RunQueueExecuteScenequeue(RunQueueExecute):
 
         process_endpoints(endpoints)
 
+        # Build a list of setscene tasks which as "unskippable"
+        # These are direct endpoints referenced by the build
+        endpoints2 = {}
+        sq_revdeps2 = []
+        sq_revdeps_new2 = []
+        def process_endpoints2(endpoints):
+            newendpoints = {}
+            for point, task in endpoints.items():
+                tasks = set([point])
+                if task:
+                    tasks |= task
+                if sq_revdeps_new2[point]:
+                    tasks |= sq_revdeps_new2[point]
+                sq_revdeps_new2[point] = set()
+                if point in self.rqdata.runq_setscene:
+                    sq_revdeps_new2[point] = tasks
+                for dep in self.rqdata.runq_depends[point]:
+                    if point in sq_revdeps2[dep]:
+                        sq_revdeps2[dep].remove(point)
+                    if tasks:
+                        sq_revdeps_new2[dep] |= tasks
+                    if (len(sq_revdeps2[dep]) == 0 or len(sq_revdeps_new2[dep]) != 0) and dep not in self.rqdata.runq_setscene:
+                        newendpoints[dep] = tasks
+            if len(newendpoints) != 0:
+                process_endpoints2(newendpoints)
+        for task in xrange(len(self.rqdata.runq_fnid)):
+            sq_revdeps2.append(copy.copy(self.rqdata.runq_revdeps[task]))
+            sq_revdeps_new2.append(set())
+            if (len(self.rqdata.runq_revdeps[task]) == 0) and task not in self.rqdata.runq_setscene:
+                endpoints2[task] = set()
+        process_endpoints2(endpoints2)
+        self.unskippable = []
+        for task in self.rqdata.runq_setscene:
+            if sq_revdeps_new2[task]:
+                self.unskippable.append(self.rqdata.runq_setscene.index(task))
+
         for task in xrange(len(self.rqdata.runq_fnid)):
             if task in self.rqdata.runq_setscene:
                 deps = set()
@@ -1625,6 +1679,13 @@ class RunQueueExecuteScenequeue(RunQueueExecute):
             # Find the next setscene to run
             for nexttask in xrange(self.stats.total):
                 if self.runq_buildable[nexttask] == 1 and self.runq_running[nexttask] != 1:
+                    if nexttask in self.unskippable:
+                        logger.debug(2, "Setscene task %s is unskippable" % self.rqdata.get_user_idstring(self.rqdata.runq_setscene[nexttask]))                      
+                    if nexttask not in self.unskippable and len(self.sq_revdeps[nexttask]) > 0 and self.sq_revdeps[nexttask].issubset(self.scenequeue_covered) and self.check_dependencies(nexttask, self.sq_revdeps[nexttask], True):
+                        logger.debug(2, "Skipping setscene for task %s" % self.rqdata.get_user_idstring(self.rqdata.runq_setscene[nexttask]))
+                        self.task_skip(nexttask)
+                        self.scenequeue_notneeded.add(nexttask)
+                        return True
                     task = nexttask
                     break
         if task is not None:

bitbake/lib/bb/server/none.py

@@ -191,8 +191,8 @@ class BitBakeServer(object):
     def saveConnectionDetails(self):
         return
 
-    def detach(self, cooker_logfile):
-        self.logfile = cooker_logfile
+    def detach(self):
+        return
 
     def establishConnection(self):
         self.connection = BitBakeServerConnection(self)

bitbake/lib/bb/server/process.py

@@ -45,10 +45,10 @@ class ServerCommunicator():
         while True:
             # don't let the user ctrl-c while we're waiting for a response
             try:
-                if self.connection.poll(.5):
+                if self.connection.poll(20):
                     return self.connection.recv()
                 else:
-                    return None
+                    bb.fatal("Timeout while attempting to communicate with bitbake server")
             except KeyboardInterrupt:
                 pass
 
@@ -256,7 +256,7 @@ class BitBakeServer(object):
     def saveConnectionDetails(self):
         return
 
-    def detach(self, cooker_logfile):
+    def detach(self):
         self.server.start() 
         return
 

bitbake/lib/bb/server/xmlrpc.py

@@ -280,8 +280,8 @@ class BitBakeServer(object):
     def saveConnectionDetails(self): 
         self.serverinfo = BitbakeServerInfo(self.server.host, self.server.port)
 
-    def detach(self, cooker_logfile):
-        daemonize.createDaemon(self.server.serve_forever, cooker_logfile)
+    def detach(self):
+        daemonize.createDaemon(self.server.serve_forever, "bitbake-cookerdaemon.log")
         del self.cooker
         del self.server
 

bitbake/lib/bb/siggen.py

@@ -49,7 +49,7 @@ class SignatureGenerator(object):
         return ("%s.%s.%s" % (stampbase, taskname, extrainfo)).rstrip('.')
 
     def stampcleanmask(self, stampbase, file_name, taskname, extrainfo):
-        return ("%s.%s*.%s" % (stampbase, taskname, extrainfo)).rstrip('.')
+        return ("%s.%s.%s" % (stampbase, taskname, extrainfo)).rstrip('.')
 
     def dump_sigtask(self, fn, task, stampbase, runtime):
         return
@@ -276,7 +276,6 @@ class SignatureGeneratorBasicHash(SignatureGeneratorBasic):
             k = fn + "." + taskname
         if clean:
             h = "*"
-            taskname = taskname + "*"
         elif k in self.taskhash:
             h = self.taskhash[k]
         else:

bitbake/lib/bb/ui/crumbs/builddetailspage.py

@@ -204,8 +204,6 @@ class BuildDetailsPage (HobPage):
     def add_build_fail_top_bar(self, actions, log_file=None):
         primary_action = "Edit %s" % actions
 
-        self.notebook.set_page("Issues")
-
         color = HobColors.ERROR
         build_fail_top = gtk.EventBox()
         #build_fail_top.set_size_request(-1, 200)
@@ -226,7 +224,16 @@ class BuildDetailsPage (HobPage):
 
         label = gtk.Label()
         label.set_alignment(0.0, 0.5)
-        label.set_markup("<span size='medium'>Check the \"Issues\" information for more details</span>")
+        # Ensure variable disk_full is defined
+        if not hasattr(self.builder, 'disk_full'):
+            self.builder.disk_full = False
+
+        if self.builder.disk_full:
+            markup = "<span size='medium'>There is no disk space left, so Hob cannot finish building your image. Free up some disk space\n"
+            markup += "and restart the build. Check the \"Issues\" tab for more details</span>"
+            label.set_markup(markup)
+        else:
+            label.set_markup("<span size='medium'>Check the \"Issues\" information for more details</span>")
         build_fail_tab.attach(label, 4, 40, 4, 9)
 
         # create button 'Edit packages'
@@ -234,22 +241,36 @@ class BuildDetailsPage (HobPage):
         #action_button.set_size_request(-1, 40)
         action_button.set_tooltip_text("Edit the %s parameters" % actions)
         action_button.connect('clicked', self.failure_primary_action_button_clicked_cb, primary_action)
-        build_fail_tab.attach(action_button, 4, 13, 9, 12)
 
         if log_file:
             open_log_button = HobAltButton("Open log")
             open_log_button.set_relief(gtk.RELIEF_HALF)
             open_log_button.set_tooltip_text("Open the build's log file")
             open_log_button.connect('clicked', self.open_log_button_clicked_cb, log_file)
-            build_fail_tab.attach(open_log_button, 14, 23, 9, 12)
 
         attach_pos = (24 if log_file else 14)
         file_bug_button = HobAltButton('File a bug')
         file_bug_button.set_relief(gtk.RELIEF_HALF)
         file_bug_button.set_tooltip_text("Open the Yocto Project bug tracking website")
         file_bug_button.connect('clicked', self.failure_activate_file_bug_link_cb)
-        build_fail_tab.attach(file_bug_button, attach_pos, attach_pos + 9, 9, 12)
 
+        if not self.builder.disk_full:
+            build_fail_tab.attach(action_button, 4, 13, 9, 12)
+            if log_file:
+                build_fail_tab.attach(open_log_button, 14, 23, 9, 12)
+            build_fail_tab.attach(file_bug_button, attach_pos, attach_pos + 9, 9, 12)
+
+        else:
+            restart_build = HobButton("Restart the build")
+            restart_build.set_tooltip_text("Restart the build")
+            restart_build.connect('clicked', self.restart_build_button_clicked_cb)
+
+            build_fail_tab.attach(restart_build, 4, 13, 9, 12)
+            build_fail_tab.attach(action_button, 14, 23, 9, 12)
+            if log_file:
+                build_fail_tab.attach(open_log_button, attach_pos, attach_pos + 9, 9, 12)
+
+        self.builder.disk_full = False
         return build_fail_top
 
     def show_fail_page(self, title):
@@ -264,6 +285,7 @@ class BuildDetailsPage (HobPage):
 
         self.vbox.pack_start(self.notebook, expand=True, fill=True)
         self.show_all()
+        self.notebook.set_page("Issues")
         self.back_button.hide()
 
     def add_build_stop_top_bar(self, action, log_file=None):
@@ -348,6 +370,7 @@ class BuildDetailsPage (HobPage):
 
         self.box_group_area.pack_end(self.button_box, expand=False, fill=False)
         self.show_all()
+        self.notebook.set_page("Log")
         self.back_button.hide()
 
         self.reset_build_status()
@@ -393,6 +416,9 @@ class BuildDetailsPage (HobPage):
         elif "Edit image" in action:
             self.builder.show_configuration()
 
+    def restart_build_button_clicked_cb(self, button):
+        self.builder.just_bake()
+
     def stop_primary_action_button_clicked_cb(self, button, action):
         if "recipes" in action:
             self.builder.show_recipes()
@@ -403,7 +429,8 @@ class BuildDetailsPage (HobPage):
 
     def open_log_button_clicked_cb(self, button, log_file):
         if log_file:
-            os.system("xdg-open /%s" % log_file)
+            log_file = "file:///" + log_file
+            gtk.show_uri(screen=button.get_screen(), uri=log_file, timestamp=0)
 
     def failure_activate_file_bug_link_cb(self, button):
         button.child.emit('activate-link', "http://bugzilla.yoctoproject.org")

bitbake/lib/bb/ui/crumbs/builder.py

@@ -38,11 +38,15 @@ from bb.ui.crumbs.builddetailspage import BuildDetailsPage
 from bb.ui.crumbs.imagedetailspage import ImageDetailsPage
 from bb.ui.crumbs.sanitycheckpage import SanityCheckPage
 from bb.ui.crumbs.hobwidget import hwc, HobButton, HobAltButton
-from bb.ui.crumbs.hig import CrumbsMessageDialog, ImageSelectionDialog, \
-                             AdvancedSettingDialog, SimpleSettingsDialog, \
-                             LayerSelectionDialog, DeployImageDialog
 from bb.ui.crumbs.persistenttooltip import PersistentTooltip
 import bb.ui.crumbs.utils
+from bb.ui.crumbs.hig.crumbsmessagedialog import CrumbsMessageDialog
+from bb.ui.crumbs.hig.simplesettingsdialog import SimpleSettingsDialog
+from bb.ui.crumbs.hig.advancedsettingsdialog import AdvancedSettingsDialog
+from bb.ui.crumbs.hig.deployimagedialog import DeployImageDialog
+from bb.ui.crumbs.hig.layerselectiondialog import LayerSelectionDialog
+from bb.ui.crumbs.hig.imageselectiondialog import ImageSelectionDialog
+from bb.ui.crumbs.hig.parsingwarningsdialog import ParsingWarningsDialog
 
 hobVer = 20120808
 
@@ -51,10 +55,10 @@ class Configuration:
 
     @classmethod
     def parse_proxy_string(cls, proxy):
-        pattern = "^\s*((http|https|ftp|git|cvs)://)?((\S+):(\S+)@)?(\S+):(\d+)/?"
+        pattern = "^\s*((http|https|ftp|git|cvs)://)?((\S+):(\S+)@)?([^\s:]+)(:(\d+))?/?"
         match = re.search(pattern, proxy)
         if match:
-            return match.group(2), match.group(4), match.group(5), match.group(6), match.group(7)
+            return match.group(2), match.group(4), match.group(5), match.group(6), match.group(8)
         else:
             return None, None, None, "", ""
 
@@ -82,13 +86,14 @@ class Configuration:
 
     @classmethod
     def make_proxy_string(cls, prot, user, passwd, host, port, default_prot=""):
-        if host == None or host == "" or port == None or port == "":
+        if host == None or host == "":# or port == None or port == "":
             return ""
 
-        return Configuration.make_host_string(prot, user, passwd, host, default_prot) + ":" + Configuration.make_port_string(port)
+        return Configuration.make_host_string(prot, user, passwd, host, default_prot) + (":" + Configuration.make_port_string(port) if port else "")
 
     def __init__(self):
         self.curr_mach = ""
+        self.selected_image = None
         # settings
         self.curr_distro = ""
         self.dldir = self.sstatedir = self.sstatemirror = ""
@@ -123,9 +128,9 @@ class Configuration:
         }
 
     def clear_selection(self):
-        self.selected_image = None
         self.selected_recipes = []
         self.selected_packages = []
+        self.initial_selected_image = None
         self.initial_selected_packages = []
         self.initial_user_selected_packages = []
 
@@ -171,6 +176,7 @@ class Configuration:
         # self.extra_setting/self.toolchain_build
         # bblayers.conf
         self.layers = params["layer"].split()
+        self.layers_non_removable = params["layers_non_removable"].split()
         self.default_task = params["default_task"]
 
         # proxy settings
@@ -438,6 +444,12 @@ class Builder(gtk.Window):
         # Indicate whether the UI is working
         self.sensitive = True
 
+        # Indicate whether the sanity check ran
+        self.sanity_checked = False
+
+        # save parsing warnings
+        self.parsing_warnings = []
+
         # create visual elements
         self.create_visual_elements()
 
@@ -455,13 +467,16 @@ class Builder(gtk.Window):
         self.handler.build.connect("build-failed",       self.handler_build_failed_cb)
         self.handler.build.connect("build-aborted",      self.handler_build_aborted_cb)
         self.handler.build.connect("task-started",       self.handler_task_started_cb)
+        self.handler.build.connect("disk-full",          self.handler_disk_full_cb)
         self.handler.build.connect("log-error",          self.handler_build_failure_cb)
+        self.handler.build.connect("log-warning",        self.handler_build_failure_cb)
         self.handler.build.connect("log",                self.handler_build_log_cb)
         self.handler.build.connect("no-provider",        self.handler_no_provider_cb)
         self.handler.connect("generating-data",          self.handler_generating_data_cb)
         self.handler.connect("data-generated",           self.handler_data_generated_cb)
         self.handler.connect("command-succeeded",        self.handler_command_succeeded_cb)
         self.handler.connect("command-failed",           self.handler_command_failed_cb)
+        self.handler.connect("parsing-warning",          self.handler_parsing_warning_cb)
         self.handler.connect("sanity-failed",            self.handler_sanity_failed_cb)
         self.handler.connect("recipe-populated",         self.handler_recipe_populated_cb)
         self.handler.connect("package-populated",        self.handler_package_populated_cb)
@@ -540,7 +555,8 @@ class Builder(gtk.Window):
           sanity_check_post_func = func
 
     def generate_configuration(self):
-        self.show_sanity_check_page()
+        if not self.sanity_checked:
+            self.show_sanity_check_page()
         self.handler.generate_configuration()
 
     def initiate_new_build_async(self):
@@ -603,15 +619,18 @@ class Builder(gtk.Window):
         # Build image
         self.set_user_config()
         toolchain_packages = []
+        base_image = None
         if self.configuration.toolchain_build:
             toolchain_packages = self.package_model.get_selected_packages_toolchain()
         if self.configuration.selected_image == self.recipe_model.__custom_image__:
             packages = self.package_model.get_selected_packages()
             image = self.hob_image
+            base_image = self.configuration.initial_selected_image
         else:
             packages = []
             image = self.configuration.selected_image
         self.handler.generate_image(image,
+                                    base_image,
                                     self.hob_toolchain,
                                     packages,
                                     toolchain_packages,
@@ -746,6 +765,20 @@ class Builder(gtk.Window):
         self.previous_step = self.current_step
         self.current_step = next_step
 
+    def set_user_config_proxies(self):
+        if self.configuration.enable_proxy == True:
+            self.handler.set_http_proxy(self.configuration.combine_proxy("http"))
+            self.handler.set_https_proxy(self.configuration.combine_proxy("https"))
+            self.handler.set_ftp_proxy(self.configuration.combine_proxy("ftp"))
+            self.handler.set_git_proxy(self.configuration.combine_host_only("git"), self.configuration.combine_port_only("git"))
+            self.handler.set_cvs_proxy(self.configuration.combine_host_only("cvs"), self.configuration.combine_port_only("cvs"))
+        elif self.configuration.enable_proxy == False:
+            self.handler.set_http_proxy("")
+            self.handler.set_https_proxy("")
+            self.handler.set_ftp_proxy("")
+            self.handler.set_git_proxy("", "")
+            self.handler.set_cvs_proxy("", "")
+
     def set_user_config(self):
         self.handler.init_cooker()
         # set bb layers
@@ -767,19 +800,7 @@ class Builder(gtk.Window):
         self.handler.set_extra_config(self.configuration.extra_setting)
         self.handler.set_extra_inherit("packageinfo")
         self.handler.set_extra_inherit("image_types")
-        # set proxies
-        if self.configuration.enable_proxy == True:
-            self.handler.set_http_proxy(self.configuration.combine_proxy("http"))
-            self.handler.set_https_proxy(self.configuration.combine_proxy("https"))
-            self.handler.set_ftp_proxy(self.configuration.combine_proxy("ftp"))
-            self.handler.set_git_proxy(self.configuration.combine_host_only("git"), self.configuration.combine_port_only("git"))
-            self.handler.set_cvs_proxy(self.configuration.combine_host_only("cvs"), self.configuration.combine_port_only("cvs"))
-        elif self.configuration.enable_proxy == False:
-            self.handler.set_http_proxy("")
-            self.handler.set_https_proxy("")
-            self.handler.set_ftp_proxy("")
-            self.handler.set_git_proxy("", "")
-            self.handler.set_cvs_proxy("", "")
+        self.set_user_config_proxies()
 
     def update_recipe_model(self, selected_image, selected_recipes):
         self.recipe_model.set_selected_image(selected_image)
@@ -830,7 +851,9 @@ class Builder(gtk.Window):
             if not self.configuration.curr_mach:
                 self.configuration.curr_mach = self.handler.runCommand(["getVariable", "HOB_MACHINE"]) or ""
             self.update_configuration_parameters(self.get_parameters_sync())
-            self.sanity_check()
+            if not self.sanity_checked:
+                self.sanity_check()
+                self.sanity_checked = True
         elif initcmd == self.handler.SANITY_CHECK:
             if self.had_network_error:
                 self.had_network_error = False
@@ -862,6 +885,15 @@ class Builder(gtk.Window):
         response = dialog.run()
         dialog.destroy()
 
+    def show_warning_dialog(self):
+        dialog = ParsingWarningsDialog(title = "View warnings",
+                warnings = self.parsing_warnings,
+                parent = None,
+                flags = gtk.DIALOG_DESTROY_WITH_PARENT
+                       | gtk.DIALOG_NO_SEPARATOR)
+        response = dialog.run()
+        dialog.destroy()
+
     def show_network_error_dialog(self):
         lbl = "<b>Hob cannot connect to the network</b>\n"
         msg = "Please check your network connection. If you are using a proxy server, please make sure it is configured correctly."
@@ -885,6 +917,9 @@ class Builder(gtk.Window):
             self.show_error_dialog(msg)
         self.reset()
 
+    def handler_parsing_warning_cb(self, handler, warn_msg):
+        self.parsing_warnings.append(warn_msg)
+
     def handler_sanity_failed_cb(self, handler, msg, network_error):
         self.reset()
         if network_error:
@@ -944,10 +979,10 @@ class Builder(gtk.Window):
         self.package_details_page.refresh_selection()
 
     def handler_recipe_populated_cb(self, handler):
-        self.image_configuration_page.update_progress_bar("Populated recipes", 0.99)
+        self.image_configuration_page.update_progress_bar("Populating recipes", 0.99)
 
     def handler_package_populated_cb(self, handler):
-        self.image_configuration_page.update_progress_bar("Populated packages", 1.0)
+        self.image_configuration_page.update_progress_bar("Populating packages", 1.0)
 
     def handler_parsing_started_cb(self, handler, message):
         if self.current_step != self.RCPPKGINFO_POPULATING:
@@ -957,10 +992,10 @@ class Builder(gtk.Window):
         if message["eventname"] == "TreeDataPreparationStarted":
             fraction = 0.6 + fraction
             self.image_configuration_page.stop_button.set_sensitive(False)
+            self.image_configuration_page.update_progress_bar("Generating dependency tree", fraction)
         else:
             self.image_configuration_page.stop_button.set_sensitive(True)
-
-        self.image_configuration_page.update_progress_bar(message["title"], fraction)
+            self.image_configuration_page.update_progress_bar(message["title"], fraction)
 
     def handler_parsing_cb(self, handler, message):
         if self.current_step != self.RCPPKGINFO_POPULATING:
@@ -969,9 +1004,10 @@ class Builder(gtk.Window):
         fraction = message["current"] * 1.0/message["total"]
         if message["eventname"] == "TreeDataPreparationProgress":
             fraction = 0.6 + 0.38 * fraction
+            self.image_configuration_page.update_progress_bar("Generating dependency tree", fraction)
         else:
             fraction = 0.6 * fraction
-        self.image_configuration_page.update_progress_bar(message["title"], fraction)
+            self.image_configuration_page.update_progress_bar(message["title"], fraction)
 
     def handler_parsing_completed_cb(self, handler, message):
         if self.current_step != self.RCPPKGINFO_POPULATING:
@@ -981,7 +1017,7 @@ class Builder(gtk.Window):
             fraction = 0.98
         else:
             fraction = 0.6
-        self.image_configuration_page.update_progress_bar(message["title"], fraction)
+        self.image_configuration_page.update_progress_bar("Generating dependency tree", fraction)
 
     def handler_build_started_cb(self, running_build):
         if self.current_step == self.FAST_IMAGE_GENERATING:
@@ -1004,7 +1040,8 @@ class Builder(gtk.Window):
             self.parameters.image_names = []
             selected_image = self.recipe_model.get_selected_image()
             if selected_image == self.recipe_model.__custom_image__:
-                linkname = 'hob-image-' + self.configuration.curr_mach
+                version = self.recipe_model.get_custom_image_version()
+                linkname = 'hob-image' + version+ "-" + self.configuration.curr_mach
             else:
                 linkname = selected_image + '-' + self.configuration.curr_mach
             image_extension = self.get_image_extension()
@@ -1117,6 +1154,9 @@ class Builder(gtk.Window):
         self.build_details_page.update_progress_bar(title + ": ", fraction)
         self.build_details_page.update_build_status(message["current"], message["total"], message["task"])
 
+    def handler_disk_full_cb(self, running_build):
+        self.disk_full = True
+
     def handler_build_failure_cb(self, running_build):
         self.build_details_page.show_issues()
 
@@ -1185,6 +1225,7 @@ class Builder(gtk.Window):
     def show_layer_selection_dialog(self):
         dialog = LayerSelectionDialog(title = "Layers",
                      layers = copy.deepcopy(self.configuration.layers),
+                     layers_non_removable = copy.deepcopy(self.configuration.layers_non_removable),
                      all_layers = self.parameters.all_layers,
                      parent = self,
                      flags = gtk.DIALOG_MODAL
@@ -1274,7 +1315,7 @@ class Builder(gtk.Window):
         dialog.destroy()
 
     def show_adv_settings_dialog(self, tab=None):
-        dialog = AdvancedSettingDialog(title = "Advanced configuration",
+        dialog = AdvancedSettingsDialog(title = "Advanced configuration",
             configuration = copy.deepcopy(self.configuration),
             all_image_types = self.parameters.image_types,
             all_package_formats = self.parameters.all_package_formats,
@@ -1310,7 +1351,8 @@ class Builder(gtk.Window):
             parent = self,
             flags = gtk.DIALOG_MODAL
                     | gtk.DIALOG_DESTROY_WITH_PARENT
-                    | gtk.DIALOG_NO_SEPARATOR)
+                    | gtk.DIALOG_NO_SEPARATOR,
+            handler = self.handler)
         button = dialog.add_button("Cancel", gtk.RESPONSE_NO)
         HobAltButton.style_button(button)
         button = dialog.add_button("Save", gtk.RESPONSE_YES)
@@ -1323,6 +1365,14 @@ class Builder(gtk.Window):
             self.configuration = dialog.configuration
             self.save_defaults() # remember settings
             settings_changed = dialog.settings_changed
+            if dialog.proxy_settings_changed:
+                self.set_user_config_proxies()
+        elif dialog.proxy_test_ran:
+            # The user might have modified the proxies in the "Proxy"
+            # tab, which in turn made the proxy settings modify in bb.
+            # If "Cancel" was pressed, restore the previous proxy
+            # settings inside bb.
+            self.set_user_config_proxies()
         dialog.destroy()
         return response == gtk.RESPONSE_YES, settings_changed
 
@@ -1480,7 +1530,7 @@ class Builder(gtk.Window):
         if response != gtk.RESPONSE_CANCEL:
             self.stopping = True
         if response == gtk.RESPONSE_OK:
-            self.build_details_page.progress_bar.set_title("Stopping the build...")
+            self.build_details_page.progress_bar.set_stop_title("Stopping the build....")
             self.build_details_page.progress_bar.set_rcstyle("stop")
             self.cancel_build_sync()
         elif response == gtk.RESPONSE_YES:

bitbake/lib/bb/ui/crumbs/hig/advancedsettingsdialog.py

@@ -0,0 +1,336 @@
+#
+# BitBake Graphical GTK User Interface
+#
+# Copyright (C) 2011-2012   Intel Corporation
+#
+# Authored by Joshua Lock <josh@linux.intel.com>
+# Authored by Dongxiao Xu <dongxiao.xu@intel.com>
+# Authored by Shane Wang <shane.wang@intel.com>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License version 2 as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+import gtk
+import hashlib
+from bb.ui.crumbs.hobwidget import HobInfoButton, HobButton
+from bb.ui.crumbs.progressbar import HobProgressBar
+from bb.ui.crumbs.hig.settingsuihelper import SettingsUIHelper
+from bb.ui.crumbs.hig.crumbsdialog import CrumbsDialog
+from bb.ui.crumbs.hig.crumbsmessagedialog import CrumbsMessageDialog
+from bb.ui.crumbs.hig.proxydetailsdialog import ProxyDetailsDialog
+
+"""
+The following are convenience classes for implementing GNOME HIG compliant
+BitBake GUI's
+In summary: spacing = 12px, border-width = 6px
+"""
+
+class AdvancedSettingsDialog (CrumbsDialog, SettingsUIHelper):
+    
+    def details_cb(self, button, parent, protocol):
+        dialog = ProxyDetailsDialog(title = protocol.upper() + " Proxy Details",
+            user = self.configuration.proxies[protocol][1],
+            passwd = self.configuration.proxies[protocol][2],
+            parent = parent,
+            flags = gtk.DIALOG_MODAL
+                    | gtk.DIALOG_DESTROY_WITH_PARENT
+                    | gtk.DIALOG_NO_SEPARATOR)
+        dialog.add_button(gtk.STOCK_CLOSE, gtk.RESPONSE_OK)
+        response = dialog.run()
+        if response == gtk.RESPONSE_OK:
+            self.configuration.proxies[protocol][1] = dialog.user
+            self.configuration.proxies[protocol][2] = dialog.passwd
+            self.refresh_proxy_components()
+        dialog.destroy()
+
+    def set_save_button(self, button):
+        self.save_button = button
+
+    def rootfs_combo_changed_cb(self, rootfs_combo, all_package_format, check_hbox):
+        combo_item = self.rootfs_combo.get_active_text()
+        modified = False
+        for child in check_hbox.get_children():
+            if isinstance(child, gtk.CheckButton):
+                check_hbox.remove(child)
+                modified = True
+        for format in all_package_format:
+            if format != combo_item:
+                check_button = gtk.CheckButton(format)
+                check_hbox.pack_start(check_button, expand=False, fill=False)
+                modified = True
+        if modified:
+            check_hbox.remove(self.pkgfmt_info)
+            check_hbox.pack_start(self.pkgfmt_info, expand=False, fill=False)
+        check_hbox.show_all()
+
+    def gen_pkgfmt_widget(self, curr_package_format, all_package_format, tooltip_combo="", tooltip_extra=""):
+        pkgfmt_vbox = gtk.VBox(False, 6)
+
+        label = self.gen_label_widget("Root file system package format")
+        pkgfmt_vbox.pack_start(label, expand=False, fill=False)
+
+        rootfs_format = ""
+        if curr_package_format:
+            rootfs_format = curr_package_format.split()[0]
+
+        rootfs_format_widget, rootfs_combo = self.gen_combo_widget(rootfs_format, all_package_format, tooltip_combo)
+        pkgfmt_vbox.pack_start(rootfs_format_widget, expand=False, fill=False)
+
+        label = self.gen_label_widget("Additional package formats")
+        pkgfmt_vbox.pack_start(label, expand=False, fill=False)
+
+        check_hbox = gtk.HBox(False, 12)
+        pkgfmt_vbox.pack_start(check_hbox, expand=False, fill=False)
+        for format in all_package_format:
+            if format != rootfs_format:
+                check_button = gtk.CheckButton(format)
+                is_active = (format in curr_package_format.split())
+                check_button.set_active(is_active)
+                check_hbox.pack_start(check_button, expand=False, fill=False)
+
+        self.pkgfmt_info = HobInfoButton(tooltip_extra, self)
+        check_hbox.pack_start(self.pkgfmt_info, expand=False, fill=False)
+
+        rootfs_combo.connect("changed", self.rootfs_combo_changed_cb, all_package_format, check_hbox)
+
+        pkgfmt_vbox.show_all()
+
+        return pkgfmt_vbox, rootfs_combo, check_hbox
+
+    def __init__(self, title, configuration, all_image_types,
+            all_package_formats, all_distros, all_sdk_machines,
+            max_threads, parent, flags, buttons=None):
+        super(AdvancedSettingsDialog, self).__init__(title, parent, flags, buttons)
+
+        # class members from other objects
+        # bitbake settings from Builder.Configuration
+        self.configuration = configuration
+        self.image_types = all_image_types
+        self.all_package_formats = all_package_formats
+        self.all_distros = all_distros[:]
+        self.all_sdk_machines = all_sdk_machines
+        self.max_threads = max_threads
+
+        # class members for internal use
+        self.distro_combo = None
+        self.dldir_text = None
+        self.sstatedir_text = None
+        self.sstatemirror_text = None
+        self.bb_spinner = None
+        self.pmake_spinner = None
+        self.rootfs_size_spinner = None
+        self.extra_size_spinner = None
+        self.gplv3_checkbox = None
+        self.toolchain_checkbox = None
+        self.image_types_checkbuttons = {}
+
+        self.md5 = self.config_md5()
+        self.settings_changed = False
+
+        # create visual elements on the dialog
+        self.save_button = None
+        self.create_visual_elements()
+        self.connect("response", self.response_cb)
+
+    def _get_sorted_value(self, var):
+        return " ".join(sorted(str(var).split())) + "\n"
+
+    def config_md5(self):
+        data = ""
+        data += ("PACKAGE_CLASSES: "      + self.configuration.curr_package_format + '\n')
+        data += ("DISTRO: "               + self._get_sorted_value(self.configuration.curr_distro))
+        data += ("IMAGE_ROOTFS_SIZE: "    + self._get_sorted_value(self.configuration.image_rootfs_size))
+        data += ("IMAGE_EXTRA_SIZE: "     + self._get_sorted_value(self.configuration.image_extra_size))
+        data += ("INCOMPATIBLE_LICENSE: " + self._get_sorted_value(self.configuration.incompat_license))
+        data += ("SDK_MACHINE: "          + self._get_sorted_value(self.configuration.curr_sdk_machine))
+        data += ("TOOLCHAIN_BUILD: "      + self._get_sorted_value(self.configuration.toolchain_build))
+        data += ("IMAGE_FSTYPES: "        + self._get_sorted_value(self.configuration.image_fstypes))
+        return hashlib.md5(data).hexdigest()
+
+    def create_visual_elements(self):
+        self.nb = gtk.Notebook()
+        self.nb.set_show_tabs(True)
+        self.nb.append_page(self.create_image_types_page(), gtk.Label("Image types"))
+        self.nb.append_page(self.create_output_page(), gtk.Label("Output"))
+        self.nb.set_current_page(0)
+        self.vbox.pack_start(self.nb, expand=True, fill=True)
+        self.vbox.pack_end(gtk.HSeparator(), expand=True, fill=True)
+
+        self.show_all()
+
+    def get_num_checked_image_types(self):
+        total = 0
+        for b in self.image_types_checkbuttons.values():
+            if b.get_active():
+              total = total + 1
+        return total
+
+    def set_save_button_state(self):
+        if self.save_button:
+            self.save_button.set_sensitive(self.get_num_checked_image_types() > 0)
+
+    def image_type_checkbutton_clicked_cb(self, button):
+        self.set_save_button_state()
+        if self.get_num_checked_image_types() == 0:
+            # Show an error dialog
+            lbl = "<b>Select an image type</b>\n\nYou need to select at least one image type."
+            dialog = CrumbsMessageDialog(self, lbl, gtk.STOCK_DIALOG_WARNING)
+            button = dialog.add_button("OK", gtk.RESPONSE_OK)
+            HobButton.style_button(button)
+            response = dialog.run()
+            dialog.destroy()
+
+    def create_image_types_page(self):
+        main_vbox = gtk.VBox(False, 16)
+        main_vbox.set_border_width(6)
+
+        advanced_vbox = gtk.VBox(False, 6)
+        advanced_vbox.set_border_width(6)
+
+        distro_vbox = gtk.VBox(False, 6)        
+        label = self.gen_label_widget("Distro:")
+        tooltip = "Selects the Yocto Project distribution you want"
+        try:
+            i = self.all_distros.index( "defaultsetup" )
+        except ValueError:
+            i = -1
+        if i != -1:
+            self.all_distros[ i ] = "Default"
+            if self.configuration.curr_distro == "defaultsetup":
+                self.configuration.curr_distro = "Default"
+        distro_widget, self.distro_combo = self.gen_combo_widget(self.configuration.curr_distro, self.all_distros, tooltip)
+        distro_vbox.pack_start(label, expand=False, fill=False)
+        distro_vbox.pack_start(distro_widget, expand=False, fill=False)
+        main_vbox.pack_start(distro_vbox, expand=False, fill=False)
+
+
+        rows = (len(self.image_types)+1)/3
+        table = gtk.Table(rows + 1, 10, True)
+        advanced_vbox.pack_start(table, expand=False, fill=False)
+
+        tooltip = "Image file system types you want."
+        info = HobInfoButton(tooltip, self)
+        label = self.gen_label_widget("Image types:")
+        align = gtk.Alignment(0, 0.5, 0, 0)
+        table.attach(align, 0, 4, 0, 1)
+        align.add(label)
+        table.attach(info, 4, 5, 0, 1)
+
+        i = 1
+        j = 1
+        for image_type in sorted(self.image_types):
+            self.image_types_checkbuttons[image_type] = gtk.CheckButton(image_type)
+            self.image_types_checkbuttons[image_type].connect("toggled", self.image_type_checkbutton_clicked_cb)
+            article = ""
+            if image_type.startswith(("a", "e", "i", "o", "u")):
+                article = "n"
+            self.image_types_checkbuttons[image_type].set_tooltip_text("Build a%s %s image" % (article, image_type))
+            table.attach(self.image_types_checkbuttons[image_type], j - 1, j + 3, i, i + 1)
+            if image_type in self.configuration.image_fstypes.split():
+                self.image_types_checkbuttons[image_type].set_active(True)
+            i += 1
+            if i > rows:
+                i = 1
+                j = j + 4
+
+        main_vbox.pack_start(advanced_vbox, expand=False, fill=False)
+        self.set_save_button_state()
+        
+        return main_vbox
+
+    def create_output_page(self):
+        advanced_vbox = gtk.VBox(False, 6)
+        advanced_vbox.set_border_width(6)
+
+        advanced_vbox.pack_start(self.gen_label_widget('<span weight="bold">Package format</span>'), expand=False, fill=False)
+        sub_vbox = gtk.VBox(False, 6)
+        advanced_vbox.pack_start(sub_vbox, expand=False, fill=False)
+        tooltip_combo = "Selects the package format used to generate rootfs."
+        tooltip_extra = "Selects extra package formats to build"
+        pkgfmt_widget, self.rootfs_combo, self.check_hbox = self.gen_pkgfmt_widget(self.configuration.curr_package_format, self.all_package_formats, tooltip_combo, tooltip_extra)
+        sub_vbox.pack_start(pkgfmt_widget, expand=False, fill=False)
+
+        advanced_vbox.pack_start(self.gen_label_widget('<span weight="bold">Image size</span>'), expand=False, fill=False)
+        sub_vbox = gtk.VBox(False, 6)
+        advanced_vbox.pack_start(sub_vbox, expand=False, fill=False)
+        label = self.gen_label_widget("Image basic size (in MB)")
+        tooltip = "Sets the basic size of your target image.\nThis is the basic size of your target image unless your selected package size exceeds this value or you select \'Image Extra Size\'."
+        rootfs_size_widget, self.rootfs_size_spinner = self.gen_spinner_widget(int(self.configuration.image_rootfs_size*1.0/1024), 0, 65536, tooltip)
+        sub_vbox.pack_start(label, expand=False, fill=False)
+        sub_vbox.pack_start(rootfs_size_widget, expand=False, fill=False)
+
+        sub_vbox = gtk.VBox(False, 6)
+        advanced_vbox.pack_start(sub_vbox, expand=False, fill=False)
+        label = self.gen_label_widget("Additional free space (in MB)")
+        tooltip = "Sets the extra free space of your target image.\nBy default, the system reserves 30% of your image size as free space. If your image contains zypper, it brings in 50MB more space. The maximum free space is 64GB."
+        extra_size_widget, self.extra_size_spinner = self.gen_spinner_widget(int(self.configuration.image_extra_size*1.0/1024), 0, 65536, tooltip)
+        sub_vbox.pack_start(label, expand=False, fill=False)
+        sub_vbox.pack_start(extra_size_widget, expand=False, fill=False)
+
+        advanced_vbox.pack_start(self.gen_label_widget('<span weight="bold">Licensing</span>'), expand=False, fill=False)
+        self.gplv3_checkbox = gtk.CheckButton("Exclude GPLv3 packages")
+        self.gplv3_checkbox.set_tooltip_text("Check this box to prevent GPLv3 packages from being included in your image")
+        if "GPLv3" in self.configuration.incompat_license.split():
+            self.gplv3_checkbox.set_active(True)
+        else:
+            self.gplv3_checkbox.set_active(False)
+        advanced_vbox.pack_start(self.gplv3_checkbox, expand=False, fill=False)
+
+        advanced_vbox.pack_start(self.gen_label_widget('<span weight="bold">Toolchain</span>'), expand=False, fill=False)
+        sub_hbox = gtk.HBox(False, 6)
+        advanced_vbox.pack_start(sub_hbox, expand=False, fill=False)
+        self.toolchain_checkbox = gtk.CheckButton("Build toolchain")
+        self.toolchain_checkbox.set_tooltip_text("Check this box to build the related toolchain with your image")
+        self.toolchain_checkbox.set_active(self.configuration.toolchain_build)
+        sub_hbox.pack_start(self.toolchain_checkbox, expand=False, fill=False)
+
+        tooltip = "Selects the host platform for which you want to run the toolchain"
+        sdk_machine_widget, self.sdk_machine_combo = self.gen_combo_widget(self.configuration.curr_sdk_machine, self.all_sdk_machines, tooltip)
+        sub_hbox.pack_start(sdk_machine_widget, expand=False, fill=False)
+
+        return advanced_vbox
+
+    def response_cb(self, dialog, response_id):
+        package_format = []
+        package_format.append(self.rootfs_combo.get_active_text())
+        for child in self.check_hbox:
+            if isinstance(child, gtk.CheckButton) and child.get_active():
+                package_format.append(child.get_label())
+        self.configuration.curr_package_format = " ".join(package_format)
+
+        distro = self.distro_combo.get_active_text()
+        if distro == "Default":
+            distro = "defaultsetup"
+        self.configuration.curr_distro = distro
+        self.configuration.image_rootfs_size = self.rootfs_size_spinner.get_value_as_int() * 1024
+        self.configuration.image_extra_size = self.extra_size_spinner.get_value_as_int() * 1024
+
+        self.configuration.image_fstypes = ""
+        for image_type in self.image_types:
+            if self.image_types_checkbuttons[image_type].get_active():
+                self.configuration.image_fstypes += (" " + image_type)
+        self.configuration.image_fstypes.strip()
+
+        if self.gplv3_checkbox.get_active():
+            if "GPLv3" not in self.configuration.incompat_license.split():
+                self.configuration.incompat_license += " GPLv3"
+        else:
+            if "GPLv3" in self.configuration.incompat_license.split():
+                self.configuration.incompat_license = self.configuration.incompat_license.split().remove("GPLv3")
+                self.configuration.incompat_license = " ".join(self.configuration.incompat_license or [])
+        self.configuration.incompat_license = self.configuration.incompat_license.strip()
+
+        self.configuration.toolchain_build = self.toolchain_checkbox.get_active()
+        self.configuration.curr_sdk_machine = self.sdk_machine_combo.get_active_text()
+        md5 = self.config_md5()
+        self.settings_changed = (self.md5 != md5)

bitbake/lib/bb/ui/crumbs/hig/crumbsdialog.py

@@ -0,0 +1,44 @@
+#
+# BitBake Graphical GTK User Interface
+#
+# Copyright (C) 2011-2012   Intel Corporation
+#
+# Authored by Joshua Lock <josh@linux.intel.com>
+# Authored by Dongxiao Xu <dongxiao.xu@intel.com>
+# Authored by Shane Wang <shane.wang@intel.com>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License version 2 as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+import gtk
+
+"""
+The following are convenience classes for implementing GNOME HIG compliant
+BitBake GUI's
+In summary: spacing = 12px, border-width = 6px
+"""
+
+class CrumbsDialog(gtk.Dialog):
+    """
+    A GNOME HIG compliant dialog widget.
+    Add buttons with gtk.Dialog.add_button or gtk.Dialog.add_buttons
+    """
+    def __init__(self, title="", parent=None, flags=0, buttons=None):
+        super(CrumbsDialog, self).__init__(title, parent, flags, buttons)
+
+        self.set_property("has-separator", False) # note: deprecated in 2.22
+
+        self.set_border_width(6)
+        self.vbox.set_property("spacing", 12)
+        self.action_area.set_property("spacing", 12)
+        self.action_area.set_property("border-width", 6)

bitbake/lib/bb/ui/crumbs/hig/crumbsmessagedialog.py

@@ -0,0 +1,95 @@
+#
+# BitBake Graphical GTK User Interface
+#
+# Copyright (C) 2011-2012   Intel Corporation
+#
+# Authored by Joshua Lock <josh@linux.intel.com>
+# Authored by Dongxiao Xu <dongxiao.xu@intel.com>
+# Authored by Shane Wang <shane.wang@intel.com>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License version 2 as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+import glib
+import gtk
+from bb.ui.crumbs.hobwidget import HobIconChecker
+from bb.ui.crumbs.hig.crumbsdialog import CrumbsDialog
+
+"""
+The following are convenience classes for implementing GNOME HIG compliant
+BitBake GUI's
+In summary: spacing = 12px, border-width = 6px
+"""
+
+class CrumbsMessageDialog(CrumbsDialog):
+    """
+    A GNOME HIG compliant dialog widget.
+    Add buttons with gtk.Dialog.add_button or gtk.Dialog.add_buttons
+    """
+    def __init__(self, parent=None, label="", icon=gtk.STOCK_INFO, msg=""):
+        super(CrumbsMessageDialog, self).__init__("", parent, gtk.DIALOG_MODAL)
+
+        self.set_border_width(6)
+        self.vbox.set_property("spacing", 12)
+        self.action_area.set_property("spacing", 12)
+        self.action_area.set_property("border-width", 6)
+
+        first_column = gtk.HBox(spacing=12)
+        first_column.set_property("border-width", 6)
+        first_column.show()
+        self.vbox.add(first_column)
+
+        self.icon = gtk.Image()
+        # We have our own Info icon which should be used in preference of the stock icon
+        self.icon_chk = HobIconChecker()
+        self.icon.set_from_stock(self.icon_chk.check_stock_icon(icon), gtk.ICON_SIZE_DIALOG)
+        self.icon.set_property("yalign", 0.00)
+        self.icon.show()
+        first_column.pack_start(self.icon, expand=False, fill=True, padding=0)
+        
+        if 0 <= len(msg) < 200:
+            lbl = label + "%s" % glib.markup_escape_text(msg)
+            self.label_short = gtk.Label()
+            self.label_short.set_use_markup(True)
+            self.label_short.set_line_wrap(True)
+            self.label_short.set_markup(lbl)
+            self.label_short.set_property("yalign", 0.00)
+            self.label_short.show()
+            first_column.add(self.label_short)
+        else:
+            second_row = gtk.VBox(spacing=12)
+            second_row.set_property("border-width", 6)
+            self.label_long = gtk.Label()
+            self.label_long.set_use_markup(True)
+            self.label_long.set_line_wrap(True)
+            self.label_long.set_markup(label)
+            self.label_long.set_alignment(0.0, 0.0)
+            second_row.pack_start(self.label_long, expand=False, fill=False, padding=0)
+            self.label_long.show()
+            self.textWindow = gtk.ScrolledWindow()
+            self.textWindow.set_shadow_type(gtk.SHADOW_IN)
+            self.textWindow.set_policy(gtk.POLICY_AUTOMATIC, gtk.POLICY_AUTOMATIC)
+            self.msgView = gtk.TextView()
+            self.msgView.set_editable(False)
+            self.msgView.set_wrap_mode(gtk.WRAP_WORD)
+            self.msgView.set_cursor_visible(False)
+            self.msgView.set_size_request(300, 300)
+            self.buf = gtk.TextBuffer()
+            self.buf.set_text(msg)
+            self.msgView.set_buffer(self.buf)
+            self.textWindow.add(self.msgView)
+            self.msgView.show()
+            second_row.add(self.textWindow)
+            self.textWindow.show()
+            first_column.add(second_row)
+            second_row.show()

bitbake/lib/bb/ui/crumbs/hig/deployimagedialog.py

@@ -0,0 +1,215 @@
+#
+# BitBake Graphical GTK User Interface
+#
+# Copyright (C) 2011-2012   Intel Corporation
+#
+# Authored by Joshua Lock <josh@linux.intel.com>
+# Authored by Dongxiao Xu <dongxiao.xu@intel.com>
+# Authored by Shane Wang <shane.wang@intel.com>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License version 2 as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+import glob
+import gtk
+import gobject
+import os
+import re
+import shlex
+import subprocess
+import tempfile
+from bb.ui.crumbs.hobwidget import hic, HobButton
+from bb.ui.crumbs.progressbar import HobProgressBar
+import bb.ui.crumbs.utils
+import bb.process
+from bb.ui.crumbs.hig.crumbsdialog import CrumbsDialog
+from bb.ui.crumbs.hig.crumbsmessagedialog import CrumbsMessageDialog
+
+"""
+The following are convenience classes for implementing GNOME HIG compliant
+BitBake GUI's
+In summary: spacing = 12px, border-width = 6px
+"""
+
+class DeployImageDialog (CrumbsDialog):
+
+    __dummy_usb__ = "--select a usb drive--"
+
+    def __init__(self, title, image_path, parent, flags, buttons=None, standalone=False):
+        super(DeployImageDialog, self).__init__(title, parent, flags, buttons)
+
+        self.image_path = image_path
+        self.standalone = standalone
+
+        self.create_visual_elements()
+        self.connect("response", self.response_cb)
+
+    def create_visual_elements(self):
+        self.set_size_request(600, 400)
+        label = gtk.Label()
+        label.set_alignment(0.0, 0.5)
+        markup = "<span font_desc='12'>The image to be written into usb drive:</span>"
+        label.set_markup(markup)
+        self.vbox.pack_start(label, expand=False, fill=False, padding=2)
+
+        table = gtk.Table(2, 10, False)
+        table.set_col_spacings(5)
+        table.set_row_spacings(5)
+        self.vbox.pack_start(table, expand=True, fill=True)
+
+        scroll = gtk.ScrolledWindow()
+        scroll.set_policy(gtk.POLICY_NEVER, gtk.POLICY_AUTOMATIC)
+        scroll.set_shadow_type(gtk.SHADOW_IN)
+        tv = gtk.TextView()
+        tv.set_editable(False)
+        tv.set_wrap_mode(gtk.WRAP_WORD)
+        tv.set_cursor_visible(False)
+        self.buf = gtk.TextBuffer()
+        self.buf.set_text(self.image_path)
+        tv.set_buffer(self.buf)
+        scroll.add(tv)
+        table.attach(scroll, 0, 10, 0, 1)
+
+        # There are 2 ways to use DeployImageDialog
+        # One way is that called by HOB when the 'Deploy Image' button is clicked
+        # The other way is that called by a standalone script.
+        # Following block of codes handles the latter way. It adds a 'Select Image' button and
+        # emit a signal when the button is clicked.
+        if self.standalone:
+                gobject.signal_new("select_image_clicked", self, gobject.SIGNAL_RUN_FIRST,
+                                   gobject.TYPE_NONE, ())
+                icon = gtk.Image()
+                pix_buffer = gtk.gdk.pixbuf_new_from_file(hic.ICON_IMAGES_DISPLAY_FILE)
+                icon.set_from_pixbuf(pix_buffer)
+                button = gtk.Button("Select Image")
+                button.set_image(icon)
+                #button.set_size_request(140, 50)
+                table.attach(button, 9, 10, 1, 2, gtk.FILL, 0, 0, 0)
+                button.connect("clicked", self.select_image_button_clicked_cb)
+
+        separator = gtk.HSeparator()
+        self.vbox.pack_start(separator, expand=False, fill=False, padding=10)
+
+        self.usb_desc = gtk.Label()
+        self.usb_desc.set_alignment(0.0, 0.5)
+        markup = "<span font_desc='12'>You haven't chosen any USB drive.</span>"
+        self.usb_desc.set_markup(markup)
+
+        self.usb_combo = gtk.combo_box_new_text()
+        self.usb_combo.connect("changed", self.usb_combo_changed_cb)
+        model = self.usb_combo.get_model()
+        model.clear()
+        self.usb_combo.append_text(self.__dummy_usb__)
+        for usb in self.find_all_usb_devices():
+            self.usb_combo.append_text("/dev/" + usb)
+        self.usb_combo.set_active(0)
+        self.vbox.pack_start(self.usb_combo, expand=False, fill=False)
+        self.vbox.pack_start(self.usb_desc, expand=False, fill=False, padding=2)
+
+        self.progress_bar = HobProgressBar()
+        self.vbox.pack_start(self.progress_bar, expand=False, fill=False)
+        separator = gtk.HSeparator()
+        self.vbox.pack_start(separator, expand=False, fill=True, padding=10)
+
+        self.vbox.show_all()
+        self.progress_bar.hide()
+
+    def set_image_text_buffer(self, image_path):
+        self.buf.set_text(image_path)
+
+    def set_image_path(self, image_path):
+        self.image_path = image_path
+
+    def popen_read(self, cmd):
+        tmpout, errors = bb.process.run("%s" % cmd)
+        return tmpout.strip()
+
+    def find_all_usb_devices(self):
+        usb_devs = [ os.readlink(u)
+            for u in glob.glob('/dev/disk/by-id/usb*')
+            if not re.search(r'part\d+', u) ]
+        return [ '%s' % u[u.rfind('/')+1:] for u in usb_devs ]
+
+    def get_usb_info(self, dev):
+        return "%s %s" % \
+            (self.popen_read('cat /sys/class/block/%s/device/vendor' % dev),
+            self.popen_read('cat /sys/class/block/%s/device/model' % dev))
+
+    def select_image_button_clicked_cb(self, button):
+            self.emit('select_image_clicked')
+
+    def usb_combo_changed_cb(self, usb_combo):
+        combo_item = self.usb_combo.get_active_text()
+        if not combo_item or combo_item == self.__dummy_usb__:
+            markup = "<span font_desc='12'>You haven't chosen any USB drive.</span>"
+            self.usb_desc.set_markup(markup)
+        else:
+            markup = "<span font_desc='12'>" + self.get_usb_info(combo_item.lstrip("/dev/")) + "</span>"
+            self.usb_desc.set_markup(markup)
+
+    def response_cb(self, dialog, response_id):
+        if response_id == gtk.RESPONSE_YES:
+            lbl = ''
+            combo_item = self.usb_combo.get_active_text()
+            if combo_item and combo_item != self.__dummy_usb__ and self.image_path:
+                cmdline = bb.ui.crumbs.utils.which_terminal()
+                if cmdline:
+                    tmpfile = tempfile.NamedTemporaryFile()
+                    cmdline += "\"sudo dd if=" + self.image_path + \
+                                " of=" + combo_item + "; echo $? > " + tmpfile.name + "\""
+                    subprocess.call(shlex.split(cmdline))
+
+                    if int(tmpfile.readline().strip()) == 0:
+                        lbl = "<b>Deploy image successfully.</b>"
+                    else:
+                        lbl = "<b>Failed to deploy image.</b>\nPlease check image <b>%s</b> exists and USB device <b>%s</b> is writable." % (self.image_path, combo_item)
+                    tmpfile.close()
+            else:
+                if not self.image_path:
+                    lbl = "<b>No selection made.</b>\nYou have not selected an image to deploy."
+                else:
+                    lbl = "<b>No selection made.</b>\nYou have not selected a USB device."
+            if len(lbl):
+                crumbs_dialog = CrumbsMessageDialog(self, lbl, gtk.STOCK_DIALOG_INFO)
+                button = crumbs_dialog.add_button("Close", gtk.RESPONSE_OK)
+                HobButton.style_button(button)
+                crumbs_dialog.run()
+                crumbs_dialog.destroy()
+
+    def update_progress_bar(self, title, fraction, status=None):
+        self.progress_bar.update(fraction)
+        self.progress_bar.set_title(title)
+        self.progress_bar.set_rcstyle(status)
+
+    def write_file(self, ifile, ofile):
+        self.progress_bar.reset()
+        self.progress_bar.show()
+
+        f_from = os.open(ifile, os.O_RDONLY)
+        f_to = os.open(ofile, os.O_WRONLY)
+
+        total_size = os.stat(ifile).st_size
+        written_size = 0
+
+        while True:
+            buf = os.read(f_from, 1024*1024)
+            if not buf:
+                break
+            os.write(f_to, buf)
+            written_size += 1024*1024
+            self.update_progress_bar("Writing to usb:", written_size * 1.0/total_size)
+
+        self.update_progress_bar("Writing completed:", 1.0)
+        os.close(f_from)
+        os.close(f_to)
+        self.progress_bar.hide()

bitbake/lib/bb/ui/crumbs/hig/imageselectiondialog.py

@@ -0,0 +1,172 @@
+#
+# BitBake Graphical GTK User Interface
+#
+# Copyright (C) 2011-2012   Intel Corporation
+#
+# Authored by Joshua Lock <josh@linux.intel.com>
+# Authored by Dongxiao Xu <dongxiao.xu@intel.com>
+# Authored by Shane Wang <shane.wang@intel.com>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License version 2 as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+import gtk
+import gobject
+import os
+from bb.ui.crumbs.hobwidget import HobViewTable, HobInfoButton, HobButton, HobAltButton
+from bb.ui.crumbs.hig.crumbsdialog import CrumbsDialog
+from bb.ui.crumbs.hig.layerselectiondialog import LayerSelectionDialog
+
+"""
+The following are convenience classes for implementing GNOME HIG compliant
+BitBake GUI's
+In summary: spacing = 12px, border-width = 6px
+"""
+
+class ImageSelectionDialog (CrumbsDialog):
+
+    __columns__ = [{
+            'col_name' : 'Image name',
+            'col_id'   : 0,
+            'col_style': 'text',
+            'col_min'  : 400,
+            'col_max'  : 400
+        }, {
+            'col_name' : 'Select',
+            'col_id'   : 1,
+            'col_style': 'radio toggle',
+            'col_min'  : 160,
+            'col_max'  : 160
+    }]
+
+
+    def __init__(self, image_folder, image_types, title, parent, flags, buttons=None, image_extension = {}):
+        super(ImageSelectionDialog, self).__init__(title, parent, flags, buttons)
+        self.connect("response", self.response_cb)
+
+        self.image_folder = image_folder
+        self.image_types  = image_types
+        self.image_list = []
+        self.image_names = []
+        self.image_extension = image_extension
+
+        # create visual elements on the dialog
+        self.create_visual_elements()
+
+        self.image_store = gtk.ListStore(gobject.TYPE_STRING, gobject.TYPE_BOOLEAN)
+        self.fill_image_store()
+
+    def create_visual_elements(self):
+        hbox = gtk.HBox(False, 6)
+
+        self.vbox.pack_start(hbox, expand=False, fill=False)
+
+        entry = gtk.Entry()
+        entry.set_text(self.image_folder)
+        table = gtk.Table(1, 10, True)
+        table.set_size_request(560, -1)
+        hbox.pack_start(table, expand=False, fill=False)
+        table.attach(entry, 0, 9, 0, 1)
+        image = gtk.Image()
+        image.set_from_stock(gtk.STOCK_OPEN, gtk.ICON_SIZE_BUTTON)
+        open_button = gtk.Button()
+        open_button.set_image(image)
+        open_button.connect("clicked", self.select_path_cb, self, entry)
+        table.attach(open_button, 9, 10, 0, 1)
+
+        self.image_table = HobViewTable(self.__columns__)
+        self.image_table.set_size_request(-1, 300)
+        self.image_table.connect("toggled", self.toggled_cb)
+        self.image_table.connect_group_selection(self.table_selected_cb)
+        self.image_table.connect("row-activated", self.row_actived_cb)
+        self.vbox.pack_start(self.image_table, expand=True, fill=True)
+
+        self.show_all()
+
+    def change_image_cb(self, model, path, columnid):
+        if not model:
+            return
+        iter = model.get_iter_first()
+        while iter:
+            rowpath = model.get_path(iter)
+            model[rowpath][columnid] = False
+            iter = model.iter_next(iter)
+
+        model[path][columnid] = True
+
+    def toggled_cb(self, table, cell, path, columnid, tree):
+        model = tree.get_model()
+        self.change_image_cb(model, path, columnid)
+
+    def table_selected_cb(self, selection):
+        model, paths = selection.get_selected_rows()
+        if paths:
+            self.change_image_cb(model, paths[0], 1)
+
+    def row_actived_cb(self, tab, model, path):
+        self.change_image_cb(model, path, 1)
+        self.emit('response', gtk.RESPONSE_YES)
+
+    def select_path_cb(self, action, parent, entry):
+        dialog = gtk.FileChooserDialog("", parent,
+                                       gtk.FILE_CHOOSER_ACTION_SELECT_FOLDER)
+        text = entry.get_text()
+        dialog.set_current_folder(text if len(text) > 0 else os.getcwd())
+        button = dialog.add_button("Cancel", gtk.RESPONSE_NO)
+        HobAltButton.style_button(button)
+        button = dialog.add_button("Open", gtk.RESPONSE_YES)
+        HobButton.style_button(button)
+        response = dialog.run()
+        if response == gtk.RESPONSE_YES:
+            path = dialog.get_filename()
+            entry.set_text(path)
+            self.image_folder = path
+            self.fill_image_store()
+
+        dialog.destroy()
+
+    def fill_image_store(self):
+        self.image_list = []
+        self.image_store.clear()
+        imageset = set()
+        for root, dirs, files in os.walk(self.image_folder):
+            # ignore the sub directories
+            dirs[:] = []
+            for f in files:
+                for image_type in self.image_types:
+                    if image_type in self.image_extension:
+                        real_types = self.image_extension[image_type]
+                    else:
+                        real_types = [image_type]
+                    for real_image_type in real_types:
+                        if f.endswith('.' + real_image_type):
+                            imageset.add(f.rsplit('.' + real_image_type)[0].rsplit('.rootfs')[0])
+                            self.image_list.append(f)
+
+        for image in imageset:
+            self.image_store.set(self.image_store.append(), 0, image, 1, False)
+
+        self.image_table.set_model(self.image_store)
+
+    def response_cb(self, dialog, response_id):
+        self.image_names = []
+        if response_id == gtk.RESPONSE_YES:
+            iter = self.image_store.get_iter_first()
+            while iter:
+                path = self.image_store.get_path(iter)
+                if self.image_store[path][1]:
+                    for f in self.image_list:
+                        if f.startswith(self.image_store[path][0] + '.'):
+                            self.image_names.append(f)
+                    break
+                iter = self.image_store.iter_next(iter)

bitbake/lib/bb/ui/crumbs/hig/layerselectiondialog.py

@@ -0,0 +1,296 @@
+#
+# BitBake Graphical GTK User Interface
+#
+# Copyright (C) 2011-2012   Intel Corporation
+#
+# Authored by Joshua Lock <josh@linux.intel.com>
+# Authored by Dongxiao Xu <dongxiao.xu@intel.com>
+# Authored by Shane Wang <shane.wang@intel.com>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License version 2 as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+import gtk
+import gobject
+import os
+import tempfile
+from bb.ui.crumbs.hobwidget import hic, HobButton, HobAltButton
+from bb.ui.crumbs.hig.crumbsdialog import CrumbsDialog
+from bb.ui.crumbs.hig.crumbsmessagedialog import CrumbsMessageDialog
+
+"""
+The following are convenience classes for implementing GNOME HIG compliant
+BitBake GUI's
+In summary: spacing = 12px, border-width = 6px
+"""
+
+class CellRendererPixbufActivatable(gtk.CellRendererPixbuf):
+    """
+    A custom CellRenderer implementation which is activatable
+    so that we can handle user clicks
+    """
+    __gsignals__    = { 'clicked' : (gobject.SIGNAL_RUN_LAST,
+                                     gobject.TYPE_NONE,
+                                     (gobject.TYPE_STRING,)), }
+
+    def __init__(self):
+        gtk.CellRendererPixbuf.__init__(self)
+        self.set_property('mode', gtk.CELL_RENDERER_MODE_ACTIVATABLE)
+        self.set_property('follow-state', True)
+
+    """
+    Respond to a user click on a cell
+    """
+    def do_activate(self, even, widget, path, background_area, cell_area, flags):
+        self.emit('clicked', path)
+
+#
+# LayerSelectionDialog
+#
+class LayerSelectionDialog (CrumbsDialog):
+
+    TARGETS = [
+        ("MY_TREE_MODEL_ROW", gtk.TARGET_SAME_WIDGET, 0),
+        ("text/plain", 0, 1),
+        ("TEXT", 0, 2),
+        ("STRING", 0, 3),
+        ]
+
+    def gen_label_widget(self, content):
+        label = gtk.Label()
+        label.set_alignment(0, 0)
+        label.set_markup(content)
+        label.show()
+        return label
+
+    def layer_widget_toggled_cb(self, cell, path, layer_store):
+        name = layer_store[path][0]
+        toggle = not layer_store[path][1]
+        layer_store[path][1] = toggle
+
+    def layer_widget_add_clicked_cb(self, action, layer_store, parent):
+        dialog = gtk.FileChooserDialog("Add new layer", parent,
+                                       gtk.FILE_CHOOSER_ACTION_SELECT_FOLDER)
+        button = dialog.add_button("Cancel", gtk.RESPONSE_NO)
+        HobAltButton.style_button(button)
+        button = dialog.add_button("Open", gtk.RESPONSE_YES)
+        HobButton.style_button(button)
+        label = gtk.Label("Select the layer you wish to add")
+        label.show()
+        dialog.set_extra_widget(label)
+        response = dialog.run()
+        path = dialog.get_filename()
+        dialog.destroy()
+
+        lbl = "<b>Error</b>\nUnable to load layer <i>%s</i> because " % path
+        if response == gtk.RESPONSE_YES:
+            import os
+            import os.path
+            layers = []
+            it = layer_store.get_iter_first()
+            while it:
+                layers.append(layer_store.get_value(it, 0))
+                it = layer_store.iter_next(it)
+
+            if not path:
+                lbl += "it is an invalid path."
+            elif not os.path.exists(path+"/conf/layer.conf"):
+                lbl += "there is no layer.conf inside the directory."
+            elif path in layers:
+                lbl += "it is already in loaded layers."
+            else:
+                layer_store.append([path])
+                return
+            dialog = CrumbsMessageDialog(parent, lbl)
+            dialog.add_button(gtk.STOCK_CLOSE, gtk.RESPONSE_OK)
+            response = dialog.run()
+            dialog.destroy()
+
+    def layer_widget_del_clicked_cb(self, action, tree_selection, layer_store):
+        model, iter = tree_selection.get_selected()
+        if iter:
+            layer_store.remove(iter)
+
+
+    def gen_layer_widget(self, layers, layers_avail, window, tooltip=""):
+        hbox = gtk.HBox(False, 6)
+
+        layer_tv = gtk.TreeView()
+        layer_tv.set_rules_hint(True)
+        layer_tv.set_headers_visible(False)
+        tree_selection = layer_tv.get_selection()
+        tree_selection.set_mode(gtk.SELECTION_SINGLE)
+
+        # Allow enable drag and drop of rows including row move
+        layer_tv.enable_model_drag_source( gtk.gdk.BUTTON1_MASK,
+            self.TARGETS,
+            gtk.gdk.ACTION_DEFAULT|
+            gtk.gdk.ACTION_MOVE)
+        layer_tv.enable_model_drag_dest(self.TARGETS,
+            gtk.gdk.ACTION_DEFAULT)
+        layer_tv.connect("drag_data_get", self.drag_data_get_cb)
+        layer_tv.connect("drag_data_received", self.drag_data_received_cb)
+
+        col0= gtk.TreeViewColumn('Path')
+        cell0 = gtk.CellRendererText()
+        cell0.set_padding(5,2)
+        col0.pack_start(cell0, True)
+        col0.set_cell_data_func(cell0, self.draw_layer_path_cb)
+        layer_tv.append_column(col0)
+
+        scroll = gtk.ScrolledWindow()
+        scroll.set_policy(gtk.POLICY_NEVER, gtk.POLICY_AUTOMATIC)
+        scroll.set_shadow_type(gtk.SHADOW_IN)
+        scroll.add(layer_tv)
+
+        table_layer = gtk.Table(2, 10, False)
+        hbox.pack_start(table_layer, expand=True, fill=True)
+
+        table_layer.attach(scroll, 0, 10, 0, 1)
+
+        layer_store = gtk.ListStore(gobject.TYPE_STRING)
+        for layer in layers:
+            layer_store.append([layer])
+
+        col1 = gtk.TreeViewColumn('Enabled')
+        layer_tv.append_column(col1)
+
+        cell1 = CellRendererPixbufActivatable()
+        cell1.set_fixed_size(-1,35)
+        cell1.connect("clicked", self.del_cell_clicked_cb, layer_store)
+        col1.pack_start(cell1, True)
+        col1.set_cell_data_func(cell1, self.draw_delete_button_cb, layer_tv)
+
+        add_button = gtk.Button()
+        add_button.set_relief(gtk.RELIEF_NONE)
+        box = gtk.HBox(False, 6)
+        box.show()
+        add_button.add(box)
+        add_button.connect("enter-notify-event", self.add_hover_cb)
+        add_button.connect("leave-notify-event", self.add_leave_cb)
+        self.im = gtk.Image()
+        self.im.set_from_file(hic.ICON_INDI_ADD_FILE)
+        self.im.show()
+        box.pack_start(self.im, expand=False, fill=False, padding=6)
+        lbl = gtk.Label("Add layer")
+        lbl.set_alignment(0.0, 0.5)
+        lbl.show()
+        box.pack_start(lbl, expand=True, fill=True, padding=6)
+        add_button.connect("clicked", self.layer_widget_add_clicked_cb, layer_store, window)
+        table_layer.attach(add_button, 0, 10, 1, 2, gtk.EXPAND | gtk.FILL, 0, 0, 6)
+        layer_tv.set_model(layer_store)
+
+        hbox.show_all()
+
+        return hbox, layer_store
+
+    def drag_data_get_cb(self, treeview, context, selection, target_id, etime):
+        treeselection = treeview.get_selection()
+        model, iter = treeselection.get_selected()
+        data = model.get_value(iter, 0)
+        selection.set(selection.target, 8, data)
+
+    def drag_data_received_cb(self, treeview, context, x, y, selection, info, etime):
+        model = treeview.get_model()
+        data = selection.data
+        drop_info = treeview.get_dest_row_at_pos(x, y)
+        if drop_info:
+            path, position = drop_info
+            iter = model.get_iter(path)
+            if (position == gtk.TREE_VIEW_DROP_BEFORE or position == gtk.TREE_VIEW_DROP_INTO_OR_BEFORE):
+                model.insert_before(iter, [data])
+            else:
+                model.insert_after(iter, [data])
+        else:
+            model.append([data])
+        if context.action == gtk.gdk.ACTION_MOVE:
+            context.finish(True, True, etime)
+        return
+
+    def add_hover_cb(self, button, event):
+        self.im.set_from_file(hic.ICON_INDI_ADD_HOVER_FILE)
+
+    def add_leave_cb(self, button, event):
+        self.im.set_from_file(hic.ICON_INDI_ADD_FILE)
+
+    def __init__(self, title, layers, layers_non_removable, all_layers, parent, flags, buttons=None):
+        super(LayerSelectionDialog, self).__init__(title, parent, flags, buttons)
+
+        # class members from other objects
+        self.layers = layers
+        self.layers_non_removable = layers_non_removable
+        self.all_layers = all_layers
+        self.layers_changed = False
+
+        # icon for remove button in TreeView
+        im = gtk.Image()
+        im.set_from_file(hic.ICON_INDI_REMOVE_FILE)
+        self.rem_icon = im.get_pixbuf()
+
+        # class members for internal use
+        self.layer_store = None
+
+        # create visual elements on the dialog
+        self.create_visual_elements()
+        self.connect("response", self.response_cb)
+
+    def create_visual_elements(self):
+        layer_widget, self.layer_store = self.gen_layer_widget(self.layers, self.all_layers, self, None)
+        layer_widget.set_size_request(450, 250)
+        self.vbox.pack_start(layer_widget, expand=True, fill=True)
+        self.show_all()
+
+    def response_cb(self, dialog, response_id):
+        model = self.layer_store
+        it = model.get_iter_first()
+        layers = []
+        while it:
+            layers.append(model.get_value(it, 0))
+            it = model.iter_next(it)
+
+        self.layers_changed = (self.layers != layers)
+        self.layers = layers
+
+    """
+    A custom cell_data_func to draw a delete 'button' in the TreeView for layers
+    other than the meta layer. The deletion of which is prevented so that the
+    user can't shoot themselves in the foot too badly.
+    """
+    def draw_delete_button_cb(self, col, cell, model, it, tv):
+        path =  model.get_value(it, 0)
+        if path in self.layers_non_removable:
+            cell.set_sensitive(False)
+            cell.set_property('pixbuf', None)
+            cell.set_property('mode', gtk.CELL_RENDERER_MODE_INERT)
+        else:
+            cell.set_property('pixbuf', self.rem_icon)
+            cell.set_sensitive(True)
+            cell.set_property('mode', gtk.CELL_RENDERER_MODE_ACTIVATABLE)
+
+        return True
+
+    """
+    A custom cell_data_func to write an extra message into the layer path cell
+    for the meta layer. We should inform the user that they can't remove it for
+    their own safety.
+    """
+    def draw_layer_path_cb(self, col, cell, model, it):
+        path = model.get_value(it, 0)
+        if path in self.layers_non_removable:
+            cell.set_property('markup', "<b>It cannot be removed</b>\n%s" % path)
+        else:
+            cell.set_property('text', path)
+
+    def del_cell_clicked_cb(self, cell, path, model):
+        it = model.get_iter_from_string(path)
+        model.remove(it)

bitbake/lib/bb/ui/crumbs/hig/parsingwarningsdialog.py

@@ -0,0 +1,161 @@
+#
+# BitBake Graphical GTK User Interface
+#
+# Copyright (C) 2011-2012   Intel Corporation
+#
+# Authored by Cristiana Voicu <cristiana.voicu@intel.com>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License version 2 as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+import gtk
+import gobject
+from bb.ui.crumbs.hobwidget import HobAltButton
+from bb.ui.crumbs.hig.crumbsdialog import CrumbsDialog
+
+"""
+The following are convenience classes for implementing GNOME HIG compliant
+BitBake GUI's
+In summary: spacing = 12px, border-width = 6px
+"""
+
+#
+# ParsingWarningsDialog
+#
+class ParsingWarningsDialog (CrumbsDialog):
+
+    def __init__(self, title, warnings, parent, flags, buttons=None):
+        super(ParsingWarningsDialog, self).__init__(title, parent, flags, buttons)
+
+        self.warnings = warnings
+        self.warning_on = 0
+        self.warn_nb = len(warnings)
+
+        # create visual elements on the dialog
+        self.create_visual_elements()
+
+    def cancel_button_cb(self, button):
+        self.destroy()
+
+    def previous_button_cb(self, button):
+        self.warning_on = self.warning_on - 1
+        self.refresh_components()
+
+    def next_button_cb(self, button):
+        self.warning_on = self.warning_on + 1
+        self.refresh_components()
+
+    def refresh_components(self):
+        lbl = self.warnings[self.warning_on]
+        #when the warning text has more than 400 chars, it uses a scroll bar
+        if 0<= len(lbl) < 400:
+            self.warning_label.set_size_request(320, 230)
+            self.warning_label.set_use_markup(True)
+            self.warning_label.set_line_wrap(True)
+            self.warning_label.set_markup(lbl)
+            self.warning_label.set_property("yalign", 0.00)
+        else:
+            self.textWindow.set_shadow_type(gtk.SHADOW_IN)
+            self.textWindow.set_policy(gtk.POLICY_AUTOMATIC, gtk.POLICY_AUTOMATIC)
+            self.msgView = gtk.TextView()
+            self.msgView.set_editable(False)
+            self.msgView.set_wrap_mode(gtk.WRAP_WORD)
+            self.msgView.set_cursor_visible(False)
+            self.msgView.set_size_request(320, 230)
+            self.buf = gtk.TextBuffer()
+            self.buf.set_text(lbl)
+            self.msgView.set_buffer(self.buf)
+            self.textWindow.add(self.msgView)
+            self.msgView.show()
+
+        if self.warning_on==0:
+            self.previous_button.set_sensitive(False)
+        else:
+            self.previous_button.set_sensitive(True)
+
+        if self.warning_on==self.warn_nb-1:
+            self.next_button.set_sensitive(False)
+        else:
+            self.next_button.set_sensitive(True)
+
+        if self.warn_nb>1:
+            self.heading = "Warning " + str(self.warning_on + 1) + " of " + str(self.warn_nb)
+            self.heading_label.set_markup('<span weight="bold">%s</span>' % self.heading)
+        else:
+            self.heading = "Warning"
+            self.heading_label.set_markup('<span weight="bold">%s</span>' % self.heading)
+
+        self.show_all()
+
+        if 0<= len(lbl) < 400:
+            self.textWindow.hide()
+        else:
+            self.warning_label.hide()
+
+    def create_visual_elements(self):
+        self.set_size_request(350, 350)
+        self.heading_label = gtk.Label()
+        self.heading_label.set_alignment(0.1, 0)
+        self.warning_label = gtk.Label()
+        self.textWindow = gtk.ScrolledWindow()
+
+        table = gtk.Table(1, 10, False)
+
+        cancel_button = gtk.Button()
+        cancel_button.set_label("Close")
+        cancel_button.connect("clicked", self.cancel_button_cb)
+        cancel_button.set_size_request(110, 30)
+
+        self.previous_button = gtk.Button()
+        image1 = gtk.image_new_from_stock(gtk.STOCK_GO_BACK, gtk.ICON_SIZE_BUTTON)
+        image1.show()
+        box = gtk.HBox(False, 6)
+        box.show()
+        self.previous_button.add(box)
+        lbl = gtk.Label("Previous")
+        lbl.show()
+        box.pack_start(image1, expand=False, fill=False, padding=3)
+        box.pack_start(lbl, expand=True, fill=True, padding=3)
+        self.previous_button.connect("clicked", self.previous_button_cb)
+        self.previous_button.set_size_request(110, 30)
+
+        self.next_button = gtk.Button()
+        image2 = gtk.image_new_from_stock(gtk.STOCK_GO_FORWARD, gtk.ICON_SIZE_BUTTON)
+        image2.show()
+        box = gtk.HBox(False, 6)
+        box.show()
+        self.next_button.add(box)
+        lbl = gtk.Label("Next")
+        lbl.show()
+        box.pack_start(lbl, expand=True, fill=True, padding=3)
+        box.pack_start(image2, expand=False, fill=False, padding=3)
+        self.next_button.connect("clicked", self.next_button_cb)
+        self.next_button.set_size_request(110, 30)
+
+        #when there more than one warning, we need "previous" and "next" button
+        if self.warn_nb>1:
+            self.vbox.pack_start(self.heading_label, expand=False, fill=False)
+            self.vbox.pack_start(self.warning_label, expand=False, fill=False)
+            self.vbox.pack_start(self.textWindow, expand=False, fill=False)
+            table.attach(cancel_button, 6, 7, 0, 1, xoptions=gtk.SHRINK)
+            table.attach(self.previous_button, 7, 8, 0, 1, xoptions=gtk.SHRINK)
+            table.attach(self.next_button, 8, 9, 0, 1, xoptions=gtk.SHRINK)
+            self.vbox.pack_end(table, expand=False, fill=False)
+        else:
+            self.vbox.pack_start(self.heading_label, expand=False, fill=False)
+            self.vbox.pack_start(self.warning_label, expand=False, fill=False)
+            self.vbox.pack_start(self.textWindow, expand=False, fill=False)
+            cancel_button = self.add_button("Cancel", gtk.RESPONSE_CANCEL)
+            HobAltButton.style_button(cancel_button)
+
+        self.refresh_components()

bitbake/lib/bb/ui/crumbs/hig/proxydetailsdialog.py

@@ -0,0 +1,90 @@
+#
+# BitBake Graphical GTK User Interface
+#
+# Copyright (C) 2011-2012   Intel Corporation
+#
+# Authored by Joshua Lock <josh@linux.intel.com>
+# Authored by Dongxiao Xu <dongxiao.xu@intel.com>
+# Authored by Shane Wang <shane.wang@intel.com>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License version 2 as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+import gtk
+from bb.ui.crumbs.hig.crumbsdialog import CrumbsDialog
+
+"""
+The following are convenience classes for implementing GNOME HIG compliant
+BitBake GUI's
+In summary: spacing = 12px, border-width = 6px
+"""
+
+class ProxyDetailsDialog (CrumbsDialog):
+
+    def __init__(self, title, user, passwd, parent, flags, buttons=None):
+        super(ProxyDetailsDialog, self).__init__(title, parent, flags, buttons)
+        self.connect("response", self.response_cb)
+
+        self.auth = not (user == None or passwd == None or user == "")
+        self.user = user or ""
+        self.passwd = passwd or ""
+
+        # create visual elements on the dialog
+        self.create_visual_elements()
+
+    def create_visual_elements(self):
+        self.auth_checkbox = gtk.CheckButton("Use authentication")
+        self.auth_checkbox.set_tooltip_text("Check this box to set the username and the password")
+        self.auth_checkbox.set_active(self.auth)
+        self.auth_checkbox.connect("toggled", self.auth_checkbox_toggled_cb)
+        self.vbox.pack_start(self.auth_checkbox, expand=False, fill=False)
+
+        hbox = gtk.HBox(False, 6)
+        self.user_label = gtk.Label("Username:")
+        self.user_text = gtk.Entry()
+        self.user_text.set_text(self.user)
+        hbox.pack_start(self.user_label, expand=False, fill=False)
+        hbox.pack_end(self.user_text, expand=False, fill=False)
+        self.vbox.pack_start(hbox, expand=False, fill=False)
+
+        hbox = gtk.HBox(False, 6)
+        self.passwd_label = gtk.Label("Password:")
+        self.passwd_text = gtk.Entry()
+        self.passwd_text.set_text(self.passwd)
+        hbox.pack_start(self.passwd_label, expand=False, fill=False)
+        hbox.pack_end(self.passwd_text, expand=False, fill=False)
+        self.vbox.pack_start(hbox, expand=False, fill=False)
+
+        self.refresh_auth_components()
+        self.show_all()
+
+    def refresh_auth_components(self):
+        self.user_label.set_sensitive(self.auth)
+        self.user_text.set_editable(self.auth)
+        self.user_text.set_sensitive(self.auth)
+        self.passwd_label.set_sensitive(self.auth)
+        self.passwd_text.set_editable(self.auth)
+        self.passwd_text.set_sensitive(self.auth)
+
+    def auth_checkbox_toggled_cb(self, button):
+        self.auth = self.auth_checkbox.get_active()
+        self.refresh_auth_components()
+
+    def response_cb(self, dialog, response_id):
+        if response_id == gtk.RESPONSE_OK:
+            if self.auth:
+                self.user = self.user_text.get_text()
+                self.passwd = self.passwd_text.get_text()
+            else:
+                self.user = None
+                self.passwd = None

bitbake/lib/bb/ui/crumbs/hig/settingsuihelper.py

@@ -0,0 +1,216 @@
+#
+# BitBake Graphical GTK User Interface
+#
+# Copyright (C) 2011-2012   Intel Corporation
+#
+# Authored by Joshua Lock <josh@linux.intel.com>
+# Authored by Dongxiao Xu <dongxiao.xu@intel.com>
+# Authored by Shane Wang <shane.wang@intel.com>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License version 2 as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+import gtk
+import os
+from bb.ui.crumbs.hobwidget import HobInfoButton, HobButton, HobAltButton
+
+"""
+The following are convenience classes for implementing GNOME HIG compliant
+BitBake GUI's
+In summary: spacing = 12px, border-width = 6px
+"""
+
+class SettingsUIHelper():
+
+    def gen_label_widget(self, content):
+        label = gtk.Label()
+        label.set_alignment(0, 0)
+        label.set_markup(content)
+        label.show()
+        return label
+
+    def gen_label_info_widget(self, content, tooltip):
+        table = gtk.Table(1, 10, False)
+        label = self.gen_label_widget(content)
+        info = HobInfoButton(tooltip, self)
+        table.attach(label, 0, 1, 0, 1, xoptions=gtk.FILL)
+        table.attach(info, 1, 2, 0, 1, xoptions=gtk.FILL, xpadding=10)
+        return table
+
+    def gen_spinner_widget(self, content, lower, upper, tooltip=""):
+        hbox = gtk.HBox(False, 12)
+        adjust = gtk.Adjustment(value=content, lower=lower, upper=upper, step_incr=1)
+        spinner = gtk.SpinButton(adjustment=adjust, climb_rate=1, digits=0)
+
+        spinner.set_value(content)
+        hbox.pack_start(spinner, expand=False, fill=False)
+
+        info = HobInfoButton(tooltip, self)
+        hbox.pack_start(info, expand=False, fill=False)
+
+        hbox.show_all()
+        return hbox, spinner
+
+    def gen_combo_widget(self, curr_item, all_item, tooltip=""):
+        hbox = gtk.HBox(False, 12)
+        combo = gtk.combo_box_new_text()
+        hbox.pack_start(combo, expand=False, fill=False)
+
+        index = 0
+        for item in all_item or []:
+            combo.append_text(item)
+            if item == curr_item:
+                combo.set_active(index)
+            index += 1
+
+        info = HobInfoButton(tooltip, self)
+        hbox.pack_start(info, expand=False, fill=False)
+
+        hbox.show_all()
+        return hbox, combo
+
+    def entry_widget_select_path_cb(self, action, parent, entry):
+        dialog = gtk.FileChooserDialog("", parent,
+                                       gtk.FILE_CHOOSER_ACTION_SELECT_FOLDER)
+        text = entry.get_text()
+        dialog.set_current_folder(text if len(text) > 0 else os.getcwd())
+        button = dialog.add_button("Cancel", gtk.RESPONSE_NO)
+        HobAltButton.style_button(button)
+        button = dialog.add_button("Open", gtk.RESPONSE_YES)
+        HobButton.style_button(button)
+        response = dialog.run()
+        if response == gtk.RESPONSE_YES:
+            path = dialog.get_filename()
+            entry.set_text(path)
+
+        dialog.destroy()
+
+    def gen_entry_widget(self, content, parent, tooltip="", need_button=True):
+        hbox = gtk.HBox(False, 12)
+        entry = gtk.Entry()
+        entry.set_text(content)
+        entry.set_size_request(350,30)
+
+        if need_button:
+            table = gtk.Table(1, 10, False)
+            hbox.pack_start(table, expand=True, fill=True)
+            table.attach(entry, 0, 9, 0, 1, xoptions=gtk.SHRINK)
+            image = gtk.Image()
+            image.set_from_stock(gtk.STOCK_OPEN,gtk.ICON_SIZE_BUTTON)
+            open_button = gtk.Button()
+            open_button.set_image(image)
+            open_button.connect("clicked", self.entry_widget_select_path_cb, parent, entry)
+            table.attach(open_button, 9, 10, 0, 1, xoptions=gtk.SHRINK)
+        else:
+            hbox.pack_start(entry, expand=True, fill=True)
+
+        if tooltip != "":
+            info = HobInfoButton(tooltip, self)
+            hbox.pack_start(info, expand=False, fill=False)
+
+        hbox.show_all()
+        return hbox, entry
+
+    def gen_mirror_entry_widget(self, content, index, match_content=""):
+        hbox = gtk.HBox(False)
+        entry = gtk.Entry()
+        content = content[:-2]
+        entry.set_text(content)
+        entry.set_size_request(350,30)
+
+        entry_match = gtk.Entry()
+        entry_match.set_text(match_content)
+        entry_match.set_size_request(100,30)
+
+        table = gtk.Table(2, 5, False)
+        table.set_row_spacings(12)
+        table.set_col_spacings(6)
+        hbox.pack_start(table, expand=True, fill=True)
+
+        label_configuration = gtk.Label("Configuration")
+        label_configuration.set_alignment(0.0,0.5)
+        label_mirror_url = gtk.Label("Mirror URL")
+        label_mirror_url.set_alignment(0.0,0.5)
+        label_match = gtk.Label("Match")
+        label_match.set_alignment(0.0,0.5)
+        label_replace_with = gtk.Label("Replace with")
+        label_replace_with.set_alignment(0.0,0.5)
+
+        combo = gtk.combo_box_new_text()
+        combo.append_text("Standard")
+        combo.append_text("Custom")
+        if match_content == "":
+            combo.set_active(0)
+        else:
+            combo.set_active(1)
+        combo.connect("changed", self.on_combo_changed, index)
+        combo.set_size_request(100,30)
+
+        delete_button = HobAltButton("Delete")
+        delete_button.connect("clicked", self.delete_cb, index, entry)
+        if content == "" and index == 0  and len(self.sstatemirrors_list) == 1:
+            delete_button.set_sensitive(False)
+        delete_button.set_size_request(100, 30)
+
+        entry_match.connect("changed", self.insert_entry_match_cb, index)
+        entry.connect("changed", self.insert_entry_cb, index, delete_button)
+
+        if match_content == "":
+            table.attach(label_configuration, 1, 2, 0, 1, xoptions=gtk.SHRINK|gtk.FILL)
+            table.attach(label_mirror_url, 2, 3, 0, 1, xoptions=gtk.SHRINK|gtk.FILL)
+            table.attach(combo, 1, 2, 1, 2, xoptions=gtk.SHRINK)
+            table.attach(entry, 2, 3, 1, 2, xoptions=gtk.SHRINK)
+            table.attach(delete_button, 3, 4, 1, 2, xoptions=gtk.SHRINK)
+        else:
+            table.attach(label_configuration, 1, 2, 0, 1, xoptions=gtk.SHRINK|gtk.FILL)
+            table.attach(label_match, 2, 3, 0, 1, xoptions=gtk.SHRINK|gtk.FILL)
+            table.attach(label_replace_with, 3, 4, 0, 1, xoptions=gtk.SHRINK|gtk.FILL)
+            table.attach(combo, 1, 2, 1, 2, xoptions=gtk.SHRINK)
+            table.attach(entry_match, 2, 3, 1, 2, xoptions=gtk.SHRINK)
+            table.attach(entry, 3, 4, 1, 2, xoptions=gtk.SHRINK)
+            table.attach(delete_button, 4, 5, 1, 2, xoptions=gtk.SHRINK)
+
+        hbox.show_all()
+        return hbox
+
+    def insert_entry_match_cb(self, entry_match, index):
+        self.sstatemirrors_list[index][2] = entry_match.get_text()
+
+    def insert_entry_cb(self, entry, index, button):
+        self.sstatemirrors_list[index][1] = entry.get_text()
+        if entry.get_text() == "" and index == 0:
+            button.set_sensitive(False)
+        else:
+            button.set_sensitive(True)
+
+    def on_combo_changed(self, combo, index):
+        if combo.get_active_text() == "Standard":
+            self.sstatemirrors_list[index][0] = 0
+            self.sstatemirrors_list[index][2] = "file://(.*)"
+        else:
+            self.sstatemirrors_list[index][0] = 1
+        self.refresh_shared_state_page()
+
+    def delete_cb(self, button, index, entry):
+        if index == 0 and len(self.sstatemirrors_list)==1:
+            entry.set_text("")
+        else:
+            self.sstatemirrors_list.pop(index)
+            self.refresh_shared_state_page()
+
+    def add_mirror(self, button):
+        tooltip = "Select the pre-built mirror that will speed your build"
+        index = len(self.sstatemirrors_list)
+        sm_list = [0, "", "file://(.*)"]
+        self.sstatemirrors_list.append(sm_list)
+        self.refresh_shared_state_page()

bitbake/lib/bb/ui/crumbs/hig/simplesettingsdialog.py

@@ -0,0 +1,722 @@
+#
+# BitBake Graphical GTK User Interface
+#
+# Copyright (C) 2011-2012   Intel Corporation
+#
+# Authored by Joshua Lock <josh@linux.intel.com>
+# Authored by Dongxiao Xu <dongxiao.xu@intel.com>
+# Authored by Shane Wang <shane.wang@intel.com>
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License version 2 as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+import gtk
+import gobject
+import hashlib
+from bb.ui.crumbs.hobwidget import hic, HobInfoButton, HobButton, HobAltButton 
+from bb.ui.crumbs.progressbar import HobProgressBar
+from bb.ui.crumbs.hig.settingsuihelper import SettingsUIHelper
+from bb.ui.crumbs.hig.crumbsdialog import CrumbsDialog
+from bb.ui.crumbs.hig.crumbsmessagedialog import CrumbsMessageDialog
+from bb.ui.crumbs.hig.proxydetailsdialog import ProxyDetailsDialog
+
+"""
+The following are convenience classes for implementing GNOME HIG compliant
+BitBake GUI's
+In summary: spacing = 12px, border-width = 6px
+"""
+
+class SimpleSettingsDialog (CrumbsDialog, SettingsUIHelper):
+
+    (BUILD_ENV_PAGE_ID,
+     SHARED_STATE_PAGE_ID,
+     PROXIES_PAGE_ID,
+     OTHERS_PAGE_ID) = range(4)
+
+    (TEST_NETWORK_NONE,
+     TEST_NETWORK_INITIAL,
+     TEST_NETWORK_RUNNING,
+     TEST_NETWORK_PASSED,
+     TEST_NETWORK_FAILED,
+     TEST_NETWORK_CANCELED) = range(6)
+
+    def __init__(self, title, configuration, all_image_types,
+            all_package_formats, all_distros, all_sdk_machines,
+            max_threads, parent, flags, handler, buttons=None):
+        super(SimpleSettingsDialog, self).__init__(title, parent, flags, buttons)
+
+        # class members from other objects
+        # bitbake settings from Builder.Configuration
+        self.configuration = configuration
+        self.image_types = all_image_types
+        self.all_package_formats = all_package_formats
+        self.all_distros = all_distros
+        self.all_sdk_machines = all_sdk_machines
+        self.max_threads = max_threads
+
+        # class members for internal use
+        self.dldir_text = None
+        self.sstatedir_text = None
+        self.sstatemirrors_list = []
+        self.sstatemirrors_changed = 0
+        self.bb_spinner = None
+        self.pmake_spinner = None
+        self.rootfs_size_spinner = None
+        self.extra_size_spinner = None
+        self.gplv3_checkbox = None
+        self.toolchain_checkbox = None
+        self.setting_store = None
+        self.image_types_checkbuttons = {}
+
+        self.md5 = self.config_md5()
+        self.proxy_md5 = self.config_proxy_md5()
+        self.settings_changed = False
+        self.proxy_settings_changed = False
+        self.handler = handler
+        self.proxy_test_ran = False
+
+        # create visual elements on the dialog
+        self.create_visual_elements()
+        self.connect("response", self.response_cb)
+
+    def _get_sorted_value(self, var):
+        return " ".join(sorted(str(var).split())) + "\n"
+
+    def config_proxy_md5(self):
+        data = ("ENABLE_PROXY: "         + self._get_sorted_value(self.configuration.enable_proxy))
+        if self.configuration.enable_proxy:
+            for protocol in self.configuration.proxies.keys():
+                data += (protocol + ": " + self._get_sorted_value(self.configuration.combine_proxy(protocol)))
+        return hashlib.md5(data).hexdigest()
+
+    def config_md5(self):
+        data = ""
+        for key in self.configuration.extra_setting.keys():
+            data += (key + ": " + self._get_sorted_value(self.configuration.extra_setting[key]))
+        return hashlib.md5(data).hexdigest()
+
+    def gen_proxy_entry_widget(self, protocol, parent, need_button=True, line=0):
+        label = gtk.Label(protocol.upper() + " proxy")
+        self.proxy_table.attach(label, 0, 1, line, line+1, xpadding=24)
+
+        proxy_entry = gtk.Entry()
+        proxy_entry.set_size_request(300, -1)
+        self.proxy_table.attach(proxy_entry, 1, 2, line, line+1, ypadding=4)
+
+        self.proxy_table.attach(gtk.Label(":"), 2, 3, line, line+1, xpadding=12, ypadding=4)
+
+        port_entry = gtk.Entry()
+        port_entry.set_size_request(60, -1)
+        self.proxy_table.attach(port_entry, 3, 4, line, line+1, ypadding=4)
+
+        details_button = HobAltButton("Details")
+        details_button.connect("clicked", self.details_cb, parent, protocol)
+        self.proxy_table.attach(details_button, 4, 5, line, line+1, xpadding=4, yoptions=gtk.EXPAND)
+
+        return proxy_entry, port_entry, details_button
+
+    def refresh_proxy_components(self):
+        self.same_checkbox.set_sensitive(self.configuration.enable_proxy)
+
+        self.http_proxy.set_text(self.configuration.combine_host_only("http"))
+        self.http_proxy.set_editable(self.configuration.enable_proxy)
+        self.http_proxy.set_sensitive(self.configuration.enable_proxy)
+        self.http_proxy_port.set_text(self.configuration.combine_port_only("http"))
+        self.http_proxy_port.set_editable(self.configuration.enable_proxy)
+        self.http_proxy_port.set_sensitive(self.configuration.enable_proxy)
+        self.http_proxy_details.set_sensitive(self.configuration.enable_proxy)
+
+        self.https_proxy.set_text(self.configuration.combine_host_only("https"))
+        self.https_proxy.set_editable(self.configuration.enable_proxy and (not self.configuration.same_proxy))
+        self.https_proxy.set_sensitive(self.configuration.enable_proxy and (not self.configuration.same_proxy))
+        self.https_proxy_port.set_text(self.configuration.combine_port_only("https"))
+        self.https_proxy_port.set_editable(self.configuration.enable_proxy and (not self.configuration.same_proxy))
+        self.https_proxy_port.set_sensitive(self.configuration.enable_proxy and (not self.configuration.same_proxy))
+        self.https_proxy_details.set_sensitive(self.configuration.enable_proxy and (not self.configuration.same_proxy))
+
+        self.ftp_proxy.set_text(self.configuration.combine_host_only("ftp"))
+        self.ftp_proxy.set_editable(self.configuration.enable_proxy and (not self.configuration.same_proxy))
+        self.ftp_proxy.set_sensitive(self.configuration.enable_proxy and (not self.configuration.same_proxy))
+        self.ftp_proxy_port.set_text(self.configuration.combine_port_only("ftp"))
+        self.ftp_proxy_port.set_editable(self.configuration.enable_proxy and (not self.configuration.same_proxy))
+        self.ftp_proxy_port.set_sensitive(self.configuration.enable_proxy and (not self.configuration.same_proxy))
+        self.ftp_proxy_details.set_sensitive(self.configuration.enable_proxy and (not self.configuration.same_proxy))
+
+        self.git_proxy.set_text(self.configuration.combine_host_only("git"))
+        self.git_proxy.set_editable(self.configuration.enable_proxy and (not self.configuration.same_proxy))
+        self.git_proxy.set_sensitive(self.configuration.enable_proxy and (not self.configuration.same_proxy))
+        self.git_proxy_port.set_text(self.configuration.combine_port_only("git"))
+        self.git_proxy_port.set_editable(self.configuration.enable_proxy and (not self.configuration.same_proxy))
+        self.git_proxy_port.set_sensitive(self.configuration.enable_proxy and (not self.configuration.same_proxy))
+        self.git_proxy_details.set_sensitive(self.configuration.enable_proxy and (not self.configuration.same_proxy))
+
+        self.cvs_proxy.set_text(self.configuration.combine_host_only("cvs"))
+        self.cvs_proxy.set_editable(self.configuration.enable_proxy and (not self.configuration.same_proxy))
+        self.cvs_proxy.set_sensitive(self.configuration.enable_proxy and (not self.configuration.same_proxy))
+        self.cvs_proxy_port.set_text(self.configuration.combine_port_only("cvs"))
+        self.cvs_proxy_port.set_editable(self.configuration.enable_proxy and (not self.configuration.same_proxy))
+        self.cvs_proxy_port.set_sensitive(self.configuration.enable_proxy and (not self.configuration.same_proxy))
+        self.cvs_proxy_details.set_sensitive(self.configuration.enable_proxy and (not self.configuration.same_proxy))
+
+        if self.configuration.same_proxy:
+            if self.http_proxy.get_text():
+                [w.set_text(self.http_proxy.get_text()) for w in self.same_proxy_addresses]
+            if self.http_proxy_port.get_text():
+                [w.set_text(self.http_proxy_port.get_text()) for w in self.same_proxy_ports]
+
+    def proxy_checkbox_toggled_cb(self, button):
+        self.configuration.enable_proxy = self.proxy_checkbox.get_active()
+        if not self.configuration.enable_proxy:
+            self.configuration.same_proxy = False
+            self.same_checkbox.set_active(self.configuration.same_proxy)
+        self.save_proxy_data()
+        self.refresh_proxy_components()
+
+    def same_checkbox_toggled_cb(self, button):
+        self.configuration.same_proxy = self.same_checkbox.get_active()
+        self.save_proxy_data()
+        self.refresh_proxy_components()
+
+    def save_proxy_data(self):
+        self.configuration.split_proxy("http", self.http_proxy.get_text() + ":" + self.http_proxy_port.get_text())
+        if self.configuration.same_proxy:
+            self.configuration.split_proxy("https", self.http_proxy.get_text() + ":" + self.http_proxy_port.get_text())
+            self.configuration.split_proxy("ftp", self.http_proxy.get_text() + ":" + self.http_proxy_port.get_text())
+            self.configuration.split_proxy("git", self.http_proxy.get_text() + ":" + self.http_proxy_port.get_text())
+            self.configuration.split_proxy("cvs", self.http_proxy.get_text() + ":" + self.http_proxy_port.get_text())
+        else:
+            self.configuration.split_proxy("https", self.https_proxy.get_text() + ":" + self.https_proxy_port.get_text())
+            self.configuration.split_proxy("ftp", self.ftp_proxy.get_text() + ":" + self.ftp_proxy_port.get_text())
+            self.configuration.split_proxy("git", self.git_proxy.get_text() + ":" + self.git_proxy_port.get_text())
+            self.configuration.split_proxy("cvs", self.cvs_proxy.get_text() + ":" + self.cvs_proxy_port.get_text())       
+
+    def response_cb(self, dialog, response_id):
+        if response_id == gtk.RESPONSE_YES:
+            # Check that all proxy entries have a corresponding port
+            for proxy, port in zip(self.all_proxy_addresses, self.all_proxy_ports):
+                if proxy.get_text() and not port.get_text():
+                    lbl = "<b>Enter all port numbers</b>\n\n"
+                    msg = "Proxy servers require a port number. Please make sure you have entered a port number for each proxy server."
+                    dialog = CrumbsMessageDialog(self, lbl, gtk.STOCK_DIALOG_WARNING, msg)
+                    button = dialog.add_button("Close", gtk.RESPONSE_OK)
+                    HobButton.style_button(button)
+                    response = dialog.run()
+                    dialog.destroy()
+                    self.emit_stop_by_name("response")
+                    return
+
+        self.configuration.dldir = self.dldir_text.get_text()
+        self.configuration.sstatedir = self.sstatedir_text.get_text()
+        self.configuration.sstatemirror = ""
+        for mirror in self.sstatemirrors_list:
+            if mirror[1] != "":
+                if mirror[1].endswith("\\1"):
+                    smirror = mirror[2] + " " + mirror[1] + " \\n "
+                else:
+                    smirror = mirror[2] + " " + mirror[1] + "\\1 \\n "
+                self.configuration.sstatemirror += smirror
+        self.configuration.bbthread = self.bb_spinner.get_value_as_int()
+        self.configuration.pmake = self.pmake_spinner.get_value_as_int()
+        self.save_proxy_data()
+        self.configuration.extra_setting = {}
+        it = self.setting_store.get_iter_first()
+        while it:
+            key = self.setting_store.get_value(it, 0)
+            value = self.setting_store.get_value(it, 1)
+            self.configuration.extra_setting[key] = value
+            it = self.setting_store.iter_next(it)
+
+        md5 = self.config_md5()
+        self.settings_changed = (self.md5 != md5)
+        self.proxy_settings_changed = (self.proxy_md5 != self.config_proxy_md5())
+
+    def create_build_environment_page(self):
+        advanced_vbox = gtk.VBox(False, 6)
+        advanced_vbox.set_border_width(6)
+
+        advanced_vbox.pack_start(self.gen_label_widget('<span weight="bold">Parallel threads</span>'), expand=False, fill=False)
+        sub_vbox = gtk.VBox(False, 6)
+        advanced_vbox.pack_start(sub_vbox, expand=False, fill=False)
+        label = self.gen_label_widget("BitBake parallel threads")
+        tooltip = "Sets the number of threads that BitBake tasks can simultaneously run. See the <a href=\""
+        tooltip += "http://www.yoctoproject.org/docs/current/poky-ref-manual/"
+        tooltip += "poky-ref-manual.html#var-BB_NUMBER_THREADS\">Poky reference manual</a> for information"
+        bbthread_widget, self.bb_spinner = self.gen_spinner_widget(self.configuration.bbthread, 1, self.max_threads, tooltip)
+        sub_vbox.pack_start(label, expand=False, fill=False)
+        sub_vbox.pack_start(bbthread_widget, expand=False, fill=False)
+
+        sub_vbox = gtk.VBox(False, 6)
+        advanced_vbox.pack_start(sub_vbox, expand=False, fill=False)
+        label = self.gen_label_widget("Make parallel threads")
+        tooltip = "Sets the maximum number of threads the host can use during the build. See the <a href=\""
+        tooltip += "http://www.yoctoproject.org/docs/current/poky-ref-manual/"
+        tooltip += "poky-ref-manual.html#var-PARALLEL_MAKE\">Poky reference manual</a> for information"
+        pmake_widget, self.pmake_spinner = self.gen_spinner_widget(self.configuration.pmake, 1, self.max_threads, tooltip)
+        sub_vbox.pack_start(label, expand=False, fill=False)
+        sub_vbox.pack_start(pmake_widget, expand=False, fill=False)
+
+        advanced_vbox.pack_start(self.gen_label_widget('<span weight="bold">Downloaded source code</span>'), expand=False, fill=False)
+        sub_vbox = gtk.VBox(False, 6)
+        advanced_vbox.pack_start(sub_vbox, expand=False, fill=False)
+        label = self.gen_label_widget("Downloads directory")
+        tooltip = "Select a folder that caches the upstream project source code"
+        dldir_widget, self.dldir_text = self.gen_entry_widget(self.configuration.dldir, self, tooltip)
+        sub_vbox.pack_start(label, expand=False, fill=False)
+        sub_vbox.pack_start(dldir_widget, expand=False, fill=False)
+
+        return advanced_vbox
+
+    def create_shared_state_page(self):
+        advanced_vbox = gtk.VBox(False)
+        advanced_vbox.set_border_width(12)
+
+        sub_vbox = gtk.VBox(False)
+        advanced_vbox.pack_start(sub_vbox, expand=False, fill=False, padding=24)
+        content = "<span>Shared state directory</span>"
+        tooltip = "Select a folder that caches your prebuilt results"
+        label = self.gen_label_info_widget(content, tooltip)
+        sstatedir_widget, self.sstatedir_text = self.gen_entry_widget(self.configuration.sstatedir, self)
+        sub_vbox.pack_start(label, expand=False, fill=False)
+        sub_vbox.pack_start(sstatedir_widget, expand=False, fill=False, padding=12)
+
+        content = "<span weight=\"bold\">Shared state mirrors</span>"
+        tooltip = "URLs pointing to pre-built mirrors that will speed your build. "
+        tooltip += "Select the \'Standard\' configuration if the structure of your "
+        tooltip += "mirror replicates the structure of your local shared state directory. "
+        tooltip += "For more information on shared state mirrors, check the <a href=\""
+        tooltip += "http://www.yoctoproject.org/docs/current/poky-ref-manual/"
+        tooltip += "poky-ref-manual.html#shared-state\">Yocto Project Reference Manual</a>."
+        table = self.gen_label_info_widget(content, tooltip)
+        advanced_vbox.pack_start(table, expand=False, fill=False)
+
+        sub_vbox = gtk.VBox(False)
+        scroll = gtk.ScrolledWindow()
+        scroll.set_policy(gtk.POLICY_NEVER, gtk.POLICY_AUTOMATIC)
+        scroll.add_with_viewport(sub_vbox)
+        scroll.connect('size-allocate', self.scroll_changed)
+        advanced_vbox.pack_start(scroll, gtk.TRUE, gtk.TRUE, 0)
+        searched_string = "file://"
+
+        if self.sstatemirrors_changed == 0:
+            self.sstatemirrors_changed = 1
+            sstatemirrors = self.configuration.sstatemirror
+            if sstatemirrors == "":
+                sm_list = [ 0, "", "file://(.*)"]
+                self.sstatemirrors_list.append(sm_list)
+            else:
+                while sstatemirrors.find(searched_string) != -1:
+                    if sstatemirrors.find(searched_string,1) != -1:
+                        sstatemirror = sstatemirrors[:sstatemirrors.find(searched_string,1)]
+                        sstatemirrors = sstatemirrors[sstatemirrors.find(searched_string,1):]
+                    else:
+                        sstatemirror = sstatemirrors
+                        sstatemirrors = sstatemirrors[1:]
+
+                    sstatemirror_fields = [x for x in sstatemirror.split(' ') if x.strip()]
+                    if sstatemirror_fields[0] == "file://(.*)":
+                        sm_list = [ 0, sstatemirror_fields[1], "file://(.*)"]
+                    else:
+                        sm_list = [ 1, sstatemirror_fields[1], sstatemirror_fields[0]]
+                    self.sstatemirrors_list.append(sm_list)
+
+        index = 0
+        for mirror in self.sstatemirrors_list:
+            if mirror[0] == 0:
+                sstatemirror_widget = self.gen_mirror_entry_widget(mirror[1], index)
+            else:
+                sstatemirror_widget = self.gen_mirror_entry_widget(mirror[1], index, mirror[2])
+            sub_vbox.pack_start(sstatemirror_widget, expand=False, fill=False, padding=9)
+            index += 1
+
+        table = gtk.Table(1, 1, False)
+        table.set_col_spacings(6)
+        add_mirror_button = HobAltButton("Add another mirror")
+        add_mirror_button.connect("clicked", self.add_mirror)
+        add_mirror_button.set_size_request(150,30)
+        table.attach(add_mirror_button, 1, 2, 0, 1, xoptions=gtk.SHRINK)
+        advanced_vbox.pack_start(table, expand=False, fill=False, padding=9)
+
+        return advanced_vbox
+
+    def refresh_shared_state_page(self):
+        page_num = self.nb.get_current_page()
+        self.nb.remove_page(page_num);
+        self.nb.insert_page(self.create_shared_state_page(), gtk.Label("Shared state"),page_num)
+        self.show_all()
+        self.nb.set_current_page(page_num)
+
+    def test_proxy_ended(self, passed):
+        self.proxy_test_running = False
+        self.set_test_proxy_state(self.TEST_NETWORK_PASSED if passed else self.TEST_NETWORK_FAILED)
+        self.set_sensitive(True)
+        self.refresh_proxy_components()
+
+    def timer_func(self):
+        self.test_proxy_progress.pulse()
+        return self.proxy_test_running
+
+    def test_network_button_cb(self, b):
+        self.set_test_proxy_state(self.TEST_NETWORK_RUNNING)
+        self.set_sensitive(False)
+        self.save_proxy_data()
+        if self.configuration.enable_proxy == True:
+            self.handler.set_http_proxy(self.configuration.combine_proxy("http"))
+            self.handler.set_https_proxy(self.configuration.combine_proxy("https"))
+            self.handler.set_ftp_proxy(self.configuration.combine_proxy("ftp"))
+            self.handler.set_git_proxy(self.configuration.combine_host_only("git"), self.configuration.combine_port_only("git"))
+            self.handler.set_cvs_proxy(self.configuration.combine_host_only("cvs"), self.configuration.combine_port_only("cvs"))
+        elif self.configuration.enable_proxy == False:
+            self.handler.set_http_proxy("")
+            self.handler.set_https_proxy("")
+            self.handler.set_ftp_proxy("")
+            self.handler.set_git_proxy("", "")
+            self.handler.set_cvs_proxy("", "")
+        self.proxy_test_ran = True
+        self.proxy_test_running = True
+        gobject.timeout_add(100, self.timer_func)
+        self.handler.trigger_network_test()
+
+    def test_proxy_focus_event(self, w, direction):
+        if self.test_proxy_state in [self.TEST_NETWORK_PASSED, self.TEST_NETWORK_FAILED]:
+            self.set_test_proxy_state(self.TEST_NETWORK_INITIAL)
+        return False
+
+    def http_proxy_changed(self, e):
+        if not self.configuration.same_proxy:
+            return
+        if e == self.http_proxy:
+            [w.set_text(self.http_proxy.get_text()) for w in self.same_proxy_addresses]
+        else:
+            [w.set_text(self.http_proxy_port.get_text()) for w in self.same_proxy_ports]
+
+    def proxy_address_focus_out_event(self, w, direction):
+        text = w.get_text()
+        if not text:
+            return False
+        if text.find("//") == -1:
+            w.set_text("http://" + text)
+        return False
+
+    def set_test_proxy_state(self, state):
+        if self.test_proxy_state == state:
+            return
+        [self.proxy_table.remove(w) for w in self.test_gui_elements]
+        if state == self.TEST_NETWORK_INITIAL:
+            self.proxy_table.attach(self.test_network_button, 1, 2, 5, 6)
+            self.test_network_button.show()
+        elif state == self.TEST_NETWORK_RUNNING:
+            self.test_proxy_progress.set_rcstyle("running")
+            self.test_proxy_progress.set_text("Testing network configuration")
+            self.proxy_table.attach(self.test_proxy_progress, 0, 5, 5, 6, xpadding=4)
+            self.test_proxy_progress.show()
+        else: # passed or failed
+            self.dummy_progress.update(1.0)
+            if state == self.TEST_NETWORK_PASSED:
+                self.dummy_progress.set_text("Your network is properly configured")
+                self.dummy_progress.set_rcstyle("running")
+            else:
+                self.dummy_progress.set_text("Network test failed")
+                self.dummy_progress.set_rcstyle("fail")
+            self.proxy_table.attach(self.dummy_progress, 0, 4, 5, 6)
+            self.proxy_table.attach(self.retest_network_button, 4, 5, 5, 6, xpadding=4)
+            self.dummy_progress.show()
+            self.retest_network_button.show()
+        self.test_proxy_state = state
+
+    def create_network_page(self):
+        advanced_vbox = gtk.VBox(False, 6)
+        advanced_vbox.set_border_width(6)
+        self.same_proxy_addresses = []
+        self.same_proxy_ports = []
+        self.all_proxy_ports = []
+        self.all_proxy_addresses = []
+
+        sub_vbox = gtk.VBox(False, 6)
+        advanced_vbox.pack_start(sub_vbox, expand=False, fill=False)
+        label = self.gen_label_widget("<span weight=\"bold\">Set the proxies used when fetching source code</span>")
+        tooltip = "Set the proxies used when fetching source code.  A blank field uses a direct internet connection."
+        info = HobInfoButton(tooltip, self)
+        hbox = gtk.HBox(False, 12)
+        hbox.pack_start(label, expand=True, fill=True)
+        hbox.pack_start(info, expand=False, fill=False)
+        sub_vbox.pack_start(hbox, expand=False, fill=False)
+
+        proxy_test_focus = []
+        self.direct_checkbox = gtk.RadioButton(None, "Direct network connection")
+        proxy_test_focus.append(self.direct_checkbox)
+        self.direct_checkbox.set_tooltip_text("Check this box to use a direct internet connection with no proxy")
+        self.direct_checkbox.set_active(not self.configuration.enable_proxy)
+        sub_vbox.pack_start(self.direct_checkbox, expand=False, fill=False)
+
+        self.proxy_checkbox = gtk.RadioButton(self.direct_checkbox, "Manual proxy configuration")
+        proxy_test_focus.append(self.proxy_checkbox)
+        self.proxy_checkbox.set_tooltip_text("Check this box to manually set up a specific proxy")
+        self.proxy_checkbox.set_active(self.configuration.enable_proxy)
+        sub_vbox.pack_start(self.proxy_checkbox, expand=False, fill=False)
+
+        self.same_checkbox = gtk.CheckButton("Use the HTTP proxy for all protocols")
+        proxy_test_focus.append(self.same_checkbox)
+        self.same_checkbox.set_tooltip_text("Check this box to use the HTTP proxy for all five proxies")
+        self.same_checkbox.set_active(self.configuration.same_proxy)
+        hbox = gtk.HBox(False, 12)
+        hbox.pack_start(self.same_checkbox, expand=False, fill=False, padding=24)
+        sub_vbox.pack_start(hbox, expand=False, fill=False)
+
+        self.proxy_table = gtk.Table(6, 5, False)
+        self.http_proxy, self.http_proxy_port, self.http_proxy_details = self.gen_proxy_entry_widget(
+            "http", self, True, 0)
+        proxy_test_focus +=[self.http_proxy, self.http_proxy_port]
+        self.http_proxy.connect("changed", self.http_proxy_changed)
+        self.http_proxy_port.connect("changed", self.http_proxy_changed)
+
+        self.https_proxy, self.https_proxy_port, self.https_proxy_details = self.gen_proxy_entry_widget(
+            "https", self, True, 1)
+        proxy_test_focus += [self.https_proxy, self.https_proxy_port]
+        self.same_proxy_addresses.append(self.https_proxy)
+        self.same_proxy_ports.append(self.https_proxy_port)
+
+        self.ftp_proxy, self.ftp_proxy_port, self.ftp_proxy_details = self.gen_proxy_entry_widget(
+            "ftp", self, True, 2)
+        proxy_test_focus += [self.ftp_proxy, self.ftp_proxy_port]
+        self.same_proxy_addresses.append(self.ftp_proxy)
+        self.same_proxy_ports.append(self.ftp_proxy_port)
+
+        self.git_proxy, self.git_proxy_port, self.git_proxy_details = self.gen_proxy_entry_widget(
+            "git", self, True, 3)
+        proxy_test_focus += [self.git_proxy, self.git_proxy_port]
+        self.same_proxy_addresses.append(self.git_proxy)
+        self.same_proxy_ports.append(self.git_proxy_port)
+
+        self.cvs_proxy, self.cvs_proxy_port, self.cvs_proxy_details = self.gen_proxy_entry_widget(
+            "cvs", self, True, 4)
+        proxy_test_focus += [self.cvs_proxy, self.cvs_proxy_port]
+        self.same_proxy_addresses.append(self.cvs_proxy)
+        self.same_proxy_ports.append(self.cvs_proxy_port)
+        self.all_proxy_ports = self.same_proxy_ports + [self.http_proxy_port]
+        self.all_proxy_addresses = self.same_proxy_addresses + [self.http_proxy]
+        sub_vbox.pack_start(self.proxy_table, expand=False, fill=False)
+        self.proxy_table.show_all()
+
+        # Create the graphical elements for the network test feature, but don't display them yet
+        self.test_network_button = HobAltButton("Test network configuration")
+        self.test_network_button.connect("clicked", self.test_network_button_cb)
+        self.test_proxy_progress = HobProgressBar()
+        self.dummy_progress = HobProgressBar()
+        self.retest_network_button = HobAltButton("Retest")
+        self.retest_network_button.connect("clicked", self.test_network_button_cb)
+        self.test_gui_elements = [self.test_network_button, self.test_proxy_progress, self.dummy_progress, self.retest_network_button]
+        # Initialize the network tester
+        self.test_proxy_state = self.TEST_NETWORK_NONE
+        self.set_test_proxy_state(self.TEST_NETWORK_INITIAL)
+        self.proxy_test_passed_id = self.handler.connect("network-passed", lambda h:self.test_proxy_ended(True))
+        self.proxy_test_failed_id = self.handler.connect("network-failed", lambda h:self.test_proxy_ended(False))
+        [w.connect("focus-in-event", self.test_proxy_focus_event) for w in proxy_test_focus]
+        [w.connect("focus-out-event", self.proxy_address_focus_out_event) for w in self.all_proxy_addresses]
+
+        self.direct_checkbox.connect("toggled", self.proxy_checkbox_toggled_cb)
+        self.proxy_checkbox.connect("toggled", self.proxy_checkbox_toggled_cb)
+        self.same_checkbox.connect("toggled", self.same_checkbox_toggled_cb)
+
+        self.refresh_proxy_components()
+        return advanced_vbox
+
+    def switch_to_page(self, page_id):
+        self.nb.set_current_page(page_id)
+
+    def details_cb(self, button, parent, protocol):
+        self.save_proxy_data()
+        dialog = ProxyDetailsDialog(title = protocol.upper() + " Proxy Details",
+            user = self.configuration.proxies[protocol][1],
+            passwd = self.configuration.proxies[protocol][2],
+            parent = parent,
+            flags = gtk.DIALOG_MODAL
+                    | gtk.DIALOG_DESTROY_WITH_PARENT
+                    | gtk.DIALOG_NO_SEPARATOR)
+        dialog.add_button(gtk.STOCK_CLOSE, gtk.RESPONSE_OK)
+        response = dialog.run()
+        if response == gtk.RESPONSE_OK:
+            self.configuration.proxies[protocol][1] = dialog.user
+            self.configuration.proxies[protocol][2] = dialog.passwd
+            self.refresh_proxy_components()
+        dialog.destroy()    
+
+    def rootfs_combo_changed_cb(self, rootfs_combo, all_package_format, check_hbox):
+        combo_item = self.rootfs_combo.get_active_text()
+        for child in check_hbox.get_children():
+            if isinstance(child, gtk.CheckButton):
+                check_hbox.remove(child)
+        for format in all_package_format:
+            if format != combo_item:
+                check_button = gtk.CheckButton(format)
+                check_hbox.pack_start(check_button, expand=False, fill=False)
+        check_hbox.show_all()
+
+    def gen_pkgfmt_widget(self, curr_package_format, all_package_format, tooltip_combo="", tooltip_extra=""):
+        pkgfmt_hbox = gtk.HBox(False, 24)
+
+        rootfs_vbox = gtk.VBox(False, 6)
+        pkgfmt_hbox.pack_start(rootfs_vbox, expand=False, fill=False)
+
+        label = self.gen_label_widget("Root file system package format")
+        rootfs_vbox.pack_start(label, expand=False, fill=False)
+
+        rootfs_format = ""
+        if curr_package_format:
+            rootfs_format = curr_package_format.split()[0]
+
+        rootfs_format_widget, rootfs_combo = self.gen_combo_widget(rootfs_format, all_package_format, tooltip_combo)
+        rootfs_vbox.pack_start(rootfs_format_widget, expand=False, fill=False)
+
+        extra_vbox = gtk.VBox(False, 6)
+        pkgfmt_hbox.pack_start(extra_vbox, expand=False, fill=False)
+
+        label = self.gen_label_widget("Additional package formats")
+        extra_vbox.pack_start(label, expand=False, fill=False)
+
+        check_hbox = gtk.HBox(False, 12)
+        extra_vbox.pack_start(check_hbox, expand=False, fill=False)
+        for format in all_package_format:
+            if format != rootfs_format:
+                check_button = gtk.CheckButton(format)
+                is_active = (format in curr_package_format.split())
+                check_button.set_active(is_active)
+                check_hbox.pack_start(check_button, expand=False, fill=False)
+
+        info = HobInfoButton(tooltip_extra, self)
+        check_hbox.pack_end(info, expand=False, fill=False)
+
+        rootfs_combo.connect("changed", self.rootfs_combo_changed_cb, all_package_format, check_hbox)
+
+        pkgfmt_hbox.show_all()
+
+        return pkgfmt_hbox, rootfs_combo, check_hbox
+
+    def editable_settings_cell_edited(self, cell, path_string, new_text, model):
+        it = model.get_iter_from_string(path_string)
+        column = cell.get_data("column")
+        model.set(it, column, new_text)
+
+    def editable_settings_add_item_clicked(self, button, model):
+        new_item = ["##KEY##", "##VALUE##"]
+
+        iter = model.append()
+        model.set (iter,
+            0, new_item[0],
+            1, new_item[1],
+       )
+
+    def editable_settings_remove_item_clicked(self, button, treeview):
+        selection = treeview.get_selection()
+        model, iter = selection.get_selected()
+
+        if iter:
+            path = model.get_path(iter)[0]
+            model.remove(iter)
+ 
+    def gen_editable_settings(self, setting, tooltip=""):
+        setting_hbox = gtk.HBox(False, 12)
+
+        vbox = gtk.VBox(False, 12)
+        setting_hbox.pack_start(vbox, expand=True, fill=True)
+
+        setting_store = gtk.ListStore(gobject.TYPE_STRING, gobject.TYPE_STRING)
+        for key in setting.keys():
+            setting_store.set(setting_store.append(), 0, key, 1, setting[key])
+
+        setting_tree = gtk.TreeView(setting_store)
+        setting_tree.set_headers_visible(True)
+        setting_tree.set_size_request(300, 100)
+
+        col = gtk.TreeViewColumn('Key')
+        col.set_min_width(100)
+        col.set_max_width(150)
+        col.set_resizable(True)
+        col1 = gtk.TreeViewColumn('Value')
+        col1.set_min_width(100)
+        col1.set_max_width(150)
+        col1.set_resizable(True)
+        setting_tree.append_column(col)
+        setting_tree.append_column(col1)
+        cell = gtk.CellRendererText()
+        cell.set_property('width-chars', 10)
+        cell.set_property('editable', True)
+        cell.set_data("column", 0)
+        cell.connect("edited", self.editable_settings_cell_edited, setting_store)
+        cell1 = gtk.CellRendererText()
+        cell1.set_property('width-chars', 10)
+        cell1.set_property('editable', True)
+        cell1.set_data("column", 1)
+        cell1.connect("edited", self.editable_settings_cell_edited, setting_store)
+        col.pack_start(cell, True)
+        col1.pack_end(cell1, True)
+        col.set_attributes(cell, text=0)
+        col1.set_attributes(cell1, text=1)
+
+        scroll = gtk.ScrolledWindow()
+        scroll.set_shadow_type(gtk.SHADOW_IN)
+        scroll.set_policy(gtk.POLICY_AUTOMATIC, gtk.POLICY_AUTOMATIC)
+        scroll.add(setting_tree)
+        vbox.pack_start(scroll, expand=True, fill=True)
+
+        # some buttons
+        hbox = gtk.HBox(True, 6)
+        vbox.pack_start(hbox, False, False)
+
+        button = gtk.Button(stock=gtk.STOCK_ADD)
+        button.connect("clicked", self.editable_settings_add_item_clicked, setting_store)
+        hbox.pack_start(button)
+
+        button = gtk.Button(stock=gtk.STOCK_REMOVE)
+        button.connect("clicked", self.editable_settings_remove_item_clicked, setting_tree)
+        hbox.pack_start(button)
+
+        info = HobInfoButton(tooltip, self)
+        setting_hbox.pack_start(info, expand=False, fill=False)
+
+        return setting_hbox, setting_store
+
+    def create_others_page(self):
+        advanced_vbox = gtk.VBox(False, 6)
+        advanced_vbox.set_border_width(6)
+
+        sub_vbox = gtk.VBox(False, 6)
+        advanced_vbox.pack_start(sub_vbox, expand=True, fill=True)
+        label = self.gen_label_widget("<span weight=\"bold\">Add your own variables:</span>")
+        tooltip = "These are key/value pairs for your extra settings. Click \'Add\' and then directly edit the key and the value"
+        setting_widget, self.setting_store = self.gen_editable_settings(self.configuration.extra_setting, tooltip)
+        sub_vbox.pack_start(label, expand=False, fill=False)
+        sub_vbox.pack_start(setting_widget, expand=True, fill=True)
+
+        return advanced_vbox
+
+    def create_visual_elements(self):
+        self.nb = gtk.Notebook()
+        self.nb.set_show_tabs(True)        
+        self.nb.append_page(self.create_build_environment_page(), gtk.Label("Build environment"))
+        self.nb.append_page(self.create_shared_state_page(), gtk.Label("Shared state"))
+        self.nb.append_page(self.create_network_page(), gtk.Label("Network"))        
+        self.nb.append_page(self.create_others_page(), gtk.Label("Others"))
+        self.nb.set_current_page(0)
+        self.vbox.pack_start(self.nb, expand=True, fill=True)
+        self.vbox.pack_end(gtk.HSeparator(), expand=True, fill=True)
+
+        self.show_all()
+
+    def destroy(self):
+        self.handler.disconnect(self.proxy_test_passed_id)
+        self.handler.disconnect(self.proxy_test_failed_id)
+        super(SimpleSettingsDialog, self).destroy()
+
+    def scroll_changed(self, widget, event, data=None):
+        adj = widget.get_vadjustment()
+        adj.set_value(adj.upper - adj.page_size)

bitbake/lib/bb/ui/crumbs/hobcolor.py

@@ -30,6 +30,7 @@ class HobColors:
     BLACK        = "#000000"
     PALE_BLUE    = "#53b8ff"
     DEEP_RED     = "#aa3e3e"
+    KHAKI        = "#fff68f"
 
     OK = WHITE
     RUNNING = PALE_GREEN

bitbake/lib/bb/ui/crumbs/hobeventhandler.py

@@ -41,6 +41,9 @@ class HobHandler(gobject.GObject):
          "command-failed"          : (gobject.SIGNAL_RUN_LAST,
                                       gobject.TYPE_NONE,
                                      (gobject.TYPE_STRING,)),
+         "parsing-warning"         : (gobject.SIGNAL_RUN_LAST,
+                                      gobject.TYPE_NONE,
+                                     (gobject.TYPE_STRING,)),
          "sanity-failed"           : (gobject.SIGNAL_RUN_LAST,
                                       gobject.TYPE_NONE,
                                      (gobject.TYPE_STRING, gobject.TYPE_INT)),
@@ -65,10 +68,17 @@ class HobHandler(gobject.GObject):
          "package-populated"       : (gobject.SIGNAL_RUN_LAST,
                                       gobject.TYPE_NONE,
                                      ()),
+         "network-passed"          : (gobject.SIGNAL_RUN_LAST,
+                                      gobject.TYPE_NONE,
+                                     ()),
+         "network-failed"          : (gobject.SIGNAL_RUN_LAST,
+                                      gobject.TYPE_NONE,
+                                     ()),
     }
 
-    (GENERATE_CONFIGURATION, GENERATE_RECIPES, GENERATE_PACKAGES, GENERATE_IMAGE, POPULATE_PACKAGEINFO, SANITY_CHECK) = range(6)
-    (SUB_PATH_LAYERS, SUB_FILES_DISTRO, SUB_FILES_MACH, SUB_FILES_SDKMACH, SUB_MATCH_CLASS, SUB_PARSE_CONFIG, SUB_SANITY_CHECK, SUB_GNERATE_TGTS, SUB_GENERATE_PKGINFO, SUB_BUILD_RECIPES, SUB_BUILD_IMAGE) = range(11)
+    (GENERATE_CONFIGURATION, GENERATE_RECIPES, GENERATE_PACKAGES, GENERATE_IMAGE, POPULATE_PACKAGEINFO, SANITY_CHECK, NETWORK_TEST) = range(7)
+    (SUB_PATH_LAYERS, SUB_FILES_DISTRO, SUB_FILES_MACH, SUB_FILES_SDKMACH, SUB_MATCH_CLASS, SUB_PARSE_CONFIG, SUB_SANITY_CHECK,
+     SUB_GNERATE_TGTS, SUB_GENERATE_PKGINFO, SUB_BUILD_RECIPES, SUB_BUILD_IMAGE, SUB_NETWORK_TEST) = range(12)
 
     def __init__(self, server, recipe_model, package_model):
         super(HobHandler, self).__init__()
@@ -88,6 +98,7 @@ class HobHandler(gobject.GObject):
         self.server = server
         self.error_msg = ""
         self.initcmd = None
+        self.parsing = False
 
     def set_busy(self):
         if not self.generating:
@@ -101,7 +112,10 @@ class HobHandler(gobject.GObject):
 
     def runCommand(self, commandline):
         try:
-            return self.server.runCommand(commandline)
+            result, error = self.server.runCommand(commandline)
+            if error:
+                raise Exception("Error running command '%s': %s" % (commandline, error))
+            return result
         except Exception as e:
             self.commands_async = []
             self.clear_busy()
@@ -139,6 +153,8 @@ class HobHandler(gobject.GObject):
             self.runCommand(["triggerEvent", "bb.event.RequestPackageInfo()"])
         elif next_command == self.SUB_SANITY_CHECK:
             self.runCommand(["triggerEvent", "bb.event.SanityCheck()"])
+        elif next_command == self.SUB_NETWORK_TEST:
+            self.runCommand(["triggerEvent", "bb.event.NetworkTest()"])
         elif next_command == self.SUB_BUILD_RECIPES:
             self.clear_busy()
             self.building = True
@@ -154,6 +170,14 @@ class HobHandler(gobject.GObject):
             if self.toolchain_packages:
                 self.runCommand(["setVariable", "TOOLCHAIN_TARGET_TASK", " ".join(self.toolchain_packages)])
                 targets.append(self.toolchain)
+            if targets[0] == "hob-image":
+                hobImage = self.runCommand(["matchFile", "hob-image.bb"])
+                if self.base_image != "Create your own image":
+                    baseImage = self.runCommand(["matchFile", self.base_image + ".bb"])
+                    version = self.runCommand(["generateNewImage", hobImage, baseImage, self.package_queue])
+                    targets[0] += version
+                    self.recipe_model.set_custom_image_version(version)
+
             self.runCommand(["buildTargets", targets, self.default_task])
 
     def display_error(self):
@@ -187,6 +211,11 @@ class HobHandler(gobject.GObject):
                     formatter = bb.msg.BBLogFormatter()
                     msg = formatter.format(event)
                     self.error_msg += msg + '\n'
+                elif event.levelno >= logging.WARNING and self.parsing == True:
+                    formatter = bb.msg.BBLogFormatter()
+                    msg = formatter.format(event)
+                    warn_msg = msg + '\n'
+                    self.emit("parsing-warning", warn_msg)
 
         elif isinstance(event, bb.event.TargetsTreeGenerated):
             self.current_phase = "data generation"
@@ -227,8 +256,10 @@ class HobHandler(gobject.GObject):
             message["eventname"] = bb.event.getName(event)
             message["current"] = 0
             message["total"] = None
-            message["title"] = "Parsing recipes: "
+            message["title"] = "Parsing recipes"
             self.emit("parsing-started", message)
+            if isinstance(event, bb.event.ParseStarted):
+                self.parsing = True
         elif isinstance(event, (bb.event.ParseProgress,
                 bb.event.CacheLoadProgress,
                 bb.event.TreeDataPreparationProgress)):
@@ -236,7 +267,7 @@ class HobHandler(gobject.GObject):
             message["eventname"] = bb.event.getName(event)
             message["current"] = event.current
             message["total"] = event.total
-            message["title"] = "Parsing recipes: "
+            message["title"] = "Parsing recipes"
             self.emit("parsing", message)
         elif isinstance(event, (bb.event.ParseCompleted,
                 bb.event.CacheLoadCompleted,
@@ -245,8 +276,16 @@ class HobHandler(gobject.GObject):
             message["eventname"] = bb.event.getName(event)
             message["current"] = event.total
             message["total"] = event.total
-            message["title"] = "Parsing recipes: "
+            message["title"] = "Parsing recipes"
             self.emit("parsing-completed", message)
+            if isinstance(event, bb.event.ParseCompleted):
+                self.parsing = False
+        elif isinstance(event, bb.event.NetworkTestFailed):
+            self.emit("network-failed")
+            self.run_next_command()
+        elif isinstance(event, bb.event.NetworkTestPassed):
+            self.emit("network-passed")
+            self.run_next_command()
 
         if self.error_msg and not self.commands_async:
             self.display_error()
@@ -341,6 +380,10 @@ class HobHandler(gobject.GObject):
         self.commands_async.append(self.SUB_SANITY_CHECK)
         self.run_next_command(self.SANITY_CHECK)
 
+    def trigger_network_test(self):
+        self.commands_async.append(self.SUB_NETWORK_TEST)
+        self.run_next_command(self.NETWORK_TEST)
+
     def generate_configuration(self):
         self.commands_async.append(self.SUB_PARSE_CONFIG)
         self.commands_async.append(self.SUB_PATH_LAYERS)
@@ -364,8 +407,9 @@ class HobHandler(gobject.GObject):
         self.commands_async.append(self.SUB_BUILD_RECIPES)
         self.run_next_command(self.GENERATE_PACKAGES)
 
-    def generate_image(self, image, toolchain, image_packages=[], toolchain_packages=[], default_task="build"):
+    def generate_image(self, image, base_image, toolchain, image_packages=[], toolchain_packages=[], default_task="build"):
         self.image = image
+        self.base_image = base_image
         self.toolchain = toolchain
         self.package_queue = image_packages
         self.toolchain_packages = toolchain_packages
@@ -398,7 +442,7 @@ class HobHandler(gobject.GObject):
         self.build.reset()
 
     def get_logfile(self):
-        return self.server.runCommand(["getVariable", "BB_CONSOLELOG"])
+        return self.server.runCommand(["getVariable", "BB_CONSOLELOG"])[0]
 
     def _remove_redundant(self, string):
         ret = []
@@ -413,8 +457,11 @@ class HobHandler(gobject.GObject):
         params["core_base"] = self.runCommand(["getVariable", "COREBASE"]) or ""
         hob_layer = params["core_base"] + "/meta-hob"
         params["layer"] = self.runCommand(["getVariable", "BBLAYERS"]) or ""
+        params["layers_non_removable"] = self.runCommand(["getVariable", "BBLAYERS_NON_REMOVABLE"]) or ""
         if hob_layer not in params["layer"].split():
             params["layer"] += (" " + hob_layer)
+        if hob_layer not in params["layers_non_removable"].split():
+            params["layers_non_removable"] += (" " + hob_layer)
         params["dldir"] = self.runCommand(["getVariable", "DL_DIR"]) or ""
         params["machine"] = self.runCommand(["getVariable", "MACHINE"]) or ""
         params["distro"] = self.runCommand(["getVariable", "DISTRO"]) or "defaultsetup"

bitbake/lib/bb/ui/crumbs/hoblistmodel.py

@@ -42,7 +42,7 @@ class PackageListModel(gtk.TreeStore):
                                 ()),
     }
 
-    __toolchain_required_packages__ = ["task-core-standalone-sdk-target", "task-core-standalone-sdk-target-dbg"]
+    __toolchain_required_packages__ = ["packagegroup-core-standalone-sdk-target", "packagegroup-core-standalone-sdk-target-dbg"]
 
     def __init__(self):
 
@@ -766,3 +766,9 @@ class RecipeListModel(gtk.ListStore):
                           binb="User Selected",
                           image_contents=True)
         self.selection_change_notification()
+
+    def set_custom_image_version(self, version):
+        self.custom_image_version = version
+
+    def get_custom_image_version(self):
+        return self.custom_image_version

bitbake/lib/bb/ui/crumbs/hobwidget.py

@@ -155,9 +155,15 @@ class HobViewTable (gtk.VBox):
             bin = binb.split(', ')
             total_no = len(bin)
             if total_no > 1 and bin[0] == "User Selected":
-                present_binb = bin[1] + ' (+' + str(total_no) + ')'
+                if total_no > 2:
+                    present_binb = bin[1] + ' (+' + str(total_no - 1) + ')'
+                else:
+                    present_binb = bin[1]
             else:
-                present_binb = bin[0] + ' (+' + str(total_no) + ')'
+                if total_no > 1:
+                    present_binb = bin[0] + ' (+' + str(total_no - 1) + ')'
+                else:
+                    present_binb = bin[0]
             cell.set_property('text', present_binb)
         else:
             cell.set_property('text', "")
@@ -515,7 +521,8 @@ class HobNotebook(gtk.Notebook):
         for child in self.pages:
             if child.lbl.get_label() == title:
                 child.grab_focus()
-                self.set_current_page(self.page_num(child))
+                self.set_current_page(self.pages.index(child))
+                return
 
 class HobWarpCellRendererText(gtk.CellRendererText):
     def __init__(self, col_number):

bitbake/lib/bb/ui/crumbs/imageconfigurationpage.py

@@ -45,6 +45,8 @@ class ImageConfigurationPage (HobPage):
         # or by manual. If by manual, all user's recipe selection and package selection are
         # cleared.
         self.machine_combo_changed_by_manual = True
+        self.stopping = False
+        self.warning_shift = 0
         self.create_visual_elements()
 
     def create_visual_elements(self):
@@ -114,9 +116,10 @@ class ImageConfigurationPage (HobPage):
         self.show_all()
 
     def update_progress_bar(self, title, fraction, status=None):
-        self.progress_bar.update(fraction)
-        self.progress_bar.set_title(title)
-        self.progress_bar.set_rcstyle(status)
+        if self.stopping == False:
+            self.progress_bar.update(fraction)
+            self.progress_bar.set_text(title)
+            self.progress_bar.set_rcstyle(status)
 
     def show_info_populating(self):
         self._pack_components(pack_config_build_button = False)
@@ -139,6 +142,37 @@ class ImageConfigurationPage (HobPage):
         if self.builder.recipe_model.get_selected_image() == self.builder.recipe_model.__custom_image__:
             self.just_bake_button.hide()
 
+    def add_warnings_bar(self):
+        #create the warnings bar shown when recipes parsing generates warnings
+        color = HobColors.KHAKI
+        warnings_bar = gtk.EventBox()
+        warnings_bar.modify_bg(gtk.STATE_NORMAL, gtk.gdk.color_parse(color))
+        warnings_bar.set_flags(gtk.CAN_DEFAULT)
+        warnings_bar.grab_default()
+
+        build_stop_tab = gtk.Table(10, 20, True)
+        warnings_bar.add(build_stop_tab)
+
+        icon = gtk.Image()
+        icon_pix_buffer = gtk.gdk.pixbuf_new_from_file(hic.ICON_INDI_ALERT_FILE)
+        icon.set_from_pixbuf(icon_pix_buffer)
+        build_stop_tab.attach(icon, 0, 2, 0, 10)
+
+        label = gtk.Label()
+        label.set_alignment(0.0, 0.5)
+        warnings_nb = len(self.builder.parsing_warnings)
+        if warnings_nb == 1:
+            label.set_markup("<span size='x-large'><b>1 recipe parsing warning</b></span>")
+        else:
+            label.set_markup("<span size='x-large'><b>%s recipe parsing warnings</b></span>" % warnings_nb)
+        build_stop_tab.attach(label, 2, 12, 0, 10)
+
+        view_warnings_button = HobButton("View warnings")
+        view_warnings_button.connect('clicked', self.view_warnings_button_clicked_cb)
+        build_stop_tab.attach(view_warnings_button, 15, 19, 1, 9)
+
+        return warnings_bar
+
     def create_config_machine(self):
         self.machine_title = gtk.Label()
         self.machine_title.set_alignment(0.0, 0.5)
@@ -185,6 +219,12 @@ class ImageConfigurationPage (HobPage):
             #self.gtable.attach(self.progress_box, 0, 40, 15, 18)
             self.gtable.attach(self.progress_bar, 0, 37, 15, 18)
             self.gtable.attach(self.stop_button, 37, 40, 15, 18, 0, 0)
+        if self.builder.parsing_warnings:
+            self.warnings_bar = self.add_warnings_bar()
+            self.gtable.attach(self.warnings_bar, 0, 40, 14, 18)
+            self.warning_shift = 4
+        else:
+            self.warning_shift = 0
         self.gtable.attach(self.machine_separator, 0, 40, 13, 14)
 
     def create_config_baseimg(self):
@@ -220,12 +260,12 @@ class ImageConfigurationPage (HobPage):
         self.image_separator = gtk.HSeparator()
 
     def set_config_baseimg_layout(self):
-        self.gtable.attach(self.image_title, 0, 40, 15, 17)
-        self.gtable.attach(self.image_title_desc, 0, 40, 18, 22)
-        self.gtable.attach(self.image_combo, 0, 12, 23, 26)
-        self.gtable.attach(self.image_desc, 0, 12, 27, 33)
-        self.gtable.attach(self.view_adv_configuration_button, 14, 36, 23, 28)
-        self.gtable.attach(self.image_separator, 0, 40, 35, 36)
+        self.gtable.attach(self.image_title, 0, 40, 15+self.warning_shift, 17+self.warning_shift)
+        self.gtable.attach(self.image_title_desc, 0, 40, 18+self.warning_shift, 22+self.warning_shift)
+        self.gtable.attach(self.image_combo, 0, 12, 23+self.warning_shift, 26+self.warning_shift)
+        self.gtable.attach(self.image_desc, 0, 12, 27+self.warning_shift, 33+self.warning_shift)
+        self.gtable.attach(self.view_adv_configuration_button, 14, 36, 23+self.warning_shift, 28+self.warning_shift)
+        self.gtable.attach(self.image_separator, 0, 40, 35+self.warning_shift, 36+self.warning_shift)
 
     def create_config_build_button(self):
         # Create the "Build packages" and "Build image" buttons at the bottom
@@ -248,9 +288,16 @@ class ImageConfigurationPage (HobPage):
         return button_box
 
     def stop_button_clicked_cb(self, button):
+        self.stopping = True
+        self.progress_bar.set_text("Stopping recipe parsing")
+        self.progress_bar.set_rcstyle("stop")
         self.builder.cancel_parse_sync()
 
+    def view_warnings_button_clicked_cb(self, button):
+        self.builder.show_warning_dialog()
+
     def machine_combo_changed_cb(self, machine_combo):
+        self.stopping = False
         combo_item = machine_combo.get_active_text()
         if not combo_item or combo_item == self.__dummy_machine__:
             return
@@ -357,7 +404,7 @@ class ImageConfigurationPage (HobPage):
         image_model = recipe_model.tree_model(filter)
         image_model.set_sort_column_id(recipe_model.COL_NAME, gtk.SORT_ASCENDING)
         active = 0
-        cnt = 1
+        cnt = 0
 
         white_pattern = []
         if self.builder.parameters.image_white_pattern:
@@ -368,13 +415,17 @@ class ImageConfigurationPage (HobPage):
         if self.builder.parameters.image_black_pattern:
             for i in self.builder.parameters.image_black_pattern.split():
                 black_pattern.append(re.compile(i))
+        black_pattern.append(re.compile("hob-image"))
 
         it = image_model.get_iter_first()
         self._image_combo_disconnect_signal()
         model = self.image_combo.get_model()
         model.clear()
         # Set a indicator text to combo store when first open
-        self.image_combo.append_text(self.__dummy_image__)
+        if not selected_image:
+            self.image_combo.append_text(self.__dummy_image__)
+            cnt = cnt + 1
+
         # append and set active
         while it:
             path = image_model.get_path(it)
@@ -428,9 +479,11 @@ class ImageConfigurationPage (HobPage):
             self.builder.reparse_post_adv_settings()        
 
     def just_bake_button_clicked_cb(self, button):
+        self.builder.parsing_warnings = []
         self.builder.just_bake()
 
     def edit_image_button_clicked_cb(self, button):
+        self.builder.configuration.initial_selected_image = self.builder.configuration.selected_image
         self.builder.show_recipes()
 
     def template_button_clicked_cb(self, button):

bitbake/lib/bb/ui/crumbs/imagedetailspage.py

@@ -26,7 +26,8 @@ from bb.ui.crumbs.hobcolor import HobColors
 from bb.ui.crumbs.hobwidget import hic, HobViewTable, HobAltButton, HobButton
 from bb.ui.crumbs.hobpages import HobPage
 import subprocess
-from bb.ui.crumbs.hig import CrumbsDialog
+from bb.ui.crumbs.hig.crumbsdialog import CrumbsDialog
+
 #
 # ImageDetailsPage
 #
@@ -404,7 +405,8 @@ class ImageDetailsPage (HobPage):
 
     def open_log_clicked_cb(self, button, log_file):
         if log_file:
-            os.system("xdg-open /%s" % log_file)
+            log_file = "file:///" + log_file
+            gtk.show_uri(screen=button.get_screen(), uri=log_file, timestamp=0)
 
     def refresh_package_detail_box(self, image_size):
         self.package_detail.update_line_widgets("Total image size: ", image_size)

bitbake/lib/bb/ui/crumbs/packageselectionpage.py

@@ -52,7 +52,7 @@ class PackageSelectionPage (HobPage):
                        'col_max'  : 300,
                        'expand'   : 'True'
                       }, {
-                       'col_name' : 'Brought in by',
+                       'col_name' : 'Brought in by (+others)',
                        'col_id'   : PackageListModel.COL_BINB,
                        'col_style': 'binb',
                        'col_min'  : 100,
@@ -167,7 +167,8 @@ class PackageSelectionPage (HobPage):
 
     def open_log_clicked_cb(self, button, log_file):
         if log_file:
-            os.system("xdg-open /%s" % log_file)
+            log_file = "file:///" + log_file
+            gtk.show_uri(screen=button.get_screen(), uri=log_file, timestamp=0)
 
     def show_page(self, log_file):
         children = self.button_box.get_children() or []
@@ -184,6 +185,7 @@ class PackageSelectionPage (HobPage):
         self.show_all()
 
     def build_image_clicked_cb(self, button):
+        self.builder.parsing_warnings = []
         self.builder.build_image()
 
     def back_button_clicked_cb(self, button):
@@ -208,8 +210,8 @@ class PackageSelectionPage (HobPage):
         selected_packages_size_str = HobPage._size_to_string(selected_packages_size)
 
         image_overhead_factor = self.builder.configuration.image_overhead_factor
-        image_rootfs_size = self.builder.configuration.image_rootfs_size * 1024 # image_rootfs_size is KB
-        image_extra_size = self.builder.configuration.image_extra_size * 1024 # image_extra_size is KB
+        image_rootfs_size = self.builder.configuration.image_rootfs_size / 1024 # image_rootfs_size is KB
+        image_extra_size = self.builder.configuration.image_extra_size / 1024 # image_extra_size is KB
         base_size = image_overhead_factor * selected_packages_size
         image_total_size = max(base_size, image_rootfs_size) + image_extra_size
         if "zypper" in self.builder.configuration.selected_packages:

bitbake/lib/bb/ui/crumbs/progressbar.py

@@ -43,6 +43,11 @@ class HobProgressBar (gtk.ProgressBar):
         text += " %.0f%%" % self.percentage
         self.set_text(text)
 
+    def set_stop_title(self, text=None):
+	if not text:
+	    text = ""
+	self.set_text(text)
+
     def reset(self):
         self.set_fraction(0)
         self.set_text("")

bitbake/lib/bb/ui/crumbs/recipeselectionpage.py

@@ -52,7 +52,7 @@ class RecipeSelectionPage (HobPage):
                        'col_max'  : 300,
                        'expand'   : 'True'
                       }, {
-                       'col_name' : 'Brought in by',
+                       'col_name' : 'Brought in by (+others)',
                        'col_id'   : RecipeListModel.COL_BINB,
                        'col_style': 'binb',
                        'col_min'  : 100,
@@ -193,6 +193,9 @@ class RecipeSelectionPage (HobPage):
         self.builder.build_packages()
 
     def back_button_clicked_cb(self, button):
+        self.builder.recipe_model.set_selected_image(self.builder.configuration.initial_selected_image)
+        self.builder.image_configuration_page.update_image_combo(self.builder.recipe_model, self.builder.configuration.initial_selected_image)
+        self.builder.image_configuration_page.update_image_desc()
         self.builder.show_configuration()
 
     def refresh_selection(self):

bitbake/lib/bb/ui/crumbs/runningbuild.py

@@ -46,7 +46,7 @@ class RunningBuildModel (gtk.TreeStore):
         color = model.get(it, self.COL_COLOR)[0]
         if not color:
             return False
-        if color == HobColors.ERROR:
+        if color == HobColors.ERROR or color == HobColors.WARNING:
             return True
         return False
 
@@ -76,7 +76,7 @@ class RunningBuild (gobject.GObject):
           'build-complete'  :  (gobject.SIGNAL_RUN_LAST,
                                 gobject.TYPE_NONE,
                                ()),
-          'build-aborted'     :  (gobject.SIGNAL_RUN_LAST,
+          'build-aborted'   :  (gobject.SIGNAL_RUN_LAST,
                                 gobject.TYPE_NONE,
                                ()),
           'task-started'    :  (gobject.SIGNAL_RUN_LAST,
@@ -85,6 +85,12 @@ class RunningBuild (gobject.GObject):
           'log-error'       :  (gobject.SIGNAL_RUN_LAST,
                                 gobject.TYPE_NONE,
                                ()),
+          'log-warning'     :  (gobject.SIGNAL_RUN_LAST,
+                                gobject.TYPE_NONE,
+                               ()),
+          'disk-full'       :  (gobject.SIGNAL_RUN_LAST,
+                                gobject.TYPE_NONE,
+                               ()),
           'no-provider'     :  (gobject.SIGNAL_RUN_LAST,
                                 gobject.TYPE_NONE,
                                (gobject.TYPE_PYOBJECT,)),
@@ -148,6 +154,7 @@ class RunningBuild (gobject.GObject):
             elif event.levelno >= logging.WARNING:
                 icon = "dialog-warning"
                 color = HobColors.WARNING
+                self.emit("log-warning")
             else:
                 icon = None
                 color = HobColors.OK
@@ -286,6 +293,7 @@ class RunningBuild (gobject.GObject):
             # Emit the appropriate signal depending on the number of failures
             if self.buildaborted:
                 self.emit ("build-aborted")
+                self.buildaborted = False
             elif (failures >= 1):
                 self.emit ("build-failed")
             else:
@@ -300,6 +308,7 @@ class RunningBuild (gobject.GObject):
 
         elif isinstance(event, bb.event.DiskFull):
             self.buildaborted = True
+            self.emit("disk-full")
 
         elif isinstance(event, bb.command.CommandFailed):
             self.emit("log", "error", "Command execution failed: %s" % (event.error))

bitbake/lib/bb/ui/depexp.py

@@ -198,17 +198,23 @@ class gtkthread(threading.Thread):
 
 def main(server, eventHandler):
     try:
-        cmdline = server.runCommand(["getCmdLineAction"])
-        if cmdline and not cmdline['action']:
-            print(cmdline['msg'])
-            return
-        elif not cmdline or (cmdline['action'] and cmdline['action'][0] != "generateDotGraph"):
+        cmdline, error = server.runCommand(["getCmdLineAction"])
+        if error:
+            print("Error getting bitbake commandline: %s" % error)
+            return 1
+        elif not cmdline:
+            print("Nothing to do.  Use 'bitbake world' to build everything, or run 'bitbake --help' for usage information.")
+            return 1
+        elif not cmdline or cmdline[0] != "generateDotGraph":
             print("This UI is only compatible with the -g option")
-            return
-        ret = server.runCommand(["generateDepTreeEvent", cmdline['action'][1], cmdline['action'][2]])
-        if ret != True:
-            print("Couldn't run command! %s" % ret)
-            return
+            return 1
+        ret, error = server.runCommand(["generateDepTreeEvent", cmdline[1], cmdline[2]])
+        if error:
+            print("Error running command '%s': %s" % (cmdline, error))
+            return 1
+        elif ret != True:
+            print("Error running command '%s': returned %s" % (cmdline, ret))
+            return 1
     except xmlrpclib.Fault as x:
         print("XMLRPC Fault getting commandline:\n %s" % x)
         return
@@ -234,7 +240,9 @@ def main(server, eventHandler):
         try:
             event = eventHandler.waitEvent(0.25)
             if gtkthread.quit.isSet():
-                server.runCommand(["stateStop"])
+                _, error = server.runCommand(["stateStop"])
+                if error:
+                    print('Unable to cleanly stop: %s' % error)
                 break
 
             if event is None:
@@ -310,9 +318,13 @@ def main(server, eventHandler):
                 break
             if shutdown == 1:
                 print("\nSecond Keyboard Interrupt, stopping...\n")
-                server.runCommand(["stateStop"])
+                _, error = server.runCommand(["stateStop"])
+                if error:
+                    print('Unable to cleanly stop: %s' % error)
             if shutdown == 0:
                 print("\nKeyboard Interrupt, closing down...\n")
-                server.runCommand(["stateShutdown"])
+                _, error = server.runCommand(["stateShutdown"])
+                if error:
+                    print('Unable to cleanly shutdown: %s' % error)
             shutdown = shutdown + 1
             pass

bitbake/lib/bb/ui/goggle.py

@@ -80,16 +80,19 @@ def main (server, eventHandler):
     running_build.connect ("build-failed", running_build_failed_cb)
 
     try:
-        cmdline = server.runCommand(["getCmdLineAction"])
-        if not cmdline:
+        cmdline, error = server.runCommand(["getCmdLineAction"])
+        if err:
+            print("Error getting bitbake commandline: %s" % error)
+            return 1
+        elif not cmdline:
             print("Nothing to do.  Use 'bitbake world' to build everything, or run 'bitbake --help' for usage information.")
             return 1
-        elif not cmdline['action']:
-            print(cmdline['msg'])
+        ret, error = server.runCommand(cmdline)
+        if error:
+            print("Error running command '%s': %s" % (cmdline, error))
             return 1
-        ret = server.runCommand(cmdline['action'])
-        if ret != True:
-            print("Couldn't get default commandline! %s" % ret)
+        elif ret != True:
+            print("Error running command '%s': returned %s" % (cmdline, ret))
             return 1
     except xmlrpclib.Fault as x:
         print("XMLRPC Fault getting commandline:\n %s" % x)

bitbake/lib/bb/ui/hob.py

@@ -22,7 +22,7 @@
 
 import sys
 import os
-requirements = "FATAL: Gtk+, PyGtk and PyGobject are required to use Hob"
+requirements = "FATAL: Hob requires Gtk+ 2.20.0 or higher, PyGtk 2.21.0 or higher"
 try:
     import gobject
     import gtk

bitbake/lib/bb/ui/knotty.py

@@ -146,7 +146,7 @@ class TerminalFilter(object):
             import curses
         except ImportError:
             sys.exit("FATAL: The knotty ui could not load the required curses python module.")
-	
+
         import termios
         self.curses = curses
         self.termios = termios
@@ -157,6 +157,8 @@ class TerminalFilter(object):
             new[3] = new[3] & ~termios.ECHO
             termios.tcsetattr(fd, termios.TCSADRAIN, new)
             curses.setupterm()
+            if curses.tigetnum("colors") > 2:
+                format.enable_color()
             self.ed = curses.tigetstr("ed")
             if self.ed:
                 self.cuu = curses.tigetstr("cuu")
@@ -187,7 +189,7 @@ class TerminalFilter(object):
             return
         if self.footer_present:
             self.clearFooter()
-        if not self.helper.tasknumber_total or self.helper.tasknumber_current == self.helper.tasknumber_total:
+        if (not self.helper.tasknumber_total or self.helper.tasknumber_current == self.helper.tasknumber_total) and not len(activetasks):
             return
         tasks = []
         for t in runningpids:
@@ -217,9 +219,19 @@ class TerminalFilter(object):
 def main(server, eventHandler, tf = TerminalFilter):
 
     # Get values of variables which control our output
-    includelogs = server.runCommand(["getVariable", "BBINCLUDELOGS"])
-    loglines = server.runCommand(["getVariable", "BBINCLUDELOGS_LINES"])
-    consolelogfile = server.runCommand(["getVariable", "BB_CONSOLELOG"])
+    includelogs, error = server.runCommand(["getVariable", "BBINCLUDELOGS"])
+    if error:
+        logger.error("Unable to get the value of BBINCLUDELOGS variable: %s" % error)
+        return 1
+    loglines, error = server.runCommand(["getVariable", "BBINCLUDELOGS_LINES"])
+    if error:
+        logger.error("Unable to get the value of BBINCLUDELOGS_LINES variable: %s" % error)
+        return 1
+    consolelogfile, error = server.runCommand(["getVariable", "BB_CONSOLELOG"])
+    if error:
+        logger.error("Unable to get the value of BB_CONSOLELOG variable: %s" % error)
+        return 1
+
     if sys.stdin.isatty() and sys.stdout.isatty():
         log_exec_tty = True
     else:
@@ -228,31 +240,36 @@ def main(server, eventHandler, tf = TerminalFilter):
     helper = uihelper.BBUIHelper()
 
     console = logging.StreamHandler(sys.stdout)
-    format = bb.msg.BBLogFormatter("%(levelname)s: %(message)s")
+    format_str = "%(levelname)s: %(message)s"
+    format = bb.msg.BBLogFormatter(format_str)
     bb.msg.addDefaultlogFilter(console)
     console.setFormatter(format)
     logger.addHandler(console)
     if consolelogfile:
         bb.utils.mkdirhier(os.path.dirname(consolelogfile))
+        conlogformat = bb.msg.BBLogFormatter(format_str)
         consolelog = logging.FileHandler(consolelogfile)
         bb.msg.addDefaultlogFilter(consolelog)
-        consolelog.setFormatter(format)
+        consolelog.setFormatter(conlogformat)
         logger.addHandler(consolelog)
 
     try:
-        cmdline = server.runCommand(["getCmdLineAction"])
-        if not cmdline:
+        cmdline, error = server.runCommand(["getCmdLineAction"])
+        if error:
+            logger.error("Unable to get bitbake commandline arguments: %s" % error)
+            return 1
+        elif not cmdline:
             print("Nothing to do.  Use 'bitbake world' to build everything, or run 'bitbake --help' for usage information.")
             return 1
-        elif not cmdline['action']:
-            print(cmdline['msg'])
+        ret, error = server.runCommand(cmdline)
+        if error:
+            logger.error("Command '%s' failed: %s" % (cmdline, error))
             return 1
-        ret = server.runCommand(cmdline['action'])
-        if ret != True:
-            print("Couldn't get default commandline! %s" % ret)
+        elif ret != True:
+            logger.error("Command '%s' failed: returned %s" % (cmdline, ret))
             return 1
     except xmlrpclib.Fault as x:
-        print("XMLRPC Fault getting commandline:\n %s" % x)
+        logger.error("XMLRPC Fault getting commandline:\n %s" % x)
         return 1
 
     parseprogress = None
@@ -312,7 +329,7 @@ def main(server, eventHandler, tf = TerminalFilter):
                 logfile = event.logfile
                 if logfile and os.path.exists(logfile):
                     termfilter.clearFooter()
-                    print("ERROR: Logfile of failure stored in: %s" % logfile)
+                    bb.error("Logfile of failure stored in: %s" % logfile)
                     if includelogs and not event.errprinted:
                         print("Log data follows:")
                         f = open(logfile, "r")
@@ -450,11 +467,15 @@ def main(server, eventHandler, tf = TerminalFilter):
             termfilter.clearFooter()
             if main.shutdown == 1:
                 print("\nSecond Keyboard Interrupt, stopping...\n")
-                server.runCommand(["stateStop"])
+                _, error = server.runCommand(["stateStop"])
+                if error:
+                    logger.error("Unable to cleanly stop: %s" % error)
             if main.shutdown == 0:
-                interrupted = True
                 print("\nKeyboard Interrupt, closing down...\n")
-                server.runCommand(["stateShutdown"])
+                interrupted = True
+                _, error = server.runCommand(["stateShutdown"])
+                if error:
+                    logger.error("Unable to cleanly shutdown: %s" % error)
             main.shutdown = main.shutdown + 1
             pass
 

bitbake/lib/bb/ui/ncurses.py

@@ -236,15 +236,18 @@ class NCursesUI:
         shutdown = 0
 
         try:
-            cmdline = server.runCommand(["getCmdLineAction"])
+            cmdline, error = server.runCommand(["getCmdLineAction"])
             if not cmdline:
                 print("Nothing to do.  Use 'bitbake world' to build everything, or run 'bitbake --help' for usage information.")
                 return
-            elif not cmdline['action']:
-                print(cmdline['msg'])
+            elif error:
+                print("Error getting bitbake commandline: %s" % error)
                 return
-            ret = server.runCommand(cmdline['action'])
-            if ret != True:
+            ret, error = server.runCommand(cmdline)
+            if error:
+                print("Error running command '%s': %s" % (cmdline, error))
+                return
+            elif ret != True:
                 print("Couldn't get default commandlind! %s" % ret)
                 return
         except xmlrpclib.Fault as x:
@@ -345,10 +348,14 @@ class NCursesUI:
                     exitflag = True
                 if shutdown == 1:
                     mw.appendText("Second Keyboard Interrupt, stopping...\n")
-                    server.runCommand(["stateStop"])
+                    _, error = server.runCommand(["stateStop"])
+                    if error:
+                        print("Unable to cleanly stop: %s" % error)
                 if shutdown == 0:
                     mw.appendText("Keyboard Interrupt, closing down...\n")
-                    server.runCommand(["stateShutdown"])
+                    _, error = server.runCommand(["stateShutdown"])
+                    if error:
+                        print("Unable to cleanly shutdown: %s" % error)
                 shutdown = shutdown + 1
                 pass
 

bitbake/lib/bb/ui/uievent.py

@@ -37,6 +37,17 @@ class BBUIEventQueue:
         self.BBServer = BBServer
         self.clientinfo = clientinfo
 
+        server = UIXMLRPCServer(self.clientinfo)
+        self.host, self.port = server.socket.getsockname()
+
+        server.register_function( self.system_quit, "event.quit" )
+        server.register_function( self.send_event, "event.sendpickle" )
+        server.socket.settimeout(1)
+
+        self.EventHandle = self.BBServer.registerEventHandler(self.host, self.port)
+
+        self.server = server
+
         self.t = threading.Thread()
         self.t.setDaemon(True)
         self.t.run = self.startCallbackHandler
@@ -73,19 +84,9 @@ class BBUIEventQueue:
 
     def startCallbackHandler(self):
 
-        server = UIXMLRPCServer(self.clientinfo)
-        self.host, self.port = server.socket.getsockname()
-
-        server.register_function( self.system_quit, "event.quit" )
-        server.register_function( self.send_event, "event.sendpickle" )
-        server.socket.settimeout(1)
-
-        self.EventHandle = self.BBServer.registerEventHandler(self.host, self.port)
-
-        self.server = server
-        while not server.quit:
-            server.handle_request()
-        server.server_close()
+        while not self.server.quit:
+            self.server.handle_request()
+        self.server.server_close()
 
     def system_quit( self ):
         """

bitbake/lib/bb/ui/uihelper.py

@@ -51,6 +51,7 @@ class BBUIHelper:
         if isinstance(event, bb.runqueue.runQueueTaskStarted) or isinstance(event, bb.runqueue.sceneQueueTaskStarted):
             self.tasknumber_current = event.stats.completed + event.stats.active + event.stats.failed + 1
             self.tasknumber_total = event.stats.total
+            self.needUpdate = True
 
     def getTasks(self):
         self.needUpdate = False

documentation/Makefile

@@ -1,72 +1,72 @@
 # This is a single Makefile to handle all generated Yocto Project documents.
 # The Makefile needs to live in the documents directory and all figures used
 # in any manuals must be .PNG files and live in the individual book's figures
-# directory as well as in the figures directory for the mega-manual.  
+# directory as well as in the figures directory for the mega-manual.
 # Note that the figures for the Yocto Project Development Manual
 # differ depending on the BRANCH being built.
 #
 # The Makefile has these targets:
 #
 #    pdf:      generates a PDF version of a manual.  Not valid for the Quick Start
-#              or the mega-manual (single, large HTML file comprised of all 
+#              or the mega-manual (single, large HTML file comprised of all
 #              Yocto Project manuals).
 #    html:     generates an HTML version of a manual.
 #    tarball:  creates a tarball for the doc files.
-#    validate: validates 
+#    validate: validates
 #    publish:  pushes generated files to the Yocto Project website
 #    clean:    removes files
 #
 # The Makefile generates an HTML and PDF version of every document except the
 # Yocto Project Quick Start and the single, HTML mega-manual, which is comprised
-# of all the individual Yocto Project manuals.  These two manuals are in HTML 
-# form only.  The variable DOC indicates the folder name for a given manual. The 
-# variable VER represents the distro version of the Yocto Release for which the 
-# manuals are being generated.  The variable BRANCH is used to indicate the 
-# branch (edison or denzil) and is used only when DOC=dev-manual or 
-# DOC=mega-manual.  If you do not specify a BRANCH, the default branch used 
-# will be for the latest Yocto Project release.  
+# of all the individual Yocto Project manuals.  These two manuals are in HTML
+# form only.  The variable DOC indicates the folder name for a given manual. The
+# variable VER represents the distro version of the Yocto Release for which the
+# manuals are being generated.  The variable BRANCH is used to indicate the
+# branch (edison or denzil) and is used only when DOC=dev-manual or
+# DOC=mega-manual.  If you do not specify a BRANCH, the default branch used
+# will be for the latest Yocto Project release.  If you build for either
+# edison or denzil, you must use BRANCH. You do not need to use BRANCH for
+# any release beyond denzil.
 #
-# To build a manual, you must invoke Makefile with the DOC argument.  If you 
-# are going to publish the manual, then you must invoke Makefile with both the 
-# DOC and the VER argument.  If you are building a particular version of the 
-# Yocto Project Development Manual or you are building any version of the 
-# mega-manual, you must use the DOC and BRANCH arguments.  
+# To build a manual, you must invoke Makefile with the DOC argument.  If you
+# are going to publish the manual, then you must invoke Makefile with both the
+# DOC and the VER argument.  Furthermore, if you are building or publishing
+# the edison or denzil versions of the Yocto Poject Development Manual or
+# the mega-manual, you must also use the BRANCH argument.
 #
 # Examples:
 #
 #     make DOC=bsp-guide
 #     make DOC=yocto-project-qs
-#     make pdf DOC=poky-ref-manual
+#     make pdf DOC=ref-manual
 #     make DOC=dev-manual BRANCH=edison
 #     make DOC=mega-manual BRANCH=denzil
 #
 # The first example generates the HTML and PDF versions of the BSP Guide.
-# The second example generates the HTML version only of the Quick Start.  Note that 
-# the Quick Start only has an HTML version available.  The third example generates 
-# both the PDF and HTML versions of the Yocto Project Reference Manual. The 
-# fourth example generates both the PDF and HTML 'edison' versions of the YP 
-# Development Manual.  The last exmample generates the HTML version of the 
-# mega-manual and uses the 'denzil' branch when choosing figures for the 
-# tarball of figures.
+# The second example generates the HTML version only of the Quick Start.  Note that
+# the Quick Start only has an HTML version available.  The third example generates
+# both the PDF and HTML versions of the Yocto Project Reference Manual. The
+# fourth example generates both the PDF and HTML 'edison' versions of the YP
+# Development Manual.  The last exmample generates the HTML version of the
+# mega-manual and uses the 'denzil' branch when choosing figures for the
+# tarball of figures.  Any example that does not use the BRANCH argument
+# builds the current version of the manual set.
 #
-# Use the publish target to push the generated manuals to the Yocto Project 
-# website.  All files needed for the manual's HTML form are pushed as well as the 
-# PDF version (if applicable).  
+# Use the publish target to push the generated manuals to the Yocto Project
+# website.  All files needed for the manual's HTML form are pushed as well as the
+# PDF version (if applicable).
 # Examples:
 #
 #    make publish DOC=bsp-guide VER=1.3
 #    make publish DOC=adt-manual VER=1.3
 #    make publish DOC=dev-manual VER=1.1.1 BRANCH=edison
-#    make publish DOC=dev-manual VER=1.2 
-#    make publish DOC=mega-manual VER=1.3 BRANCH=denzil
+#    make publish DOC=dev-manual VER=1.2 BRANCH=denzil
 #
-# The first example publishes the 1.2 version of both the PDF and HTML versions of 
-# the BSP Guide.  The second example publishes the 1.2 version of both the PDF and 
+# The first example publishes the 1.3 version of both the PDF and HTML versions of
+# the BSP Guide.  The second example publishes the 1.3 version of both the PDF and
 # HTML versions of the ADT Manual. The third example publishes the PDF and HTML
 # 'edison' versions of the YP Development Manual.  The fourth example publishes
-# the PDF and HTML 'master' versions of the YP Development Manual.  The last
-# example publishes the 1.3 version of the mega-manual (HTML-only) and the 
-# version generated and published is based on the 'denzil' branch.
+# the PDF and HTML 'denzil' versions of the YP Development Manual.
 #
 
 ifeq ($(DOC),bsp-guide)
@@ -92,7 +92,7 @@ XSLTOPTS = --stringparam html.stylesheet dev-style.css \
 ALLPREQ = html pdf tarball
 #
 # Note that the tarfile might produce the "Cannot stat: No such file or directory" error
-# message for .PNG files that are not present when building a particular branch.  The 
+# message for .PNG files that are not present when building a particular branch.  The
 # list of files is all-inclusive for all branches.  Note, if you don't provide a BRANCH
 # option, it defaults to the latest stuff.  This would be appropriate for "master" branch.
 #
@@ -119,11 +119,8 @@ TARFILES = dev-style.css dev-manual.html dev-manual.pdf \
 TARFILES = dev-style.css dev-manual.html dev-manual.pdf \
            figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \
            figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \
-           figures/kernel-example-repos-denzil.png \
-           figures/kernel-overview-1.png figures/kernel-overview-2.png \
-           figures/kernel-overview-3-denzil.png \
-           figures/source-repos.png figures/yp-download.png \
-           figures/wip.png
+           figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \
+           figures/source-repos.png figures/yp-download.png
 	endif
 
 MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf
@@ -179,16 +176,13 @@ TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png figures
         else
 TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png figures/building-an-image.png  \
 	figures/using-a-pre-built-image.png \
-	figures/poky-title.png \
+	figures/poky-title.png figures/buildhistory.png figures/buildhistory-web.png \
 	figures/adt-title.png figures/bsp-title.png \
 	figures/kernel-title.png figures/kernel-architecture-overview.png \
 	figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \
 	figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \
-	figures/kernel-example-repos-denzil.png \
-	figures/kernel-overview-1.png figures/kernel-overview-2.png \
-	figures/kernel-overview-3-denzil.png \
-	figures/source-repos.png figures/yp-download.png \
-	figures/wip.png
+	figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \
+	figures/source-repos.png figures/yp-download.png figures/kernel-dev-title.png
 	endif
 
 MANUALS = $(DOC)/$(DOC).html
@@ -197,7 +191,7 @@ STYLESHEET = $(DOC)/*.css
 
 endif
 
-ifeq ($(DOC),poky-ref-manual)
+ifeq ($(DOC),ref-manual)
 XSLTOPTS = --stringparam html.stylesheet ref-style.css \
            --stringparam  chapter.autolabel 1 \
            --stringparam  appendix.autolabel A \
@@ -205,7 +199,8 @@ XSLTOPTS = --stringparam html.stylesheet ref-style.css \
            --stringparam  section.label.includes.component.label 1 \
            --xinclude
 ALLPREQ = html pdf tarball
-TARFILES = poky-ref-manual.html ref-style.css figures/poky-title.png
+TARFILES = ref-manual.html ref-style.css figures/poky-title.png \
+	figures/buildhistory.png figures/buildhistory-web.png
 MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf
 FIGURES = figures
 STYLESHEET = $(DOC)/*.css
@@ -240,6 +235,20 @@ FIGURES = figures
 STYLESHEET = $(DOC)/*.css
 endif
 
+ifeq ($(DOC),kernel-dev)
+XSLTOPTS = --stringparam html.stylesheet kernel-dev-style.css \
+           --stringparam  chapter.autolabel 1 \
+           --stringparam  appendix.autolabel A \
+           --stringparam  section.autolabel 1 \
+           --stringparam  section.label.includes.component.label 1 \
+           --xinclude
+ALLPREQ = html pdf tarball
+TARFILES = kernel-dev.html kernel-dev.pdf kernel-dev-style.css figures/kernel-dev-title.png
+MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf
+FIGURES = figures
+STYLESHEET = $(DOC)/*.css
+endif
+
 
 ##
 # These URI should be rewritten by your distribution's xml catalog to
@@ -264,10 +273,10 @@ else
 
 	cd $(DOC); ../tools/poky-docbook-to-pdf $(DOC).xml ../template; cd ..
 endif
-    
+
 html:
 ifeq ($(DOC),mega-manual)
-#       See http://www.sagehill.net/docbookxsl/HtmlOutput.html 
+#       See http://www.sagehill.net/docbookxsl/HtmlOutput.html
 	@echo " "
 	@echo "******** Building "$(DOC)
 	@echo " "
@@ -281,7 +290,7 @@ ifeq ($(DOC),mega-manual)
 	@echo " "
 	cd $(DOC); rm mega-manual.html; mv mega-output.html mega-manual.html; cd ..
 else
-#       See http://www.sagehill.net/docbookxsl/HtmlOutput.html 
+#       See http://www.sagehill.net/docbookxsl/HtmlOutput.html
 	@echo " "
 	@echo "******** Building "$(DOC)
 	@echo " "
@@ -314,4 +323,4 @@ publish:
 	fi
 
 clean:
-	rm -f $(MANUALS)
+	rm -rf $(MANUALS); rm $(DOC)/$(DOC).tgz;

documentation/adt-manual/adt-command.xml

@@ -6,22 +6,22 @@
 <title>Using the Command Line</title>
 
     <para>
-        Recall that earlier the manual discussed how to use an existing toolchain 
-        tarball that had been installed into <filename>/opt/poky</filename>, 
-        which is outside of the build directory 
-        (see the section "<link linkend='using-an-existing-toolchain-tarball'>Using an Existing 
-        Toolchain Tarball)</link>".  
-        And, that sourcing your architecture-specific environment setup script 
-        initializes a suitable cross-toolchain development environment.  
-        During the setup, locations for the compiler, QEMU scripts, QEMU binary, 
-        a special version of <filename>pkgconfig</filename> and other useful 
+        Recall that earlier the manual discussed how to use an existing toolchain
+        tarball that had been installed into <filename>/opt/poky</filename>,
+        which is outside of the
+        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+        (see the section "<link linkend='using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball)</link>".
+        And, that sourcing your architecture-specific environment setup script
+        initializes a suitable cross-toolchain development environment.
+        During the setup, locations for the compiler, QEMU scripts, QEMU binary,
+        a special version of <filename>pkgconfig</filename> and other useful
         utilities are added to the <filename>PATH</filename> variable.
-        Variables to assist <filename>pkgconfig</filename> and <filename>autotools</filename> 
-        are also defined so that, 
-        for example, <filename>configure.sh</filename> can find pre-generated 
-        test results for tests that need target hardware on which to run.  
-        These conditions allow you to easily use the toolchain outside of the 
-        OpenEmbedded build environment on both autotools-based projects and 
+        Variables to assist <filename>pkgconfig</filename> and <filename>autotools</filename>
+        are also defined so that,
+        for example, <filename>configure.sh</filename> can find pre-generated
+        test results for tests that need target hardware on which to run.
+        These conditions allow you to easily use the toolchain outside of the
+        OpenEmbedded build environment on both autotools-based projects and
         Makefile-based projects.
     </para>
 
@@ -29,47 +29,175 @@
 <title>Autotools-Based Projects</title>
 
     <para>
-        For an Autotools-based project, you can use the cross-toolchain by just 
-        passing the appropriate host option to <filename>configure.sh</filename>.
-        The host option you use is derived from the name of the environment setup 
-        script in <filename>/opt/poky</filename> resulting from installation of the 
-        cross-toolchain tarball.
-        For example, the host option for an ARM-based target that uses the GNU EABI 
-        is <filename>armv5te-poky-linux-gnueabi</filename>.
-        Note that the name of the script is 
-        <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
-        Thus, the following command works:
-        <literallayout class='monospaced'>
-     $ configure --host=armv5te-poky-linux-gnueabi \
+        Once you have a suitable cross-toolchain installed, it is very easy to
+        develop a project outside of the OpenEmbedded build system.
+        This section presents a simple "Helloworld" example that shows how
+        to set up, compile, and run the project.
+    </para>
+
+    <section id='creating-and-running-a-project-based-on-gnu-autotools'>
+        <title>Creating and Running a Project Based on GNU Autotools</title>
+
+        <para>
+            Follow these steps to create a simple autotools-based project:
+            <orderedlist>
+                <listitem><para><emphasis>Create your directory:</emphasis>
+                    Create a clean directory for your project and then make
+                    that directory your working location:
+                    <literallayout class='monospaced'>
+     $ mkdir $HOME/helloworld
+     $ cd $HOME/helloworld
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Populate the directory:</emphasis>
+                    Create <filename>hello.c</filename>, <filename>Makefile.am</filename>,
+                    and <filename>configure.in</filename> files as follows:
+                    <itemizedlist>
+                        <listitem><para>For <filename>hello.c</filename>, include
+                            these lines:
+                            <literallayout class='monospaced'>
+     #include &lt;stdio.h&gt;
+
+     main()
+        {
+           printf("Hello World!\n");
+        }
+                            </literallayout></para></listitem>
+                        <listitem><para>For <filename>Makefile.am</filename>,
+                            include these lines:
+                            <literallayout class='monospaced'>
+     bin_PROGRAMS = hello
+     hello_SOURCES = hello.c
+                            </literallayout></para></listitem>
+                        <listitem><para>For <filename>configure.in</filename>,
+                            include these lines:
+                            <literallayout class='monospaced'>
+     AC_INIT(hello.c)
+     AM_INIT_AUTOMAKE(hello,0.1)
+     AC_PROG_CC
+     AC_PROG_INSTALL
+     AC_OUTPUT(Makefile)
+                            </literallayout></para></listitem>
+                    </itemizedlist></para></listitem>
+                <listitem><para><emphasis>Source the cross-toolchain
+                    environment setup file:</emphasis>
+                    Installation of the cross-toolchain creates a cross-toolchain
+                    environment setup script in <filename>/opt/poky/&lt;release&gt;</filename>.
+                    Before you can use the tools to develop your project, you must
+                    source this setup script.
+                    The script begins with the string "environment-setup" and contains
+                    the machine architecture, which is followed by the string
+                    "poky-linux".
+                    Here is an example for an environment setup using the
+                    32-bit Intel x86 Architecture and using the
+                    &DISTRO_NAME; Yocto Project release:
+                    <literallayout class='monospaced'>
+     $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Generate the local <filename>aclocal.m4</filename>
+                    files and create the configure script:</emphasis>
+                    The following GNU Autotools generate the local
+                    <filename>aclocal.m4</filename> files and create the
+                    configure script:
+                    <literallayout class='monospaced'>
+     $ aclocal
+     $ autoconf
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Generate files needed by GNU
+                    coding standards:</emphasis>
+                    GNU coding standards require certain files in order for the
+                    project to be compliant.
+                    This command creates those files:
+                    <literallayout class='monospaced'>
+     $ touch NEWS README AUTHORS ChangeLog
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Generate the <filename>configure</filename>
+                    file:</emphasis>
+                    This command generates the <filename>configure</filename>:
+                    <literallayout class='monospaced'>
+     $ automake -a
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Cross-compile the project:</emphasis>
+                    This command compiles the project using the cross-compiler:
+                    <literallayout class='monospaced'>
+     $ ./configure ${CONFIGURE_FLAGS}
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Make and install the project:</emphasis>
+                    These two commands generate and install the project into the
+                    destination directory:
+                    <literallayout class='monospaced'>
+     $ make
+     $ make install DESTDIR=./tmp
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Verify the installation:</emphasis>
+                    This command is a simple way to verify the installation
+                    of your project.
+                    Running the command prints the architecture on which
+                    the binary file can run.
+                    This architecture should be the same architecture that
+                    the installed cross-toolchain supports.
+                    <literallayout class='monospaced'>
+     $ file ./tmp/usr/local/bin/hello
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Execute your project:</emphasis>
+                    To execute the project in the shell, simply enter the name.
+                    You could also copy the binary to the actual target hardware
+                    and run the project there as well:
+                    <literallayout class='monospaced'>
+     $ ./hello
+                    </literallayout>
+                    As expected, the project displays the "Hello World!" message.
+                    </para></listitem>
+            </orderedlist>
+        </para>
+    </section>
+
+    <section id='passing-host-options'>
+        <title>Passing Host Options</title>
+
+        <para>
+            For an Autotools-based project, you can use the cross-toolchain by just
+            passing the appropriate host option to <filename>configure.sh</filename>.
+            The host option you use is derived from the name of the environment setup
+            script in <filename>/opt/poky</filename> resulting from installation of the
+            cross-toolchain tarball.
+            For example, the host option for an ARM-based target that uses the GNU EABI
+            is <filename>armv5te-poky-linux-gnueabi</filename>.
+            You will notice that the name of the script is
+            <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
+            Thus, the following command works:
+            <literallayout class='monospaced'>
+     $ ./configure --host=armv5te-poky-linux-gnueabi \
         --with-libtool-sysroot=&lt;sysroot-dir&gt;
-        </literallayout>
-    </para>
-    <para>
-        This single command updates your project and rebuilds it using the appropriate 
-        cross-toolchain tools.
-    </para>
-    <note>
-        If <filename>configure</filename> script results in problems recognizing the 
-        <filename>--with-libtool-sysroot=&lt;sysroot-dir&gt;</filename> option, 
-        regenerate the script to enable the support by doing the following and then 
-        re-running the script:
-        <literallayout class='monospaced'>
+            </literallayout>
+        </para>
+
+        <para>
+            This single command updates your project and rebuilds it using the appropriate
+            cross-toolchain tools.
+            <note>
+                If <filename>configure</filename> script results in problems recognizing the
+                <filename>--with-libtool-sysroot=&lt;sysroot-dir&gt;</filename> option,
+                regenerate the script to enable the support by doing the following and then
+                re-running the script:
+                <literallayout class='monospaced'>
      $ libtoolize --automake
      $ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \
         [-I &lt;dir_containing_your_project-specific_m4_macros&gt;]
      $ autoconf
      $ autoheader
      $ automake -a
-        </literallayout>
-    </note>       
+                </literallayout>
+            </note>
+        </para>
+    </section>
 </section>
 
 <section id='makefile-based-projects'>
 <title>Makefile-Based Projects</title>
 
     <para>
-        For a Makefile-based project, you use the cross-toolchain by making sure 
-        the tools are used.  
+        For a Makefile-based project, you use the cross-toolchain by making sure
+        the tools are used.
         You can do this as follows:
         <literallayout class='monospaced'>
      CC=arm-poky-linux-gnueabi-gcc

documentation/adt-manual/adt-intro.xml

@@ -6,44 +6,44 @@
 <title>Introduction</title>
 
 <para>
-    Welcome to the Yocto Project Application Developer's Guide.  
-    This manual provides information that lets you begin developing applications 
+    Welcome to the Yocto Project Application Developer's Guide.
+    This manual provides information that lets you begin developing applications
     using the Yocto Project.
 </para>
 
 <para>
-    The Yocto Project provides an application development environment based on 
+    The Yocto Project provides an application development environment based on
     an Application Development Toolkit (ADT) and the availability of stand-alone
     cross-development toolchains and other tools.
     This manual describes the ADT and how you can configure and install it,
-    how to access and use the cross-development toolchains, how to 
+    how to access and use the cross-development toolchains, how to
     customize the development packages installation,
-    how to use command line development for both Autotools-based and Makefile-based projects, 
-    and an introduction to the Eclipse Yocto Plug-in. 
+    how to use command line development for both Autotools-based and Makefile-based projects,
+    and an introduction to the Eclipse Yocto Plug-in.
 </para>
 
 <section id='adt-intro-section'>
     <title>The Application Development Toolkit (ADT)</title>
 
     <para>
-        Part of the Yocto Project development solution is an Application Development 
+        Part of the Yocto Project development solution is an Application Development
         Toolkit (ADT).
-        The ADT provides you with a custom-built, cross-development 
+        The ADT provides you with a custom-built, cross-development
         platform suited for developing a user-targeted product application.
     </para>
 
     <para>
         Fundamentally, the ADT consists of the following:
         <itemizedlist>
-            <listitem><para>An architecture-specific cross-toolchain and matching 
+            <listitem><para>An architecture-specific cross-toolchain and matching
                 sysroot both built by the OpenEmbedded build system, which uses Poky.
-                The toolchain and sysroot are based on a metadata configuration and extensions, 
+                The toolchain and sysroot are based on a metadata configuration and extensions,
                 which allows you to cross-develop on the host machine for the target hardware.
                 </para></listitem>
             <listitem><para>The Eclipse IDE Yocto Plug-in.</para></listitem>
             <listitem><para>The Quick EMUlator (QEMU), which lets you simulate target hardware.
                 </para></listitem>
-            <listitem><para>Various user-space tools that greatly enhance your application 
+            <listitem><para>Various user-space tools that greatly enhance your application
                 development experience.</para></listitem>
         </itemizedlist>
     </para>
@@ -52,11 +52,13 @@
         <title>The Cross-Toolchain</title>
 
         <para>
-            The cross-toolchain consists of a cross-compiler, cross-linker, and cross-debugger 
+            The cross-toolchain consists of a cross-compiler, cross-linker, and cross-debugger
             that are used to develop user-space applications for targeted hardware.
             This toolchain is created either by running the ADT Installer script, a toolchain installer
-            script, or through a build directory that is based on your metadata 
-            configuration or extension for your targeted device.  
+            script, or through a
+            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> that
+            is based on your metadata
+            configuration or extension for your targeted device.
             The cross-toolchain works with a matching target sysroot.
         </para>
     </section>
@@ -65,10 +67,10 @@
         <title>Sysroot</title>
 
         <para>
-            The matching target sysroot contains needed headers and libraries for generating 
-            binaries that run on the target architecture.  
-            The sysroot is based on the target root filesystem image that is built by 
-            the OpenEmbedded build system Poky and uses the same metadata configuration 
+            The matching target sysroot contains needed headers and libraries for generating
+            binaries that run on the target architecture.
+            The sysroot is based on the target root filesystem image that is built by
+            the OpenEmbedded build system Poky and uses the same metadata configuration
             used to build the cross-toolchain.
         </para>
     </section>
@@ -77,24 +79,24 @@
         <title>Eclipse Yocto Plug-in</title>
 
         <para>
-            The Eclipse IDE is a popular development environment and it fully supports 
-            development using the Yocto Project.  
-            When you install and configure the Eclipse Yocto Project Plug-in into 
-            the Eclipse IDE, you maximize your Yocto Project experience.  
-            Installing and configuring the Plug-in results in an environment that 
-            has extensions specifically designed to let you more easily develop software.  
-            These extensions allow for cross-compilation, deployment, and execution of 
-            your output into a QEMU emulation session.  
-            You can also perform cross-debugging and profiling.  
-            The environment also supports a suite of tools that allows you to perform 
-            remote profiling, tracing, collection of power data, collection of 
+            The Eclipse IDE is a popular development environment and it fully supports
+            development using the Yocto Project.
+            When you install and configure the Eclipse Yocto Project Plug-in into
+            the Eclipse IDE, you maximize your Yocto Project experience.
+            Installing and configuring the Plug-in results in an environment that
+            has extensions specifically designed to let you more easily develop software.
+            These extensions allow for cross-compilation, deployment, and execution of
+            your output into a QEMU emulation session.
+            You can also perform cross-debugging and profiling.
+            The environment also supports a suite of tools that allows you to perform
+            remote profiling, tracing, collection of power data, collection of
             latency data, and collection of performance data.
         </para>
 
         <para>
             For information about the application development workflow that uses the Eclipse
             IDE and for a detailed example of how to install and configure the Eclipse
-            Yocto Project Plug-in, see the 
+            Yocto Project Plug-in, see the
             "<ulink url='&YOCTO_DOCS_DEV_URL;#adt-eclipse'>Working Within Eclipse</ulink>" section
             of the Yocto Project Development Manual.
         </para>
@@ -104,17 +106,19 @@
         <title>The QEMU Emulator</title>
 
         <para>
-            The QEMU emulator allows you to simulate your hardware while running your 
+            The QEMU emulator allows you to simulate your hardware while running your
             application or image.
             QEMU is made available a number of ways:
             <itemizedlist>
-                <listitem><para>If you use the ADT Installer script to install ADT, you can 
+                <listitem><para>If you use the ADT Installer script to install ADT, you can
                     specify whether or not to install QEMU.</para></listitem>
-                <listitem><para>If you have downloaded a Yocto Project release and unpacked 
-                    it to create a source directory and you have sourced  
-                    the environment setup script, QEMU is installed and automatically 
+                <listitem><para>If you have downloaded a Yocto Project release and unpacked
+                    it to create a
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> and
+                    you have sourced
+                    the environment setup script, QEMU is installed and automatically
                     available.</para></listitem>
-                <listitem><para>If you have installed the cross-toolchain 
+                <listitem><para>If you have installed the cross-toolchain
                     tarball and you have sourcing the toolchain's setup environment script, QEMU
                     is also installed and automatically available.</para></listitem>
             </itemizedlist>
@@ -125,38 +129,38 @@
         <title>User-Space Tools</title>
 
         <para>
-            User-space tools are included as part of the distribution.  
-            You will find these tools helpful during development.  
-            The tools include LatencyTOP, PowerTOP, OProfile, Perf, SystemTap, and Lttng-ust.  
+            User-space tools are included as part of the distribution.
+            You will find these tools helpful during development.
+            The tools include LatencyTOP, PowerTOP, OProfile, Perf, SystemTap, and Lttng-ust.
             These tools are common development tools for the Linux platform.
             <itemizedlist>
-                <listitem><para><emphasis>LatencyTOP:</emphasis> LatencyTOP focuses on latency 
+                <listitem><para><emphasis>LatencyTOP:</emphasis> LatencyTOP focuses on latency
                     that causes skips in audio,
-                    stutters in your desktop experience, or situations that overload your server 
-                    even when you have plenty of CPU power left.  
-                    You can find out more about LatencyTOP at 
+                    stutters in your desktop experience, or situations that overload your server
+                    even when you have plenty of CPU power left.
+                    You can find out more about LatencyTOP at
                     <ulink url='http://www.latencytop.org/'></ulink>.</para></listitem>
-                <listitem><para><emphasis>PowerTOP:</emphasis> Helps you determine what   
-                    software is using the most power.  
-                    You can find out more about PowerTOP at 
-                    <ulink url='http://www.linuxpowertop.org/'></ulink>.</para></listitem>
-                <listitem><para><emphasis>OProfile:</emphasis> A system-wide profiler for Linux 
-                    systems that is capable of profiling all running code at low overhead.  
-                    You can find out more about OProfile at 
+                <listitem><para><emphasis>PowerTOP:</emphasis> Helps you determine what
+                    software is using the most power.
+                    You can find out more about PowerTOP at
+                    <ulink url='https://01.org/powertop/'></ulink>.</para></listitem>
+                <listitem><para><emphasis>OProfile:</emphasis> A system-wide profiler for Linux
+                    systems that is capable of profiling all running code at low overhead.
+                    You can find out more about OProfile at
                     <ulink url='http://oprofile.sourceforge.net/about/'></ulink>.</para></listitem>
-                <listitem><para><emphasis>Perf:</emphasis> Performance counters for Linux used 
-                    to keep track of certain types of hardware and software events.  
-                    For more information on these types of counters see 
-                    <ulink url='https://perf.wiki.kernel.org/'></ulink> and click 
+                <listitem><para><emphasis>Perf:</emphasis> Performance counters for Linux used
+                    to keep track of certain types of hardware and software events.
+                    For more information on these types of counters see
+                    <ulink url='https://perf.wiki.kernel.org/'></ulink> and click
                     on “Perf tools.”</para></listitem>
-                <listitem><para><emphasis>SystemTap:</emphasis> A free software infrastructure 
-                    that simplifies information gathering about a running Linux system.  
-                    This information helps you diagnose performance or functional problems.  
-                    SystemTap is not available as a user-space tool through the Eclipse IDE Yocto Plug-in.  
-                    See <ulink url='http://sourceware.org/systemtap'></ulink> for more information 
+                <listitem><para><emphasis>SystemTap:</emphasis> A free software infrastructure
+                    that simplifies information gathering about a running Linux system.
+                    This information helps you diagnose performance or functional problems.
+                    SystemTap is not available as a user-space tool through the Eclipse IDE Yocto Plug-in.
+                    See <ulink url='http://sourceware.org/systemtap'></ulink> for more information
                     on SystemTap.</para></listitem>
-                <listitem><para><emphasis>Lttng-ust:</emphasis> A User-space Tracer designed to 
-                    provide detailed information on user-space activity.  
+                <listitem><para><emphasis>Lttng-ust:</emphasis> A User-space Tracer designed to
+                    provide detailed information on user-space activity.
                     See <ulink url='http://lttng.org/ust'></ulink> for more information on Lttng-ust.
                     </para></listitem>
             </itemizedlist>

documentation/adt-manual/adt-manual.xml

@@ -2,7 +2,7 @@
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
 [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
 
-<book id='adt-manual' lang='en' 
+<book id='adt-manual' lang='en'
       xmlns:xi="http://www.w3.org/2003/XInclude"
       xmlns="http://docbook.org/ns/docbook"
       >
@@ -10,10 +10,10 @@
 
         <mediaobject>
             <imageobject>
-                <imagedata fileref='figures/adt-title.png' 
-                    format='SVG' 
+                <imagedata fileref='figures/adt-title.png'
+                    format='SVG'
                     align='left' scalefit='1' width='100%'/>
-            </imageobject>    
+            </imageobject>
         </mediaobject>
 
         <title></title>
@@ -51,9 +51,14 @@
             </revision>
             <revision>
                 <revnumber>1.3</revnumber>
-                <date>Sometime in 2012</date>
+                <date>October 2012</date>
                 <revremark>Released with the Yocto Project 1.3 Release.</revremark>
             </revision>
+            <revision>
+                <revnumber>1.4</revnumber>
+                <date>Sometime in 2013</date>
+                <revremark>Released with the Yocto Project 1.4 Release.</revremark>
+            </revision>
         </revhistory>
 
     <copyright>
@@ -63,12 +68,12 @@
 
     <legalnotice>
       <para>
-        Permission is granted to copy, distribute and/or modify this document under 
+        Permission is granted to copy, distribute and/or modify this document under
         the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
       </para>
       <note>
           Due to production processes, there could be differences between the Yocto Project
-          documentation bundled in the release tarball and the 
+          documentation bundled in the release tarball and the
           <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink> on
           the <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website.
           For the latest version of this manual, see the manual on the website.
@@ -92,6 +97,6 @@
 -->
 
 </book>
-<!-- 
-vim: expandtab tw=80 ts=4 
+<!--
+vim: expandtab tw=80 ts=4
 -->

documentation/adt-manual/adt-package.xml

@@ -6,10 +6,10 @@
 <title>Optionally Customizing the Development Packages Installation</title>
 
     <para>
-        Because the Yocto Project is suited for embedded Linux development, it is 
-        likely that you will need to customize your development packages installation.  
-        For example, if you are developing a minimal image, then you might not need 
-        certain packages (e.g. graphics support packages).  
+        Because the Yocto Project is suited for embedded Linux development, it is
+        likely that you will need to customize your development packages installation.
+        For example, if you are developing a minimal image, then you might not need
+        certain packages (e.g. graphics support packages).
         Thus, you would like to be able to remove those packages from your target sysroot.
     </para>
 
@@ -17,24 +17,24 @@
     <title>Package Management Systems</title>
 
     <para>
-        The OpenEmbedded build system supports the generation of sysroot files using 
+        The OpenEmbedded build system supports the generation of sysroot files using
         three different Package Management Systems (PMS):
         <itemizedlist>
-            <listitem><para><emphasis>OPKG:</emphasis> A less well known PMS whose use 
-                originated in the OpenEmbedded and OpenWrt embedded Linux projects.  
+            <listitem><para><emphasis>OPKG:</emphasis> A less well known PMS whose use
+                originated in the OpenEmbedded and OpenWrt embedded Linux projects.
                 This PMS works with files packaged in an <filename>.ipk</filename> format.
-                See <ulink url='http://en.wikipedia.org/wiki/Opkg'></ulink> for more 
+                See <ulink url='http://en.wikipedia.org/wiki/Opkg'></ulink> for more
                 information about OPKG.</para></listitem>
-            <listitem><para><emphasis>RPM:</emphasis> A more widely known PMS intended for GNU/Linux 
-                distributions.  
+            <listitem><para><emphasis>RPM:</emphasis> A more widely known PMS intended for GNU/Linux
+                distributions.
                 This PMS works with files packaged in an <filename>.rms</filename> format.
-                The build system currently installs through this PMS by default.  
+                The build system currently installs through this PMS by default.
                 See <ulink url='http://en.wikipedia.org/wiki/RPM_Package_Manager'></ulink>
                 for more information about RPM.</para></listitem>
-            <listitem><para><emphasis>Debian:</emphasis> The PMS for Debian-based systems 
-                is built on many PMS tools.  
-                The lower-level PMS tool <filename>dpkg</filename> forms the base of the Debian PMS.  
-                For information on dpkg see 
+            <listitem><para><emphasis>Debian:</emphasis> The PMS for Debian-based systems
+                is built on many PMS tools.
+                The lower-level PMS tool <filename>dpkg</filename> forms the base of the Debian PMS.
+                For information on dpkg see
                 <ulink url='http://en.wikipedia.org/wiki/Dpkg'></ulink>.</para></listitem>
         </itemizedlist>
     </para>
@@ -44,13 +44,13 @@
     <title>Configuring the PMS</title>
 
     <para>
-        Whichever PMS you are using, you need to be sure that the 
+        Whichever PMS you are using, you need to be sure that the
         <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
         variable in the <filename>conf/local.conf</filename>
-        file is set to reflect that system.  
+        file is set to reflect that system.
         The first value you choose for the variable specifies the package file format for the root
         filesystem at sysroot.
-        Additional values specify additional formats for convenience or testing.  
+        Additional values specify additional formats for convenience or testing.
         See the configuration file for details.
     </para>
 
@@ -61,14 +61,14 @@
     </note>
 
     <para>
-        As an example, consider a scenario where you are using OPKG and you want to add 
+        As an example, consider a scenario where you are using OPKG and you want to add
         the <filename>libglade</filename> package to the target sysroot.
     </para>
 
     <para>
-        First, you should generate the <filename>ipk</filename> file for the 
-        <filename>libglade</filename> package and add it 
-        into a working <filename>opkg</filename> repository.  
+        First, you should generate the <filename>ipk</filename> file for the
+        <filename>libglade</filename> package and add it
+        into a working <filename>opkg</filename> repository.
         Use these commands:
         <literallayout class='monospaced'>
      $ bitbake libglade
@@ -77,12 +77,12 @@
     </para>
 
     <para>
-        Next, source the environment setup script found in the 
-        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>.  
-        Follow that by setting up the installation destination to point to your 
-        sysroot as <filename>&lt;sysroot_dir&gt;</filename>.  
+        Next, source the environment setup script found in the
+        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+        Follow that by setting up the installation destination to point to your
+        sysroot as <filename>&lt;sysroot_dir&gt;</filename>.
         Finally, have an OPKG configuration file <filename>&lt;conf_file&gt;</filename>
-        that corresponds to the <filename>opkg</filename> repository you have just created. 
+        that corresponds to the <filename>opkg</filename> repository you have just created.
         The following command forms should now work:
         <literallayout class='monospaced'>
      $ opkg-cl –f &lt;conf_file&gt; -o &lt;sysroot_dir&gt; update

documentation/adt-manual/adt-prepare.xml

@@ -8,7 +8,7 @@
 
 <para>
     In order to develop applications, you need set up your host development system.
-    Several ways exist that allow you to install cross-development tools, QEMU, the  
+    Several ways exist that allow you to install cross-development tools, QEMU, the
     Eclipse Yocto Plug-in, and other tools.
     This chapter describes how to prepare for application development.
 </para>
@@ -18,43 +18,43 @@
 
     <para>
         The following list describes installation methods that set up varying degrees of tool
-        availabiltiy on your system.
+        availability on your system.
         Regardless of the installation method you choose,
         you must <filename>source</filename> the cross-toolchain
         environment setup script before you use a toolchain.
-        See the "<link linkend='setting-up-the-cross-development-environment'>Setting Up the 
+        See the "<link linkend='setting-up-the-cross-development-environment'>Setting Up the
         Cross-Development Environment</link>" section for more information.
     </para>
 
     <note>
         <para>Avoid mixing installation methods when installing toolchains for different architectures.
         For example, avoid using the ADT Installer to install some toolchains and then hand-installing
-        cross-development toolchains by running the toolchain installer for different architectures. 
+        cross-development toolchains by running the toolchain installer for different architectures.
         Mixing installation methods can result in situations where the ADT Installer becomes
         unreliable and might not install the toolchain.</para>
-        <para>If you must mix installation methods, you might avoid problems by deleting 
-        <filename>/var/lib/opkg</filename>, thus purging the <filename>opkg</filename> package 
+        <para>If you must mix installation methods, you might avoid problems by deleting
+        <filename>/var/lib/opkg</filename>, thus purging the <filename>opkg</filename> package
         metadata</para>
     </note>
-    
+
     <para>
         <itemizedlist>
             <listitem><para><emphasis>Use the ADT Installer Script:</emphasis>
                 This method is the recommended way to install the ADT because it
                 automates much of the process for you.
                 For example, you can configure the installation to install the QEMU emulator
-                and the user-space NFS, specify which root filesystem profiles to download, 
+                and the user-space NFS, specify which root filesystem profiles to download,
                 and define the target sysroot location.</para></listitem>
             <listitem><para><emphasis>Use an Existing Toolchain:</emphasis>
                 Using this method, you select and download an architecture-specific
                 toolchain installer and then run the script to hand-install the toolchain.
-                If you use this method, you just get the cross-toolchain and QEMU - you do not 
+                If you use this method, you just get the cross-toolchain and QEMU - you do not
                 get any of the other mentioned benefits had you run the ADT Installer script.</para></listitem>
             <listitem><para><emphasis>Use the Toolchain from within the Build Directory:</emphasis>
-                If you already have a 
-                <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>, 
+                If you already have a
+                <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
                 you can build the cross-toolchain within the directory.
-                However, like the previous method mentioned, you only get the cross-toolchain and QEMU - you 
+                However, like the previous method mentioned, you only get the cross-toolchain and QEMU - you
                 do not get any of the other benefits without taking separate steps.</para></listitem>
         </itemizedlist>
     </para>
@@ -63,8 +63,16 @@
         <title>Using the ADT Installer</title>
 
         <para>
-            To run the ADT Installer, you need to first get the ADT Installer tarball and then run the ADT
-            Installer Script.
+            To run the ADT Installer, you need to get the ADT Installer tarball, be sure
+            you have the necessary host development packages that support the ADT Installer,
+            and then run the ADT Installer Script.
+        </para>
+
+        <para>
+            For a list of the host packages needed to support ADT installation and use, see the
+            "ADT Installer Extras" lists in the
+            "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" section
+            of the Yocto Project Reference Manual.
         </para>
 
         <section id='getting-the-adt-installer-tarball'>
@@ -72,27 +80,27 @@
 
             <para>
                 The ADT Installer is contained in the ADT Installer tarball.
-                You can download the tarball into any directory from the 
+                You can download the tarball into any directory from the
                 <ulink url='&YOCTO_DL_URL;/releases'>Index of Releases</ulink>, specifically
-                at  
+                at
                 <ulink url='&YOCTO_ADTINSTALLER_DL_URL;'></ulink>.
-                Or, you can use BitBake to generate the tarball inside the existing 
-                <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>.
+                Or, you can use BitBake to generate the tarball inside the existing
+                <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
             </para>
 
             <para>
-                If you use BitBake to generate the ADT Installer tarball, you must 
-                <filename>source</filename> the environment setup script 
-                (<filename>&OE_INIT_FILE;</filename>) located 
-                in the source directory before running the <filename>bitbake</filename>
+                If you use BitBake to generate the ADT Installer tarball, you must
+                <filename>source</filename> the environment setup script
+                (<filename>&OE_INIT_FILE;</filename>) located
+                in the Source Directory before running the <filename>bitbake</filename>
                 command that creates the tarball.
             </para>
 
             <para>
-                The following example commands download the Poky tarball, set up the 
-                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>, 
-                set up the environment while also creating the default build directory, 
-                and run the <filename>bitbake</filename> command that results in the tarball 
+                The following example commands download the Poky tarball, set up the
+                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
+                set up the environment while also creating the default Build Directory,
+                and run the <filename>bitbake</filename> command that results in the tarball
                 <filename>~/yocto-project/build/tmp/deploy/sdk/adt_installer.tar.bz2</filename>:
                 <literallayout class='monospaced'>
      $ cd ~
@@ -112,107 +120,97 @@
             <para>
                 Before running the ADT Installer script, you need to unpack the tarball.
                 You can unpack the tarball in any directory you wish.
-                For example, this command copies the ADT Installer tarball from where 
-                it was built into the home directory and then unpacks the tarball into 
+                For example, this command copies the ADT Installer tarball from where
+                it was built into the home directory and then unpacks the tarball into
                 a top-level directory named <filename>adt-installer</filename>:
                 <literallayout class='monospaced'>
      $ cd ~
      $ cp ~/poky/build/tmp/deploy/sdk/adt_installer.tar.bz2 $HOME
      $ tar -xjf adt_installer.tar.bz2
                 </literallayout>
-                Unpacking it creates the directory <filename>adt-installer</filename>, 
+                Unpacking it creates the directory <filename>adt-installer</filename>,
                 which contains the ADT Installer script (<filename>adt_installer</filename>)
                 and its configuration file (<filename>adt_installer.conf</filename>).
             </para>
 
             <para>
-                Before you run the script, however, you should examine the ADT Installer configuration 
-                file and be sure you are going to get what you want.  
+                Before you run the script, however, you should examine the ADT Installer configuration
+                file and be sure you are going to get what you want.
                 Your configurations determine which kernel and filesystem image are downloaded.
             </para>
 
-            <para>  
-                The following list describes the configurations you can define for the ADT Installer.  
-                For configuration values and restrictions, see the comments in  
+            <para>
+                The following list describes the configurations you can define for the ADT Installer.
+                For configuration values and restrictions, see the comments in
                 the <filename>adt-installer.conf</filename> file:
 
                 <itemizedlist>
-                    <listitem><para><filename>YOCTOADT_REPO</filename>: This area 
-                        includes the IPKG-based packages and the root filesystem upon which 
-                        the installation is based.  
-                        If you want to set up your own IPKG repository pointed to by 
-                        <filename>YOCTOADT_REPO</filename>, you need to be sure that the 
-                        directory structure follows the same layout as the reference directory 
-                        set up at <ulink url='http://adtrepo.yoctoproject.org'></ulink>.  
+                    <listitem><para><filename>YOCTOADT_REPO</filename>: This area
+                        includes the IPKG-based packages and the root filesystem upon which
+                        the installation is based.
+                        If you want to set up your own IPKG repository pointed to by
+                        <filename>YOCTOADT_REPO</filename>, you need to be sure that the
+                        directory structure follows the same layout as the reference directory
+                        set up at <ulink url='http://adtrepo.yoctoproject.org'></ulink>.
                         Also, your repository needs to be accessible through HTTP.</para></listitem>
-                    <listitem><para><filename>YOCTOADT_TARGETS</filename>: The machine 
-                        target architectures for which you want to set up cross-development 
+                    <listitem><para><filename>YOCTOADT_TARGETS</filename>: The machine
+                        target architectures for which you want to set up cross-development
                         environments.</para></listitem>
-                    <listitem><para><filename>YOCTOADT_QEMU</filename>: Indicates whether 
+                    <listitem><para><filename>YOCTOADT_QEMU</filename>: Indicates whether
                         or not to install the emulator QEMU.</para></listitem>
-                    <listitem><para><filename>YOCTOADT_NFS_UTIL</filename>: Indicates whether 
-                        or not to install user-mode NFS.  
-                        If you plan to use the Eclipse IDE Yocto plug-in against QEMU, 
+                    <listitem><para><filename>YOCTOADT_NFS_UTIL</filename>: Indicates whether
+                        or not to install user-mode NFS.
+                        If you plan to use the Eclipse IDE Yocto plug-in against QEMU,
                         you should install NFS.
-                        <note>To boot QEMU images using our userspace NFS server, you need 
-                            to be running <filename>portmap</filename> or <filename>rpcbind</filename>. 
-                            If you are running <filename>rpcbind</filename>, you will also need to add the 
-                            <filename>-i</filename> option when <filename>rpcbind</filename> starts up. 
-                            Please make sure you understand the security implications of doing this. 
-                            You might also have to modify your firewall settings to allow 
+                        <note>To boot QEMU images using our userspace NFS server, you need
+                            to be running <filename>portmap</filename> or <filename>rpcbind</filename>.
+                            If you are running <filename>rpcbind</filename>, you will also need to add the
+                            <filename>-i</filename> option when <filename>rpcbind</filename> starts up.
+                            Please make sure you understand the security implications of doing this.
+                            You might also have to modify your firewall settings to allow
                             NFS booting to work.</note></para></listitem>
-                    <listitem><para><filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename>: The root 
-                        filesystem images you want to download from the 
+                    <listitem><para><filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename>: The root
+                        filesystem images you want to download from the
                         <filename>YOCTOADT_IPKG_REPO</filename> repository.</para></listitem>
-                    <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_IMAGE_&lt;arch&gt;</filename>: The 
+                    <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_IMAGE_&lt;arch&gt;</filename>: The
                         particular root filesystem used to extract and create the target sysroot.
-                        The value of this variable must have been specified with 
+                        The value of this variable must have been specified with
                         <filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename>.
-                        For example, if you downloaded both <filename>minimal</filename> and 
-                        <filename>sato-sdk</filename> images by setting 
+                        For example, if you downloaded both <filename>minimal</filename> and
+                        <filename>sato-sdk</filename> images by setting
                         <filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename>
                         to "minimal sato-sdk", then <filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename>
-                        must be set to either <filename>minimal</filename> or 
+                        must be set to either <filename>minimal</filename> or
                         <filename>sato-sdk</filename>.</para></listitem>
-                    <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_LOC_&lt;arch&gt;</filename>: The 
+                    <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_LOC_&lt;arch&gt;</filename>: The
                         location on the development host where the target sysroot is created.
                         </para></listitem>
                 </itemizedlist>
             </para>
 
             <para>
-                After you have configured the <filename>adt_installer.conf</filename> file, 
+                After you have configured the <filename>adt_installer.conf</filename> file,
                 run the installer using the following command.
-                Be sure that you are not trying to use cross-compilation tools. 
-                When you run the installer, the environment must use a 
+                Be sure that you are not trying to use cross-compilation tools.
+                When you run the installer, the environment must use a
                 host <filename>gcc</filename>:
                 <literallayout class='monospaced'>
      $ cd ~/adt-installer
      $ ./adt_installer
                 </literallayout>
-            </para>
-
-            <note>
-                The ADT Installer requires the <filename>libtool</filename> package to complete.  
-                If you install the recommended packages as described in  
-                "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>"
-                section of the Yocto Project Quick Start, then you will have libtool installed.
-            </note>
-
-            <para>
-                Once the installer begins to run, you are asked to enter the location for 
+                Once the installer begins to run, you are asked to enter the location for
                 cross-toolchain installation.
                 The default location is <filename>/opt/poky/&lt;release&gt;</filename>.
-                After selecting the location, you are prompted to run in  
-                interactive or silent mode.  
-                If you want to closely monitor the installation, choose “I” for interactive 
-                mode rather than “S” for silent mode.  
+                After selecting the location, you are prompted to run in
+                interactive or silent mode.
+                If you want to closely monitor the installation, choose “I” for interactive
+                mode rather than “S” for silent mode.
                 Follow the prompts from the script to complete the installation.
             </para>
 
             <para>
                 Once the installation completes, the ADT, which includes the cross-toolchain, is installed.
-                You will notice environment setup files for the cross-toolchain in 
+                You will notice environment setup files for the cross-toolchain in
                 <filename>&YOCTO_ADTPATH_DIR;</filename>,
                 and image tarballs in the <filename>adt-installer</filename>
                 directory according to your installer configurations, and the target sysroot located
@@ -226,57 +224,65 @@
         <title>Using a Cross-Toolchain Tarball</title>
 
         <para>
-            If you want to simply install the cross-toolchain by hand, you can do so by running the 
-            toolchain installer.  
-            If you use this method to install the cross-toolchain and you still need to install the target 
+            If you want to simply install the cross-toolchain by hand, you can do so by running the
+            toolchain installer.
+            If you use this method to install the cross-toolchain and you still need to install the target
             sysroot, you will have to extract and install sysroot separately.
-            For information on how to do this, see the 
+            For information on how to do this, see the
             "<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" section.
         </para>
 
         <para>
             Follow these steps:
             <orderedlist>
-                <listitem><para>Go to  
-                    <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink> 
-                    and find the folder that matches your host development system 
-                    (i.e. <filename>i686</filename> for 32-bit machines or 
+                <listitem><para>Go to
+                    <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>
+                    and find the folder that matches your host development system
+                    (i.e. <filename>i686</filename> for 32-bit machines or
                     <filename>x86-64</filename> for 64-bit machines).</para></listitem>
-                <listitem><para>Go into that folder and download the toolchain installer whose name 
+                <listitem><para>Go into that folder and download the toolchain installer whose name
                     includes the appropriate target architecture.
-                    For example, if your host development system is an Intel-based 64-bit system and 
-                    you are going to use your cross-toolchain for an Intel-based 32-bit target, go into the 
+                    For example, if your host development system is an Intel-based 64-bit system and
+                    you are going to use your cross-toolchain for an Intel-based 32-bit target, go into the
                     <filename>x86_64</filename> folder and download the following installer:
                     <literallayout class='monospaced'>
      poky-eglibc-x86_64-i586-toolchain-gmae-&DISTRO;.sh
                     </literallayout>
-                    <note><para>As an alternative to steps one and two, you can build the toolchain installer 
-                        if you have a <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>.
+                    <note><para>As an alternative to steps one and two, you can build the toolchain installer
+                        if you have a <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
                         If you need GMAE, you should use the <filename>bitbake meta-toolchain-gmae</filename>
-                        command. 
+                        command.
                         The resulting installation script when run will support such development.
-                        However, if you are not concerned with GMAE, 
+                        However, if you are not concerned with GMAE,
                         you can generate the toolchain installer using
                         <filename>bitbake meta-toolchain</filename>.</para>
-                        <para>Use the appropriate <filename>bitbake</filename> command only after you have 
-                        sourced the <filename>oe-build-init-env</filename> script located in the source
-                        directory.  
-                        When the <filename>bitbake</filename> command completes, the toolchain installer will 
-                        be in <filename>tmp/deploy/sdk</filename> in the build directory.
+                        <para>Use the appropriate <filename>bitbake</filename> command only after you have
+                        sourced the <filename>&OE_INIT_PATH;</filename> script located in the Source
+                        Directory and you have made sure your <filename>conf/local.conf</filename>
+                        variables are correct.
+                        In particular, you need to be sure the
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+                        variable matches the architecture for which you are building and that the
+                        <filename>SDKMACHINE</filename> variable is correctly set if you are building
+                        a toolchain for an architecture that differs from your current
+                        development host machine.</para>
+                        <para>When the <filename>bitbake</filename> command completes, the
+                        toolchain installer will be in <filename>tmp/deploy/sdk</filename> in the
+                        Build Directory.
                         </para></note>
                     </para></listitem>
                 <listitem><para>Once you have the installer, run it to install the toolchain.
-                    You must change the permissions on the toolchain installer 
+                    You must change the permissions on the toolchain installer
                     script so that it is executable.</para>
-                    <para>The following command shows how to run the installer given a toolchain tarball 
+                    <para>The following command shows how to run the installer given a toolchain tarball
                     for a 64-bit development host system and a 32-bit target architecture.
                     The example assumes the toolchain installer is located in <filename>~/Downloads/</filename>.
                     <literallayout class='monospaced'>
      $ ~/Downloads/poky-eglibc-x86_64-i586-toolchain-gmae-&DISTRO;.sh
                     </literallayout>
                     <note>
-                        If you do not have write permissions for the directory into which you are installing 
-                        the toolchain, the toolchain installer notifies you and exits.  
+                        If you do not have write permissions for the directory into which you are installing
+                        the toolchain, the toolchain installer notifies you and exits.
                         Be sure you have write permissions in the directory and run the installer again.
                     </note>
                     Once the tarball is expanded, the cross-toolchain is installed.
@@ -290,50 +296,50 @@
         <title>Using BitBake and the Build Directory</title>
 
         <para>
-            A final way of making the cross-toolchain available is to use BitBake 
-            to generate the toolchain within an existing 
-            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>.
-            This method does not install the toolchain into the 
+            A final way of making the cross-toolchain available is to use BitBake
+            to generate the toolchain within an existing
+            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+            This method does not install the toolchain into the
             <filename>/opt</filename> directory.
-            As with the previous method, if you need to install the target sysroot, you must 
+            As with the previous method, if you need to install the target sysroot, you must
             do that separately as well.
         </para>
 
         <para>
-            Follow these steps to generate the toolchain into the build directory:
+            Follow these steps to generate the toolchain into the Build Directory:
             <orderedlist>
-                <listitem><para>Source the environment setup script 
-                    <filename>&OE_INIT_FILE;</filename> located in the 
-                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source directory</ulink>.
-                    </para></listitem> 
-                <listitem><para>At this point, you should be sure that the 
-                    <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable 
-                    in the <filename>local.conf</filename> file found in the 
-                    <filename>conf</filename> directory of the build directory
+                <listitem><para>Source the environment setup script
+                    <filename>&OE_INIT_FILE;</filename> located in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                    </para></listitem>
+                <listitem><para>At this point, you should be sure that the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable
+                    in the <filename>local.conf</filename> file found in the
+                    <filename>conf</filename> directory of the Build Directory
                     is set for the target architecture.
-                    Comments within the <filename>local.conf</filename> file list the values you 
-                    can use for the <filename>MACHINE</filename> variable.  
-                    <note>You can populate the build directory with the cross-toolchains for more 
-                        than a single architecture.  
-                        You just need to edit the <filename>MACHINE</filename> variable in the 
-                        <filename>local.conf</filename> file and re-run the BitBake 
+                    Comments within the <filename>local.conf</filename> file list the values you
+                    can use for the <filename>MACHINE</filename> variable.
+                    <note>You can populate the Build Directory with the cross-toolchains for more
+                        than a single architecture.
+                        You just need to edit the <filename>MACHINE</filename> variable in the
+                        <filename>local.conf</filename> file and re-run the BitBake
                         command.</note></para></listitem>
-                <listitem><para>Run <filename>bitbake meta-ide-support</filename> to complete the 
+                <listitem><para>Run <filename>bitbake meta-ide-support</filename> to complete the
                     cross-toolchain generation.
-                    <note>If you change out of your working directory after you 
+                    <note>If you change out of your working directory after you
                         <filename>source</filename> the environment setup script and before you run
-                        the <filename>bitbake</filename> command, the command might not work. 
-                        Be sure to run the <filename>bitbake</filename> command immediately 
-                        after checking or editing the <filename>local.conf</filename> but without 
+                        the <filename>bitbake</filename> command, the command might not work.
+                        Be sure to run the <filename>bitbake</filename> command immediately
+                        after checking or editing the <filename>local.conf</filename> but without
                         changing out of your working directory.</note>
-                    Once the <filename>bitbake</filename> command finishes, 
-                    the cross-toolchain is generated and populated within the build directory.
-                    You will notice environment setup files for the cross-toolchain in the 
-                    build directory in the <filename>tmp</filename> directory.
+                    Once the <filename>bitbake</filename> command finishes,
+                    the cross-toolchain is generated and populated within the Build Directory.
+                    You will notice environment setup files for the cross-toolchain in the
+                    Build Directory in the <filename>tmp</filename> directory.
                     Setup script filenames contain the strings <filename>environment-setup</filename>.</para>
                     <para>Be aware that when you use this method to install the toolchain you still need
                     to separately extract and install the sysroot filesystem.
-                    For information on how to do this, see the 
+                    For information on how to do this, see the
                     "<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" section.
                     </para></listitem>
             </orderedlist>
@@ -345,24 +351,24 @@
     <title>Setting Up the Cross-Development Environment</title>
 
     <para>
-        Before you can develop using the cross-toolchain, you need to set up the 
-        cross-development environment by sourcing the toolchain's environment setup script.  
+        Before you can develop using the cross-toolchain, you need to set up the
+        cross-development environment by sourcing the toolchain's environment setup script.
         If you used the ADT Installer or hand-installed cross-toolchain,
         then you can find this script in the <filename>&YOCTO_ADTPATH_DIR;</filename>
-        directory.  
-        If you installed the toolchain in the 
-        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>, 
-        you can find the environment setup 
-        script for the toolchain in the build directory's <filename>tmp</filename> directory.
+        directory.
+        If you installed the toolchain in the
+        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
+        you can find the environment setup
+        script for the toolchain in the Build Directory's <filename>tmp</filename> directory.
     </para>
 
-    <para> 
-        Be sure to run the environment setup script that matches the architecture for 
-        which you are developing.  
+    <para>
+        Be sure to run the environment setup script that matches the architecture for
+        which you are developing.
         Environment setup scripts begin with the string “<filename>environment-setup</filename>”
-        and include as part of their name the architecture.  
-        For example, the toolchain environment setup script for a 64-bit IA-based architecture would 
-        be the following: 
+        and include as part of their name the architecture.
+        For example, the toolchain environment setup script for a 64-bit IA-based architecture would
+        be the following:
         <literallayout class='monospaced'>
      &YOCTO_ADTPATH_DIR;/environment-setup-x86_64-poky-linux
         </literallayout>
@@ -373,7 +379,7 @@
     <title>Securing Kernel and Filesystem Images</title>
 
     <para>
-        You will need to have a kernel and filesystem image to boot using your 
+        You will need to have a kernel and filesystem image to boot using your
         hardware or the QEMU emulator.
         Furthermore, if you plan on booting your image using NFS or you want to use the root filesystem
         as the target sysroot, you need to extract the root filesystem.
@@ -385,62 +391,62 @@
         <para>
             To get the kernel and filesystem images, you either have to build them or download
             pre-built versions.
-            You can find examples for both these situations in the 
-            "<ulink url='&YOCTO_DOCS_QS_URL;#test-run'>A Quick Test Run</ulink>" section of   
+            You can find examples for both these situations in the
+            "<ulink url='&YOCTO_DOCS_QS_URL;#test-run'>A Quick Test Run</ulink>" section of
             the Yocto Project Quick Start.
         </para>
 
-        <para> 
-            The Yocto Project ships basic kernel and filesystem images for several 
-            architectures (<filename>x86</filename>, <filename>x86-64</filename>, 
-            <filename>mips</filename>, <filename>powerpc</filename>, and <filename>arm</filename>) 
-            that you can use unaltered in the QEMU emulator.  
-            These kernel images reside in the release 
+        <para>
+            The Yocto Project ships basic kernel and filesystem images for several
+            architectures (<filename>x86</filename>, <filename>x86-64</filename>,
+            <filename>mips</filename>, <filename>powerpc</filename>, and <filename>arm</filename>)
+            that you can use unaltered in the QEMU emulator.
+            These kernel images reside in the release
             area - <ulink url='&YOCTO_MACHINES_DL_URL;'></ulink>
             and are ideal for experimentation using Yocto Project.
-            For information on the image types you can build using the OpenEmbedded build system, 
+            For information on the image types you can build using the OpenEmbedded build system,
             see the
-            "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in  
+            "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in
             the Yocto Project Reference Manual.
         </para>
 
         <para>
             If you are planning on developing against your image and you are not
-            building or using one of the Yocto Project development images 
+            building or using one of the Yocto Project development images
             (e.g. core-image-*-dev), you must be sure to include the development
             packages as part of your image recipe.
-        </para>            
+        </para>
 
         <para>
-            Furthermore, if you plan on remotely deploying and debugging your 
-            application from within the 
+            Furthermore, if you plan on remotely deploying and debugging your
+            application from within the
             Eclipse IDE, you must have an image that contains the Yocto Target Communication
-            Framework (TCF) agent (<filename>tcf-agent</filename>). 
-            By default, the Yocto Project provides only one type pre-built image that contains the 
+            Framework (TCF) agent (<filename>tcf-agent</filename>).
+            By default, the Yocto Project provides only one type pre-built image that contains the
             <filename>tcf-agent</filename>.
             And, those images are SDK (e.g.<filename>core-image-sato-sdk</filename>).
         </para>
 
         <para>
-            If you want to use a different image type that contains the <filename>tcf-agent</filename>, 
+            If you want to use a different image type that contains the <filename>tcf-agent</filename>,
             you can do so one of two ways:
             <itemizedlist>
-                <listitem><para>Modify the <filename>conf/local.conf</filename> configuration in 
-                    the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>
+                <listitem><para>Modify the <filename>conf/local.conf</filename> configuration in
+                    the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
                     and then rebuild the image.
-                    With this method, you need to modify the 
+                    With this method, you need to modify the
                     <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
-                    variable to have the value of "tools-debug" before rebuilding the image. 
+                    variable to have the value of "tools-debug" before rebuilding the image.
                     Once the image is rebuilt, the <filename>tcf-agent</filename> will be included
                     in the image and is launched automatically after the boot.</para></listitem>
                 <listitem><para>Manually build the <filename>tcf-agent</filename>.
                     To build the agent, follow these steps:
                     <orderedlist>
-                        <listitem><para>Be sure the ADT is installed as described in the 
+                        <listitem><para>Be sure the ADT is installed as described in the
                             "<link linkend='installing-the-adt'>Installing the ADT and Toolchains</link>" section.
                             </para></listitem>
-                        <listitem><para>Set up the cross-development environment as described in the 
-                            "<link linkend='setting-up-the-cross-development-environment'>Setting 
+                        <listitem><para>Set up the cross-development environment as described in the
+                            "<link linkend='setting-up-the-cross-development-environment'>Setting
                             Up the Cross-Development Environment</link>" section.</para></listitem>
                         <listitem><para>Get the <filename>tcf-agent</filename> source code using
                             the following commands:
@@ -449,17 +455,17 @@
      $ cd agent
                             </literallayout></para></listitem>
                         <listitem><para>Modify the <filename>Makefile.inc</filename> file
-                            for the cross-compilation environment by setting the 
-                            <filename>OPSYS</filename> and 
+                            for the cross-compilation environment by setting the
+                            <filename>OPSYS</filename> and
                             <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
                             variables according to your target.</para></listitem>
-                        <listitem><para>Use the cross-development tools to build the 
-                            <filename>tcf-agent</filename>.  
+                        <listitem><para>Use the cross-development tools to build the
+                            <filename>tcf-agent</filename>.
                             Before you "Make" the file, be sure your cross-tools are set up first.
                             See the "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>"
                             section for information on how to make sure the cross-tools are set up
                             correctly.</para>
-                            <para>If the build is successful, the <filename>tcf-agent</filename> output will 
+                            <para>If the build is successful, the <filename>tcf-agent</filename> output will
                             be <filename>obj/$(OPSYS)/$(MACHINE)/Debug/agent</filename>.</para></listitem>
                         <listitem><para>Deploy the agent into the image's root filesystem.</para></listitem>
                     </orderedlist>
@@ -474,19 +480,19 @@
         <para>
             You must extract the root filesystem if you want to boot the image using NFS
             or you want to use the root filesystem as the target sysroot.
-            For example, the Eclipse IDE environment with the Eclipse Yocto Plug-in installed allows you 
+            For example, the Eclipse IDE environment with the Eclipse Yocto Plug-in installed allows you
             to use QEMU to boot under NFS.
             Another example is if you want to develop your target application using the
-            root filesystem as the target sysroot. 
+            root filesystem as the target sysroot.
         </para>
 
-        <para> 
+        <para>
             To extract the root filesystem, first <filename>source</filename>
-            the cross-development environment setup script and then 
-            use the <filename>runqemu-extract-sdk</filename> command on the 
-            filesystem image. 
+            the cross-development environment setup script and then
+            use the <filename>runqemu-extract-sdk</filename> command on the
+            filesystem image.
             For example, the following commands set up the environment and then extract
-            the root filesystem from a previously built filesystem image tarball named  
+            the root filesystem from a previously built filesystem image tarball named
             <filename>core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2</filename>.
             The example extracts the root filesystem into the <filename>$HOME/qemux86-sato</filename>
             directory:
@@ -496,7 +502,7 @@
         tmp/deploy/images/core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2 \
         $HOME/qemux86-sato
             </literallayout>
-            In this case, you could now point to the target sysroot at 
+            In this case, you could now point to the target sysroot at
             <filename>$HOME/qemux86-sato</filename>.
         </para>
     </section>

documentation/bsp-guide/bsp-guide.xml

@@ -2,7 +2,7 @@
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
 [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
 
-<book id='bsp-guide' lang='en' 
+<book id='bsp-guide' lang='en'
       xmlns:xi="http://www.w3.org/2003/XInclude"
       xmlns="http://docbook.org/ns/docbook"
       >
@@ -10,13 +10,13 @@
 
         <mediaobject>
             <imageobject>
-                <imagedata fileref='figures/bsp-title.png' 
-                    format='SVG' 
+                <imagedata fileref='figures/bsp-title.png'
+                    format='SVG'
                     align='center' scalefit='1' width='100%'/>
-            </imageobject>    
+            </imageobject>
         </mediaobject>
 
-        <title></title> 
+        <title></title>
 
         <authorgroup>
             <author>
@@ -63,9 +63,14 @@
             </revision>
             <revision>
                 <revnumber>1.3</revnumber>
-                <date>Sometime in 2012</date>
+                <date>October 2012</date>
                 <revremark>Released with the Yocto Project 1.3 Release.</revremark>
             </revision>
+            <revision>
+                <revnumber>1.4</revnumber>
+                <date>Sometime in 2013</date>
+                <revremark>Released with the Yocto Project 1.4 Release.</revremark>
+            </revision>
         </revhistory>
 
     <copyright>
@@ -75,12 +80,12 @@
 
     <legalnotice>
       <para>
-        Permission is granted to copy, distribute and/or modify this document under 
+        Permission is granted to copy, distribute and/or modify this document under
         the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-nc-sa/2.0/uk/">Creative Commons Attribution-Non-Commercial-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
       </para>
       <note>
           Due to production processes, there could be differences between the Yocto Project
-          documentation bundled in the release tarball and the 
+          documentation bundled in the release tarball and the
           <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink> on
           the <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website.
           For the latest version of this manual, see the manual on the website.
@@ -97,6 +102,6 @@
 -->
 
 </book>
-<!-- 
-vim: expandtab tw=80 ts=4 
+<!--
+vim: expandtab tw=80 ts=4
 -->

documentation/dev-manual/dev-manual-bsp-appendix.xml

@@ -1,713 +0,0 @@
-<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
-
-<appendix id='dev-manual-bsp-appendix'>
-
-<title>BSP Development Example</title>
-
-<para>
-    This appendix provides a complete BSP development example.
-    The example assumes the following:
-    <itemizedlist>
-        <listitem><para>No previous preparation or use of the Yocto Project.</para></listitem>
-        <listitem><para>Use of the Fish River Island 2 Board Support Package (BSP) as a "base" BSP from 
-            which to work.  
-            The example begins with the Fish River Island 2 BSP as the starting point
-            but ends by building a new 'atom-pc' BSP, which was based on the Fish River Island 2 BSP.
-            </para></listitem>  
-        <listitem><para>Shell commands assume <filename>bash</filename></para></listitem>
-        <listitem><para>Example was developed on an Intel-based Core i7 platform running 
-            Ubuntu 10.04 LTS released in April of 2010.</para></listitem>        
-    </itemizedlist>             
-</para>
-
-<section id='getting-local-yocto-project-files-and-bsp-files'>
-    <title>Getting Local Source Files and BSP Files</title>
-
-    <para>
-        You need to have the <link linkend='source-directory'>Source Directory</link>
-        available on your host system.  
-        You can set up this directory through tarball extraction or by cloning the 
-        <filename>poky</filename> Git repository.
-        The following paragraphs describe both methods.
-        For additional information, see the bulleted item
-        "<link linkend='local-yp-release'>Yocto Project Release</link>".
-    </para> 
-
-    <para>
-        As mentioned, one way to set up the Source Directory is to use Git to clone the 
-        <filename>poky</filename> repository. 
-        These commands create a local copy of the Git repository.
-        By default, the top-level directory of the repository is named <filename>poky</filename>:
-        <literallayout class='monospaced'>
-     $ git clone git://git.yoctoproject.org/poky
-     $ cd poky
-        </literallayout> 
-        Alternatively, you can start with the downloaded Poky "&DISTRO_NAME;" tarball.
-        These commands unpack the tarball into a Source Directory structure.
-        By default, the top-level directory of the Source Directory is named
-        <filename>&YOCTO_POKY;</filename>:
-        <literallayout class='monospaced'>
-     $ tar xfj &YOCTO_POKY_TARBALL;
-     $ cd &YOCTO_POKY;
-        </literallayout> 
-        <note><para>If you're using the tarball method, you can ignore all the following steps that
-        ask you to carry out Git operations.  
-        You already have the results of those operations
-        in the form of the &DISTRO_NAME; release tarballs.
-        Consequently, there is nothing left to do other than extract those tarballs into the 
-        proper locations.</para>
-
-        <para>Once you expand the released tarball, you have a snapshot of the Git repository
-        that represents a specific release.
-        Fundamentally, this is different than having a local copy of the Poky Git repository.  
-        Given the tarball method, changes you make are building on top of a release.
-        With the Git repository method you have the ability to track development
-        and keep changes in revision control.
-        See the 
-        "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>" section
-        for more discussion around these differences.</para></note>
-    </para>
-
-    <para>
-        With the local <filename>poky</filename> Git repository set up, 
-        you have all the development branches available to you from which you can work. 
-        Next, you need to be sure that your local repository reflects the exact
-        release in which you are interested.
-        From inside the repository you can see the development branches that represent
-        areas of development that have diverged from the main (master) branch
-        at some point, such as a branch to track a maintenance release's development.  
-        You can also see the tag names used to mark snapshots of stable releases or 
-        points in the repository.
-        Use the following commands to list out the branches and the tags in the repository, 
-        respectively.
-        <literallayout class='monospaced'>
-     $ git branch -a
-     $ git tag -l
-        </literallayout> 
-        For this example, we are going to use the Yocto Project &DISTRO; Release, which is code
-        named "&DISTRO_NAME;". 
-        To make sure we have a local area (branch in Git terms) on our machine that 
-        reflects the &DISTRO; release, we can use the following commands:
-        <literallayout class='monospaced'>
-     $ cd ~/poky
-     $ git fetch --tags
-     $ git checkout -b &DISTRO_NAME;-&POKYVERSION; origin/&DISTRO_NAME;
-     Switched to a new branch '&DISTRO_NAME;-&POKYVERSION;'
-        </literallayout>
-        The <filename>git fetch --tags</filename> is somewhat redundant since you just set 
-        up the repository and should have all the tags.
-        The <filename>fetch</filename> command makes sure all the tags are available in your
-        local repository.
-        The Git <filename>checkout</filename> command with the <filename>-b</filename> option
-        creates a local branch for you named <filename>&DISTRO_NAME;-&POKYVERSION;</filename>.
-        Your local branch begins in the same state as the Yocto Project &DISTRO; released tarball 
-        marked with the <filename>&DISTRO_NAME;-&POKYVERSION;</filename> tag in the source repositories.
-    </para>
-</section> 
-
-<section id='choosing-a-base-bsp-app'>
-    <title>Choosing a Base BSP</title>
-
-    <para>
-        For this example, the base BSP is the <trademark class='registered'>Intel</trademark>
-        <trademark class='trade'>Atom</trademark> Processor E660 with Intel Platform 
-        Controller Hub EG20T Development Kit, which is otherwise referred to as "Fish River Island 2."
-        The BSP layer is <filename>meta-fri2</filename>.  
-        The base BSP is simply the BSP
-        we will be using as a starting point, so don't worry if you don't actually have Fish River Island 2
-        hardware.
-        The remainder of the example transforms the base BSP into a BSP that should be
-        able to boot on generic atom-pc (netbook) hardware.
-    </para>
-
-    <para>
-        For information on how to choose a base BSP, see
-        "<link linkend='developing-a-board-support-package-bsp'>Developing a Board Support Package (BSP)</link>".
-    </para>
-</section>
-
-<section id='getting-your-base-bsp-app'>
-    <title>Getting Your Base BSP</title>
-
-    <para>
-        You need to have the base BSP layer on your development system.  
-        Similar to the local <link linkend='source-directory'>Source Directory</link>, 
-        you can get the BSP 
-        layer in a couple of different ways:  
-        download the BSP tarball and extract it, or set up a local Git repository that 
-        has the BSP layers.  
-        You should use the same method that you used to set up the Source Directory earlier.
-        See "<link linkend='getting-setup'>Getting Setup</link>" for information on how to get 
-        the BSP files.
-    </para>
-
-    <para>
-        This example assumes the BSP layer will be located within a directory named
-        <filename>meta-intel</filename> contained within the <filename>poky</filename>
-        parent directory.  
-        The following steps will automatically create the
-        <filename>meta-intel</filename> directory and the contained 
-        <filename>meta-fri2</filename> starting point in both the Git and the tarball cases.
-    </para>
-
-    <para>
-        If you're using the Git method, you could do the following to create
-        the starting layout after you have made sure you are in the <filename>poky</filename>
-        directory created in the previous steps:
-        <literallayout class='monospaced'>
-     $ git clone git://git.yoctoproject.org/meta-intel.git
-     $ cd meta-intel
-        </literallayout> 
-        Alternatively, you can start with the downloaded Fish River Island 2 tarball.
-        You can download the &DISTRO_NAME; version of the BSP tarball from the
-        <ulink url='&YOCTO_HOME_URL;/download'>Downloads</ulink> page of the 
-        Yocto Project website. 
-        Here is the specific link for the tarball needed for this example:
-        <ulink url='&YOCTO_MACHINES_DL_URL;/fri2-noemgd/fri2-noemgd-&DISTRO_NAME;-&POKYVERSION;.tar.bz2'></ulink>.
-        Again, be sure that you are already in the <filename>poky</filename> directory
-        as described previously before installing the tarball:
-        <literallayout class='monospaced'>
-     $ tar xfj fri2-noemgd-&DISTRO_NAME;-&POKYVERSION;.tar.bz2
-     $ cd meta-intel
-        </literallayout> 
-    </para>
-        
-    <para>
-        The <filename>meta-intel</filename> directory contains all the metadata 
-        that supports BSP creation.  
-        If you're using the Git method, the following
-        step will switch to the &DISTRO_NAME; metadata.
-        If you're using the tarball method, you already have the correct metadata and can 
-        skip to the next step.
-        Because <filename>meta-intel</filename> is its own Git repository, you will want
-        to be sure you are in the appropriate branch for your work.
-        For this example we are going to use the <filename>&DISTRO_NAME;</filename> 
-        branch. 
-        <literallayout class='monospaced'>
-     $ git checkout -b &DISTRO_NAME;-&POKYVERSION; origin/&DISTRO_NAME;
-     Branch &DISTRO_NAME;-&POKYVERSION; set up to track remote branch &DISTRO_NAME; from origin.
-     Switched to a new branch '&DISTRO_NAME;-&POKYVERSION;'
-        </literallayout>
-    </para>
-</section>
-
-<section id='making-a-copy-of-the-base bsp-to-create-your-new-bsp-layer-app'>
-    <title>Making a Copy of the Base BSP to Create Your New BSP Layer</title>
-
-    <para>
-        Now that you have set up the Source Directory and included the base BSP files, you need to 
-        create a new layer for your BSP.
-        To create your BSP layer, you simply copy the <filename>meta-fri2</filename>
-        layer to a new layer.
-    </para>
-
-    <para>  
-        For this example, the new layer will be named <filename>meta-mymachine</filename>.  
-        The name should follow the BSP layer naming convention, which is 
-        <filename>meta-&lt;name&gt;</filename>.  
-        The following assumes your working directory is <filename>meta-intel</filename> 
-        inside your Source Directory.  
-        To start your new layer, just copy the new layer alongside the existing
-        BSP layers in the <filename>meta-intel</filename> directory:
-        <literallayout class='monospaced'>
-     $ cp -a meta-fri2/ meta-mymachine 
-        </literallayout>
-    </para>
-</section>
-
-<section id='making-changes-to-your-bsp-app'>
-    <title>Making Changes to Your BSP</title>
-
-    <para>
-        Right now you have two identical BSP layers with different names:  
-        <filename>meta-fri2</filename> and <filename>meta-mymachine</filename>.  
-        You need to change your configurations so that they work for your new BSP and 
-        your particular hardware.
-        The following sections look at each of these areas of the BSP.
-    </para>
-
-    <section id='changing-the-bsp-configuration'>
-        <title>Changing the BSP Configuration</title>
-   
-        <para>  
-            We will look first at the configurations, which are all done in the layer’s 
-            <filename>conf</filename> directory.
-        </para>
-
-        <para>
-            First, since in this example the new BSP will not support EMGD, we will get rid of the 
-            <filename>fri2.conf</filename> file and then rename the 
-            <filename>fri2-noemgd.conf</filename> file to <filename>mymachine.conf</filename>.  
-            Much of what we do in the configuration directory is designed to help the OpenEmbedded 
-            build system work with the new layer and to be able to find and use the right software.  
-            The following two commands result in a single machine configuration file named 
-            <filename>mymachine.conf</filename>.  
-            <literallayout class='monospaced'>
-     $ rm meta-mymachine/conf/machine/fri2.conf
-     $ mv meta-mymachine/conf/machine/fri2-noemgd.conf \
-     meta-mymachine/conf/machine/mymachine.conf
-            </literallayout>
-        </para>
-
-        <para>
-            Next, we need to make changes to the <filename>mymachine.conf</filename> itself.
-            The only changes we want to make for this example are to the comment lines.  
-            Changing comments, of course, is never strictly necessary, but it's always good form to make
-            them reflect reality as much as possible.
-
-            Here, simply substitute the Fish River Island 2 name with an appropriate name for the BSP 
-            (<filename>mymachine</filename> in this case) and change the description to 
-            something that describes your hardware.
-        </para>
-
-        <para>
-            Note that inside the <filename>mymachine.conf</filename> is the 
-            <filename>PREFERRED_VERSION_linux-yocto</filename> statement. 
-            This statement identifies the kernel that the BSP is going to use.
-            In this case, the BSP is using <filename>linux-yocto</filename>, which is the 
-            current Yocto Project kernel based on the Linux 3.4 release. 
-        </para>
-
-        <para>
-            The next configuration file in the new BSP layer we need to edit is
-            <filename>meta-mymachine/conf/layer.conf</filename>.
-            This file identifies build information needed for the new layer.  
-            You can see the 
-            "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-layer'>Layer Configuration File</ulink>" section
-            in The Board Support Packages (BSP) Development Guide for more information on this configuration file.  
-            Basically, we are changing the existing statements to work with our BSP. 
-        </para>
-
-        <para>
-            The file contains these statements that reference the Fish River Island 2 BSP:
-            <literallayout class='monospaced'>
-     BBFILE_COLLECTIONS += "fri2"
-     BBFILE_PATTERN_fri2 := "^${LAYERDIR}/"
-     BBFILE_PRIORITY_fri2 = "6"
-
-     LAYERDEPENDS_fri2 = "intel"
-            </literallayout>
-        </para>
-
-        <para>
-            Simply substitute the machine string name <filename>fri2</filename>
-            with the new machine name <filename>mymachine</filename> to get the following:
-            <literallayout class='monospaced'>
-     BBFILE_COLLECTIONS += "mymachine"
-     BBFILE_PATTERN_mymachine := "^${LAYERDIR}/"
-     BBFILE_PRIORITY_mymachine = "6"
-
-     LAYERDEPENDS_mymachine = "intel"
-            </literallayout>
-        </para>
-    </section>
-
-    <section id='changing-the-recipes-in-your-bsp'>
-        <title>Changing the Recipes in Your BSP</title>
-
-        <para>
-            Now we will take a look at the recipes in your new layer.  
-            The standard BSP structure has areas for BSP, graphics, core, and kernel recipes.  
-            When you create a BSP, you use these areas for appropriate recipes and append files.  
-            Recipes take the form of <filename>.bb</filename> files, while append files take
-            the form of <filename>.bbappend</filename> files.  
-            If you want to leverage the existing recipes the OpenEmbedded build system uses
-            but change those recipes, you can use <filename>.bbappend</filename> files.  
-            All new recipes and append files for your layer must go in the layer’s 
-            <filename>recipes-bsp</filename>, <filename>recipes-kernel</filename>, 
-            <filename>recipes-core</filename>, and 
-            <filename>recipes-graphics</filename> directories.    
-        </para>
-
-        <section id='changing-recipes-bsp'>
-            <title>Changing&nbsp;&nbsp;<filename>recipes-bsp</filename></title>
-
-            <para>
-                First, let's look at <filename>recipes-bsp</filename>.
-                For this example we are not adding any new BSP recipes.  
-                And, we only need to remove the formfactor we do not want and change the name of 
-                the remaining one that doesn't support EMGD.  
-                These commands take care of the <filename>recipes-bsp</filename> recipes:
-                <literallayout class='monospaced'>
-     $ rm -rf meta-mymachine/recipes-bsp/formfactor/formfactor/fri2
-     $ mv meta-mymachine/recipes-bsp/formfactor/formfactor/fri2-noemgd/ \
-     meta-mymachine/recipes-bsp/formfactor/formfactor/mymachine
-                </literallayout>
-            </para>
-        </section>
-
-        <section id='changing-recipes-graphics'>
-            <title>Changing&nbsp;&nbsp;<filename>recipes-graphics</filename></title>
-
-            <para>
-                Now let's look at <filename>recipes-graphics</filename>.
-                For this example we want to remove anything that supports EMGD and 
-                be sure to rename remaining directories appropriately.  
-                The following commands clean up the <filename>recipes-graphics</filename> directory:
-                <literallayout class='monospaced'>
-     $ rm -rf meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/fri2
-     $ mv meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/fri2-noemgd \
-        meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/mymachine   
-                </literallayout>
-            </para>
-
-            <para>
-                At this point the <filename>recipes-graphics</filename> directory just has files that 
-                support Video Electronics Standards Association (VESA) graphics modes and not EMGD.  
-            </para>
-        </section>
-
-        <section id='changing-recipes-kernel'>
-            <title>Changing&nbsp;&nbsp;<filename>recipes-kernel</filename></title>
-
-            <para>
-                Finally, let's look at <filename>recipes-kernel</filename> changes.
-                Recall that the BSP uses the <filename>linux-yocto</filename> kernel as determined
-                earlier in the <filename>mymachine.conf</filename>.
-                The recipe for that kernel is not located in the  
-                BSP layer but rather in the Source Directory at 
-                <filename>meta/recipes-kernel/linux</filename> and is 
-                named <filename>linux-yocto_3.4.bb</filename>.
-                The <filename>SRCREV_machine</filename> and <filename>SRCREV_meta</filename>
-                statements point to the exact commits used by the Yocto Project development team
-                in their source repositories that identify the right kernel for our hardware.
-                In other words, the <filename>SRCREV</filename> values are simply Git commit 
-                IDs that identify which commit on each
-                of the kernel branches (machine and meta) will be checked out and used to build
-                the kernel.
-            </para>
- 
-            <para>
-                However, in the <filename>meta-mymachine</filename> layer in 
-                <filename>recipes-kernel/linux</filename> resides a <filename>.bbappend</filename>
-                file named <filename>linux-yocto_3.4.bbappend</filename> that 
-                appends the information to the recipe of the same name 
-                that is found in <filename>meta/recipes-kernel/linux</filename>.
-                Thus, the <filename>SRCREV</filename> statements in our 
-                <filename>mymachine</filename> append file override
-                the more general statements found in the more general recipe.
-            </para>
-
-            <para>
-                The <filename>SRCREV</filename> statements in the 
-                <filename>mymachine</filename> append file currently identify
-                the kernel that supports the Fish River Island 2 BSP with and without EMGD support.
-                Here are the statements:
-                <note>The commit ID strings used in this manual might not match the actual commit
-                    ID strings found in the <filename>linux-yocto_3.4.bbappend</filename> file.
-                    For the example, this difference does not matter.</note> 
-                <literallayout class='monospaced'>
-     SRCREV_machine_pn-linux-yocto_fri2 ?= \
-        "59c3ff750831338d05ab67d5efd7fc101c451aff"
-     #SRCREV_meta_pn-linux-yocto_fri2 ?= \
-        "c5bddf8ea379406ffec550528e17b777a0eba24b"
-
-     SRCREV_machine_pn-linux-yocto_fri2-noemgd ?= \
-        "59c3ff750831338d05ab67d5efd7fc101c451aff"
-     #SRCREV_meta_pn-linux-yocto_fir2-noemgd ?= \
-        "c5bddf8ea379406ffec550528e17b777a0eba24b"
-                </literallayout>
-                <note>The <filename>SRCREV_meta_pn-linux-yocto_fir2-noemgd</filename>
-                   statements in the <filename>mymachine</filename> append file, 
-                   which originated from the Fish River Island 2 BSP, are 
-                   commented out.
-                   The reason they are not used is because the commit IDs are identical to 
-                   those in the general <filename>linux-yocto_3.4.bbappend</filename> recipe, 
-                   which is found in <filename>meta/recipes-kernel/linux</filename>.
-                   </note>
-            </para>
-
-            <para>
-                You will notice that there are two pairs of <filename>SRCREV</filename> statements.  
-                The top pair identifies the kernel that supports
-                EMGD, which we don’t care about in this example.  
-                The bottom pair identifies the kernel that we will use:  
-                <filename>linux-yocto</filename>.  
-                At this point though, the unique commit strings all are still associated with 
-                Fish River Island 2 and not <filename>meta-mymachine</filename>.
-            </para>
-
-            <para>  
-                To fix this situation in <filename>linux-yocto_3.4.bbappend</filename>
-                for <filename>mymachine</filename>,
-                we delete the two <filename>SRCREV</filename> statements that support 
-                EMGD (the top pair).
-                We also change the remaining pair to specify <filename>mymachine</filename>
-                and insert the commit identifiers to identify the kernel in which we 
-                are interested, which will be based on the <filename>atom-pc-standard</filename>
-                kernel.
-                In this case, because we're working with the &DISTRO_NAME; branch of everything, we
-                need to use the <filename>SRCREV</filename> values for the atom-pc branch
-                that are associated with the &DISTRO_NAME; release. 
-            </para>
-
-            <para> 
-                To find the machine value, we need to find the <filename>SRCREV</filename>
-                value that &DISTRO_NAME; uses for the atom-pc branch, which we find in the
-                <filename>poky/meta-yocto-bsp/recipes-kernel/linux/linux-yocto_3.4.bbappend</filename>
-                file.
-                The machine <filename>SRCREV</filename> we want is in the 
-                <filename>SRCREV_machine_atom-pc</filename> variable.
-            </para>
-
-            <para>  
-                The meta <filename>SRCREV</filename> isn't specified in this file, so if you    
-                needed it, you would find it in the base kernel recipe in the
-                <filename>poky/meta/recipes-kernel/linux/linux-yocto_3.4.bb</filename>.
-                Recall that for this example the commit ID's for the <filename>SRCREV</filename>
-                meta statements are identical and do not have to be used in the 
-                <filename>mymachine</filename> append file.
-            </para>
-
-            <para>  
-                Here are the final <filename>SRCREV</filename> statements for the 
-                <filename>mymachine</filename> append file:
-                <literallayout class='monospaced'>
-     SRCREV_machine_pn-linux-yocto_mymachine ?= \
-        "0985844fa6235422c67ef269952fa4e765f252f9"
-     #SRCREV_meta_pn-linux-yocto_mymachine ?= \
-        "c5bddf8ea379406ffec550528e17b777a0eba24b"
-                </literallayout>
-            </para>
-
-            <para>
-                In this example, we're using the <filename>SRCREV</filename> values we 
-                found already captured in the &DISTRO_NAME; release because we're creating a BSP based on 
-                &DISTRO_NAME;.  
-                If, instead, we had based our BSP on the master branches, we would want to use 
-                the most recent <filename>SRCREV</filename> values taken directly from the kernel's
-                repository.
-                We will not be doing that for this example.
-                However, if you do base a future BSP on master and
-                if you are familiar with Git repositories, you probably won’t have trouble locating the 
-                exact commit strings in the Yocto Project source repositories you need to change 
-                the <filename>SRCREV</filename> statements.  
-                You can find all the <filename>machine</filename> and <filename>meta</filename> 
-                branch points (commits) for the <filename>linux-yocto-3.4</filename> kernel at
-                <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/linux-yocto-3.4'></ulink>.  
-            </para>
-
-            <para>
-                If you need a little more assistance after going to the link then do the following:
-                <orderedlist>
-                    <listitem><para>Expand the list of branches by clicking <filename>[…]</filename></para></listitem>
-                    <listitem><para>Click on the <filename>standard/default/common-pc/atom-pc</filename> 
-                        branch</para></listitem>
-                    <listitem><para>Click on the commit column header to view the top commit</para></listitem>
-                    <listitem><para>Copy the commit string for use in the 
-                        <filename>linux-yocto_3.4.bbappend</filename> file</para></listitem>
-                </orderedlist>
-            </para>
-
-            <para>
-                For the <filename>SRCREV</filename> statement that points to the <filename>meta</filename>
-                branch use the same procedure except expand the <filename>meta</filename>
-                branch in step 2 above.
-            </para>
-
-            <para>
-                Also in the <filename>linux-yocto_3.4.bbappend</filename> file are 
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>, 
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>, 
-                and 
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> statements.  
-                Two sets of these exist: one set supports EMGD and one set does not.
-                Because we are not interested in supporting EMGD those three can be deleted.
-                The remaining three must be changed so that <filename>mymachine</filename> replaces
-                <filename>fri2-noemgd</filename> and <filename>fri2</filename>.
-            </para>
-
-            <para>
-                Because we are using the <filename>atom-pc</filename> branch for this new BSP, we can also find
-                the exact branch we need for the <filename>KMACHINE</filename>  
-                and <filename>KBRANCH</filename> variables in our new BSP from the value
-                we find in the
-                <filename>poky/meta-yocto-bsp/recipes-kernel/linux/linux-yocto_3.4.bbappend</filename>
-                file we looked at in a previous step.  
-                In this case, the values we want are in the <filename>KMACHINE_atom-pc</filename> variable
-                and the <filename>KBRANCH_atom-pc</filename> variables in that file.
-                Here is the final <filename>linux-yocto_3.4.bbappend</filename> file after all 
-                the edits:
-                <literallayout class='monospaced'>
-     FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
-
-     COMPATIBLE_MACHINE_mymachine = "mymachine"
-     KMACHINE_mymachine  = "atom-pc"
-     KBRANCH_mymachine  = "standard/default/common-pc/atom-pc"
-
-     SRCREV_machine_pn-linux-yocto_mymachine ?= \
-        "f29531a41df15d74be5ad47d958e4117ca9e489e"
-     SRCREV_meta_pn-linux-yocto_mymachine ?= \
-        "b14a08f5c7b469a5077c10942f4e1aec171faa9d"
-                </literallayout>
-            </para>
-        </section>
-    </section>
-
-    <section id='bsp-recipe-change-summary'>
-        <title>BSP Recipe Change Summary</title>
-
-        <para>
-            In summary, the edits to the layer’s recipe files result in removal of any files and 
-            statements that do not support your targeted hardware in addition to the inclusion 
-            of any new recipes you might need.  
-            In this example, it was simply a matter of ridding the new layer 
-            <filename>meta-mymachine</filename> of any code that supported the EMGD features
-            and making sure we were identifying the kernel that supports our example, which
-            is the <filename>atom-pc-standard</filename> kernel.  
-            We did not introduce any new recipes to the layer. 
-        </para>
-
-        <para>
-            Finally, it is also important to update the layer’s <filename>README</filename>
-            file so that the information in it reflects your BSP.
-        </para>
-    </section>
-</section>
-
-<section id='preparing-for-the-build-app'>
-    <title>Preparing for the Build</title>
-
-    <para>
-        To get ready to build your image that uses the new layer you need to do the following:
-        <orderedlist>
-            <listitem><para>Get the environment ready for the build by sourcing the environment 
-                script. 
-                The environment script is in the top-level of the Source Directory.
-                The script has the string 
-                <filename>init-build-env</filename> in the file’s name.  
-                For this example, the following command gets the build environment ready:                       
-                <literallayout class='monospaced'>
-     $ source oe-init-build-env yocto-build
-                </literallayout>
-                When you source the script, a build directory is created in the current 
-                working directory.  
-                In our example we were in the <filename>poky</filename> directory.  
-                Thus, entering the previous command created the <filename>yocto-build</filename> directory.  
-                If you do not provide a name for the build directory it defaults to 
-                <filename>build</filename>.  
-                The <filename>yocto-build</filename> directory contains a
-                <filename>conf</filename> directory that has 
-                two configuration files you will need to check:  <filename>bblayers.conf</filename>
-                and <filename>local.conf</filename>.</para></listitem>
-            <listitem><para>Check and edit the resulting <filename>local.conf</filename> file.
-                This file minimally identifies the machine for which to build the image by 
-                configuring the <filename>MACHINE</filename> variable.  
-                For this example you must set the variable to mymachine as follows:
-                <literallayout class='monospaced'>
-     MACHINE ??= “mymachine”
-                </literallayout>
-                You should also be sure any other variables in which you are interested are set.  
-                Some variables to consider are <filename>BB_NUMBER_THREADS</filename>
-                and <filename>PARALLEL_MAKE</filename>, both of which can greatly reduce your build time 
-                if your development system supports multiple cores.
-                For development systems that support multiple cores, a good rule of thumb is to set 
-                both the <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename> 
-                variables to twice the number of cores your system supports.</para></listitem>
-            <listitem><para>Update the <filename>bblayers.conf</filename> file so that it includes 
-                both the path to your new BSP layer and the path to the 
-                <filename>meta-intel</filename> layer.  
-                In this example, you need to include both these paths as part of the 
-                <filename>BBLAYERS</filename> variable:
-                <literallayout class='monospaced'>
-     $HOME/poky/meta-intel
-     $HOME/poky/meta-intel/meta-mymachine
-                </literallayout></para></listitem>
-        </orderedlist>
-    </para>
-
-    <para>
-        The  
-        <ulink url='&YOCTO_DOCS_REF_URL;#ref-variables-glos'>Variables Glossary</ulink> chapter in the 
-        Yocto Project Reference Manual has more information on configuration variables.
-    </para>
-</section>
-
-<section id='building-the-image-app'>
-    <title>Building and Booting the Image</title>
-
-    <para>
-        To build the image for our <filename>meta-mymachine</filename> BSP enter the following command 
-        from the same shell from which you ran the setup script.  
-        You should run the <filename>bitbake</filename> command without any intervening shell commands.  
-        For example, moving your working directory around could cause problems.  
-        Here is the command for this example:
-        <literallayout class='monospaced'>
-     $ bitbake -k core-image-sato
-        </literallayout>
-    </para>
-
-    <para>
-        This command specifies an image that has Sato support and that can be run from a USB device or 
-        from a CD without having to first install anything.  
-        The build process takes significant time and includes thousands of tasks, which are reported 
-        at the console.  
-        If the build results in any type of error you should check for misspellings in the 
-        files you changed or problems with your host development environment such as missing packages.
-    </para>
-
-    <para>
-        Finally, once you have an image, you can try booting it from a device
-        (e.g. a USB device).
-        To prepare a bootable USB device, insert a USB flash drive into your build system and
-        copy the <filename>.hddimg</filename> file, located in the 
-        <filename>poky/build/tmp/deploy/images</filename>
-        directory after a successful build to the flash drive.  
-        Assuming the USB flash drive takes device <filename>/dev/sdf</filename>, 
-        use <filename>dd</filename> to copy the live image to it.  
-        For example:
-        <literallayout class='monospaced'>
-     # dd if=core-image-sato-mymachine-20111101223904.hddimg of=/dev/sdf
-     # sync
-     # eject /dev/sdf
-        </literallayout>
-        You should now have a bootable USB flash device.  
-    </para>
-
-    <para>
-        Insert the device
-        into a bootable USB socket on the target, and power it on.  
-        The system should boot to the Sato graphical desktop.
-        <footnote><para>Because 
-            this new image is not in any way tailored to the system you're
-            booting it on, which is assumed to be some sort of atom-pc (netbook) system for this
-            example, it might not be completely functional though it should at least boot to a text
-            prompt.  
-            Specifically, it might fail to boot into graphics without some tweaking.  
-            If this ends up being the case, a possible next step would be to replace the 
-            <filename>mymachine.conf</filename>
-            contents with the contents of <filename>atom-pc.conf</filename> and replace 
-            <filename>xorg.conf</filename> with <filename>atom-pc xorg.conf</filename>
-            in <filename>meta-yocto</filename> and see if it fares any better.  
-            In any case, following the previous steps will give you a buildable image that 
-            will probably boot on most systems.
-            Getting things working like you want
-            them to for your hardware will normally require some amount of experimentation with
-            configuration settings.</para></footnote> 
-    </para>
-
-    <para>
-        For reference, the sato image produced by the previous steps for &DISTRO_NAME; 
-        should look like the following in terms of size.
-        If your sato image is much different from this,
-        you probably made a mistake in one of the above steps:
-        <literallayout class='monospaced'>
-     260538368 2012-04-27 01:44 core-image-sato-mymachine-20120427025051.hddimg
-        </literallayout>
-        <note>The previous instructions are also present in the README that was copied
-        from meta-fri2, which should also be updated to reflect the specifics of your
-        new BSP.  
-        That file and the <filename>README.hardware</filename> file in the top-level 
-        <filename>poky</filename> directory
-        also provides some suggestions for things to try if booting fails and produces
-        strange error messages.</note>
-    </para>
-</section>
-</appendix>
-
-
-<!--
-vim: expandtab tw=80 ts=4
--->

documentation/dev-manual/dev-manual-intro.xml

@@ -10,22 +10,22 @@
 
         <para>
             Welcome to the Yocto Project Development Manual!
-            This manual gives you an idea of how to use the Yocto Project to develop embedded Linux 
-            images and user-space applications to run on targeted devices. 
+            This manual gives you an idea of how to use the Yocto Project to develop embedded Linux
+            images and user-space applications to run on targeted devices.
             Reading this manual gives you an overview of image, kernel, and user-space application development
-            using the Yocto Project. 
+            using the Yocto Project.
             Because much of the information in this manual is general, it contains many references to other
             sources where you can find more detail.
             For example, detailed information on Git, repositories and open source in general
-            can be found in many places.  
-            Another example is how to get set up to use the Yocto Project, which our Yocto Project 
+            can be found in many places.
+            Another example is how to get set up to use the Yocto Project, which our Yocto Project
             Quick Start covers.
         </para>
 
-        <para>  
-            The Yocto Project Development Manual, however, does provide detailed examples on how to create a 
-            Board Support Package (BSP), change the kernel source code, and reconfigure the kernel.
-            You can find this information in the appendices of the manual.
+        <para>
+            The Yocto Project Development Manual, however, does provide detailed examples
+            on how to change the kernel source code, reconfigure the kernel, and develop
+            an application using the popular <trademark class='trade'>Eclipse</trademark> IDE.
         </para>
     </section>
 
@@ -35,16 +35,16 @@
         <para>
             The following list describes what you can get from this guide:
             <itemizedlist>
-                <listitem><para>Information that lets you get set 
+                <listitem><para>Information that lets you get set
                     up to develop using the Yocto Project.</para></listitem>
-                <listitem><para>Information to help developers who are new to the open source environment 
-                    and to the distributed revision control system Git, which the Yocto Project 
+                <listitem><para>Information to help developers who are new to the open source environment
+                    and to the distributed revision control system Git, which the Yocto Project
                     uses.</para></listitem>
                 <listitem><para>An understanding of common end-to-end development models and tasks.</para></listitem>
-                <listitem><para>Development case overviews for both system development and user-space 
+                <listitem><para>Development case overviews for both system development and user-space
                     applications.</para></listitem>
-                <listitem><para>An overview and understanding of the emulation environment used with 
-                    the Yocto Project (QEMU).</para></listitem>
+                <listitem><para>An overview and understanding of the emulation environment used with
+                    the Yocto Project - the Quick EMUlator (QEMU).</para></listitem>
                 <listitem><para>An understanding of basic kernel architecture and concepts.</para></listitem>
                 <listitem><para>Many references to other sources of related information.</para></listitem>
             </itemizedlist>
@@ -57,18 +57,18 @@
         <para>
             This manual will not give you the following:
             <itemizedlist>
-                <listitem><para>Step-by-step instructions if those instructions exist in other Yocto 
-                    Project documentation.  
-                    For example, the Yocto Project Application Developer's Guide contains detailed 
-                    instruction on how to run the 
+                <listitem><para>Step-by-step instructions if those instructions exist in other Yocto
+                    Project documentation.
+                    For example, the Yocto Project Application Developer's Guide contains detailed
+                    instruction on how to run the
                     <ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>,
                     which is used to set up a cross-development environment.</para></listitem>
-                <listitem><para>Reference material.  
-                    This type of material resides in an appropriate reference manual.  
-                    For example, system variables are documented in the 
+                <listitem><para>Reference material.
+                    This type of material resides in an appropriate reference manual.
+                    For example, system variables are documented in the
                     <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>.</para></listitem>
-                <listitem><para>Detailed public information that is not specific to the Yocto Project.  
-                    For example, exhaustive information on how to use Git is covered better through the 
+                <listitem><para>Detailed public information that is not specific to the Yocto Project.
+                    For example, exhaustive information on how to use Git is covered better through the
                     Internet than in this manual.</para></listitem>
             </itemizedlist>
         </para>
@@ -76,58 +76,58 @@
 
     <section id='other-information'>
         <title>Other Information</title>
- 
+
         <para>
             Because this manual presents overview information for many different topics, you will
             need to supplement it with other information.
             The following list presents other sources of information you might find helpful:
             <itemizedlist>
                 <listitem><para><emphasis>The <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>:
-                    </emphasis> The home page for the Yocto Project provides lots of information on the project 
+                    </emphasis> The home page for the Yocto Project provides lots of information on the project
                     as well as links to software and documentation.</para></listitem>
                 <listitem><para><emphasis>
-                    <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>:</emphasis> This short document lets you get started 
+                    <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>:</emphasis> This short document lets you get started
                     with the Yocto Project quickly and start building an image.</para></listitem>
-                <listitem><para><emphasis> 
-                    <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>:</emphasis> This manual is a reference 
-                    guide to the OpenEmbedded build system known as "Poky."  
-                    The manual also contains a reference chapter on Board Support Package (BSP) 
+                <listitem><para><emphasis>
+                    <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>:</emphasis> This manual is a reference
+                    guide to the OpenEmbedded build system known as "Poky."
+                    The manual also contains a reference chapter on Board Support Package (BSP)
                     layout.</para></listitem>
                 <listitem><para><emphasis>
                     <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>:</emphasis>
-                    This guide provides information that lets you get going with the Application 
-                    Development Toolkit (ADT) and stand-alone cross-development toolchains to 
+                    This guide provides information that lets you get going with the Application
+                    Development Toolkit (ADT) and stand-alone cross-development toolchains to
                     develop projects using the Yocto Project.</para></listitem>
                 <listitem><para><emphasis>
                     <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>:</emphasis>
-                    This guide defines the structure for BSP components.  
+                    This guide defines the structure for BSP components.
                     Having a commonly understood structure encourages standardization.</para></listitem>
                 <listitem><para><emphasis>
                     <ulink url='&YOCTO_DOCS_KERNEL_URL;'>Yocto Project Kernel Architecture and Use Manual</ulink>:</emphasis>
-                    This manual describes the architecture of the Yocto Project kernel and provides 
+                    This manual describes the architecture of the Yocto Project kernel and provides
                     some work flow examples.</para></listitem>
                 <listitem><para><emphasis>
                     <ulink url='http://www.youtube.com/watch?v=3ZlOu-gLsh0'>
                     Eclipse IDE Yocto Plug-in</ulink>:</emphasis> A step-by-step instructional video that
-                    demonstrates how an application developer uses Yocto Plug-in features within 
+                    demonstrates how an application developer uses Yocto Plug-in features within
                     the Eclipse IDE.</para></listitem>
                 <listitem><para><emphasis>
                     <ulink url='&YOCTO_WIKI_URL;/wiki/FAQ'>FAQ</ulink>:</emphasis>
                     A list of commonly asked questions and their answers.</para></listitem>
                 <listitem><para><emphasis>
                     <ulink url='&YOCTO_HOME_URL;/download/yocto/yocto-project-&DISTRO;-release-notes-poky-&POKYVERSION;'>
-                    Release Notes</ulink>:</emphasis> Features, updates and known issues for the current 
+                    Release Notes</ulink>:</emphasis> Features, updates and known issues for the current
                     release of the Yocto Project.</para></listitem>
                 <listitem><para><emphasis>
-                    <ulink url='&YOCTO_HOME_URL;/projects/hob'>
-                    Hob</ulink>:</emphasis> A graphical user interface for BitBake. 
+                    <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>
+                    Hob</ulink>:</emphasis> A graphical user interface for BitBake.
                     Hob's primary goal is to enable a user to perform common tasks more easily.</para></listitem>
                 <listitem><para><emphasis>
-                    <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance'>
-                    Build Appliance</ulink>:</emphasis> A bootable custom embedded Linux image you can 
-                    either build using a non-Linux development system (VMware applications) or download 
+                    <ulink url='&YOCTO_HOME_URL;/download/build-appliance-0'>
+                    Build Appliance</ulink>:</emphasis> A bootable custom embedded Linux image you can
+                    either build using a non-Linux development system (VMware applications) or download
                     from the Yocto Project website.
-                    See the <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance'>Build Appliance</ulink>
+                    See the <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance-manual'>Build Appliance</ulink>
                     page for more information.</para></listitem>
                 <listitem><para><emphasis>
                     <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink>:</emphasis>
@@ -135,20 +135,23 @@
                     If you find problems with the Yocto Project, you should report them using this
                     application.</para></listitem>
                 <listitem><para><emphasis>
-                    Yocto Project Mailing Lists:</emphasis> To subscribe to the Yocto Project mailing 
+                    Yocto Project Mailing Lists:</emphasis> To subscribe to the Yocto Project mailing
                     lists, click on the following URLs and follow the instructions:
                     <itemizedlist>
-                        <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> for a 
+                        <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> for a
                             Yocto Project Discussions mailing list.</para></listitem>
-                        <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> for a 
+                        <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> for a
                             Yocto Project Discussions mailing list about the Poky build system.</para></listitem>
                         <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto-announce'></ulink>
                             for a mailing list to receive official Yocto Project announcements for developments and
                             as well as Yocto Project milestones.</para></listitem>
+                        <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo'></ulink> for a
+                            listing of all public mailing lists on <filename>lists.yoctoproject.org</filename>.
+                            </para></listitem>
                     </itemizedlist></para></listitem>
                 <listitem><para><emphasis>Internet Relay Chat (IRC):</emphasis>
-                    Two IRC channels on freenode are available 
-                    for Yocto Project and Poky discussions: <filename>#yocto</filename> and 
+                    Two IRC channels on freenode are available
+                    for Yocto Project and Poky discussions: <filename>#yocto</filename> and
                     <filename>#poky</filename>, respectively.</para></listitem>
                 <listitem><para><emphasis>
                     <ulink url='&OH_HOME_URL;'>OpenedHand</ulink>:</emphasis>
@@ -157,30 +160,30 @@
                     OpenedHand was acquired by Intel Corporation in 2008.</para></listitem>
                 <listitem><para><emphasis>
                     <ulink url='http://www.intel.com/'>Intel Corporation</ulink>:</emphasis>
-                    A multinational semiconductor chip manufacturer company whose Software and 
+                    A multinational semiconductor chip manufacturer company whose Software and
                     Services Group created and supports the Yocto Project.
                     Intel acquired OpenedHand in 2008.</para></listitem>
                 <listitem><para><emphasis>
                     <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis>
-                    The build system used by the Yocto Project. 
-                    This project is the upstream, generic, embedded distribution from which the Yocto 
+                    The build system used by the Yocto Project.
+                    This project is the upstream, generic, embedded distribution from which the Yocto
                     Project derives its build system (Poky) from and to which it contributes.</para></listitem>
                 <listitem><para><emphasis>
                     <ulink url='http://developer.berlios.de/projects/bitbake/'>
-                    BitBake</ulink>:</emphasis> The tool used by the OpenEmbedded build system 
+                    BitBake</ulink>:</emphasis> The tool used by the OpenEmbedded build system
                     to process project metadata.</para></listitem>
                 <listitem><para><emphasis>
                     BitBake User Manual:</emphasis>
                     A comprehensive guide to the BitBake tool.
-                    If you want information on BitBake, see the user manual inculded in the 
-                    <filename>bitbake/doc/manual</filename> directory of the 
+                    If you want information on BitBake, see the user manual inculded in the
+                    <filename>bitbake/doc/manual</filename> directory of the
                     <link linkend='source-directory'>Source Directory</link>.</para></listitem>
                 <listitem><para><emphasis>
                     <ulink url='http://wiki.qemu.org/Index.html'>Quick EMUlator (QEMU)</ulink>:
                     </emphasis> An open-source machine emulator and virtualizer.</para></listitem>
             </itemizedlist>
         </para>
-    </section>   
+    </section>
 </chapter>
 <!--
 vim: expandtab tw=80 ts=4

documentation/dev-manual/dev-manual-kernel-appendix-orig.xml

@@ -7,96 +7,105 @@
 <title>Kernel Modification Example</title>
 
     <para>
-        Kernel modification involves changing or adding configurations to an existing kernel,  
-        changing or adding recipes to the kernel that are needed to support specific hardware features, 
-        or even altering the source code itself.  
-        This appendix presents simple examples that modify the kernel source code, 
+        Kernel modification involves changing or adding configurations to an existing kernel,
+        changing or adding recipes to the kernel that are needed to support specific hardware features,
+        or even altering the source code itself.
+        This appendix presents simple examples that modify the kernel source code,
         change the kernel configuration, and add a kernel source recipe.
+        <note>
+            You can use the <filename>yocto-kernel</filename> script
+            found in the <link linkend='source-directory'>Source Directory</link>
+            under <filename>scripts</filename> to manage kernel patches and configuration.
+            See the "<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'>Managing kernel Patches and Config Items with yocto-kernel</ulink>"
+            section in the Yocto Project Board Support Packages (BSP) Developer's Guide for
+            more information.</note>
     </para>
 
     <section id='modifying-the-kernel-source-code'>
         <title>Modifying the Kernel Source Code</title>
 
         <para>
-            This example adds some simple QEMU emulator console output at boot time by 
+            This example adds some simple QEMU emulator console output at boot time by
             adding <filename>printk</filename> statements to the kernel's
             <filename>calibrate.c</filename> source code file.
             Booting the modified image causes the added messages to appear on the emulator's
             console.
-        </para> 
+        </para>
 
         <section id='understanding-the-files-you-need'>
             <title>Understanding the Files You Need</title>
-          
+
             <para>
-                Before you modify the kernel, you need to know what Git repositories and file 
+                Before you modify the kernel, you need to know what Git repositories and file
                 structures you need.
-                Briefly, you need the following: 
+                Briefly, you need the following:
                 <itemizedlist>
-                    <listitem><para>A local 
-                        <link linkend='source-directory'>source directory</link> for the 
+                    <listitem><para>A local
+                        <link linkend='source-directory'>Source Directory</link> for the
                         poky Git repository</para></listitem>
                     <listitem><para>Local copies of the
                         <link linkend='poky-extras-repo'><filename>poky-extras</filename></link>
-                        Git repository placed within the source directory.</para></listitem>  
-                    <listitem><para>A bare clone of the 
-                        <link linkend='local-kernel-files'>Yocto Project Kernel</link> upstream Git 
+                        Git repository placed within the Source Directory.</para></listitem>
+                    <listitem><para>A bare clone of the
+                        <link linkend='local-kernel-files'>Yocto Project Kernel</link> upstream Git
                         repository to which you want to push your modifications.
                         </para></listitem>
-                    <listitem><para>A copy of that bare clone in which you make your source 
+                    <listitem><para>A copy of that bare clone in which you make your source
                         modifications</para></listitem>
                 </itemizedlist>
             </para>
 
-            <para> 
-                The following figure summarizes these four areas.  
-                Within each rectangular that represents a data structure, a  
-                host development directory pathname appears at the 
-                lower left-hand corner of the box.  
+            <para>
+                The following figure summarizes these four areas.
+                Within each rectangular that represents a data structure, a
+                host development directory pathname appears at the
+                lower left-hand corner of the box.
                 These pathnames are the locations used in this example.
                 The figure also provides key statements and commands used during the kernel
                 modification process:
             </para>
 
             <para>
-                <imagedata fileref="figures/kernel-example-repos-denzil.png" width="7in" depth="5in" 
+                <imagedata fileref="figures/kernel-example-repos-generic.png" width="7in" depth="5in"
                     align="center" scale="100" />
             </para>
 
             <para>
                 Here is a brief description of the four areas:
                 <itemizedlist>
-                    <listitem><para><emphasis>Local Source Directory:</emphasis> 
-                        This area contains all the metadata that supports building images 
+                    <listitem><para><emphasis>Local Source Directory:</emphasis>
+                        This area contains all the metadata that supports building images
                         using the OpenEmbedded build system.
-                        In this example, the source directory also 
-                        contains the build directory, which contains the configuration directory 
+                        In this example, the
+                        <link linkend='source-directory'>Source Directory</link> also
+                        contains the
+                        <link linkend='build-directory'>Build Directory</link>,
+                        which contains the configuration directory
                         that lets you control the build.
-                        Also in this example, the source directory contains local copies of the 
+                        Also in this example, the Source Directory contains local copies of the
                         <filename>poky-extras</filename> Git repository.</para>
                         <para>See the bulleted item
                         "<link linkend='local-yp-release'>Yocto Project Release</link>"
                         for information on how to get these files on your local system.</para></listitem>
-                    <listitem><para><emphasis>Local copies of the<filename>poky-extras</filename> 
-                        Git Repository:</emphasis> 
-                        This area contains the <filename>meta-kernel-dev</filename> layer, 
+                    <listitem><para><emphasis>Local copies of the&nbsp;<filename>poky-extras</filename>&nbsp;Git Repository:</emphasis>
+                        This area contains the <filename>meta-kernel-dev</filename> layer,
                         which is where you make changes that append the kernel build recipes.
-                        You edit <filename>.bbappend</filename> files to locate your 
+                        You edit <filename>.bbappend</filename> files to locate your
                         local kernel source files and to identify the kernel being built.
                         This Git repository is a gathering place for extensions to the Yocto Project
                         (or really any) kernel recipes that faciliate the creation and development
                         of kernel features, BSPs or configurations.</para>
                         <para>See the bulleted item
-                        "<link linkend='poky-extras-repo'>The 
-                        <filename>poky-extras</filename> Git Repository</link>" 
-                        for information on how to get these files.</para></listitem>                
-                    <listitem><para><emphasis>Bare Clone of the Yocto Project kernel:</emphasis> 
-                        This bare Git repository tracks the upstream Git repository of the Linux 
+                        "<link linkend='poky-extras-repo'>The
+                        <filename>poky-extras</filename> Git Repository</link>"
+                        for information on how to get these files.</para></listitem>
+                    <listitem><para><emphasis>Bare Clone of the Yocto Project kernel:</emphasis>
+                        This bare Git repository tracks the upstream Git repository of the Linux
                         Yocto kernel source code you are changing.
                         When you modify the kernel you must work through a bare clone.
-                        All source code changes you make to the kernel must be committed and 
+                        All source code changes you make to the kernel must be committed and
                         pushed to the bare clone using Git commands.
-                        As mentioned, the <filename>.bbappend</filename> file in the 
+                        As mentioned, the <filename>.bbappend</filename> file in the
                         <filename>poky-extras</filename> repository points to the bare clone
                         so that the build process can locate the locally changed source files.</para>
                         <para>See the bulleted item
@@ -104,16 +113,16 @@
                         for information on how to set up the bare clone.
                         </para></listitem>
                     <listitem><para><emphasis>Copy of the Yocto Project Kernel Bare Clone:</emphasis>
-                        This Git repository contains the actual source files that you modify.  
+                        This Git repository contains the actual source files that you modify.
                         Any changes you make to files in this location need to ultimately be pushed
                         to the bare clone using the <filename>git push</filename> command.</para>
                         <para>See the bulleted item
                         "<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
                         for information on how to set up the bare clone.
-                        <note>Typically, Git workflows follow a scheme where changes made to a local area 
+                        <note>Typically, Git workflows follow a scheme where changes made to a local area
                         are pulled into a Git repository.
-                        However, because the <filename>git pull</filename> command does not work 
-                        with bare clones, this workflow pushes changes to the 
+                        However, because the <filename>git pull</filename> command does not work
+                        with bare clones, this workflow pushes changes to the
                         repository even though you could use other more complicated methods to
                         get changes into the bare clone.</note>
                         </para></listitem>
@@ -125,27 +134,29 @@
             <title>Setting Up the Local Source Directory</title>
 
             <para>
-                You can set up the source directory through tarball extraction or by 
-                cloning the <filename>poky</filename> Git repository.  
-                This example uses <filename>poky</filename> as the root directory of the 
-                local source directory.
+                You can set up the
+                <link linkend='source-directory'>Source Directory</link>
+                through tarball extraction or by
+                cloning the <filename>poky</filename> Git repository.
+                This example uses <filename>poky</filename> as the root directory of the
+                local Source Directory.
                 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 source directory set up, 
-                you have many development branches from which you can work. 
-                From inside the local repository you can see the branch names and the tag names used 
+                Once you have Source Directory set up,
+                you have many development branches from which you can work.
+                From inside the local repository you can see the branch names and the tag names used
                 in the upstream Git repository by 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. 
+                </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'>
@@ -160,23 +171,24 @@
             <title>Setting Up the Local poky-extras Git Repository</title>
 
             <para>
-                This example creates a local copy of the <filename>poky-extras</filename> Git 
-                repository inside the <filename>poky</filename> source directory.
-                See the bulleted item "<link linkend='poky-extras-repo'>The 
-                <filename>poky-extras</filename> Git Repository</link>" 
+                This example creates a local copy of the <filename>poky-extras</filename> Git
+                repository inside the <filename>poky</filename> Source Directory.
+                See the bulleted item "<link linkend='poky-extras-repo'>The
+                <filename>poky-extras</filename> Git Repository</link>"
                 for information on how to set up a local copy of the
                 <filename>poky-extras</filename> repository.
             </para>
 
             <para>
-                Because this example uses the Yocto Project &DISTRO; Release code 
-                named "&DISTRO_NAME;", which maps to the <filename>&DISTRO_NAME;</filename> 
-                branch in the repository, you need to be sure you are using that 
-                branch for <filename>poky-extra</filename>.
-                The following commands create and checkout the local 
+                Because this example uses the Yocto Project &DISTRO; Release code
+                named "&DISTRO_NAME;", which maps to the <filename>&DISTRO_NAME;</filename>
+                branch in the repository, you need to be sure you are using that
+                branch for <filename>poky-extras</filename>.
+                The following commands create and checkout the local
                 branch you are using for the <filename>&DISTRO_NAME;</filename>
                 branch:
                 <literallayout class='monospaced'>
+     $ cd ~/poky/poky-extras
      $ 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;'
@@ -188,29 +200,28 @@
             <title>Setting Up the Bare Clone and its Copy</title>
 
             <para>
-                This example modifies the <filename>linux-yocto-3.2</filename> kernel.
-                Thus, you need to create a bare clone of that kernel and then make a copy of the 
+                This example modifies the <filename>linux-yocto-3.4</filename> kernel.
+                Thus, you need to create a bare clone of that kernel and then make a copy of the
                 bare clone.
                 See the bulleted item
-                "<link linkend='local-kernel-files'>Yocto Project Kernel</link>" 
+                "<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
                 for information on how to do that.
             </para>
 
             <para>
-                The bare clone exists for the kernel build tools and simply as the receiving end 
+                The bare clone exists for the kernel build tools and simply as the receiving end
                 of <filename>git push</filename>
                 commands after you make edits and commits inside the copy of the clone.
-                The copy (<filename>my-linux-yocto-3.2-work</filename> in this example) has to have 
+                The copy (<filename>my-linux-yocto-3.4-work</filename> in this example) has to have
                 a local branch created and checked out for your work.
                 This example uses <filename>common-pc-base</filename> as the local branch.
                 The following commands create and checkout the branch:
                 <literallayout class='monospaced'>
-     $ cd ~/my-linux-yocto-3.2-work
-     $ git checkout -b common-pc-base origin/standard/default/common-pc/base
-     Checking out files: 100% (532/532), done.
-     Branch common-pc-base set up to track remote branch 
-        standard/default/common-pc/base from origin.
-     Switched to a new branch 'common-pc-base'
+     $ cd ~/my-linux-yocto-3.4-work
+     $ git checkout -b standard-common-pc-base origin/standard/common-pc/base
+     Branch standard-common-pc-base set up to track remote branch
+        standard/common-pc/base from origin.
+     Switched to a new branch 'standard-common-pc-base'
                 </literallayout>
             </para>
         </section>
@@ -219,22 +230,22 @@
             <title>Building and Booting the Default QEMU Kernel Image</title>
 
             <para>
-                Before we make changes to the kernel source files, this example first builds the 
+                Before we make changes to the kernel source files, this example first builds the
                 default image and then boots it inside the QEMU emulator.
                 <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-build-env</filename> script.
+                    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 
+                    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 <filename>BB_NUMBER_THREADS</filename> and 
-                    <filename>PARALLEL_MAKE</filename> to twice the number 
+                    As a guideline, set both <filename>BB_NUMBER_THREADS</filename> and
+                    <filename>PARALLEL_MAKE</filename> to twice the number
                     of cores your machine supports.
                 </note>
                 The following two commands <filename>source</filename> the build environment setup script
@@ -242,11 +253,36 @@
                 If necessary, the script creates the build directory:
                 <literallayout class='monospaced'>
      $ cd ~/poky
-     $ source oe-init-build-env
+     $ source &OE_INIT_FILE;
+     You had no conf/local.conf file. This configuration file has therefore been
+     created for you with some default values. You may wish to edit it to use a
+     different MACHINE (target hardware) or enable parallel build options to take
+     advantage of multiple cores for example. See the file for more information as
+     common configuration options are commented.
 
-          ### Shell environment set up for builds. ###
+     The Yocto Project has extensive documentation about OE including a reference manual
+     which can be found at:
+         http://yoctoproject.org/documentation
 
-     You can now run 'bitbake &lt;target&gt;'
+     For more information about OpenEmbedded see their website:
+         http://www.openembedded.org/
+
+     You had no conf/bblayers.conf file. The configuration file has been created for
+     you with some default values. To add additional metadata layers into your
+     configuration please add entries to this file.
+
+     The Yocto Project has extensive documentation about OE including a reference manual
+     which can be found at:
+         http://yoctoproject.org/documentation
+
+     For more information about OpenEmbedded see their website:
+         http://www.openembedded.org/
+
+
+
+     ### Shell environment set up for builds. ###
+
+     You can now run 'bitbake &lt;target&gt;>'
 
      Common targets are:
          core-image-minimal
@@ -269,7 +305,7 @@
                 before starting the build.</note>
             </para>
 
-            <para>  
+            <para>
                 After the build completes, you can start the QEMU emulator using the resulting image
                 <filename>qemux86</filename> as follows:
                 <literallayout class='monospaced'>
@@ -281,9 +317,9 @@
                 As the image boots in the emulator, console message and status output appears
                 across the terminal window.
                 Because the output scrolls by quickly, it is difficult to read.
-                To examine the output, you log into the system using the 
+                To examine the output, you log into the system using the
                 login <filename>root</filename> with no password.
-                Once you are logged in, issue the following command to scroll through the 
+                Once you are logged in, issue the following command to scroll through the
                 console output:
                 <literallayout class='monospaced'>
      # dmesg | less
@@ -301,7 +337,7 @@
 
             <para>
                 The file you change in this example is named <filename>calibrate.c</filename>
-                and is located in the <filename>my-linux-yocto-3.2-work</filename> Git repository
+                and is located in the <filename>my-linux-yocto-3.4-work</filename> Git repository
                 (the copy of the bare clone) in <filename>init</filename>.
                 This example simply inserts several <filename>printk</filename> statements
                 at the beginning of the <filename>calibrate_delay</filename> function.
@@ -324,7 +360,7 @@
            </para>
 
            <para>
-               Here is the altered code showing five new <filename>printk</filename> statements 
+               Here is the altered code showing five new <filename>printk</filename> statements
                near the top of the function:
                 <literallayout class='monospaced'>
      void __cpuinit calibrate_delay(void)
@@ -356,16 +392,16 @@
            </para>
 
            <para>
-               Once the source code has been modified, you need to use Git to push the changes to 
-               the bare clone.  
-               If you do not push the changes, then the OpenEmbedded build system will not pick 
+               Once the source code has been modified, you need to use Git to push the changes to
+               the bare clone.
+               If you do not push the changes, then the OpenEmbedded build system will not pick
                up the changed source files.
            </para>
 
            <para>
                The following command pushes the changes to the bare clone:
                <literallayout class='monospaced'>
-     $ git push origin common-pc-base:standard/default/common-pc/base
+     $ git push origin standard-common-pc-base:standard/default/common-pc/base
                </literallayout>
            </para>
        </section>
@@ -375,43 +411,43 @@
 
            <para>
                At this point, the source has been changed and pushed.
-               The example now defines some variables used by the OpenEmbedded build system 
+               The example now defines some variables used by the OpenEmbedded build system
                to locate your kernel source.
                You essentially need to identify where to find the kernel recipe and the changed source code.
-               You also need to be sure some basic configurations are in place that identify the 
+               You also need to be sure some basic configurations are in place that identify the
                type of machine you are building and to help speed up the build should your host support
                multiple-core and thread capabilities.
            </para>
 
            <para>
                Do the following to make sure the build parameters are set up for the example.
-               Once you set up these build parameters, they do not have to change unless you 
+               Once you set up these build parameters, they do not have to change unless you
                change the target architecture of the machine you are building or you move
                the bare clone, copy of the clone, or the <filename>poky-extras</filename> repository:
                <itemizedlist>
-                   <listitem><para><emphasis>Build for the Correct Target Architecture:</emphasis> The 
-                       <filename>local.conf</filename> file in the build directory defines the build's 
+                   <listitem><para><emphasis>Build for the Correct Target Architecture:</emphasis> The
+                       <filename>local.conf</filename> file in the build directory defines the build's
                        target architecture.
-                       By default, <filename>MACHINE</filename> is set to 
-                       <filename>qemux86</filename>, which specifies a 32-bit 
-                       <trademark class='registered'>Intel</trademark> Architecture 
-                       target machine suitable for the QEMU emulator.  
+                       By default, <filename>MACHINE</filename> is set to
+                       <filename>qemux86</filename>, which specifies a 32-bit
+                       <trademark class='registered'>Intel</trademark> Architecture
+                       target machine suitable for the QEMU emulator.
                        In this example, <filename>MACHINE</filename> is correctly configured.
                        </para></listitem>
-                   <listitem><para><emphasis>Optimize Build Time:</emphasis> Also in the 
-                       <filename>local.conf</filename> file are two variables that can speed your 
+                   <listitem><para><emphasis>Optimize Build Time:</emphasis> Also in the
+                       <filename>local.conf</filename> file are two variables that can speed your
                        build time if your host supports multi-core and multi-thread capabilities:
                        <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>.
-                       If the host system has multiple cores then you can optimize build time 
-                       by setting both these variables to twice the number of 
+                       If the host system has multiple cores then you can optimize build time
+                       by setting both these variables to twice the number of
                        cores.</para></listitem>
                    <listitem><para><emphasis>Identify Your <filename>meta-kernel-dev</filename>
-                       Layer:</emphasis> The <filename>BBLAYERS</filename> variable in the 
-                       <filename>bblayers.conf</filename> file found in the 
+                       Layer:</emphasis> The <filename>BBLAYERS</filename> variable in the
+                       <filename>bblayers.conf</filename> file found in the
                        <filename>poky/build/conf</filename> directory needs to have the path to your local
-                       <filename>meta-kernel-dev</filename> layer.  
-                       By default, the <filename>BBLAYERS</filename> variable contains paths to  
-                       <filename>meta</filename> and <filename>meta-yocto</filename> in the 
+                       <filename>meta-kernel-dev</filename> layer.
+                       By default, the <filename>BBLAYERS</filename> variable contains paths to
+                       <filename>meta</filename> and <filename>meta-yocto</filename> in the
                        <filename>poky</filename> Git repository.
                        Add the path to your <filename>meta-kernel-dev</filename> location.
                        Be sure to substitute your user information in the statement.
@@ -420,40 +456,44 @@
      BBLAYERS = " \
        /home/scottrif/poky/meta \
        /home/scottrif/poky/meta-yocto \
+       /home/scottrif/poky/meta-yocto-bsp \
        /home/scottrif/poky/poky-extras/meta-kernel-dev \
        "
                        </literallayout></para></listitem>
-                   <listitem><para><emphasis>Identify Your Source Files:</emphasis> In the 
-                       <filename>linux-yocto_3.2.bbappend</filename> file located in the 
+                   <listitem><para><emphasis>Identify Your Source Files:</emphasis> In the
+                       <filename>linux-yocto_3.4.bbappend</filename> file located in the
                        <filename>poky-extras/meta-kernel-dev/recipes-kernel/linux</filename>
-                       directory, you need to identify the location of the 
+                       directory, you need to identify the location of the
                        local source code, which in this example is the bare clone named
-                       <filename>linux-yocto-3.2.git</filename>.
+                       <filename>linux-yocto-3.4.git</filename>.
                        To do this, set the <filename>KSRC_linux_yocto</filename> variable to point to your
-                       local <filename>linux-yocto-3.2.git</filename> Git repository by adding the 
+                       local <filename>linux-yocto-3.4.git</filename> Git repository by adding the
                        following statement.
-                       Be sure to substitute your user information in the statement:
+                       Also, be sure the <filename>SRC_URI</filename> variable is pointing to
+                       your kernel source files by removing the comment.
+                       Finally, be sure to substitute your user information in the statement:
                        <literallayout class='monospaced'>
-     KSRC_linux_yocto_3_2 ?= "/home/scottrif/linux-yocto-3.2.git"
+     KSRC_linux_yocto_3_4 ?= "/home/scottrif/linux-yocto-3.4.git"
+     SRC_URI = "git://${KSRC_linux_yocto_3_4};protocol=file;nocheckout=1;branch=${KBRANCH},meta;name=machine,meta"
                        </literallayout></para></listitem>
                </itemizedlist>
            </para>
 
            <note>
-               <para>Before attempting to build the modified kernel, there is one more set of changes you 
+               <para>Before attempting to build the modified kernel, there is one more set of changes you
                need to make in the <filename>meta-kernel-dev</filename> layer.
-               Because all the kernel <filename>.bbappend</filename> files are parsed during the 
-               build process regardless of whether you are using them or not, you should either 
-               comment out the <filename>COMPATIBLE_MACHINE</filename> statements in all 
-               unused <filename>.bbappend</filename> files, or simply remove (or rename) all the files 
-               except the one your are using for the build 
-               (i.e. <filename>linux-yocto_3.2.bbappend</filename> in this example).</para>
+               Because all the kernel <filename>.bbappend</filename> files are parsed during the
+               build process regardless of whether you are using them or not, you should either
+               comment out the <filename>COMPATIBLE_MACHINE</filename> statements in all
+               unused <filename>.bbappend</filename> files, or simply remove (or rename) all the files
+               except the one your are using for the build
+               (i.e. <filename>linux-yocto_3.4.bbappend</filename> in this example).</para>
                <para>If you do not make one of these two adjustments, your machine will be compatible
-               with all the kernel recipes in the <filename>meta-kernel-dev</filename> layer. 
+               with all the kernel recipes in the <filename>meta-kernel-dev</filename> layer.
                When your machine is comapatible with all the kernel recipes, the build attempts
                to build all kernels in the layer.
                You could end up with build errors blocking your work.</para>
-           </note>            
+           </note>
        </section>
 
         <section id='building-and-booting-the-modified-qemu-kernel-image'>
@@ -464,14 +504,14 @@
                 Do the following:
                 <orderedlist>
                     <listitem><para>Your environment should be set up since you previously sourced
-                        the <filename>oe-init-build-env</filename> script.
+                        the <filename>&OE_INIT_FILE;</filename> script.
                         If it isn't, source the script again from <filename>poky</filename>.
                         <literallayout class='monospaced'>
      $ cd ~/poky
-     $ source oe-init-build-env
+     $ source &OE_INIT_FILE;
                         </literallayout>
                         </para></listitem>
-                    <listitem><para>Be sure old images are cleaned out by running the 
+                    <listitem><para>Be sure old images are cleaned out by running the
                         <filename>cleanall</filename> BitBake task as follows from your build directory:
                         <literallayout class='monospaced'>
      $ bitbake -c cleanall linux-yocto
@@ -484,7 +524,7 @@
                         <literallayout class='monospaced'>
      $ bitbake -k core-image-minimal
                         </literallayout></para></listitem>
-                    <listitem><para>Finally, boot the modified image in the QEMU emulator 
+                    <listitem><para>Finally, boot the modified image in the QEMU emulator
                         using this command:
                         <literallayout class='monospaced'>
      $ runqemu qemux86
@@ -493,7 +533,7 @@
             </para>
 
             <para>
-                Log into the machine using <filename>root</filename> with no password and then 
+                Log into the machine using <filename>root</filename> with no password and then
                 use the following shell command to scroll through the console's boot output.
                 <literallayout class='monospaced'>
      # dmesg | less
@@ -501,304 +541,11 @@
             </para>
 
             <para>
-                You should see the results of your <filename>printk</filename> statements 
+                You should see the results of your <filename>printk</filename> statements
                 as part of the output.
             </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-build-env</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-build-env
-
-          ### 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-build-env</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-build-env
-                </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.2</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.2.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>
 
 <!--

documentation/dev-manual/dev-manual-start.xml

@@ -7,14 +7,14 @@
 <title>Getting Started with the Yocto Project</title>
 
 <para>
-    This chapter introduces the Yocto Project and gives you an idea of what you need to get started.  
-    You can find enough information to set up your development host and build or use images for 
-    hardware supported by the Yocto Project by reading the 
+    This chapter introduces the Yocto Project and gives you an idea of what you need to get started.
+    You can find enough information to set up your development host and build or use images for
+    hardware supported by the Yocto Project by reading the
     <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
 </para>
 
 <para>
-    The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides 
+    The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides
     some higher-level concepts you might want to consider.
 </para>
 
@@ -22,24 +22,24 @@
     <title>Introducing the Yocto Project</title>
 
     <para>
-        The Yocto Project is an open-source collaboration project focused on embedded Linux development.  
-        The project currently provides a build system, which is 
+        The Yocto Project is an open-source collaboration project focused on embedded Linux development.
+        The project currently provides a build system, which is
         referred to as the OpenEmbedded build system in the Yocto Project documentation.
-        The Yocto Project provides various ancillary tools suitable for the embedded developer  
-        and also features the Sato reference User Interface, which is optimized for 
+        The Yocto Project provides various ancillary tools suitable for the embedded developer
+        and also features the Sato reference User Interface, which is optimized for
         stylus driven, low-resolution screens.
     </para>
 
     <para>
-        You can use the OpenEmbedded build system, which uses 
-        BitBake to develop complete Linux 
-        images and associated user-space applications for architectures based on ARM, MIPS, PowerPC, 
-        x86 and x86-64.  
+        You can use the OpenEmbedded build system, which uses
+        BitBake to develop complete Linux
+        images and associated user-space applications for architectures based on ARM, MIPS, PowerPC,
+        x86 and x86-64.
         While the Yocto Project does not provide a strict testing framework,
-        it does provide or generate for you artifacts that let you perform target-level and 
-        emulated testing and debugging.  
+        it does provide or generate for you artifacts that let you perform target-level and
+        emulated testing and debugging.
         Additionally, if you are an <trademark class='trade'>Eclipse</trademark>
-        IDE user, you can install an Eclipse Yocto Plug-in to allow you to 
+        IDE user, you can install an Eclipse Yocto Plug-in to allow you to
         develop within that familiar environment.
     </para>
 </section>
@@ -50,58 +50,59 @@
     <para>
         Here is what you need to get set up to use the Yocto Project:
         <itemizedlist>
-            <listitem><para><emphasis>Host System:</emphasis>  You should have a reasonably current 
+            <listitem><para><emphasis>Host System:</emphasis>  You should have a reasonably current
                 Linux-based host system.
-                You will have the best results with a recent release of Fedora, 
-                OpenSUSE, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project
-                and officially supported. 
+                You will have the best results with a recent release of Fedora,
+                OpenSUSE, Debian, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project
+                and officially supported.
                 For a list of the distributions under validation and their status, see the
-                <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution
-                Support</ulink> wiki page.</para>
+                "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section
+                in the Yocto Project Reference Manual and the wiki page at
+                <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>.</para>
                 <para>
                 You should also have about 100 gigabytes of free disk space for building images.
                 </para></listitem>
             <listitem><para><emphasis>Packages:</emphasis>  The OpenEmbedded build system
-                requires certain packages exist on your development system (e.g. Python 2.6 or 2.7).  
-                See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" 
+                requires certain packages exist on your development system (e.g. Python 2.6 or 2.7).
+                See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>"
                 section in the Yocto Project Quick Start for the exact package
-                requirements and the installation commands to install them 
+                requirements and the installation commands to install them
                 for the supported distributions.</para></listitem>
-            <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis>  
-                You need a release of the Yocto Project.  
-                You set up a with local <link linkend='source-directory'>source directory</link>
-                one of two ways depending on whether you 
+            <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis>
+                You need a release of the Yocto Project.
+                You set that up with a local <link linkend='source-directory'>Source Directory</link>
+                one of two ways depending on whether you
                 are going to contribute back into the Yocto Project or not.
                 <note>
                     Regardless of the method you use, this manual refers to the resulting local
-                    hierarchical set of files as the "source directory."
+                    hierarchical set of files as the "Source Directory."
                 </note>
                 <itemizedlist>
-                    <listitem><para><emphasis>Tarball Extraction:</emphasis>  If you are not going to contribute 
-                        back into the Yocto Project, you can simply download a Yocto Project release you want 
+                    <listitem><para><emphasis>Tarball Extraction:</emphasis>  If you are not going to contribute
+                        back into the Yocto Project, you can simply download a Yocto Project release you want
                         from the website’s <ulink url='&YOCTO_HOME_URL;/download'>download page</ulink>.
                         Once you have the tarball, just extract it into a directory of your choice.</para>
-                        <para>For example, the following command extracts the Yocto Project &DISTRO; 
-                        release tarball 
-                        into the current working directory and sets up the local source directory
+                        <para>For example, the following command extracts the Yocto Project &DISTRO;
+                        release tarball
+                        into the current working directory and sets up the local Source Directory
                         with a top-level folder named <filename>&YOCTO_POKY;</filename>:
                         <literallayout class='monospaced'>
      $ tar xfj &YOCTO_POKY_TARBALL;
                         </literallayout></para>
-                        <para>This method does not produce a local Git repository. 
+                        <para>This method does not produce a local Git repository.
                         Instead, you simply end up with a snapshot of the release.</para></listitem>
                     <listitem><para><emphasis>Git Repository Method:</emphasis>  If you are going to be contributing
                         back into the Yocto Project or you simply want to keep up
                         with the latest developments, you should use Git commands to set up a local
                         Git repository of the upstream <filename>poky</filename> source repository.
-                        Doing so creates a repository with a complete history of changes and allows 
+                        Doing so creates a repository with a complete history of changes and allows
                         you to easily submit your changes upstream to the project.
                         Because you cloned the repository, you have access to all the Yocto Project development
                         branches and tag names used in the upstream repository.</para>
-                        <para>The following transcript shows how to clone the <filename>poky</filename>  
+                        <para>The following transcript shows how to clone the <filename>poky</filename>
                         Git repository into the current working directory.
                         <note>You can view the Yocto Project Source Repositories at
-                        <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink></note>  
+                        <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink></note>
                         The command creates the local repository in a directory named <filename>poky</filename>.
                         For information on Git used within the Yocto Project, see the
                         "<link linkend='git'>Git</link>" section.
@@ -119,27 +120,27 @@
                         wiki page</ulink>, which describes how to create both <filename>poky</filename>
                         and <filename>meta-intel</filename> Git repositories.</para></listitem>
                 </itemizedlist></para></listitem>
-            <listitem id='local-kernel-files'><para><emphasis>Yocto Project Kernel:</emphasis>  
-                If you are going to be making modifications to a supported Yocto Project kernel, you 
+            <listitem id='local-kernel-files'><para><emphasis>Yocto Project Kernel:</emphasis>
+                If you are going to be making modifications to a supported Yocto Project kernel, you
                 need to establish local copies of the source.
                 You can find Git repositories of supported Yocto Project Kernels organized under
                 "Yocto Linux Kernel" in the Yocto Project Source Repositories at
                 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
-                <para>This setup involves creating a bare clone of the Yocto Project kernel and then 
+                <para>This setup can involve creating a bare clone of the Yocto Project kernel and then
                 copying that cloned repository.
                 You can create the bare clone and the copy of the bare clone anywhere you like.
-                For simplicity, it is recommended that you create these structures outside of the 
-                source directory (usually <filename>poky</filename>).</para>
+                For simplicity, it is recommended that you create these structures outside of the
+                Source Directory (usually <filename>poky</filename>).</para>
                 <para>As an example, the following transcript shows how to create the bare clone
-                of the <filename>linux-yocto-3.4</filename> kernel and then create a copy of 
+                of the <filename>linux-yocto-3.4</filename> kernel and then create a copy of
                 that clone.
-                <note>When you have a local Yocto Project kernel Git repository, you can 
-                reference that repository rather than the upstream Git repository as 
+                <note>When you have a local Yocto Project kernel Git repository, you can
+                reference that repository rather than the upstream Git repository as
                 part of the <filename>clone</filename> command.
                 Doing so can speed up the process.</note></para>
-                <para>In the following example, the bare clone is named 
-                <filename>linux-yocto-3.4.git</filename>, while the 
-                copy is named <filename>my-linux-yocto-3.4-work</filename>: 
+                <para>In the following example, the bare clone is named
+                <filename>linux-yocto-3.4.git</filename>, while the
+                copy is named <filename>my-linux-yocto-3.4-work</filename>:
                 <literallayout class='monospaced'>
      $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.4 linux-yocto-3.4.git
      Initialized empty Git repository in /home/scottrif/linux-yocto-3.4.git/
@@ -152,25 +153,25 @@
                 <para>Now create a clone of the bare clone just created:
                 <literallayout class='monospaced'>
      $ git clone linux-yocto-3.4.git my-linux-yocto-3.4-work
-     Initialized empty Git repository in /home/scottrif/my-linux-yocto-3.4-work/.git/
-     Checking out files: 100% (37619/37619), done.
+     Cloning into 'my-linux-yocto-3.4-work'...
+     done.
                 </literallayout></para></listitem>
             <listitem id='poky-extras-repo'><para><emphasis>
                 The <filename>poky-extras</filename> Git Repository</emphasis>:
-                The <filename>poky-extras</filename> Git repository contains metadata needed 
+                The <filename>poky-extras</filename> Git repository contains metadata needed
                 only if you are modifying and building the kernel image.
                 In particular, it contains the kernel BitBake append (<filename>.bbappend</filename>)
-                files that you 
+                files that you
                 edit to point to your locally modified kernel source files and to build the kernel
-                image. 
-                Pointing to these local files is much more efficient than requiring a download of the 
+                image.
+                Pointing to these local files is much more efficient than requiring a download of the
                 kernel's source files from upstream each time you make changes to the kernel.</para>
-                <para>You can find the <filename>poky-extras</filename> Git Repository in the 
-                "Yocto Metadata Layers" area of the Yocto Project Source Repositories at 
+                <para>You can find the <filename>poky-extras</filename> Git Repository in the
+                "Yocto Metadata Layers" area of the Yocto Project Source Repositories at
                 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
-                It is good practice to create this Git repository inside the source directory.</para>
-                <para>Following is an example that creates the <filename>poky-extras</filename> Git 
-                repository inside the source directory, which is named <filename>poky</filename> 
+                It is good practice to create this Git repository inside the Source Directory.</para>
+                <para>Following is an example that creates the <filename>poky-extras</filename> Git
+                repository inside the Source Directory, which is named <filename>poky</filename>
                 in this case:
                 <literallayout class='monospaced'>
      $ cd ~/poky
@@ -182,21 +183,21 @@
      Receiving objects: 100% (618/618), 526.26 KiB | 111 KiB/s, done.
      Resolving deltas: 100% (192/192), done.
                 </literallayout></para></listitem>
-           <listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board 
-                Support Packages (BSPs):</emphasis>  
-                The Yocto Project provides a layer called <filename>meta-intel</filename> and 
+           <listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board
+                Support Packages (BSPs):</emphasis>
+                The Yocto Project provides a layer called <filename>meta-intel</filename> and
                 it is maintained in its own separate Git repository.
-                The <filename>meta-intel</filename> layer contains many supported 
+                The <filename>meta-intel</filename> layer contains many supported
                 <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>.</para>
                 <para>Similar considerations exist for setting up the <filename>meta-intel</filename>
-                layer.  
+                layer.
                 You can get set up for BSP development one of two ways: tarball extraction or
                 with a local Git repository.
-                It is a good idea to use the same method that you used to set up the source directory.
-                Regardless of the method you use, the Yocto Project uses the following BSP layer 
+                It is a good idea to use the same method that you used to set up the Source Directory.
+                Regardless of the method you use, the Yocto Project uses the following BSP layer
                 naming scheme:
-                <literallayout class='monospaced'> 
-     meta-&lt;BSP_name&gt; 
+                <literallayout class='monospaced'>
+     meta-&lt;BSP_name&gt;
                 </literallayout>
                 where <filename>&lt;BSP_name&gt;</filename> is the recognized BSP name.
                 Here are some examples:
@@ -210,22 +211,22 @@
                 section in the Yocto Project Board Support Package (BSP) Developer's Guide for more
                 information on BSP Layers.
                 <itemizedlist>
-                    <listitem><para><emphasis>Tarball Extraction:</emphasis>  You can download any released 
-                        BSP tarball from the same 
-                        <ulink url='&YOCTO_HOME_URL;/download'>download site</ulink> used 
-                        to get the Yocto Project release.  
+                    <listitem><para><emphasis>Tarball Extraction:</emphasis>  You can download any released
+                        BSP tarball from the same
+                        <ulink url='&YOCTO_HOME_URL;/download'>download site</ulink> used
+                        to get the Yocto Project release.
                         Once you have the tarball, just extract it into a directory of your choice.
                         Again, this method just produces a snapshot of the BSP layer in the form
                         of a hierarchical directory structure.</para></listitem>
-                    <listitem><para><emphasis>Git Repository Method:</emphasis>  If you are working 
-                        with a local Git repository for your source directory, you should also use this method 
+                    <listitem><para><emphasis>Git Repository Method:</emphasis>  If you are working
+                        with a local Git repository for your Source Directory, you should also use this method
                         to set up the <filename>meta-intel</filename> Git repository.
-                        You can locate the <filename>meta-intel</filename> Git repository in the 
+                        You can locate the <filename>meta-intel</filename> Git repository in the
                         "Yocto Metadata Layers" area of the Yocto Project Source Repositories at
                         <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
                         <para>Typically, you set up the <filename>meta-intel</filename> Git repository inside
-                        the source directory.
-                        For example, the following transcript shows the steps to clone the 
+                        the Source Directory.
+                        For example, the following transcript shows the steps to clone the
                         <filename>meta-intel</filename>
                         Git repository inside the local <filename>poky</filename> Git repository.
                         <literallayout class='monospaced'>
@@ -238,15 +239,15 @@
      Receiving objects: 100% (3380/3380), 1.77 MiB | 128 KiB/s, done.
      Resolving deltas: 100% (1689/1689), done.
                         </literallayout></para>
-                        <para>The same  
+                        <para>The same
                         <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>
-                        wiki page</ulink> referenced earlier covers how to 
+                        wiki page</ulink> referenced earlier covers how to
                         set up the <filename>meta-intel</filename> Git repository.</para></listitem>
                 </itemizedlist></para></listitem>
-            <listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis>  If you are developing 
+            <listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis>  If you are developing
                 applications using the Eclipse Integrated Development Environment (IDE),
-                you will need this plug-in.  
-                See the 
+                you will need this plug-in.
+                See the
                 "<link linkend='setting-up-the-eclipse-ide'>Setting up the Eclipse IDE</link>"
                 section for more information.</para></listitem>
         </itemizedlist>
@@ -257,8 +258,8 @@
     <title>Building Images</title>
 
     <para>
-        The build process creates an entire Linux distribution, including the toolchain, from source.  
-        For more information on this topic, see the 
+        The build process creates an entire Linux distribution, including the toolchain, from source.
+        For more information on this topic, see the
         "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
         section in the Yocto Project Quick Start.
     </para>
@@ -266,27 +267,27 @@
     <para>
         The build process is as follows:
         <orderedlist>
-            <listitem><para>Make sure you have set up the source directory described in the 
+            <listitem><para>Make sure you have set up the Source Directory described in the
                 previous section.</para></listitem>
-            <listitem><para>Initialize the build environment by sourcing a build environment 
+            <listitem><para>Initialize the build environment by sourcing a build environment
                 script.</para></listitem>
             <listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file,
-                which is found in the 
-                <link linkend='build-directory'>build directory</link>, 
-                is set up how you want it.  
-                This file defines many aspects of the build environment including 
-                the target machine architecture through the 
-                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable, 
-                the development machine's processor use through the 
-                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</ulink></filename> and 
+                which is found in the
+                <link linkend='build-directory'>Build Directory</link>,
+                is set up how you want it.
+                This file defines many aspects of the build environment including
+                the target machine architecture through the
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable,
+                the development machine's processor use through the
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</ulink></filename> and
                 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'>PARALLEL_MAKE</ulink></filename> variables, and
-                a centralized tarball download directory through the  
+                a centralized tarball download directory through the
                 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.</para></listitem>
             <listitem><para>Build the image using the <filename>bitbake</filename> command.
-                If you want information on BitBake, see the user manual inculded in the 
-                <filename>bitbake/doc/manual</filename> directory of the 
+                If you want information on BitBake, see the user manual inculded in the
+                <filename>bitbake/doc/manual</filename> directory of the
                 <link linkend='source-directory'>Source Directory</link>.</para></listitem>
-            <listitem><para>Run the image either on the actual hardware or using the QEMU 
+            <listitem><para>Run the image either on the actual hardware or using the QEMU
                 emulator.</para></listitem>
         </orderedlist>
     </para>
@@ -296,60 +297,60 @@
     <title>Using Pre-Built Binaries and QEMU</title>
 
     <para>
-        Another option you have to get started is to use pre-built binaries. 
-        The Yocto Project provides many types of binaries with each release. 
-        See the <ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>
+        Another option you have to get started is to use pre-built binaries.
+        The Yocto Project provides many types of binaries with each release.
+        See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
         chapter in the Yocto Project Reference Manual
         for descriptions of the types of binaries that ship with a Yocto Project
         release.
     </para>
 
     <para>
-        Using a pre-built binary is ideal for developing software applications to run on your 
-        target hardware.  
-        To do this, you need to be able to access the appropriate cross-toolchain tarball for 
-        the architecture on which you are developing.  
-        If you are using an SDK type image, the image ships with the complete toolchain native to 
-        the architecture. 
-        If you are not using an SDK type image, you need to separately download and 
+        Using a pre-built binary is ideal for developing software applications to run on your
+        target hardware.
+        To do this, you need to be able to access the appropriate cross-toolchain tarball for
+        the architecture on which you are developing.
+        If you are using an SDK type image, the image ships with the complete toolchain native to
+        the architecture.
+        If you are not using an SDK type image, you need to separately download and
         install the stand-alone Yocto Project cross-toolchain tarball.
     </para>
 
     <para>
-        Regardless of the type of image you are using, you need to download the pre-built kernel 
-        that you will boot in the QEMU emulator and then download and extract the target root 
+        Regardless of the type of image you are using, you need to download the pre-built kernel
+        that you will boot in the QEMU emulator and then download and extract the target root
         filesystem for your target machine’s architecture.
         You can get architecture-specific binaries and filesystems from
         <ulink url='&YOCTO_MACHINES_DL_URL;'>machines</ulink>.
         You can get installation scripts for stand-alone toolchains from
         <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchains</ulink>.
-        Once you have all your files, you set up the environment to emulate the hardware 
-        by sourcing an environment setup script. 
+        Once you have all your files, you set up the environment to emulate the hardware
+        by sourcing an environment setup script.
         Finally, you start the QEMU emulator.
-        You can find details on all these steps in the 
+        You can find details on all these steps in the
         "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
-        section of the Yocto Project Quick Start. 
+        section of the Yocto Project Quick Start.
     </para>
 
-    <para> 
+    <para>
         Using QEMU to emulate your hardware can result in speed issues
         depending on the target and host architecture mix.
-        For example, using the <filename>qemux86</filename> image in the emulator 
-        on an Intel-based 32-bit (x86) host machine is fast because the target and 
+        For example, using the <filename>qemux86</filename> image in the emulator
+        on an Intel-based 32-bit (x86) host machine is fast because the target and
         host architectures match.
         On the other hand, using the <filename>qemuarm</filename> image on the same Intel-based
         host can be slower.
-        But, you still achieve faithful emulation of ARM-specific issues. 
+        But, you still achieve faithful emulation of ARM-specific issues.
     </para>
 
     <para>
         To speed things up, the QEMU images support using <filename>distcc</filename>
-        to call a cross-compiler outside the emulated system. 
+        to call a cross-compiler outside the emulated system.
         If you used <filename>runqemu</filename> to start QEMU, and the
-        <filename>distccd</filename> application is present on the host system, any 
+        <filename>distccd</filename> application is present on the host system, any
         BitBake cross-compiling toolchain available from the build system is automatically
         used from within QEMU simply by calling <filename>distcc</filename>.
-        You can accomplish this by defining the cross-compiler variable 
+        You can accomplish this by defining the cross-compiler variable
         (e.g. <filename>export CC="distcc"</filename>).
         Alternatively, if you are using a suitable SDK image or the appropriate
         stand-alone toolchain is present in <filename>/opt/poky</filename>,
@@ -357,27 +358,27 @@
     </para>
 
     <note>
-        Several mechanisms exist that let you connect to the system running on the 
+        Several mechanisms exist that let you connect to the system running on the
         QEMU emulator:
         <itemizedlist>
-            <listitem><para>QEMU provides a framebuffer interface that makes standard 
+            <listitem><para>QEMU provides a framebuffer interface that makes standard
                 consoles available.</para></listitem>
             <listitem><para>Generally, headless embedded devices have a serial port.
                 If so, you can configure the operating system of the running image
-                to use that port to run a console. 
+                to use that port to run a console.
                 The connection uses standard IP networking.</para></listitem>
             <listitem><para>SSH servers exist in some QEMU images.
-                The <filename>core-image-sato</filename> QEMU image has a Dropbear secure 
+                The <filename>core-image-sato</filename> QEMU image has a Dropbear secure
                 shell (ssh) server that runs with the root password disabled.
-                The <filename>core-image-basic</filename> and <filename>core-image-lsb</filename> QEMU images 
+                The <filename>core-image-basic</filename> and <filename>core-image-lsb</filename> QEMU images
                 have OpenSSH instead of Dropbear.
-                Including these SSH servers allow you to use standard <filename>ssh</filename> and 
+                Including these SSH servers allow you to use standard <filename>ssh</filename> and
                 <filename>scp</filename> commands.
-                The <filename>core-image-minimal</filename> QEMU image, however, contains no ssh 
+                The <filename>core-image-minimal</filename> QEMU image, however, contains no ssh
                 server.</para></listitem>
-            <listitem><para>You can use a provided, user-space NFS server to boot the QEMU session 
+            <listitem><para>You can use a provided, user-space NFS server to boot the QEMU session
                 using a local copy of the root filesystem on the host.
-                In order to make this connection, you must extract a root filesystem tarball by using the 
+                In order to make this connection, you must extract a root filesystem tarball by using the
                 <filename>runqemu-extract-sdk</filename> command.
                 After running the command, you must then point the <filename>runqemu</filename>
                 script to the extracted directory instead of a root filesystem image file.</para></listitem>

documentation/dev-manual/dev-manual.xml

@@ -2,7 +2,7 @@
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
 [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
 
-<book id='dev-manual' lang='en' 
+<book id='dev-manual' lang='en'
       xmlns:xi="http://www.w3.org/2003/XInclude"
       xmlns="http://docbook.org/ns/docbook"
       >
@@ -10,13 +10,13 @@
 
         <mediaobject>
             <imageobject>
-                <imagedata fileref='figures/dev-title.png' 
-                    format='SVG' 
+                <imagedata fileref='figures/dev-title.png'
+                    format='SVG'
                     align='left' scalefit='1' width='100%'/>
-            </imageobject> 
+            </imageobject>
         </mediaobject>
 
-        <title></title> 
+        <title></title>
 
         <authorgroup>
             <author>
@@ -41,9 +41,14 @@
             </revision>
             <revision>
                 <revnumber>1.3</revnumber>
-                <date>Sometime in 2012</date>
+                <date>October 2012</date>
                 <revremark>Released with the Yocto Project 1.3 Release.</revremark>
             </revision>
+            <revision>
+                <revnumber>1.4</revnumber>
+                <date>Sometime in 2013</date>
+                <revremark>Released with the Yocto Project 1.4 Release.</revremark>
+            </revision>
         </revhistory>
 
     <copyright>
@@ -53,9 +58,9 @@
 
     <legalnotice>
       <para>
-          Permission is granted to copy, distribute and/or modify this document under 
+          Permission is granted to copy, distribute and/or modify this document under
           the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">
-          Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by 
+          Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by
           Creative Commons.
       </para>
 
@@ -76,15 +81,11 @@
 
     <xi:include href="dev-manual-newbie.xml"/>
 
-    <xi:include href="dev-manual-common-tasks.xml"/>
-
     <xi:include href="dev-manual-model.xml"/>
 
-    <xi:include href="dev-manual-bsp-appendix.xml"/>
-
-    <xi:include href="dev-manual-kernel-appendix.xml"/>
+    <xi:include href="dev-manual-common-tasks.xml"/>
 
 </book>
-<!-- 
-vim: expandtab tw=80 ts=4 
+<!--
+vim: expandtab tw=80 ts=4
 -->

documentation/kernel-dev/kernel-dev-common.xml

@@ -0,0 +1,667 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='kernel-dev-common'>
+
+<title>Common Tasks</title>
+
+<para>
+    This chapter presents several common tasks that are performed when you
+    work with the Yocto Project Linux kernel.
+    These tasks include preparing a layer, modifying an existing recipe,
+    iterative development, working with your own sources, and incorporating
+    out-of-tree modules.
+</para>
+
+    <section id='creating-and-preparing-a-layer'>
+        <title>Creating and Preparing a Layer</title>
+
+        <para>
+            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 BitBake append files
+            (<filename>.bbappend</filename>) and provides a convenient
+            mechanism to create your own recipe files
+            (<filename>.bb</filename>).
+            For details on how to create and work with layers, see the following
+            sections in the Yocto Project Development Manual:
+            <itemizedlist>
+                <listitem><para>"<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" for
+                    general information on layers and how to create them.</para></listitem>
+                <listitem><para>"<ulink url='&YOCTO_DOCS_DEV_URL;#get-your-layer-setup-for-the-build'>Get Your Layer Setup for the Build</ulink>" for
+                    specific instructions on setting up a layer for kernel
+                    development.</para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='modifying-an-existing-recipe'>
+        <title>Modifying an Existing Recipe</title>
+
+        <para>
+            In many cases, you can customize an existing linux-yocto recipe to
+            meet the needs of your project.
+            Each release of the Yocto Project provides a few Linux
+            kernel recipes from which you can choose.
+            These are located in the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+            in <filename>meta/recipes-kernel/linux</filename>.
+        </para>
+
+        <para>
+            Modifying an existing recipe can consist of the following:
+            <itemizedlist>
+                <listitem><para>Creating the append file</para></listitem>
+                <listitem><para>Applying patches</para></listitem>
+                <listitem><para>Changing the configuration</para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            Before modifying an existing recipe, be sure that you have created
+            a minimal, custom layer from which you can work.
+            See the "<link linkend='creating-and-preparing-a-layer'>Creating and Preparing a Layer</link>"
+            section for some general resources.
+            You can also see the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#get-your-layer-setup-for-the-build'>Get Your Layer Setup for the Build</ulink>" section
+            of the Yocto Project Development Manual for a detailed
+            example.
+        </para>
+
+        <section id='creating-the-append-file'>
+            <title>Creating the Append File</title>
+
+            <para>
+                You create this file in your custom layer.
+                You also name it accordingly based on the linux-yocto recipe
+                you are using.
+                For example, if you are modifying the
+                <filename>meta/recipes-kernel/linux/linux-yocto_3.4.bb</filename>
+                recipe, the append file will typical be located as follows
+                within your custom layer:
+                <literallayout class='monospaced'>
+     &lt;your-layer&gt;/recipes-kernel/linux/linux-yocto_3.4.bbappend
+                </literallayout>
+                The append file should initially contain the following text:
+                <literallayout class='monospaced'>
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'>FILESEXTRAPATHS</ulink> := "${THISDIR}/${PN}"
+                </literallayout>
+                The path <filename>${THISDIR}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename> expands
+                to "linux-yocto" in the current directory for this example.
+                If you add any new files that modify the kernel recipe,
+                you need to place them in your layer in the following area:
+                <literallayout class='monospaced'>
+     &lt;your-layer&gt;/recipes-kernel/linux/linux-yocto/
+                </literallayout>
+                <note>If you are working on a new machine Board Support Package
+                    (BSP), be sure to refer to the
+                    <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
+                </note>
+            </para>
+        </section>
+
+        <section id='applying-patches'>
+            <title>Applying Patches</title>
+
+            <para>
+                If you have a single patch or a small series of patches
+                that you want to apply to the Linux kernel source, you
+                can do so just as you would with any other recipe.
+                You first copy the patches to the path added to
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
+                in your <filename>.bbappend</filename> file as described in
+                the previous section, and then reference them in
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                statements.
+            </para>
+
+            <para>
+                For example, you can apply a three-patch series by adding the
+                following lines to your linux-yocto <filename>.bbappend</filename>
+                file in your layer:
+                <literallayout class='monospaced'>
+     SRC_URI += "file://0001-first-change.patch"
+     SRC_URI += "file://0002-first-change.patch"
+     SRC_URI += "file://0003-first-change.patch"
+                </literallayout>
+                The next time you run BitBake to build the Linux kernel, BitBake
+                detects the change in the recipe and fetches and applies the patches
+                before building the kernel.
+            </para>
+
+            <para>
+                For a detailed example showing how to patch the kernel, see the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"
+                section in the Yocto Project Development Manual.
+            </para>
+        </section>
+
+        <section id='changing-the-configuration'>
+            <title>Changing the Configuration</title>
+
+            <para>
+                You can make wholesale or incremental changes to the Linux
+                kernel <filename>.config</filename> file by including a
+                <filename>defconfig</filename> or by specifying
+                configuration fragments in the <filename>SRC_URI</filename>.
+            </para>
+
+            <para>
+                If you have a complete Linux kernel <filename>.config</filename>
+                file you want to use, copy it to the
+                <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink><filename>}</filename>
+                directory within your layer and name it "defconfig".
+                Then, add the following line to your linux-yocto
+                <filename>.bbappend</filename> file in your layer:
+                <literallayout class='monospaced'>
+     SRC_URI += "file://defconfig"
+                </literallayout>
+            </para>
+
+            <para>
+                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 <filename>8250.cfg</filename> in the
+                <filename>${FILES}</filename> directory with the following
+                content (without indentation):
+                <literallayout class='monospaced'>
+     CONFIG_SERIAL_8250=y
+     CONFIG_SERIAL_8250_CONSOLE=y
+     CONFIG_SERIAL_8250_PCI=y
+     CONFIG_SERIAL_8250_NR_UARTS=4
+     CONFIG_SERIAL_8250_RUNTIME_UARTS=4
+     CONFIG_SERIAL_CORE=y
+     CONFIG_SERIAL_CORE_CONSOLE=y
+                </literallayout>
+                Next, include this configuration fragment in a
+                <filename>SRC_URI</filename> statement in your
+                <filename>.bbappend</filename> file:
+                <literallayout class='monospaced'>
+     SRC_URI += "file://8250.cfg"
+                </literallayout>
+                The next time you run BitBake to build the Linux kernel, BitBake
+                detects the change in the recipe and fetches and applies the
+                new configuration before building the kernel.
+            </para>
+
+            <para>
+                For a detailed example showing how to configure the kernel,
+                see the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"
+                section in the Yocto Project Development Manual.
+            </para>
+        </section>
+    </section>
+
+    <section id='using-an-iterative-development-process'>
+        <title>Using an Iterative Development Process</title>
+
+        <para>
+            If you do not have existing patches or configuration files,
+            you can iteratively generate them from within the BitBake build
+            environment as described within this section.
+            During an iterative workflow, running a previously completed BitBake
+            task causes BitBake to invalidate the tasks that follow the
+            completed task in the build sequence.
+            Invalidated tasks rebuild the next time you run the build using
+            BitBake.
+        </para>
+
+        <para>
+            As you read this section, be sure to substitute the name
+            of your Linux kernel recipe for the term
+            "linux-yocto".
+        </para>
+
+        <section id='generating-configuration-files'>
+            <title>Generating Configuration Files</title>
+
+            <para>
+                You can manipulate the <filename>.config</filename> file
+                used to build a linux-yocto recipe with the
+                <filename>menuconfig</filename> command as follows:
+                <literallayout class='monospaced'>
+     $ bitbake linux-yocto -c menuconfig
+                </literallayout>
+                This command starts the Linux kernel configuration tool,
+                which allows you to prepare a new
+                <filename>.config</filename> file for the build.
+                When you exit the tool, be sure to save your changes
+                at the prompt.
+            </para>
+
+            <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-MACHINE'><filename>MACHINE</filename></ulink><filename>}-${KTYPE}-build</filename> directory.
+                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.
+            </para>
+
+            <para>
+                A better method is to create a configuration fragment using the
+                differences between two configuration files: one previously
+                created and saved, and one freshly created using the
+                <filename>menuconfig</filename> tool.
+            </para>
+
+            <para>
+                To create a configuration fragment using this method, follow
+                these steps:
+                <orderedlist>
+                    <listitem><para>Complete a build at least through the kernel
+                        configuration task as follows:
+                        <literallayout class='monospaced'>
+     $ bitbake linux-yocto -c kernel_configme -f
+                        </literallayout></para></listitem>
+                    <listitem><para>Copy and rename the resulting
+                        <filename>.config</filename> file (e.g.
+                        <filename>config.orig</filename>).
+                        </para></listitem>
+                    <listitem><para>Run the <filename>menuconfig</filename>
+                        command:
+                        <literallayout class='monospaced'>
+     $ bitbake linux-yocto -c menuconfig
+                        </literallayout></para></listitem>
+                    <listitem><para>Prepare a configuration fragment based on
+                        the differences between the two files.
+                        </para></listitem>
+                </orderedlist>
+            </para>
+
+            <para>
+                Ultimately, the configuration fragment file needs to be a
+                list of Linux kernel <filename>CONFIG_</filename> assignments.
+                It cannot be in <filename>diff</filename> format.
+                Here is an example of a command that creates your
+                configuration fragment file.
+                Regardless of the exact command you use, plan on reviewing
+                the output as you can usually remove some of the defaults:
+                <literallayout class='monospaced'>
+     $ diff -Nurp config.orig .config | sed -n "s/^\+//p" > frag.cfg
+                </literallayout>
+                See the "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
+                section for information on how to use the output as a
+                configuration fragment.
+                <note>
+                    You can also use this method to create configuration
+                    fragments for a BSP.
+                    See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
+                    section for more information.
+                </note>
+            </para>
+
+            <para>
+                The kernel tools also provide configuration validation.
+                You can use these tools to produce warnings for when a
+                requested configuration does not appear in the final
+                <filename>.config</filename> file or when you override a
+                policy configuration in a hardware configuration fragment.
+                Here is an example with some sample output of the command
+                that runs these tools:
+                <literallayout class='monospaced'>
+     $ bitbake linux-yocto -c kernel_configcheck -f
+
+     ...
+
+     NOTE: validating kernel configuration
+     This BSP sets 3 invalid/obsolete kernel options.
+     These config options are not offered anywhere within this kernel.
+     The full list can be found in your kernel src dir at:
+     meta/cfg/standard/mybsp/invalid.cfg
+
+     This BSP sets 21 kernel options that are possibly non-hardware related.
+     The full list can be found in your kernel src dir at:
+     meta/cfg/standard/mybsp/specified_non_hdw.cfg
+
+     WARNING: There were 2 hardware options requested that do not
+              have a corresponding value present in the final ".config" file.
+              This probably means you aren't getting the config you wanted.
+              The full list can be found in your kernel src dir at:
+              meta/cfg/standard/mybsp/mismatch.cfg
+                </literallayout>
+            </para>
+
+            <para>
+                The output describes the various problems that you can
+                encounter along with where to find the offending configuration
+                items.
+                You can use the information in the logs to adjust your
+                configuration files and then repeat the
+                <filename>kernel_configme</filename> and
+                <filename>kernel_configcheck</filename> commands until
+                they produce no warnings.
+            </para>
+
+            <para>
+                For more information on how to use the
+                <filename>menuconfig</filename> tool, see the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#using-menuconfig'>Using <filename>menuconfig</filename></ulink>"
+                section in the Yocto Project Development Manual.
+            </para>
+        </section>
+
+        <section id='modifying-source-code'>
+            <title>Modifying Source Code</title>
+
+            <para>
+                You can experiment with source code changes and create a
+                simple patch without leaving the BitBake environment.
+                To get started, be sure to complete a build at
+                least through the kernel configuration task:
+                <literallayout class='monospaced'>
+     $ bitbake linux-yocto -c kernel_configme -f
+                </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.
+            </para>
+
+            <para>
+                You can edit the sources as you would any other Linux source
+                tree.
+                However, keep in mind that you will lose changes if you
+                trigger the <filename>fetch</filename> task for the recipe.
+                You can avoid triggering this task by not issuing BitBake's
+                <filename>cleanall</filename>, <filename>cleansstate</filename>,
+                or forced <filename>fetch</filename> commands.
+                Also, do not modify the recipe itself while working
+                with temporary changes or BitBake might run the
+                <filename>fetch</filename> command depending on the
+                changes to the recipe.
+            </para>
+
+            <para>
+                To test your temporary changes, instruct BitBake to run the
+                <filename>compile</filename> again.
+                The <filename>-f</filename> option forces the command to run
+                even though BitBake might think it has already done so:
+                <literallayout class='monospaced'>
+     $ bitbake linux-yocto -c compile -f
+                </literallayout>
+                If the compile fails, you can update the sources and repeat
+                the <filename>compile</filename>.
+                Once compilation is successful, you can inspect and test
+                the resulting build (i.e. kernel, modules, and so forth) from
+                the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
+                <literallayout class='monospaced'>
+     ${WORKDIR}/linux-${MACHINE}-${KTYPE}-build
+                </literallayout>
+                Alternatively, you can run the <filename>deploy</filename>
+                command to place the kernel image in the
+                <filename>tmp/deploy/images</filename> directory:
+                <literallayout class='monospaced'>
+	$ bitbake linux-yocto -c deploy
+                </literallayout>
+                And, of course, you can perform the remaining installation and
+                packaging steps by issuing:
+                <literallayout class='monospaced'>
+	$ bitbake linux-yocto
+                </literallayout>
+            </para>
+
+            <para>
+                For rapid iterative development, the edit-compile-repeat loop
+                described in this section is preferable to rebuilding the
+                entire recipe because the installation and packaging tasks
+                are very time consuming.
+            </para>
+
+            <para>
+                Once you are satisfied with your source code modifications,
+                you can make them permanent by generating patches and
+                applying them to the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                statement as described in section
+                "<link linkend='applying-patches'>Applying Patches</link>" section.
+                If you are not familiar with generating patches, refer to the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-the-patch'>Creating the Patch</ulink>"
+                section in the Yocto Project Development Manual.
+            </para>
+        </section>
+    </section>
+
+    <section id='working-with-your-own-sources'>
+        <title>Working With Your Own Sources</title>
+
+        <para>
+            If you cannot work with one of the Linux kernel
+            versions supported by existing linux-yocto recipes, you can
+            still make use of the Yocto Project Linux kernel tooling by
+            working with your own sources.
+            When you use your own sources, you will not be able to
+            leverage the existing kernel
+            <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> and
+            stabilization work of the linux-yocto sources.
+            However, you will be able to manage your own Metadata in the same
+            format as the linux-yocto sources.
+            Maintaining format compatibility facilitates converging with
+            linux-yocto on a future, mutually-supported kernel version.
+        </para>
+
+        <para>
+            To help you use your own sources, the Yocto Project provides a
+            linux-yocto custom recipe
+            (<filename>linux-yocto-custom.bb</filename>) that uses
+            <filename>kernel.org</filename> sources
+            and the Yocto Project Linux kernel tools for managing
+            kernel Metadata.
+            You can find this recipe in the
+            <filename>poky</filename> Git repository of the
+            Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
+            at:
+            <literallayout class="monospaced">
+     poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
+            </literallayout>
+        </para>
+
+        <para>
+            Here are some basic steps you can use to work with your own sources:
+            <orderedlist>
+                <listitem><para>Copy the <filename>linux-yocto-custom.bb</filename>
+                    recipe to your layer and give it a meaningful name.
+                    The name should include the version of the Linux kernel you
+                    are using (e.g. <filename>linux-yocto-myproject_3.5.bb</filename>,
+                    where "3.5" is the base version of the Linux kernel
+                    with which you would be working).</para></listitem>
+                <listitem><para>In the same directory inside your layer,
+                    create a matching directory
+                    to store your patches and configuration files (e.g.
+                    <filename>linux-yocto-myproject</filename>).
+                    </para></listitem>
+                <listitem><para>Edit the following variables in your recipe
+                    as appropriate for your project:
+                    <itemizedlist>
+                        <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>:
+                            The <filename>SRC_URI</filename> should be a Git
+                            repository that uses one of the supported Git fetcher
+                            protocols (i.e. <filename>file</filename>,
+                            <filename>git</filename>, <filename>http</filename>,
+                            and so forth).
+                            The skeleton recipe provides an example
+                            <filename>SRC_URI</filename> as a syntax reference.
+                            </para></listitem>
+                        <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>:
+                            The Linux kernel version you are using (e.g.
+                            "3.4").</para></listitem>
+                        <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION_EXTENSION'><filename>LINUX_VERSION_EXTENSION</filename></ulink>:
+                            The Linux kernel <filename>CONFIG_LOCALVERSION</filename>
+                            that is compiled into the resulting kernel and visible
+                            through the <filename>uname</filename> command.
+                            </para></listitem>
+                        <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>:
+                            The commit ID from which you want to build.
+                            </para></listitem>
+                        <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
+                            Treat this variable the same as you would in any other
+                            recipe.
+                            Increment the variable to indicate to the OpenEmbedded
+                            build system that the recipe has changed.
+                            </para></listitem>
+                        <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
+                            The default <filename>PV</filename> assignment is
+                            typically adequate.
+                            It combines the <filename>LINUX_VERSION</filename>
+                            with the Source Control Manager (SCM) revision
+                            as derived from the
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>
+                            variable.
+                            The combined results are a string with
+                            the following form:
+                            <literallayout class='monospaced'>
+     3.4.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2
+                            </literallayout>
+                            While lengthy, the extra verbosity in <filename>PV</filename>
+                            helps ensure you are using the exact
+                            sources from which you intend to build.
+                            </para></listitem>
+                        <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>:
+                            A list of the machines supported by your new recipe.
+                            This variable in the example recipe is set
+                            by default to a regular expression that matches
+                            only the empty string, "(^$)".
+                            This default setting triggers an explicit build
+                            failure.
+                            You must change it to match a list of the machines
+                            that your new recipe supports.
+                            For example, to support the <filename>qemux86</filename>
+                            and <filename>qemux86-64</filename> machines, use
+                            the following form:
+                            <literallayout class='monospaced'>
+     COMPATIBLE_MACHINE = "qemux86|qemux86-64"
+                            </literallayout></para></listitem>
+                    </itemizedlist></para></listitem>
+                <listitem><para>Provide further customizations to your recipe
+                    as needed just as you would customize an existing
+                    linux-yocto recipe.
+                    See the "<link linkend='modifying-an-existing-recipe'>Modifying
+                    an Existing Recipe</link>" section for information.
+                    </para></listitem>
+            </orderedlist>
+        </para>
+    </section>
+
+    <section id='incorporating-out-of-tree-modules'>
+        <title>Incorporating Out-of-Tree Modules</title>
+
+        <para>
+            While it is always preferable to work with sources integrated
+            into the Linux kernel sources, if you need an external kernel
+            module, the <filename>hello-mod.bb</filename> recipe is available
+            as a template from which you can create your own out-of-tree
+            Linux kernel module recipe.
+        </para>
+
+        <para>
+            This template recipe is located in the
+            <filename>poky</filename> Git repository of the
+            Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
+            at:
+            <literallayout class="monospaced">
+     poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
+            </literallayout>
+        </para>
+
+        <para>
+            To get started, copy this recipe to your layer and give it a
+            meaningful name (e.g. <filename>mymodule_1.0.bb</filename>).
+            In the same directory, create a directory named
+            <filename>files</filename> where you can store any source files,
+            patches, or other files necessary for building
+            the module that do not come with the sources.
+            Finally, update the recipe as appropriate for the module.
+            Typically you will need to set the following variables:
+            <itemizedlist>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE*</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            Depending on the build system used by the module sources, you might
+            need to make some adjustments.
+            For example, a typical module <filename>Makefile</filename> looks
+            much like the one provided with the <filename>hello-mod</filename>
+            template:
+            <literallayout class='monospaced'>
+     obj-m := hello.o
+
+     SRC := $(shell pwd)
+
+     all:
+         $(MAKE) -C $(KERNEL_SRC) M=$(SRC)
+
+     modules_install:
+         $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
+     ...
+            </literallayout>
+        </para>
+
+        <para>
+            The important point to note here is the
+            <filename>KERNEL_SRC</filename> variable.
+            The module <filename>bbclass</filename> sets this variable,
+            as well as the <filename>KERNEL_PATH</filename> variable
+            to <filename>${STAGING_KERNEL_DIR}</filename> with the
+            necessary Linux kernel build information to build modules.
+            If your module <filename>Makefile</filename> uses a different
+            variable, you might want to override the
+            <filename>do_compile()</filename> step, or create a patch to
+            the <filename>Makefile</filename> to work with the more typical
+            <filename>KERNEL_SRC</filename> or <filename>KERNEL_PATH</filename>
+            variables.
+        </para>
+
+        <para>
+            After you have prepared your recipe, you will likely want to
+            include the module in your images.
+            To do this, see the documentation for the following variables in
+            the Yocto Project Reference Manual and set one of them as
+            appropriate in your machine configuration file:
+            <itemizedlist>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            modules are often not required for boot and can be excluded from
+            certain build configurations.
+            The following allows for the most flexibility:
+            <literallayout class='monospaced'>
+     MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
+            </literallayout>
+            Where the value is derived by appending the module filename without
+            the <filename>.ko</filename> extension to the string
+            "kernel-module-".
+        </para>
+
+        <para>
+            Because the variable is <filename>RRECOMMENDS</filename> and not
+            a <filename>RDEPENDS</filename> variable, the build will not fail
+            if this module is not available to include in the image.
+        </para>
+    </section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->

documentation/kernel-dev/kernel-dev-customization.xsl

@@ -0,0 +1,8 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
+  
+  <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" />
+
+<!--  <xsl:param name="generate.toc" select="'article nop'"></xsl:param>  -->
+
+</xsl:stylesheet>

documentation/kernel-dev/kernel-dev-examples.xml

@@ -0,0 +1,918 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='kernel-how-to'>
+
+<title>Working with the Yocto Project Kernel</title>
+
+
+<section id='actions-org'>
+    <title>Introduction</title>
+    <para>
+        This chapter describes how to accomplish tasks involving a kernel's tree structure.
+        The information is designed to help the developer that wants to modify the Yocto
+        Project kernel and contribute changes upstream to the Yocto Project.
+        The information covers the following:
+        <itemizedlist>
+            <listitem><para>Tree construction</para></listitem>
+            <listitem><para>Build strategies</para></listitem>
+            <listitem><para>Workflow examples</para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+    <section id='tree-construction'>
+        <title>Tree Construction</title>
+        <para>
+            This section describes construction of the Yocto Project kernel source repositories
+            as accomplished by the Yocto Project team to create kernel repositories.
+            These kernel repositories are found under the heading "Yocto Linux Kernel" at
+            <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>&YOCTO_GIT_URL;/cgit.cgi</ulink>
+            and can be shipped as part of a Yocto Project release.
+            The team creates these repositories by
+            compiling and executing the set of feature descriptions for every BSP/feature
+            in the product.
+            Those feature descriptions list all necessary patches,
+            configuration, branching, tagging and feature divisions found in a kernel.
+            Thus, the Yocto Project kernel repository (or tree) is built.
+        </para>
+        <para>
+            The existence of this tree allows you to access and clone a particular
+            Yocto Project kernel repository and use it to build images based on their configurations
+            and features.
+        </para>
+        <para>
+            You can find the files used to describe all the valid features and BSPs
+            in the Yocto Project kernel in any clone of the Yocto Project kernel source repository
+            Git tree.
+            For example, the following command clones the Yocto Project baseline kernel that
+            branched off of <filename>linux.org</filename> version 3.4:
+            <literallayout class='monospaced'>
+     $ git clone git://git.yoctoproject.org/linux-yocto-3.4
+            </literallayout>
+            For another example of how to set up a local Git repository of the Yocto Project
+            kernel files, see the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted
+            item in the Yocto Project Development Manual.
+        </para>
+        <para>
+            Once you have cloned the kernel Git repository on your local machine, you can
+            switch to the <filename>meta</filename> branch within the repository.
+            Here is an example that assumes the local Git repository for the kernel is in
+            a top-level directory named <filename>linux-yocto-3.4</filename>:
+            <literallayout class='monospaced'>
+     $ cd ~/linux-yocto-3.4
+     $ git checkout -b meta origin/meta
+            </literallayout>
+            Once you have checked out and switched to the <filename>meta</filename> branch,
+            you can see a snapshot of all the kernel configuration and feature descriptions that are
+            used to build that particular kernel repository.
+            These descriptions are in the form of <filename>.scc</filename> files.
+        </para>
+        <para>
+            You should realize, however, that browsing your local kernel repository
+            for feature descriptions and patches is not an effective way to determine what is in a
+            particular kernel branch.
+            Instead, you should use Git directly to discover the changes in a branch.
+            Using Git is an efficient and flexible way to inspect changes to the kernel.
+            For examples showing how to use Git to inspect kernel commits, see the following sections
+            in this chapter.
+            <note>
+                Ground up reconstruction of the complete kernel tree is an action only taken by the
+                Yocto Project team during an active development cycle.
+                When you create a clone of the kernel Git repository, you are simply making it
+                efficiently available for building and development.
+            </note>
+        </para>
+        <para>
+            The following steps describe what happens when the Yocto Project Team constructs
+            the Yocto Project kernel source Git repository (or tree) found at
+            <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the
+            introduction of a new top-level kernel feature or BSP.
+            These are the actions that effectively create the tree
+            that includes the new feature, patch or BSP:
+            <orderedlist>
+                <listitem><para>A top-level kernel feature is passed to the kernel build subsystem.
+                    Normally, this feature is a BSP for a particular kernel type.</para></listitem>
+                <listitem><para>The file that describes the top-level feature is located by searching
+                    these system directories:
+                    <itemizedlist>
+                        <listitem><para>The in-tree kernel-cache directories, which are located
+                            in <filename>meta/cfg/kernel-cache</filename></para></listitem>
+                        <listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements
+                            found in recipes</para></listitem>
+                    </itemizedlist>
+                    For a typical build, the target of the search is a
+                    feature description in an <filename>.scc</filename> file
+                    whose name follows this format:
+                    <literallayout class='monospaced'>
+     &lt;bsp_name&gt;-&lt;kernel_type&gt;.scc
+                    </literallayout>
+                </para></listitem>
+                <listitem><para>Once located, the feature description is either compiled into a simple script
+                    of actions, or into an existing equivalent script that is already part of the
+                    shipped kernel.</para></listitem>
+                <listitem><para>Extra features are appended to the top-level feature description.
+                    These features can come from the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
+                    variable in recipes.</para></listitem>
+                <listitem><para>Each extra feature is located, compiled and appended to the script
+                    as described in step three.</para></listitem>
+                <listitem><para>The script is executed to produce a series of <filename>meta-*</filename>
+                    directories.
+                    These directories are descriptions of all the branches, tags, patches and configurations that
+                    need to be applied to the base Git repository to completely create the
+                    source (build) branch for the new BSP or feature.</para></listitem>
+                <listitem><para>The base repository is cloned, and the actions
+                    listed in the <filename>meta-*</filename> directories are applied to the
+                    tree.</para></listitem>
+                <listitem><para>The Git repository is left with the desired branch checked out and any
+                    required branching, patching and tagging has been performed.</para></listitem>
+            </orderedlist>
+        </para>
+        <para>
+            The kernel tree is now ready for developer consumption to be locally cloned,
+            configured, and built into a Yocto Project kernel specific to some target hardware.
+            <note><para>The generated <filename>meta-*</filename> directories add to the kernel
+                as shipped with the Yocto Project release.
+                Any add-ons and configuration data are applied to the end of an existing branch.
+                The full repository generation that is found in the
+                official Yocto Project kernel repositories at
+                <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>
+                is the combination of all supported boards and configurations.</para>
+                <para>The technique the Yocto Project team uses is flexible and allows for seamless
+                blending of an immutable history with additional patches specific to a
+                deployment.
+                Any additions to the kernel become an integrated part of the branches.</para>
+            </note>
+        </para>
+    </section>
+
+    <section id='build-strategy'>
+        <title>Build Strategy</title>
+        <para>
+            Once a local Git repository of the Yocto Project kernel exists on a development system,
+            you can consider the compilation phase of kernel development - building a kernel image.
+            Some prerequisites exist that are validated by the build process before compilation
+            starts:
+        </para>
+
+        <itemizedlist>
+            <listitem><para>The
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> points
+                to the kernel Git repository.</para></listitem>
+            <listitem><para>A BSP build branch exists.
+                This branch has the following form:
+                <literallayout class='monospaced'>
+     &lt;kernel_type&gt;/&lt;bsp_name&gt;
+                </literallayout></para></listitem>
+        </itemizedlist>
+
+        <para>
+            The OpenEmbedded build system makes sure these conditions exist before attempting compilation.
+            Other means, however, do exist, such as as bootstrapping a BSP, see
+            the "<link linkend='workflow-examples'>Workflow Examples</link>".
+        </para>
+
+        <para>
+            Before building a kernel, the build process verifies the tree
+            and configures the kernel by processing all of the
+            configuration "fragments" specified by feature descriptions in the <filename>.scc</filename>
+            files.
+            As the features are compiled, associated kernel configuration fragments are noted
+            and recorded in the <filename>meta-*</filename> series of directories in their compilation order.
+            The fragments are migrated, pre-processed and passed to the Linux Kernel
+            Configuration subsystem (<filename>lkc</filename>) as raw input in the form
+            of a <filename>.config</filename> file.
+            The <filename>lkc</filename> uses its own internal dependency constraints to do the final
+            processing of that information and generates the final <filename>.config</filename> file
+            that is used during compilation.
+        </para>
+
+        <para>
+            Using the board's architecture and other relevant values from the board's template,
+            kernel compilation is started and a kernel image is produced.
+        </para>
+
+        <para>
+            The other thing that you notice once you configure a kernel is that
+            the build process generates a build tree that is separate from your kernel's local Git
+            source repository tree.
+            This build tree has a name that uses the following form, where
+            <filename>${MACHINE}</filename> is the metadata name of the machine (BSP) and "kernel_type" is one
+            of the Yocto Project supported kernel types (e.g. "standard"):
+        <literallayout class='monospaced'>
+     linux-${MACHINE}-&lt;kernel_type&gt;-build
+        </literallayout>
+        </para>
+
+        <para>
+            The existing support in the <filename>kernel.org</filename> tree achieves this
+            default functionality.
+        </para>
+
+        <para>
+            This behavior means that all the generated files for a particular machine or BSP are now in
+            the build tree directory.
+            The files include the final <filename>.config</filename> file, all the <filename>.o</filename>
+            files, the <filename>.a</filename> files, and so forth.
+            Since each machine or BSP has its own separate build directory in its own separate branch
+            of the Git repository, you can easily switch between different builds.
+        </para>
+    </section>
+
+    <section id='workflow-examples'>
+        <title>Workflow Examples</title>
+
+        <para>
+            As previously noted, the Yocto Project kernel has built-in Git integration.
+            However, these utilities are not the only way to work with the kernel repository.
+            The Yocto Project has not made changes to Git or to other tools that
+            would invalidate alternate workflows.
+            Additionally, the way the kernel repository is constructed results in using
+            only core Git functionality, thus allowing any number of tools or front ends to use the
+            resulting tree.
+        </para>
+
+        <para>
+            This section contains several workflow examples.
+            Many of the examples use Git commands.
+            You can find Git documentation at
+            <ulink url='http://git-scm.com/documentation'></ulink>.
+            You can find a simple overview of using Git with the Yocto Project in the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
+            section of the Yocto Project Development Manual.
+        </para>
+
+        <section id='change-inspection-kernel-changes-commits'>
+            <title>Change Inspection: Changes/Commits</title>
+
+            <para>
+                A common question when working with a kernel is:
+                "What changes have been applied to this tree?"
+            </para>
+
+            <para>
+                In projects that have a collection of directories that
+                contain patches to the kernel, it is possible to inspect or "grep" the contents
+                of the directories to get a general feel for the changes.
+                This sort of patch inspection is not an efficient way to determine what has been
+                done to the kernel.
+                The reason it is inefficient is because there are many optional patches that are
+                selected based on the kernel type and the feature description.
+                Additionally, patches could exist in directories that are not included in the search.
+            </para>
+
+            <para>
+                A more efficient way to determine what has changed in the branch is to use
+                Git and inspect or search the kernel tree.
+                This method gives you a full view of not only the source code modifications,
+                but also provides the reasons for the changes.
+            </para>
+
+            <section id='what-changed-in-a-kernel'>
+                <title>What Changed in a Kernel?</title>
+
+                <para>
+                    Following are a few examples that show how to use Git commands to examine changes.
+                    Because Git repositories in the Yocto Project do not break existing Git
+                    functionality, and because there exists many permutations of these types of
+                    Git commands, many methods exist by which you can discover changes.
+                    <note>
+                        In the following examples, unless you provide a commit range,
+                        <filename>kernel.org</filename> history is blended with Yocto Project
+                        kernel changes.
+                        You can form ranges by using branch names from the kernel tree as the
+                        upper and lower commit markers with the Git commands.
+                        You can see the branch names through the web interface to the
+                        Yocto Project source repositories at
+                        <ulink url='http://git.yoctoproject.org/cgit.cgi'></ulink>.
+                        For example, the branch names for the <filename>linux-yocto-3.4</filename>
+                        kernel repository can be seen at
+                        <ulink url='http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads'></ulink>.
+                    </note>
+                    To see a full range of the changes, use the
+                    <filename>git whatchanged</filename> command and specify a commit range
+                    for the branch (<filename>&lt;commit&gt;..&lt;commit&gt;</filename>).
+                </para>
+
+                <para>
+                    Here is an example that looks at what has changed in the
+                    <filename>emenlow</filename> branch of the
+                    <filename>linux-yocto-3.4</filename> kernel.
+                    The lower commit range is the commit associated with the
+                    <filename>standard/base</filename> branch, while
+                    the upper commit range is the commit associated with the
+                    <filename>standard/emenlow</filename> branch.
+                    <literallayout class='monospaced'>
+     $ git whatchanged origin/standard/base..origin/standard/emenlow
+                    </literallayout>
+                </para>
+
+                <para>
+                    To see a summary of changes use the <filename>git log</filename> command.
+                    Here is an example using the same branches:
+                    <literallayout class='monospaced'>
+     $ git log --oneline origin/standard/base..origin/standard/emenlow
+                    </literallayout>
+                    The <filename>git log</filename> output might be more useful than
+                    the <filename>git whatchanged</filename> as you get
+                    a short, one-line summary of each change and not the entire commit.
+                </para>
+
+                <para>
+                    If you want to see code differences associated with all the changes, use
+                    the <filename>git diff</filename> command.
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     $ git diff origin/standard/base..origin/standard/emenlow
+                    </literallayout>
+                </para>
+
+                <para>
+                    You can see the commit log messages and the text differences using the
+                    <filename>git show</filename> command:
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     $ git show origin/standard/base..origin/standard/emenlow
+                    </literallayout>
+                </para>
+
+                <para>
+                    You can create individual patches for each change by using the
+                    <filename>git format-patch</filename> command.
+                    Here is an example that that creates patch files for each commit and
+                    places them in your <filename>Documents</filename> directory:
+                    <literallayout class='monospaced'>
+     $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
+                    </literallayout>
+                </para>
+            </section>
+
+            <section id='show-a-particular-feature-or-branch-change'>
+                <title>Show a Particular Feature or Branch Change</title>
+
+                <para>
+                    Developers use tags in the Yocto Project kernel tree to divide changes for significant
+                    features or branches.
+                    Once you know a particular tag, you can use Git commands
+                    to show changes associated with the tag and find the branches that contain
+                    the feature.
+                    <note>
+                        Because BSP branch, <filename>kernel.org</filename>, and feature tags are all
+                        present, there could be many tags.
+                    </note>
+                    The <filename>git show &lt;tag&gt;</filename> command shows changes that are tagged by
+                    a feature.
+                    Here is an example that shows changes tagged by the <filename>systemtap</filename>
+                    feature:
+                    <literallayout class='monospaced'>
+     $ git show systemtap
+                    </literallayout>
+                    You can use the <filename>git branch --contains &lt;tag&gt;</filename> command
+                    to show the branches that contain a particular feature.
+                    This command shows the branches that contain the <filename>systemtap</filename>
+                    feature:
+                    <literallayout class='monospaced'>
+     $ git branch --contains systemtap
+                    </literallayout>
+                </para>
+
+                <para>
+                    You can use many other comparisons to isolate BSP and kernel changes.
+                    For example, you can compare against <filename>kernel.org</filename> tags
+                    such as the <filename>v3.4</filename> tag.
+                </para>
+            </section>
+        </section>
+
+        <section id='development-saving-kernel-modifications'>
+            <title>Development: Saving Kernel Modifications</title>
+
+            <para>
+                Another common operation is to build a BSP supplied by the Yocto Project, make some
+                changes, rebuild, and then test.
+                Those local changes often need to be exported, shared or otherwise maintained.
+            </para>
+
+            <para>
+                Since the Yocto Project kernel source tree is backed by Git, this activity is
+                much easier as compared to with previous releases.
+                Because Git tracks file modifications, additions and deletions, it is easy
+                to modify the code and later realize that you need to save the changes.
+                It is also easy to determine what has changed.
+                This method also provides many tools to commit, undo and export those modifications.
+            </para>
+
+            <para>
+                This section and its sub-sections, describe general application of Git's
+                <filename>push</filename> and <filename>pull</filename> commands, which are used to
+                get your changes upstream or source your code from an upstream repository.
+                The Yocto Project provides scripts that help you work in a collaborative development
+                environment.
+                For information on these scripts, see the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change
+                Upstream and Request a Pull</ulink>" and
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-patch'>Using Email to Submit a Patch</ulink>"
+                sections in the Yocto Project Development Manual.
+            </para>
+
+            <para>
+                There are many ways to save kernel modifications.
+                The technique employed
+                depends on the destination for the patches:
+
+                <itemizedlist>
+                    <listitem><para>Bulk storage</para></listitem>
+                    <listitem><para>Internal sharing either through patches or by using Git</para></listitem>
+                    <listitem><para>External submissions</para></listitem>
+                    <listitem><para>Exporting for integration into another Source Code
+                        Manager (SCM)</para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                Because of the following list of issues, the destination of the patches also influences
+                the method for gathering them:
+
+                <itemizedlist>
+                    <listitem><para>Bisectability</para></listitem>
+                    <listitem><para>Commit headers</para></listitem>
+                    <listitem><para>Division of subsystems for separate submission or review</para></listitem>
+                </itemizedlist>
+            </para>
+
+            <section id='bulk-export'>
+                <title>Bulk Export</title>
+
+                <para>
+                    This section describes how you can "bulk" export changes that have not
+                    been separated or divided.
+                    This situation works well when you are simply storing patches outside of the kernel
+                    source repository, either permanently or temporarily, and you are not committing
+                    incremental changes during development.
+                    <note>
+                        This technique is not appropriate for full integration of upstream submission
+                        because changes are not properly divided and do not provide an avenue for per-change
+                        commit messages.
+                        Therefore, this example assumes that changes have not been committed incrementally
+                        during development and that you simply must gather and export them.
+                    </note>
+                    <literallayout class='monospaced'>
+     # bulk export of ALL modifications without separation or division
+     # of the changes
+
+     $ git add .
+     $ git commit -s -a -m &lt;msg&gt;
+        or
+     $ git commit -s -a # and interact with $EDITOR
+                    </literallayout>
+                </para>
+
+                <para>
+                    The previous operations capture all the local changes in the project source
+                    tree in a single Git commit.
+                    And, that commit is also stored in the project's source tree.
+                </para>
+
+                <para>
+                    Once the changes are exported, you can restore them manually using a template
+                    or through integration with the <filename>default_kernel</filename>.
+                </para>
+
+            </section>
+
+            <section id='incremental-planned-sharing'>
+                <title>Incremental/Planned Sharing</title>
+
+                <para>
+                    This section describes how to save modifications when you are making incremental
+                    commits or practicing planned sharing.
+                    The examples in this section assume that you have incrementally committed
+                    changes to the tree during development and now need to export them.
+                    The sections that follow
+                    describe how you can export your changes internally through either patches or by
+                    using Git commands.
+                </para>
+
+                <para>
+                    During development, the following commands are of interest.
+                    For full Git documentation, refer to the Git documentation at
+                    <ulink url='http://github.com'></ulink>.
+
+                    <literallayout class='monospaced'>
+     # edit a file
+     $ vi &lt;path&gt;/file
+     # stage the change
+     $ git add &lt;path&gt;/file
+     # commit the change
+     $ git commit -s
+     # remove a file
+     $ git rm &lt;path&gt;/file
+     # commit the change
+     $ git commit -s
+
+     ... etc.
+                    </literallayout>
+                </para>
+
+                <para>
+                    Distributed development with Git is possible when you use a universally
+                    agreed-upon unique commit identifier (set by the creator of the commit) that maps to a
+                    specific change set with a specific parent.
+                    This identifier is created for you when
+                    you create a commit, and is re-created when you amend, alter or re-apply
+                    a commit.
+                    As an individual in isolation, this is of no interest.
+                    However, if you
+                    intend to share your tree with normal Git <filename>push</filename> and
+                    <filename>pull</filename> operations for
+                    distributed development, you should consider the ramifications of changing a
+                    commit that you have already shared with others.
+                </para>
+
+                <para>
+                    Assuming that the changes have not been pushed upstream, or pulled into
+                    another repository, you can update both the commit content and commit messages
+                    associated with development by using the following commands:
+
+                    <literallayout class='monospaced'>
+     $ Git add &lt;path&gt;/file
+     $ Git commit --amend
+     $ Git rebase or Git rebase -i
+                    </literallayout>
+                </para>
+
+                <para>
+                    Again, assuming that the changes have not been pushed upstream, and that
+                    no pending works-in-progress exist (use <filename>git status</filename> to check), then
+                    you can revert (undo) commits by using the following commands:
+
+                    <literallayout class='monospaced'>
+     # remove the commit, update working tree and remove all
+     # traces of the change
+     $ git reset --hard HEAD^
+     # remove the commit, but leave the files changed and staged for re-commit
+     $ git reset --soft HEAD^
+     # remove the commit, leave file change, but not staged for commit
+     $ git reset --mixed HEAD^
+                    </literallayout>
+                </para>
+
+                <para>
+                    You can create branches, "cherry-pick" changes, or perform any number of Git
+                    operations until the commits are in good order for pushing upstream
+                    or for pull requests.
+                    After a <filename>push</filename> or <filename>pull</filename> command,
+                    commits are normally considered
+                    "permanent" and you should not modify them.
+                    If the commits need to be changed, you can incrementally do so with new commits.
+                    These practices follow standard Git workflow and the <filename>kernel.org</filename> best
+                    practices, which is recommended.
+                    <note>
+                        It is recommended to tag or branch before adding changes to a Yocto Project
+                        BSP or before creating a new one.
+                        The reason for this recommendation is because the branch or tag provides a
+                        reference point to facilitate locating and exporting local changes.
+                    </note>
+                </para>
+
+                <section id='export-internally-via-patches'>
+                    <title>Exporting Changes Internally by Using Patches</title>
+
+                    <para>
+                        This section describes how you can extract committed changes from a working directory
+                        by exporting them as patches.
+                        Once the changes have been extracted, you can use the patches for upstream submission,
+                        place them in a Yocto Project template for automatic kernel patching,
+                        or apply them in many other common uses.
+                    </para>
+
+                    <para>
+                        This example shows how to create a directory with sequentially numbered patches.
+                        Once the directory is created, you can apply it to a repository using the
+                        <filename>git am</filename> command to reproduce the original commit and all
+                        the related information such as author, date, commit log, and so forth.
+                        <note>
+                            The new commit identifiers (ID) will be generated upon re-application.
+                            This action reflects that the commit is now applied to an underlying commit
+                            with a different ID.
+                        </note>
+                        <literallayout class='monospaced'>
+     # &lt;first-commit&gt; can be a tag if one was created before development
+     # began. It can also be the parent branch if a branch was created
+     # before development began.
+
+     $ git format-patch -o &lt;dir&gt; &lt;first commit&gt;..&lt;last commit&gt;
+                        </literallayout>
+                    </para>
+
+                    <para>
+                        In other words:
+                        <literallayout class='monospaced'>
+     # Identify commits of interest.
+
+     # If the tree was tagged before development
+     $ git format-patch -o &lt;save dir&gt; &lt;tag&gt;
+
+     # If no tags are available
+     $ git format-patch -o &lt;save dir&gt; HEAD^  # last commit
+     $ git format-patch -o &lt;save dir&gt; HEAD^^ # last 2 commits
+     $ git whatchanged # identify last commit
+     $ git format-patch -o &lt;save dir&gt; &lt;commit id&gt;
+     $ git format-patch -o &lt;save dir&gt; &lt;rev-list&gt;
+                        </literallayout>
+                    </para>
+                </section>
+
+                <section id='export-internally-via-git'>
+                    <title>Exporting Changes Internally by Using Git</title>
+
+                    <para>
+                        This section describes how you can export changes from a working directory
+                        by pushing the changes into a master repository or by making a pull request.
+                        Once you have pushed the changes to the master repository, you can then
+                        pull those same changes into a new kernel build at a later time.
+                    </para>
+
+                    <para>
+                        Use this command form to push the changes:
+                        <literallayout class='monospaced'>
+     $ git push ssh://&lt;master_server&gt;/&lt;path_to_repo&gt;
+        &lt;local_branch&gt;:&lt;remote_branch&gt;
+                        </literallayout>
+                    </para>
+
+                    <para>
+                        For example, the following command pushes the changes from your local branch
+                        <filename>yocto/standard/common-pc/base</filename> to the remote branch with the same name
+                        in the master repository <filename>//git.mycompany.com/pub/git/kernel-3.4</filename>.
+                        <literallayout class='monospaced'>
+     $ git push ssh://git.mycompany.com/pub/git/kernel-3.4 \
+        yocto/standard/common-pc/base:yocto/standard/common-pc/base
+                        </literallayout>
+                    </para>
+
+                    <para>
+                        A pull request entails using the <filename>git request-pull</filename> command to compose
+                        an email to the
+                        maintainer requesting that a branch be pulled into the master repository, see
+                        <ulink url='http://github.com/guides/pull-requests'></ulink> for an example.
+                        <note>
+                            Other commands such as <filename>git stash</filename> or branching can also be used to save
+                            changes, but are not covered in this document.
+                        </note>
+                    </para>
+                </section>
+            </section>
+
+            <section id='export-for-external-upstream-submission'>
+                <title>Exporting Changes for External (Upstream) Submission</title>
+
+                <para>
+                    This section describes how to export changes for external upstream submission.
+                    If the patch series is large or the maintainer prefers to pull
+                    changes, you can submit these changes by using a pull request.
+                    However, it is common to send patches as an email series.
+                    This method allows easy review and integration of the changes.
+                    <note>
+                        Before sending patches for review be sure you understand the
+                        community standards for submitting and documenting changes and follow their best practices.
+                        For example, kernel patches should follow standards such as:
+                        <itemizedlist>
+                            <listitem><para>
+                                <ulink url='http://linux.yyz.us/patch-format.html'></ulink></para></listitem>
+                            <listitem><para>Documentation/SubmittingPatches (in any linux
+                                kernel source tree)</para></listitem>
+                        </itemizedlist>
+                    </note>
+                </para>
+
+                <para>
+                    The messages used to commit changes are a large part of these standards.
+                    Consequently, be sure that the headers for each commit have the required information.
+                    For information on how to follow the Yocto Project commit message standards, see the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a
+                    Change</ulink>" section in the Yocto Project Development Manual.
+                </para>
+
+                <para>
+                    If the initial commits were not properly documented or do not meet those standards,
+                    you can re-base by using the <filename>git rebase -i</filename> command to
+                    manipulate the commits and
+                    get them into the required format.
+                    Other techniques such as branching and cherry-picking commits are also viable options.
+                </para>
+
+                <para>
+                    Once you complete the commits, you can generate the email that sends the patches
+                    to the maintainer(s) or lists that review and integrate changes.
+                    The command <filename>git send-email</filename> is commonly used to ensure
+                    that patches are properly
+                    formatted for easy application and avoid mailer-induced patch damage.
+                </para>
+
+                <para>
+                    The following is an example of dumping patches for external submission:
+                    <literallayout class='monospaced'>
+     # dump the last 4 commits
+     $ git format-patch --thread -n -o ~/rr/ HEAD^^^^
+     $ git send-email --compose --subject '[RFC 0/N] &lt;patch series summary&gt;' \
+      --to foo@yoctoproject.org --to bar@yoctoproject.org \
+      --cc list@yoctoproject.org  ~/rr
+     # the editor is invoked for the 0/N patch, and when complete the entire
+     # series is sent via email for review
+                    </literallayout>
+                </para>
+            </section>
+
+            <section id='export-for-import-into-other-scm'>
+                <title>Exporting Changes for Import into Another SCM</title>
+
+                <para>
+                    When you want to export changes for import into another
+                    Source Code Manager (SCM), you can use any of the previously discussed
+                    techniques.
+                    However, if the patches are manually applied to a secondary tree and then
+                    that tree is checked into the SCM, you can lose change information such as
+                    commit logs.
+                    This process is not recommended.
+                </para>
+
+                <para>
+                    Many SCMs can directly import Git commits, or can translate Git patches so that
+                    information is not lost.
+                    Those facilities are SCM-dependent and you should use them whenever possible.
+                </para>
+            </section>
+        </section>
+
+        <section id='scm-working-with-the-yocto-project-kernel-in-another-scm'>
+            <title>Working with the Yocto Project Kernel in Another SCM</title>
+
+            <para>
+                This section describes kernel development in an SCM other than Git,
+                which is not the same as exporting changes to another SCM described earlier.
+                For this scenario, you use the OpenEmbedded build system to
+                develop the kernel in a different SCM.
+                The following must be true for you to accomplish this:
+                <itemizedlist>
+                    <listitem><para>The delivered Yocto Project kernel must be exported into the second
+                        SCM.</para></listitem>
+                    <listitem><para>Development must be exported from that secondary SCM into a
+                        format that can be used by the OpenEmbedded build system.</para></listitem>
+                </itemizedlist>
+            </para>
+
+            <section id='exporting-delivered-kernel-to-scm'>
+                <title>Exporting the Delivered Kernel to the SCM</title>
+
+                <para>
+                    Depending on the SCM, it might be possible to export the entire Yocto Project
+                    kernel Git repository, branches and all, into a new environment.
+                    This method is preferred because it has the most flexibility and potential to maintain
+                    the meta data associated with each commit.
+                </para>
+
+                <para>
+                    When a direct import mechanism is not available, it is still possible to
+                    export a branch (or series of branches) and check them into a new repository.
+                </para>
+
+                <para>
+                    The following commands illustrate some of the steps you could use to
+                    import the <filename>yocto/standard/common-pc/base</filename>
+                    kernel into a secondary SCM:
+                    <literallayout class='monospaced'>
+     $ git checkout yocto/standard/common-pc/base
+     $ cd .. ; echo linux/.git &gt; .cvsignore
+     $ cvs import -m "initial import" linux MY_COMPANY start
+                    </literallayout>
+                </para>
+
+                <para>
+                    You could now relocate the CVS repository and use it in a centralized manner.
+                </para>
+
+                <para>
+                    The following commands illustrate how you can condense and merge two BSPs into a
+                    second SCM:
+                    <literallayout class='monospaced'>
+     $ git checkout yocto/standard/common-pc/base
+     $ git merge yocto/standard/common-pc-64/base
+     # resolve any conflicts and commit them
+     $ cd .. ; echo linux/.git &gt; .cvsignore
+     $ cvs import -m "initial import" linux MY_COMPANY start
+                    </literallayout>
+                </para>
+            </section>
+
+            <section id='importing-changes-for-build'>
+                <title>Importing Changes for the Build</title>
+
+                <para>
+                    Once development has reached a suitable point in the second development
+                    environment, you need to export the changes as patches.
+                    To export them, place the changes in a recipe and
+                    automatically apply them to the kernel during patching.
+                </para>
+            </section>
+        </section>
+
+        <section id='bsp-creating'>
+            <title>Creating a BSP Based on an Existing Similar BSP</title>
+
+            <para>
+                This section overviews the process of creating a BSP based on an
+                existing similar BSP.
+                The information is introductory in nature and does not provide step-by-step examples.
+                For detailed information on how to create a new BSP, see
+                the "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" section in the
+                Yocto Project Board Support Package (BSP) Developer's Guide, or see the
+                <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>Transcript:_creating_one_generic_Atom_BSP_from_another</ulink>
+                wiki page.
+            </para>
+
+            <para>
+                The basic steps you need to follow are:
+                <orderedlist>
+                    <listitem><para><emphasis>Make sure you have set up a local Source Directory:</emphasis>
+                        You must create a local
+                        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+                        by either creating a Git repository (recommended) or
+                        extracting a Yocto Project release tarball.</para></listitem>
+                    <listitem><para><emphasis>Choose an existing BSP available with the Yocto Project:</emphasis>
+                        Try to map your board features as closely to the features of a BSP that is
+                        already supported and exists in the Yocto Project.
+                        Starting with something as close as possible to your board makes developing
+                        your BSP easier.
+                        You can find all the BSPs that are supported and ship with the Yocto Project
+                        on the Yocto Project's Download page at
+                        <ulink url='&YOCTO_HOME_URL;/download'></ulink>.</para></listitem>
+                    <listitem><para><emphasis>Be sure you have the Base BSP:</emphasis>
+                        You need to either have a local Git repository of the base BSP set up or
+                        have downloaded and extracted the files from a release BSP tarball.
+                        Either method gives you access to the BSP source files.</para></listitem>
+                    <listitem><para><emphasis>Make a copy of the existing BSP, thus isolating your new
+                        BSP work:</emphasis>
+                        Copying the existing BSP file structure gives you a new area in which to work.</para></listitem>
+                    <listitem><para><emphasis>Make configuration and recipe changes to your new BSP:</emphasis>
+                        Configuration changes involve the files in the BSP's <filename>conf</filename>
+                        directory.
+                        Changes include creating a machine-specific configuration file and editing the
+                        <filename>layer.conf</filename> file.
+                        The configuration changes identify the kernel you will be using.
+                        Recipe changes include removing, modifying, or adding new recipe files that
+                        instruct the build process on what features to include in the image.</para></listitem>
+                    <listitem><para><emphasis>Prepare for the build:</emphasis>
+                        Before you actually initiate the build, you need to set up the build environment
+                        by sourcing the environment initialization script.
+                        After setting up the environment, you need to make some build configuration
+                        changes to the <filename>local.conf</filename> and <filename>bblayers.conf</filename>
+                        files.</para></listitem>
+                    <listitem><para><emphasis>Build the image:</emphasis>
+                        The OpenEmbedded build system uses BitBake to create the image.
+                        You need to decide on the type of image you are going to build (e.g. minimal, base,
+                        core, sato, and so forth) and then start the build using the <filename>bitbake</filename>
+                        command.</para></listitem>
+                </orderedlist>
+            </para>
+        </section>
+
+        <section id='tip-dirty-string'>
+            <title>"-dirty" String</title>
+
+            <para>
+                If kernel images are being built with "-dirty" on the end of the version
+                string, this simply means that modifications in the source
+                directory have not been committed.
+                <literallayout class='monospaced'>
+     $ git status
+                </literallayout>
+            </para>
+
+            <para>
+                You can use the above Git command to report modified, removed, or added files.
+                You should commit those changes to the tree regardless of whether they will be saved,
+                exported, or used.
+                Once you commit the changes you need to rebuild the kernel.
+            </para>
+
+            <para>
+                To brute force pickup and commit all such pending changes, enter the following:
+                <literallayout class='monospaced'>
+     $ git add .
+     $ git commit -s -a -m "getting rid of -dirty"
+                </literallayout>
+            </para>
+
+            <para>
+                Next, rebuild the kernel.
+            </para>
+        </section>
+    </section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->

documentation/kernel-dev/kernel-dev-faq.xml

@@ -0,0 +1,131 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='kernel-dev-faq'>
+<title>Kernel Development FAQ</title>
+<qandaset>
+    <qandaentry>
+        <question>
+            <para>
+                How do I use my own Linux kernel <filename>.config</filename>
+                file?
+            </para>
+        </question>
+        <answer>
+            <para>
+                Refer to the "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
+                section for information.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                How do I create configuration fragments?
+            </para>
+        </question>
+        <answer>
+            <para>
+                Refer to the "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
+                section for information.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                How do I use my own Linux kernel sources?
+            </para>
+        </question>
+        <answer>
+            <para>
+                Refer to the "<link linkend='working-with-your-own-sources'>Working With Your Own Sources</link>"
+                section for information.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                How do I install/not-install the kernel image on the rootfs?
+            </para>
+        </question>
+        <answer>
+            <para>
+                The kernel image (e.g. <filename>vmlinuz</filename>) is provided
+                by the <filename>kernel-image</filename> package.
+                Image recipes depend on <filename>kernel-base</filename>.
+                To specify whether or not the kernel
+                image is installed in the generated root filesystem, override
+                <filename>RDEPENDS_kernel-base</filename> to include or not
+                include "kernel-image".</para>
+                <para>See the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>"
+                section in the Yocto Project Development Manual for information on
+                how to use an append file to override metadata.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                How do I install a specific kernel module?
+            </para>
+        </question>
+        <answer>
+            <para>
+                Linux kernel modules are packaged individually.
+                To ensure a specific kernel module is included in an image,
+                include it in the appropriate machine
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
+                variable.</para>
+                <para>These other variables are useful for installing specific
+                modules:
+                <literallayout class='monospaced'>
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink>
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>
+                </literallayout>
+                For example, set the following in the <filename>qemux86.conf</filename>
+                file to include the <filename>ab123</filename> kernel modules
+                with images built for the <filename>qemux86</filename> machine:
+                <literallayout class='monospaced'>
+     MACHINE_EXTRA_RRECOMMENDS += "kernel-module-ab123"
+                </literallayout>
+                For more information, see the
+                "<link linkend='incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</link>"
+                section.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                How do I change the Linux kernel command line?
+            </para>
+        </question>
+        <answer>
+            <para>
+                The Linux kernel command line is typically specified in
+                the machine config using the <filename>APPEND</filename> variable.
+                For example, you can add some helpful debug information doing
+                the following:
+                <literallayout class='monospaced'>
+     APPEND += "printk.time=y initcall_debug debug"
+                </literallayout>
+            </para>
+        </answer>
+    </qandaentry>
+
+</qandaset>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->

documentation/kernel-dev/kernel-dev-intro.xml

@@ -0,0 +1,124 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='kernel-dev-intro'>
+<title>Introduction</title>
+
+    <section id='kernel-dev-overview'>
+        <title>Overview</title>
+
+        <para>
+            Regardless of how you intend to make use of the Yocto Project,
+            chances are you will work with the Linux kernel.
+            This manual provides background information on the Yocto Linux kernel
+            <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,
+            describes common tasks you can perform using the kernel tools,
+            and shows you how to use the Metadata needed to work with
+            the kernel inside the Yocto Project.
+       </para>
+
+       <para>
+            Each Yocto Project release has a set of linux-yocto recipes, whose
+            Git repositories you can view in the Yocto
+            <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> under
+            the "Yocto Linux Kernel" heading.
+            New recipes for the release track the latest upstream developments
+            and introduce newly supported platforms.
+            Previous recipes in the release are refreshed and supported for at
+            least one additional release.
+            As they align, these previous releases are updated to include the
+            latest from the Long Term Support Initiative (LTSI) project.
+            Also included is a linux-yocto development recipe
+            (<filename>linux-yocto-dev.bb</filename>) should you want to work
+            with the very latest in upstream Linux kernel development and
+            Metadata development.
+        </para>
+
+        <para>
+            The Yocto Project also provides a powerful set of kernel
+            tools for managing Linux kernel sources and configuration data.
+            You can use these tools to make a single configuration change,
+            apply multiple patches, or work with your own kernel sources.
+        </para>
+
+        <para>
+            In particular, the kernel tools allow you to generate configuration
+            fragments that specify only what you must, and nothing more.
+            Configuration fragments only need to contain the highest level
+            visible <filename>CONFIG</filename> options as presented by the Linux
+            kernel <filename>menuconfig</filename> system.
+            Contrast this against a complete Linux kernel
+            <filename>.config</filename>, which includes all the automatically
+            selected <filename>CONFIG</filename> options.
+            This efficiency reduces your maintenance effort and allows you
+            to further separate your configuration in ways that make sense for
+            your project.
+            A common split separates policy and hardware.
+            For example, all your kernels might support
+            the <filename>proc</filename> and <filename>sys</filename> filesystems,
+            but only specific boards require sound, USB, or specific drivers.
+            Specifying these configurations individually allows you to aggregate
+            them together as needed, but maintains them in only one place.
+            Similar logic applies to separating source changes.
+        </para>
+
+        <para>
+            If you do not maintain your own kernel sources and need to make
+            only minimal changes to the sources, the released recipes provide a
+            vetted base upon which to layer your changes.
+            Doing so allows you to benefit from the continual kernel
+            integration and testing performed during development of the
+            Yocto Project.
+        </para>
+
+        <para>
+            If, instead, you have a very specific Linux kernel source tree
+            and are unable to align with one of the official linux-yocto
+            recipes, an alternative exists by which you can use the Yocto
+            Project Linux kernel tools with your own kernel sources.
+        </para>
+    </section>
+
+    <section id='kernel-dev-other-resources'>
+        <title>Other Resources</title>
+
+        <para>
+            The sections that follow provide instructions for completing
+            specific Linux kernel development tasks.
+            These instructions assume you are comfortable working with
+            <ulink url='http://developer.berlios.de/projects/bitbake/'>BitBake</ulink>
+            recipes and basic open-source development tools.
+            Understanding these concepts will facilitate the process of working
+            with the kernel recipes.
+            If you find you need some additional background, please be sure to
+            review and understand the following documentation:
+            <itemizedlist>
+                <listitem><para><ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>
+                    </para></listitem>
+                <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#modifying-temporary-source-code'>Modifying Temporary Source Code</ulink>"
+                    section in the Yocto Project Development Manual
+                    </para></listitem>
+                <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" section
+                    in the Yocto Project Development Manual</para></listitem>
+                <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#modifying-the-kernel'>Modifying the Kernel</ulink>" section
+                    in the Yocto Project Development Manual.</para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            Finally, while this document focuses on the manual creation of
+            recipes, patches, and configuration files, the Yocto Project
+            Board Support Package (BSP) tools are available to automate
+            this process with existing content and work well to create the
+            initial framework and boilerplate code.
+            For details on these tools, see the
+            "<ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>Using the Yocto Project's BSP Tools</ulink>"
+            section in the Yocto Project Board Support Package (BSP) Developer's
+            Guide.
+        </para>
+    </section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->

documentation/kernel-dev/kernel-dev-style.css

@@ -0,0 +1,978 @@
+/*
+   Generic XHTML / DocBook XHTML CSS Stylesheet.
+
+   Browser wrangling and typographic design by
+      Oyvind Kolas / pippin@gimp.org
+
+   Customised for Poky by
+      Matthew Allum / mallum@o-hand.com
+
+   Thanks to:
+     Liam R. E. Quin
+     William Skaggs
+     Jakub Steiner
+
+   Structure
+   ---------
+
+   The stylesheet is divided into the following sections:
+
+       Positioning
+          Margins, paddings, width, font-size, clearing.
+       Decorations
+          Borders, style
+       Colors
+          Colors
+       Graphics
+          Graphical backgrounds
+       Nasty IE tweaks
+          Workarounds needed to make it work in internet explorer,
+          currently makes the stylesheet non validating, but up until
+          this point it is validating.
+       Mozilla extensions
+          Transparency for footer
+	  Rounded corners on boxes
+
+*/
+
+
+  /*************** /
+ /  Positioning   /
+/ ***************/
+
+body {
+  font-family: Verdana, Sans, sans-serif;
+
+  min-width: 640px;
+  width: 80%;
+  margin:  0em auto;
+  padding: 2em 5em 5em 5em;
+  color: #333;
+}
+
+h1,h2,h3,h4,h5,h6,h7 {
+  font-family: Arial, Sans;
+  color: #00557D;
+  clear: both;
+}
+
+h1 {
+  font-size: 2em;
+  text-align: left;
+  padding: 0em 0em 0em 0em;
+  margin: 2em 0em 0em 0em;
+}
+
+h2.subtitle {
+  margin: 0.10em 0em 3.0em 0em;
+  padding: 0em 0em 0em 0em;
+  font-size: 1.8em;
+  padding-left: 20%;
+  font-weight: normal;
+  font-style: italic;
+}
+
+h2 {
+  margin: 2em 0em 0.66em 0em;
+  padding: 0.5em 0em 0em 0em;
+  font-size: 1.5em;
+  font-weight: bold;
+}
+
+h3.subtitle {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+  font-size: 142.14%;
+  text-align: right;
+}
+
+h3 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 140%;
+  font-weight: bold;
+}
+
+h4 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 120%;
+  font-weight: bold;
+}
+
+h5 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 110%;
+  font-weight: bold;
+}
+
+h6 {
+  margin: 1em 0em 0em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 110%;
+  font-weight: bold;
+}
+
+.authorgroup {
+  background-color: transparent;
+  background-repeat: no-repeat;
+  padding-top: 256px;
+  background-image: url("figures/kernel-dev-title.png");
+  background-position: left top;
+  margin-top: -256px;
+  padding-right: 50px;
+  margin-left: 0px;
+  text-align: right;
+  width: 740px;
+}
+
+h3.author {
+  margin: 0em 0me 0em 0em;
+  padding: 0em 0em 0em 0em;
+  font-weight: normal;
+  font-size: 100%;
+  color: #333;
+  clear: both;
+}
+
+.author tt.email {
+  font-size: 66%;
+}
+
+.titlepage hr {
+  width: 0em;
+  clear: both;
+}
+
+.revhistory {
+  padding-top: 2em;
+  clear: both;
+}
+
+.toc,
+.list-of-tables,
+.list-of-examples,
+.list-of-figures {
+  padding: 1.33em 0em 2.5em 0em;
+  color: #00557D;
+}
+
+.toc p,
+.list-of-tables p,
+.list-of-figures p,
+.list-of-examples p {
+  padding: 0em 0em 0em 0em;
+  padding: 0em 0em 0.3em;
+  margin: 1.5em 0em 0em 0em;
+}
+
+.toc p b,
+.list-of-tables p b,
+.list-of-figures p b,
+.list-of-examples p b{
+  font-size: 100.0%;
+  font-weight: bold;
+}
+
+.toc dl,
+.list-of-tables dl,
+.list-of-figures dl,
+.list-of-examples dl {
+  margin: 0em 0em 0.5em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.toc dt {
+  margin: 0em 0em 0em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.toc dd {
+  margin: 0em 0em 0em 2.6em;
+  padding: 0em 0em 0em 0em;
+}
+
+div.glossary dl,
+div.variablelist dl {
+}
+
+.glossary dl dt,
+.variablelist dl dt,
+.variablelist dl dt span.term {
+  font-weight: normal;
+  width: 20em;
+  text-align: right;
+}
+
+.variablelist dl dt {
+  margin-top: 0.5em;
+}
+
+.glossary dl dd,
+.variablelist dl dd {
+  margin-top: -1em;
+  margin-left: 25.5em;
+}
+
+.glossary dd p,
+.variablelist dd p {
+  margin-top: 0em;
+  margin-bottom: 1em;
+}
+
+
+div.calloutlist table td {
+  padding: 0em 0em 0em 0em;
+  margin: 0em 0em 0em 0em;
+}
+
+div.calloutlist table td p {
+  margin-top: 0em;
+  margin-bottom: 1em;
+}
+
+div p.copyright {
+  text-align: left;
+}
+
+div.legalnotice p.legalnotice-title {
+  margin-bottom: 0em;
+}
+
+p {
+  line-height: 1.5em;
+  margin-top: 0em;
+
+}
+
+dl {
+  padding-top: 0em;
+}
+
+hr {
+  border: solid 1px;
+}
+
+
+.mediaobject,
+.mediaobjectco {
+  text-align: center;
+}
+
+img {
+  border: none;
+}
+
+ul {
+  padding: 0em 0em 0em 1.5em;
+}
+
+ul li {
+  padding: 0em 0em 0em 0em;
+}
+
+ul li p {
+  text-align: left;
+}
+
+table {
+  width :100%;
+}
+
+th {
+  padding: 0.25em;
+  text-align: left;
+  font-weight: normal;
+  vertical-align: top;
+}
+
+td {
+  padding: 0.25em;
+  vertical-align: top;
+}
+
+p a[id] {
+  margin: 0px;
+  padding: 0px;
+  display: inline;
+  background-image: none;
+}
+
+a {
+  text-decoration: underline;
+  color: #444;
+}
+
+pre {
+    overflow: auto;
+}
+
+a:hover {
+  text-decoration: underline;
+  /*font-weight: bold;*/
+}
+
+
+div.informalfigure,
+div.informalexample,
+div.informaltable,
+div.figure,
+div.table,
+div.example {
+  margin: 1em 0em;
+  padding: 1em;
+  page-break-inside: avoid;
+}
+
+
+div.informalfigure p.title b,
+div.informalexample p.title b,
+div.informaltable p.title b,
+div.figure p.title b,
+div.example p.title b,
+div.table p.title b{
+    padding-top: 0em;
+    margin-top: 0em;
+    font-size: 100%;
+    font-weight: normal;
+}
+
+.mediaobject .caption,
+.mediaobject .caption p  {
+  text-align: center;
+  font-size: 80%;
+  padding-top: 0.5em;
+  padding-bottom: 0.5em;
+}
+
+.epigraph {
+  padding-left: 55%;
+  margin-bottom: 1em;
+}
+
+.epigraph p {
+  text-align: left;
+}
+
+.epigraph .quote {
+  font-style: italic;
+}
+.epigraph .attribution {
+  font-style: normal;
+  text-align: right;
+}
+
+span.application {
+  font-style: italic;
+}
+
+.programlisting {
+  font-family: monospace;
+  font-size: 80%;
+  white-space: pre;
+  margin: 1.33em 0em;
+  padding: 1.33em;
+}
+
+.tip,
+.warning,
+.caution,
+.note {
+  margin-top: 1em;
+  margin-bottom: 1em;
+
+}
+
+/* force full width of table within div */
+.tip table,
+.warning table,
+.caution table,
+.note table {
+  border: none;
+  width: 100%;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  padding: 0.8em 0.0em 0.0em 0.0em;
+  margin : 0em 0em 0em 0em;
+}
+
+.tip p,
+.warning p,
+.caution p,
+.note p {
+  margin-top: 0.5em;
+  margin-bottom: 0.5em;
+  padding-right: 1em;
+  text-align: left;
+}
+
+.acronym {
+  text-transform: uppercase;
+}
+
+b.keycap,
+.keycap {
+  padding: 0.09em 0.3em;
+  margin: 0em;
+}
+
+.itemizedlist li {
+  clear: none;
+}
+
+.filename {
+  font-size: medium;
+  font-family: Courier, monospace;
+}
+
+
+div.navheader, div.heading{
+  position: absolute;
+  left: 0em;
+  top: 0em;
+  width: 100%;
+  background-color: #cdf;
+  width: 100%;
+}
+
+div.navfooter, div.footing{
+  position: fixed;
+  left: 0em;
+  bottom: 0em;
+  background-color: #eee;
+  width: 100%;
+}
+
+
+div.navheader td,
+div.navfooter td {
+  font-size: 66%;
+}
+
+div.navheader table th {
+  /*font-family: Georgia, Times, serif;*/
+  /*font-size: x-large;*/
+  font-size: 80%;
+}
+
+div.navheader table {
+  border-left: 0em;
+  border-right: 0em;
+  border-top: 0em;
+  width: 100%;
+}
+
+div.navfooter table {
+  border-left: 0em;
+  border-right: 0em;
+  border-bottom: 0em;
+  width: 100%;
+}
+
+div.navheader table td a,
+div.navfooter table td a {
+  color: #777;
+  text-decoration: none;
+}
+
+/* normal text in the footer */
+div.navfooter table td {
+  color: black;
+}
+
+div.navheader table td a:visited,
+div.navfooter table td a:visited {
+  color: #444;
+}
+
+
+/* links in header and footer */
+div.navheader table td a:hover,
+div.navfooter table td a:hover {
+  text-decoration: underline;
+  background-color: transparent;
+  color: #33a;
+}
+
+div.navheader hr,
+div.navfooter hr {
+  display: none;
+}
+
+
+.qandaset tr.question td p {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.qandaset tr.answer td p {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+}
+.answer td {
+  padding-bottom: 1.5em;
+}
+
+.emphasis {
+  font-weight: bold;
+}
+
+
+  /************* /
+ / decorations  /
+/ *************/
+
+.titlepage {
+}
+
+.part .title {
+}
+
+.subtitle {
+    border: none;
+}
+
+/*
+h1 {
+  border: none;
+}
+
+h2 {
+  border-top: solid 0.2em;
+  border-bottom: solid 0.06em;
+}
+
+h3 {
+  border-top: 0em;
+  border-bottom: solid 0.06em;
+}
+
+h4 {
+  border: 0em;
+  border-bottom: solid 0.06em;
+}
+
+h5 {
+  border: 0em;
+}
+*/
+
+.programlisting {
+  border: solid 1px;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example {
+  border: 1px solid;
+}
+
+
+
+.tip,
+.warning,
+.caution,
+.note {
+  border: 1px solid;
+}
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  border-bottom: 1px solid;
+}
+
+.question td {
+  border-top: 1px solid black;
+}
+
+.answer {
+}
+
+
+b.keycap,
+.keycap {
+  border: 1px solid;
+}
+
+
+div.navheader, div.heading{
+  border-bottom: 1px solid;
+}
+
+
+div.navfooter, div.footing{
+  border-top: 1px solid;
+}
+
+  /********* /
+ /  colors  /
+/ *********/
+
+body {
+  color: #333;
+  background: white;
+}
+
+a {
+  background: transparent;
+}
+
+a:hover {
+  background-color: #dedede;
+}
+
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7,
+h8 {
+  background-color: transparent;
+}
+
+hr {
+  border-color: #aaa;
+}
+
+
+.tip, .warning, .caution, .note {
+  border-color: #fff;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  border-bottom-color: #fff;
+}
+
+
+.warning {
+  background-color: #f0f0f2;
+}
+
+.caution {
+  background-color: #f0f0f2;
+}
+
+.tip {
+  background-color: #f0f0f2;
+}
+
+.note {
+  background-color: #f0f0f2;
+}
+
+.glossary dl dt,
+.variablelist dl dt,
+.variablelist dl dt span.term {
+  color: #044;
+}
+
+div.figure,
+div.table,
+div.example,
+div.informalfigure,
+div.informaltable,
+div.informalexample {
+  border-color: #aaa;
+}
+
+pre.programlisting {
+  color: black;
+  background-color: #fff;
+  border-color: #aaa;
+  border-width: 2px;
+}
+
+.guimenu,
+.guilabel,
+.guimenuitem {
+  background-color: #eee;
+}
+
+
+b.keycap,
+.keycap {
+  background-color: #eee;
+  border-color: #999;
+}
+
+
+div.navheader {
+  border-color: black;
+}
+
+
+div.navfooter {
+  border-color: black;
+}
+
+
+  /*********** /
+ /  graphics  /
+/ ***********/
+
+/*
+body {
+  background-image: url("images/body_bg.jpg");
+  background-attachment: fixed;
+}
+
+.navheader,
+.note,
+.tip {
+  background-image: url("images/note_bg.jpg");
+  background-attachment: fixed;
+}
+
+.warning,
+.caution {
+  background-image: url("images/warning_bg.jpg");
+  background-attachment: fixed;
+}
+
+.figure,
+.informalfigure,
+.example,
+.informalexample,
+.table,
+.informaltable {
+  background-image: url("images/figure_bg.jpg");
+  background-attachment: fixed;
+}
+
+*/
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7{
+}
+
+/*
+Example of how to stick an image as part of the title.
+
+div.article .titlepage .title
+{
+  background-image: url("figures/white-on-black.png");
+  background-position: center;
+  background-repeat: repeat-x;
+}
+*/
+
+div.preface .titlepage .title,
+div.colophon .title,
+div.chapter .titlepage .title,
+div.article .titlepage .title
+{
+}
+
+div.section div.section .titlepage .title,
+div.sect2 .titlepage .title {
+    background: none;
+}
+
+
+h1.title {
+  background-color: transparent;
+  background-image: url("figures/yocto-project-bw.png");
+  background-repeat: no-repeat;
+  height: 256px;
+  text-indent: -9000px;
+  overflow:hidden;
+}
+
+h2.subtitle {
+  background-color: transparent;
+  text-indent: -9000px;
+  overflow:hidden;
+  width: 0px;
+  display: none;
+}
+
+  /*************************************** /
+ /  pippin.gimp.org specific alterations  /
+/ ***************************************/
+
+/*
+div.heading, div.navheader {
+  color: #777;
+  font-size: 80%;
+  padding: 0;
+  margin: 0;
+  text-align: left;
+  position: absolute;
+  top: 0px;
+  left: 0px;
+  width: 100%;
+  height: 50px;
+  background: url('/gfx/heading_bg.png') transparent;
+  background-repeat: repeat-x;
+  background-attachment: fixed;
+  border: none;
+}
+
+div.heading a {
+  color: #444;
+}
+
+div.footing, div.navfooter {
+  border: none;
+  color: #ddd;
+  font-size: 80%;
+  text-align:right;
+
+  width: 100%;
+  padding-top: 10px;
+  position: absolute;
+  bottom: 0px;
+  left: 0px;
+
+  background: url('/gfx/footing_bg.png') transparent;
+}
+*/
+
+
+
+  /****************** /
+ /  nasty ie tweaks  /
+/ ******************/
+
+/*
+div.heading, div.navheader {
+  width:expression(document.body.clientWidth + "px");
+}
+
+div.footing, div.navfooter {
+  width:expression(document.body.clientWidth + "px");
+  margin-left:expression("-5em");
+}
+body {
+  padding:expression("4em 5em 0em 5em");
+}
+*/
+
+  /**************************************** /
+ / mozilla vendor specific css extensions  /
+/ ****************************************/
+/*
+div.navfooter, div.footing{
+  -moz-opacity: 0.8em;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example,
+.tip,
+.warning,
+.caution,
+.note {
+  -moz-border-radius: 0.5em;
+}
+
+b.keycap,
+.keycap {
+  -moz-border-radius: 0.3em;
+}
+*/
+
+table tr td table tr td {
+  display: none;
+}
+
+
+hr {
+  display: none;
+}
+
+table {
+  border: 0em;
+}
+
+ .photo {
+  float: right;
+  margin-left:   1.5em;
+  margin-bottom: 1.5em;
+  margin-top: 0em;
+  max-width:      17em;
+  border:     1px solid gray;
+  padding:    3px;
+  background: white;
+}
+ .seperator {
+   padding-top: 2em;
+   clear: both;
+  }
+
+  #validators {
+      margin-top: 5em;
+      text-align: right;
+      color: #777;
+  }
+  @media print {
+      body {
+          font-size: 8pt;
+      }
+      .noprint {
+          display: none;
+      }
+  }
+
+
+.tip,
+.note {
+   background: #f0f0f2;
+   color: #333;
+   padding: 20px;
+   margin: 20px;
+}
+
+.tip h3,
+.note h3 {
+   padding: 0em;
+   margin: 0em;
+   font-size: 2em;
+   font-weight: bold;
+   color: #333;
+}
+
+.tip a,
+.note a {
+   color: #333;
+   text-decoration: underline;
+}
+
+.footnote {
+   font-size: small;
+   color: #333;
+}
+
+/* Changes the announcement text */
+.tip h3,
+.warning h3,
+.caution h3,
+.note h3 {
+   font-size:large;
+   color: #00557D;
+}

documentation/kernel-dev/kernel-dev.xml

@@ -0,0 +1,80 @@
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<book id='kernel-dev' lang='en'
+      xmlns:xi="http://www.w3.org/2003/XInclude"
+      xmlns="http://docbook.org/ns/docbook"
+      >
+    <bookinfo>
+
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref='figures/kernel-dev-title.png'
+                    format='SVG'
+                    align='left' scalefit='1' width='100%'/>
+            </imageobject>
+        </mediaobject>
+
+        <title></title>
+
+        <authorgroup>
+            <author>
+                <firstname>Darren</firstname> <surname>Hart</surname>
+                <affiliation>
+                    <orgname>Intel Corporation</orgname>
+                </affiliation>
+                <email>darren.hart@intel.com</email>
+            </author>
+        </authorgroup>
+
+        <revhistory>
+            <revision>
+                <revnumber>1.4</revnumber>
+                <date>Sometime in 2013</date>
+                <revremark>Released with the Yocto Project 1.4 Release.</revremark>
+            </revision>
+        </revhistory>
+
+    <copyright>
+      <year>&COPYRIGHT_YEAR;</year>
+      <holder>Linux Foundation</holder>
+    </copyright>
+
+    <legalnotice>
+      <para>
+        Permission is granted to copy, distribute and/or modify this document under
+        the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
+      </para>
+      <note>
+          Due to production processes, there could be differences between the Yocto Project
+          documentation bundled in the release tarball and the
+          <ulink url='&YOCTO_DOCS_KERNEL_URL;'>Yocto Project Linux Kernel Development Manual</ulink> on
+          the <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website.
+          For the latest version of this manual, see the manual on the website.
+      </note>
+    </legalnotice>
+
+    </bookinfo>
+
+    <xi:include href="kernel-dev-intro.xml"/>
+
+    <xi:include href="kernel-dev-common.xml"/>
+
+    <xi:include href="kernel-dev-advanced.xml"/>
+
+<!--
+    <xi:include href="kernel-dev-examples.xml"/>
+-->
+
+    <xi:include href="kernel-dev-faq.xml"/>
+
+<!--    <index id='index'>
+      <title>Index</title>
+    </index>
+-->
+
+</book>
+<!--
+vim: expandtab tw=80 ts=4
+-->

documentation/kernel-manual/kernel-concepts.xml

@@ -22,38 +22,38 @@
     <section id='kernel-goals'>
         <title>Kernel Goals</title>
         <para>
-            The complexity of embedded kernel design has increased dramatically. 
+            The complexity of embedded kernel design has increased dramatically.
             Whether it is managing multiple implementations of a particular feature or tuning and
-            optimizing board specific features, both flexibility and maintainability are key concerns. 
+            optimizing board specific features, both flexibility and maintainability are key concerns.
             The Linux kernels available through the Yocto Project are presented with the embedded
-            developer's needs in mind and have evolved to assist in these key concerns. 
+            developer's needs in mind and have evolved to assist in these key concerns.
             For example, prior methods such as applying hundreds of patches to an extracted
             tarball have been replaced with proven techniques that allow easy inspection,
-            bisection and analysis of changes. 
-            Application of these techniques also creates a platform for performing integration and 
+            bisection and analysis of changes.
+            Application of these techniques also creates a platform for performing integration and
             collaboration with the thousands of upstream development projects.
         </para>
         <para>
             With all these considerations in mind, the Yocto Project's kernel and development team
             strives to attain these goals:
         <itemizedlist>
-            <listitem><para>Allow the end user to leverage community best practices to seamlessly 
+            <listitem><para>Allow the end user to leverage community best practices to seamlessly
             manage the development, build and debug cycles.</para></listitem>
-            <listitem><para>Create a platform for performing integration and collaboration with the 
+            <listitem><para>Create a platform for performing integration and collaboration with the
             thousands of upstream development projects that exist.</para></listitem>
-            <listitem><para>Provide mechanisms that support many different work flows, front-ends and 
+            <listitem><para>Provide mechanisms that support many different work flows, front-ends and
             management techniques.</para></listitem>
-            <listitem><para>Deliver the most up-to-date kernel possible while still ensuring that 
+            <listitem><para>Deliver the most up-to-date kernel possible while still ensuring that
             the baseline kernel is the most stable official release.</para></listitem>
-            <listitem><para>Include major technological features as part of the Yocto Project's 
+            <listitem><para>Include major technological features as part of the Yocto Project's
             upward revision strategy.</para></listitem>
-            <listitem><para>Present a kernel Git repository that, similar to the upstream 
-            <filename>kernel.org</filename> tree, 
+            <listitem><para>Present a kernel Git repository that, similar to the upstream
+            <filename>kernel.org</filename> tree,
             has a clear and continuous history.</para></listitem>
-            <listitem><para>Deliver a key set of supported kernel types, where each type is tailored 
+            <listitem><para>Deliver a key set of supported kernel types, where each type is tailored
             to meet a specific use (e.g. networking, consumer, devices, and so forth).</para></listitem>
             <listitem><para>Employ a Git branching strategy that, from a developer's point of view,
-            results in a linear path from the baseline <filename>kernel.org</filename>, 
+            results in a linear path from the baseline <filename>kernel.org</filename>,
             through a select group of features and
             ends with their BSP-specific commits.</para></listitem>
         </itemizedlist>
@@ -63,78 +63,78 @@
     <section id='kernel-big-picture'>
         <title>Yocto Project Kernel Development and Maintenance Overview</title>
         <para>
-            Kernels available through the Yocto Project, like other kernels, are based off the Linux 
-            kernel releases from <ulink url='http://www.kernel.org'></ulink>.  
+            Kernels available through the Yocto Project, like other kernels, are based off the Linux
+            kernel releases from <ulink url='http://www.kernel.org'></ulink>.
             At the beginning of a major development cycle, the Yocto Project team
-            chooses its kernel based on factors such as release timing, the anticipated release 
-            timing of final upstream <filename>kernel.org</filename> versions, and Yocto Project 
+            chooses its kernel based on factors such as release timing, the anticipated release
+            timing of final upstream <filename>kernel.org</filename> versions, and Yocto Project
             feature requirements.
             Typically, the kernel chosen is in the
             final stages of development by the community.
             In other words, the kernel is in the release
-            candidate or "rc" phase and not yet a final release. 
-            But, by being in the final stages of external development, the team knows that the 
-            <filename>kernel.org</filename> final release will clearly be within the early stages of 
+            candidate or "rc" phase and not yet a final release.
+            But, by being in the final stages of external development, the team knows that the
+            <filename>kernel.org</filename> final release will clearly be within the early stages of
             the Yocto Project development window.
         </para>
         <para>
             This balance allows the team to deliver the most up-to-date kernel
-            as possible, while still ensuring that the team has a stable official release for
+            possible, while still ensuring that the team has a stable official release for
             the baseline Linux kernel version.
         </para>
         <para>
-            The ultimate source for kernels available through the Yocto Project are released kernels 
+            The ultimate source for kernels available through the Yocto Project are released kernels
             from <filename>kernel.org</filename>.
-            In addition to a foundational kernel from <filename>kernel.org</filename>, the  
+            In addition to a foundational kernel from <filename>kernel.org</filename>, the
             kernels available contain a mix of important new mainline
             developments, non-mainline developments (when there is no alternative),
             Board Support Package (BSP) developments,
             and custom features.
-            These additions result in a commercially released Yocto Project Linux kernel that caters 
+            These additions result in a commercially released Yocto Project Linux kernel that caters
             to specific embedded designer needs for targeted hardware.
         </para>
         <para>
-            Once a kernel is officially released, the Yocto Project team goes into 
-            their next development cycle, or upward revision (uprev) cycle, while still 
+            Once a kernel is officially released, the Yocto Project team goes into
+            their next development cycle, or upward revision (uprev) cycle, while still
             continuing maintenance on the released kernel.
             It is important to note that the most sustainable and stable way
             to include feature development upstream is through a kernel uprev process.
             Back-porting hundreds of individual fixes and minor features from various
             kernel versions is not sustainable and can easily compromise quality.
         </para>
-        <para> 
+        <para>
             During the uprev cycle, the Yocto Project team uses an ongoing analysis of
             kernel development, BSP support, and release timing to select the best
             possible <filename>kernel.org</filename> version.
             The team continually monitors community kernel
             development to look for significant features of interest.
-            The team does consider back-porting large features if they have a significant advantage. 
+            The team does consider back-porting large features if they have a significant advantage.
             User or community demand can also trigger a back-port or creation of new
-            functionality in the Yocto Project baseline kernel during the uprev cycle. 
+            functionality in the Yocto Project baseline kernel during the uprev cycle.
         </para>
         <para>
             Generally speaking, every new kernel both adds features and introduces new bugs.
             These consequences are the basic properties of upstream kernel development and are
-            managed by the Yocto Project team's kernel strategy. 
-            It is the Yocto Project team's policy to not back-port minor features to the released kernel. 
-            They only consider back-porting significant technological jumps - and, that is done 
-            after a complete gap analysis. 
-            The reason for this policy is that back-porting any small to medium sized change 
-            from an evolving kernel can easily create mismatches, incompatibilities and very 
+            managed by the Yocto Project team's kernel strategy.
+            It is the Yocto Project team's policy to not back-port minor features to the released kernel.
+            They only consider back-porting significant technological jumps - and, that is done
+            after a complete gap analysis.
+            The reason for this policy is that back-porting any small to medium sized change
+            from an evolving kernel can easily create mismatches, incompatibilities and very
             subtle errors.
         </para>
         <para>
             These policies result in both a stable and a cutting
-            edge kernel that mixes forward ports of existing features and significant and critical 
-            new functionality. 
-            Forward porting functionality in the kernels available through the Yocto Project kernel 
+            edge kernel that mixes forward ports of existing features and significant and critical
+            new functionality.
+            Forward porting functionality in the kernels available through the Yocto Project kernel
             can be thought of as a "micro uprev."
-            The many “micro uprevs” produce a kernel version with a mix of 
-            important new mainline, non-mainline, BSP developments and feature integrations. 
+            The many “micro uprevs” produce a kernel version with a mix of
+            important new mainline, non-mainline, BSP developments and feature integrations.
             This kernel gives insight into new features and allows focused
             amounts of testing to be done on the kernel, which prevents
-            surprises when selecting the next major uprev. 
-            The quality of these cutting edge kernels is evolving and the kernels are used in leading edge 
+            surprises when selecting the next major uprev.
+            The quality of these cutting edge kernels is evolving and the kernels are used in leading edge
             feature and BSP development.
         </para>
     </section>
@@ -142,33 +142,33 @@
     <section id='kernel-architecture'>
         <title>Kernel Architecture</title>
         <para>
-            This section describes the architecture of the kernels available through the 
+            This section describes the architecture of the kernels available through the
             Yocto Project and provides information
             on the mechanisms used to achieve that architecture.
         </para>
-        
+
         <section id='architecture-overview'>
             <title>Overview</title>
             <para>
-                As mentioned earlier, a key goal of the Yocto Project is to present the 
-                developer with 
-                a kernel that has a clear and continuous history that is visible to the user. 
-                The architecture and mechanisms used achieve that goal in a manner similar to the 
+                As mentioned earlier, a key goal of the Yocto Project is to present the
+                developer with
+                a kernel that has a clear and continuous history that is visible to the user.
+                The architecture and mechanisms used achieve that goal in a manner similar to the
                 upstream <filename>kernel.org</filename>.
             </para>
             <para>
                 You can think of a Yocto Project kernel as consisting of a baseline Linux kernel with
                 added features logically structured on top of the baseline.
-                The features are tagged and organized by way of a branching strategy implemented by the 
+                The features are tagged and organized by way of a branching strategy implemented by the
                 source code manager (SCM) Git.
                 For information on Git as applied to the Yocto Project, see the
-                "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>" section in the 
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>" section in the
                 Yocto Project Development Manual.
             </para>
             <para>
-                The result is that the user has the ability to see the added features and 
+                The result is that the user has the ability to see the added features and
                 the commits that make up those features.
-                In addition to being able to see added features, the user can also view the history of what 
+                In addition to being able to see added features, the user can also view the history of what
                 made up the baseline kernel.
             </para>
             <para>
@@ -178,73 +178,73 @@
                 <imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" />
             </para>
             <para>
-                In the illustration, the "Kernel.org Branch Point" 
-                marks the specific spot (or release) from 
-                which the Yocto Project kernel is created.  
+                In the illustration, the "Kernel.org Branch Point"
+                marks the specific spot (or release) from
+                which the Yocto Project kernel is created.
                 From this point "up" in the tree, features and differences are organized and tagged.
             </para>
             <para>
                 The "Yocto Project Baseline Kernel" contains functionality that is common to every kernel
-                type and BSP that is organized further up the tree.  
-                Placing these common features in the 
-                tree this way means features don't have to be duplicated along individual branches of the 
+                type and BSP that is organized further up the tree.
+                Placing these common features in the
+                tree this way means features don't have to be duplicated along individual branches of the
                 structure.
             </para>
             <para>
                 From the Yocto Project Baseline Kernel, branch points represent specific functionality
                 for individual BSPs as well as real-time kernels.
-                The illustration represents this through three BSP-specific branches and a real-time 
-                kernel branch.  
+                The illustration represents this through three BSP-specific branches and a real-time
+                kernel branch.
                 Each branch represents some unique functionality for the BSP or a real-time kernel.
             </para>
             <para>
-                In this example structure, the real-time kernel branch has common features for all 
+                In this example structure, the real-time kernel branch has common features for all
                 real-time kernels and contains
-                more branches for individual BSP-specific real-time kernels.  
-                The illustration shows three branches as an example. 
+                more branches for individual BSP-specific real-time kernels.
+                The illustration shows three branches as an example.
                 Each branch points the way to specific, unique features for a respective real-time
                 kernel as they apply to a given BSP.
             </para>
             <para>
-                The resulting tree structure presents a clear path of markers (or branches) to the 
-                developer that, for all practical purposes, is the kernel needed for any given set 
+                The resulting tree structure presents a clear path of markers (or branches) to the
+                developer that, for all practical purposes, is the kernel needed for any given set
                 of requirements.
             </para>
         </section>
- 
+
         <section id='branching-and-workflow'>
             <title>Branching Strategy and Workflow</title>
             <para>
-                The Yocto Project team creates kernel branches at points where functionality is 
+                The Yocto Project team creates kernel branches at points where functionality is
                 no longer shared and thus, needs to be isolated.
                 For example, board-specific incompatibilities would require different functionality
-                and would require a branch to separate the features. 
+                and would require a branch to separate the features.
                 Likewise, for specific kernel features, the same branching strategy is used.
             </para>
             <para>
-                This branching strategy results in a tree that has features organized to be specific 
-                for particular functionality, single kernel types, or a subset of kernel types.  
-                This strategy also results in not having to store the same feature twice 
+                This branching strategy results in a tree that has features organized to be specific
+                for particular functionality, single kernel types, or a subset of kernel types.
+                This strategy also results in not having to store the same feature twice
                 internally in the tree.
-                Rather, the kernel team stores the unique differences required to apply the 
+                Rather, the kernel team stores the unique differences required to apply the
                 feature onto the kernel type in question.
                 <note>
-                    The Yocto Project team strives to place features in the tree such that they can be 
+                    The Yocto Project team strives to place features in the tree such that they can be
                     shared by all boards and kernel types where possible.
                     However, during development cycles or when large features are merged,
-                    the team cannot always follow this practice. 
+                    the team cannot always follow this practice.
                     In those cases, the team uses isolated branches to merge features.
                 </note>
             </para>
             <para>
-                BSP-specific code additions are handled in a similar manner to kernel-specific additions. 
+                BSP-specific code additions are handled in a similar manner to kernel-specific additions.
                 Some BSPs only make sense given certain kernel types.
-                So, for these types, the team creates branches off the end of that kernel type for all 
-                of the BSPs that are supported on that kernel type.  
-                From the perspective of the tools that create the BSP branch, the BSP is really no 
+                So, for these types, the team creates branches off the end of that kernel type for all
+                of the BSPs that are supported on that kernel type.
+                From the perspective of the tools that create the BSP branch, the BSP is really no
                 different than a feature.
                 Consequently, the same branching strategy applies to BSPs as it does to features.
-                So again, rather than store the BSP twice, the team only stores the unique 
+                So again, rather than store the BSP twice, the team only stores the unique
                 differences for the BSP across the supported multiple kernels.
             </para>
             <para>
@@ -252,47 +252,47 @@
                 important to realize that from the developer's point of view, there is a linear
                 path that travels from the baseline <filename>kernel.org</filename>, through a select
                 group of features and ends with their BSP-specific commits.
-                In other words, the divisions of the kernel are transparent and are not relevant 
-                to the developer on a day-to-day basis.  
+                In other words, the divisions of the kernel are transparent and are not relevant
+                to the developer on a day-to-day basis.
                 From the developer's perspective, this path is the "master" branch.
-                The developer does not need to be aware of the existence of any other branches at all.  
+                The developer does not need to be aware of the existence of any other branches at all.
                 Of course, there is value in the existence of these branches
-                in the tree, should a person decide to explore them. 
-                For example, a comparison between two BSPs at either the commit level or at the line-by-line 
+                in the tree, should a person decide to explore them.
+                For example, a comparison between two BSPs at either the commit level or at the line-by-line
                 code <filename>diff</filename> level is now a trivial operation.
             </para>
             <para>
-                Working with the kernel as a structured tree follows recognized community best practices. 
+                Working with the kernel as a structured tree follows recognized community best practices.
                 In particular, the kernel as shipped with the product, should be
                 considered an "upstream source" and viewed as a series of
-                historical and documented modifications (commits). 
+                historical and documented modifications (commits).
                 These modifications represent the development and stabilization done
                 by the Yocto Project kernel development team.
             </para>
             <para>
                 Because commits only change at significant release points in the product life cycle,
                 developers can work on a branch created
-                from the last relevant commit in the shipped Yocto Project kernel. 
+                from the last relevant commit in the shipped Yocto Project kernel.
                 As mentioned previously, the structure is transparent to the developer
                 because the kernel tree is left in this state after cloning and building the kernel.
             </para>
         </section>
-     
+
         <section id='source-code-manager-git'>
             <title>Source Code Manager - Git</title>
             <para>
                 The Source Code Manager (SCM) is Git.
-                This SCM is the obvious mechanism for meeting the previously mentioned goals.  
+                This SCM is the obvious mechanism for meeting the previously mentioned goals.
                 Not only is it the SCM for <filename>kernel.org</filename> but,
-                Git continues to grow in popularity and supports many different work flows, 
+                Git continues to grow in popularity and supports many different work flows,
                 front-ends and management techniques.
             </para>
             <para>
                 You can find documentation on Git at <ulink url='http://git-scm.com/documentation'></ulink>.
                 You can also get an introduction to Git as it applies to the Yocto Project in the
                 "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
-                section in the Yocto Project Development Manual. 
-                These referenced sections overview Git and describe a minimal set of 
+                section in the Yocto Project Development Manual.
+                These referenced sections overview Git and describe a minimal set of
                 commands that allows you to be functional using Git.
                 <note>
                     You can use as much, or as little, of what Git has to offer to accomplish what
@@ -307,11 +307,11 @@
         <title>Kernel Configuration</title>
         <para>
             Kernel configuration, along with kernel features, defines how a kernel
-            image is built for the Yocto Project. 
+            image is built for the Yocto Project.
             Through configuration settings, you can customize a Yocto Project kernel to be
             specific to particular hardware.
             For example, you can specify sound support or networking support.
-            This section describes basic concepts behind Kernel configuration within the 
+            This section describes basic concepts behind Kernel configuration within the
             Yocto Project and references you to other areas for specific configuration
             applications.
         </para>
@@ -319,52 +319,52 @@
         <para>
             Conceptually, configuration of a Yocto Project kernel occurs similarly to that needed for any
             Linux kernel.
-            The build process for a Yocto Project kernel uses a <filename>.config</filename> file, which 
-            is created through the Linux Kernel Coinfiguration (LKC) tool.
-            You can directly set various configurations in the 
-            <filename>.config</filename> file by using the <filename>menuconfig</filename> 
+            The build process for a Yocto Project kernel uses a <filename>.config</filename> file, which
+            is created through the Linux Kernel Configuration (LKC) tool.
+            You can directly set various configurations in the
+            <filename>.config</filename> file by using the <filename>menuconfig</filename>
             tool as built by BitBake.
             You can also define configurations in the file by using configuration fragments.
             <note>
                 It is not recommended that you edit the <filename>.config</filename> file directly.
             </note>
-            Here are some brief descriptions of the ways you can affect the 
+            Here are some brief descriptions of the ways you can affect the
             <filename>.config</filename> file:
             <itemizedlist>
-                <listitem><para><emphasis>The <filename>menuconfig</filename> Tool:</emphasis> 
-                    One of many front-ends that allows you to define kernel configurations.  
-                    Some others are <filename>make config</filename>, 
+                <listitem><para><emphasis>The <filename>menuconfig</filename> Tool:</emphasis>
+                    One of many front-ends that allows you to define kernel configurations.
+                    Some others are <filename>make config</filename>,
                     <filename>make nconfig</filename>, and <filename>make gconfig</filename>.
-                    In the Yocto Project environment, you must use BitBake to build the 
+                    In the Yocto Project environment, you must use BitBake to build the
                     <filename>menuconfig</filename> tool before you can use it to define
                     configurations:
                     <literallayout class='monospaced'>
      $ bitbake linux-yocto -c menuconfig
                     </literallayout>
                     After the tool is built, you can interact with it normally.
-                    You can see how <filename>menuconfig</filename> is used to change a simple 
-                    kernel configuration in the 
-                    "<ulink url='&YOCTO_DOCS_DEV_URL;#changing-the-config-smp-configuration-using-menuconfig'>Changing the&nbsp;&nbsp;<filename>CONFIG_SMP</filename> Configuration Using&nbsp;&nbsp;<filename>menuconfig</filename></ulink>" 
+                    You can see how <filename>menuconfig</filename> is used to change a simple
+                    kernel configuration in the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"
                     section of the Yocto Project Development Manual.
                     For general information on <filename>menuconfig</filename>, see
                     <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.
                     </para></listitem>
-                <listitem><para><emphasis>Configuration Fragments:</emphasis> A file with a 
-                    list of kernel options just as they would appear syntactically in the 
+                <listitem><para><emphasis>Configuration Fragments:</emphasis> A file with a
+                    list of kernel options just as they would appear syntactically in the
                     <filename>.config</filename> file.
                     Configuration fragments are typically logical groupings and are assembled
                     by the OpenEmbedded build system to produce input used by the LKC
                     that ultimately generates the <filename>.config</filename> file.</para>
-                    <para>The 
+                    <para>The
                     <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'>KERNEL_FEATURES</ulink></filename>
                     variable can be used to list configuration fragments.
-                    For further discussion on applying configuration fragments, see the 
+                    For further discussion on applying configuration fragments, see the
                     "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-kernel'>Linux Kernel Configuration</ulink>"
                     section in the Yocto Project Board Support Package (BSP) Guide.
                     </para></listitem>
             </itemizedlist>
         </para>
-    </section> 
+    </section>
 
     <section id='kernel-tools'>
         <title>Kernel Tools</title>
@@ -381,11 +381,11 @@
                 <listitem><para>Group patches into named, reusable features.</para></listitem>
                 <listitem><para>Allow top-down control of included features.</para></listitem>
                 <listitem><para>Bind kernel configurations to kernel patches and features.</para></listitem>
-                <listitem><para>Present a seamless Git repository that blends Yocto Project value 
+                <listitem><para>Present a seamless Git repository that blends Yocto Project value
                     with the <filename>kernel.org</filename> history and development.</para></listitem>
             </itemizedlist>
         </para>
-    </section> 
+    </section>
 </chapter>
 <!--
 vim: expandtab tw=80 ts=4

documentation/kernel-manual/kernel-doc-intro.xml

@@ -10,9 +10,9 @@
     <title>Introduction</title>
     <para>
         The Yocto Project presents kernels as a fully patched, history-clean Git
-        repositories. 
+        repositories.
         Each repository represents selected features, board support,
-        and configurations extensively tested by the Yocto Project. 
+        and configurations extensively tested by the Yocto Project.
         Yocto Project kernels allow the end user to leverage community
         best practices to seamlessly manage the development, build and debug cycles.
     </para>
@@ -22,14 +22,14 @@
         The manual consists of two sections:
         <itemizedlist>
             <listitem><para><emphasis>Concepts:</emphasis> Describes concepts behind a kernel.
-                You will understand how a kernel is organized and why it is organized in 
-                the way it is.  You will understand the benefits of a kernel's organization 
-                and the mechanisms used to work with the kernel and how to apply it in your 
+                You will understand how a kernel is organized and why it is organized in
+                the way it is.  You will understand the benefits of a kernel's organization
+                and the mechanisms used to work with the kernel and how to apply it in your
                 design process.</para></listitem>
-            <listitem><para><emphasis>Using a Kernel:</emphasis> Describes best practices 
+            <listitem><para><emphasis>Using a Kernel:</emphasis> Describes best practices
                 and "how-to" information
-                that lets you put a kernel to practical use.  
-                Some examples are how to examine changes in a branch and how to 
+                that lets you put a kernel to practical use.
+                Some examples are how to examine changes in a branch and how to
                 save kernel modifications.</para></listitem>
         </itemizedlist>
     </para>
@@ -38,10 +38,9 @@
         For more information on the Linux kernel, see the following links:
         <itemizedlist>
             <listitem><para>The Linux Foundation's guide for kernel development
-                process - <ulink url='http://ldn.linuxfoundation.org/book/1-a-guide-kernel-development-process'></ulink></para></listitem>
-<!--            <listitem><para><ulink url='http://userweb.kernel.org/~akpm/stuff/tpp.txt'></ulink></para></listitem> -->
-            <listitem><para>A fairly encompassing guide on Linux kernel development - 
-                <ulink url='http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/HOWTO;hb=HEAD'></ulink></para></listitem> 
+                process - <ulink url='http://www.linuxfoundation.org/content/1-guide-kernel-development-process'></ulink></para></listitem>
+            <listitem><para>A fairly encompassing guide on Linux kernel development -
+                <ulink url='http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob_plain;f=Documentation/HOWTO;hb=HEAD'></ulink></para></listitem>
         </itemizedlist>
     </para>
 
@@ -54,12 +53,14 @@
             <listitem><para>
                 "<ulink url='&YOCTO_DOCS_DEV_URL;#kernel-modification-workflow'>Kernel Modification Workflow</ulink>"
                 </para></listitem>
-            <listitem><para> 
-                "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-kernel-appendix'>Kernel Modification Example</ulink>"</para></listitem>
+            <listitem><para>
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"</para></listitem>
+            <listitem><para>
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"</para></listitem>
         </itemizedlist>
     </para>
 
-    <para> 
+    <para>
         For general information on the Yocto Project, visit the website at
         <ulink url='&YOCTO_HOME_URL;'></ulink>.
     </para>

documentation/kernel-manual/kernel-how-to.xml

@@ -10,11 +10,11 @@
 <section id='actions-org'>
     <title>Introduction</title>
     <para>
-        This chapter describes how to accomplish tasks involving a kernel's tree structure. 
-        The information is designed to help the developer that wants to modify the Yocto 
+        This chapter describes how to accomplish tasks involving a kernel's tree structure.
+        The information is designed to help the developer that wants to modify the Yocto
         Project kernel and contribute changes upstream to the Yocto Project.
         The information covers the following:
-        <itemizedlist> 
+        <itemizedlist>
             <listitem><para>Tree construction</para></listitem>
             <listitem><para>Build strategies</para></listitem>
             <listitem><para>Workflow examples</para></listitem>
@@ -25,72 +25,72 @@
     <section id='tree-construction'>
         <title>Tree Construction</title>
         <para>
-            This section describes construction of the Yocto Project kernel source repositories 
+            This section describes construction of the Yocto Project kernel source repositories
             as accomplished by the Yocto Project team to create kernel repositories.
             These kernel repositories are found under the heading "Yocto Linux Kernel" at
             <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>&YOCTO_GIT_URL;/cgit.cgi</ulink>
-            and can be shipped as part of a Yocto Project release. 
+            and can be shipped as part of a Yocto Project release.
             The team creates these repositories by
             compiling and executing the set of feature descriptions for every BSP/feature
-            in the product. 
+            in the product.
             Those feature descriptions list all necessary patches,
             configuration, branching, tagging and feature divisions found in a kernel.
             Thus, the Yocto Project kernel repository (or tree) is built.
         </para>
         <para>
-            The existence of this tree allows you to access and clone a particular 
+            The existence of this tree allows you to access and clone a particular
             Yocto Project kernel repository and use it to build images based on their configurations
             and features.
         </para>
         <para>
-            You can find the files used to describe all the valid features and BSPs 
-            in the Yocto Project kernel in any clone of the Yocto Project kernel source repository 
+            You can find the files used to describe all the valid features and BSPs
+            in the Yocto Project kernel in any clone of the Yocto Project kernel source repository
             Git tree.
-            For example, the following command clones the Yocto Project baseline kernel that 
+            For example, the following command clones the Yocto Project baseline kernel that
             branched off of <filename>linux.org</filename> version 3.4:
             <literallayout class='monospaced'>
      $ git clone git://git.yoctoproject.org/linux-yocto-3.4
             </literallayout>
             For another example of how to set up a local Git repository of the Yocto Project
-            kernel files, see the 
-            "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted 
+            kernel files, see the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted
             item in the Yocto Project Development Manual.
         </para>
-        <para>  
-            Once you have cloned the kernel Git repository on your local machine, you can 
+        <para>
+            Once you have cloned the kernel Git repository on your local machine, you can
             switch to the <filename>meta</filename> branch within the repository.
-            Here is an example that assumes the local Git repository for the kernel is in 
+            Here is an example that assumes the local Git repository for the kernel is in
             a top-level directory named <filename>linux-yocto-3.4</filename>:
             <literallayout class='monospaced'>
      $ cd ~/linux-yocto-3.4
      $ git checkout -b meta origin/meta
             </literallayout>
             Once you have checked out and switched to the <filename>meta</filename> branch,
-            you can see a snapshot of all the kernel configuration and feature descriptions that are 
+            you can see a snapshot of all the kernel configuration and feature descriptions that are
             used to build that particular kernel repository.
-            These descriptions are in the form of <filename>.scc</filename> files. 
+            These descriptions are in the form of <filename>.scc</filename> files.
         </para>
         <para>
             You should realize, however, that browsing your local kernel repository
             for feature descriptions and patches is not an effective way to determine what is in a
-            particular kernel branch. 
+            particular kernel branch.
             Instead, you should use Git directly to discover the changes in a branch.
-            Using Git is an efficient and flexible way to inspect changes to the kernel.  
+            Using Git is an efficient and flexible way to inspect changes to the kernel.
             For examples showing how to use Git to inspect kernel commits, see the following sections
             in this chapter.
             <note>
-                Ground up reconstruction of the complete kernel tree is an action only taken by the 
-                Yocto Project team during an active development cycle.  
-                When you create a clone of the kernel Git repository, you are simply making it 
+                Ground up reconstruction of the complete kernel tree is an action only taken by the
+                Yocto Project team during an active development cycle.
+                When you create a clone of the kernel Git repository, you are simply making it
                 efficiently available for building and development.
             </note>
         </para>
         <para>
             The following steps describe what happens when the Yocto Project Team constructs
-            the Yocto Project kernel source Git repository (or tree) found at 
-            <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the 
-            introduction of a new top-level kernel feature or BSP. 
-            These are the actions that effectively create the tree 
+            the Yocto Project kernel source Git repository (or tree) found at
+            <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the
+            introduction of a new top-level kernel feature or BSP.
+            These are the actions that effectively create the tree
             that includes the new feature, patch or BSP:
             <orderedlist>
                 <listitem><para>A top-level kernel feature is passed to the kernel build subsystem.
@@ -103,7 +103,7 @@
                         <listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements
                             found in recipes</para></listitem>
                     </itemizedlist>
-                    For a typical build, the target of the search is a 
+                    For a typical build, the target of the search is a
                     feature description in an <filename>.scc</filename> file
                     whose name follows this format:
                     <literallayout class='monospaced'>
@@ -113,19 +113,19 @@
                 <listitem><para>Once located, the feature description is either compiled into a simple script
                     of actions, or into an existing equivalent script that is already part of the
                     shipped kernel.</para></listitem>
-                <listitem><para>Extra features are appended to the top-level feature description. 
-                    These features can come from the 
+                <listitem><para>Extra features are appended to the top-level feature description.
+                    These features can come from the
                     <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
                     variable in recipes.</para></listitem>
-                <listitem><para>Each extra feature is located, compiled and appended to the script 
+                <listitem><para>Each extra feature is located, compiled and appended to the script
                     as described in step three.</para></listitem>
                 <listitem><para>The script is executed to produce a series of <filename>meta-*</filename>
-                    directories. 
+                    directories.
                     These directories are descriptions of all the branches, tags, patches and configurations that
                     need to be applied to the base Git repository to completely create the
                     source (build) branch for the new BSP or feature.</para></listitem>
                 <listitem><para>The base repository is cloned, and the actions
-                    listed in the <filename>meta-*</filename> directories are applied to the 
+                    listed in the <filename>meta-*</filename> directories are applied to the
                     tree.</para></listitem>
                 <listitem><para>The Git repository is left with the desired branch checked out and any
                     required branching, patching and tagging has been performed.</para></listitem>
@@ -133,17 +133,17 @@
         </para>
         <para>
             The kernel tree is now ready for developer consumption to be locally cloned,
-            configured, and built into a Yocto Project kernel specific to some target hardware. 
-            <note><para>The generated <filename>meta-*</filename> directories add to the kernel 
-                as shipped with the Yocto Project release. 
-                Any add-ons and configuration data are applied to the end of an existing branch. 
-                The full repository generation that is found in the 
+            configured, and built into a Yocto Project kernel specific to some target hardware.
+            <note><para>The generated <filename>meta-*</filename> directories add to the kernel
+                as shipped with the Yocto Project release.
+                Any add-ons and configuration data are applied to the end of an existing branch.
+                The full repository generation that is found in the
                 official Yocto Project kernel repositories at
                 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>
                 is the combination of all supported boards and configurations.</para>
-                <para>The technique the Yocto Project team uses is flexible and allows for seamless 
-                blending of an immutable history with additional patches specific to a 
-                deployment. 
+                <para>The technique the Yocto Project team uses is flexible and allows for seamless
+                blending of an immutable history with additional patches specific to a
+                deployment.
                 Any additions to the kernel become an integrated part of the branches.</para>
             </note>
         </para>
@@ -152,15 +152,16 @@
     <section id='build-strategy'>
         <title>Build Strategy</title>
         <para>
-            Once a local Git repository of the Yocto Project kernel exists on a development system, 
+            Once a local Git repository of the Yocto Project kernel exists on a development system,
             you can consider the compilation phase of kernel development - building a kernel image.
             Some prerequisites exist that are validated by the build process before compilation
             starts:
         </para>
 
         <itemizedlist>
-            <listitem><para>The <filename>SRC_URI</filename> points to the kernel Git 
-                repository.</para></listitem>
+            <listitem><para>The
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> points
+                to the kernel Git repository.</para></listitem>
             <listitem><para>A BSP build branch exists.
                 This branch has the following form:
                 <literallayout class='monospaced'>
@@ -170,22 +171,22 @@
 
         <para>
             The OpenEmbedded build system makes sure these conditions exist before attempting compilation.
-            Other means, however, do exist, such as as bootstrapping a BSP, see 
+            Other means, however, do exist, such as as bootstrapping a BSP, see
             the "<link linkend='workflow-examples'>Workflow Examples</link>".
         </para>
 
         <para>
-            Before building a kernel, the build process verifies the tree 
+            Before building a kernel, the build process verifies the tree
             and configures the kernel by processing all of the
             configuration "fragments" specified by feature descriptions in the <filename>.scc</filename>
-            files. 
+            files.
             As the features are compiled, associated kernel configuration fragments are noted
-            and recorded in the <filename>meta-*</filename> series of directories in their compilation order. 
+            and recorded in the <filename>meta-*</filename> series of directories in their compilation order.
             The fragments are migrated, pre-processed and passed to the Linux Kernel
-            Configuration subsystem (<filename>lkc</filename>) as raw input in the form 
+            Configuration subsystem (<filename>lkc</filename>) as raw input in the form
             of a <filename>.config</filename> file.
             The <filename>lkc</filename> uses its own internal dependency constraints to do the final
-            processing of that information and generates the final <filename>.config</filename> file 
+            processing of that information and generates the final <filename>.config</filename> file
             that is used during compilation.
         </para>
 
@@ -196,9 +197,9 @@
 
         <para>
             The other thing that you notice once you configure a kernel is that
-            the build process generates a build tree that is separate from your kernel's local Git 
+            the build process generates a build tree that is separate from your kernel's local Git
             source repository tree.
-            This build tree has a name that uses the following form, where 
+            This build tree has a name that uses the following form, where
             <filename>${MACHINE}</filename> is the metadata name of the machine (BSP) and "kernel_type" is one
             of the Yocto Project supported kernel types (e.g. "standard"):
         <literallayout class='monospaced'>
@@ -207,13 +208,13 @@
         </para>
 
         <para>
-            The existing support in the <filename>kernel.org</filename> tree achieves this 
+            The existing support in the <filename>kernel.org</filename> tree achieves this
             default functionality.
         </para>
 
         <para>
-            This behavior means that all the generated files for a particular machine or BSP are now in 
-            the build tree directory.  
+            This behavior means that all the generated files for a particular machine or BSP are now in
+            the build tree directory.
             The files include the final <filename>.config</filename> file, all the <filename>.o</filename>
             files, the <filename>.a</filename> files, and so forth.
             Since each machine or BSP has its own separate build directory in its own separate branch
@@ -228,18 +229,18 @@
             As previously noted, the Yocto Project kernel has built-in Git integration.
             However, these utilities are not the only way to work with the kernel repository.
             The Yocto Project has not made changes to Git or to other tools that
-            would invalidate alternate workflows. 
-            Additionally, the way the kernel repository is constructed results in using 
-            only core Git functionality, thus allowing any number of tools or front ends to use the 
+            would invalidate alternate workflows.
+            Additionally, the way the kernel repository is constructed results in using
+            only core Git functionality, thus allowing any number of tools or front ends to use the
             resulting tree.
         </para>
 
         <para>
             This section contains several workflow examples.
-            Many of the examples use Git commands. 
-            You can find Git documentation at 
+            Many of the examples use Git commands.
+            You can find Git documentation at
             <ulink url='http://git-scm.com/documentation'></ulink>.
-            You can find a simple overview of using Git with the Yocto Project in the 
+            You can find a simple overview of using Git with the Yocto Project in the
             "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
             section of the Yocto Project Development Manual.
         </para>
@@ -248,25 +249,25 @@
             <title>Change Inspection: Kernel Changes/Commits</title>
 
             <para>
-                A common question when working with a BSP or kernel is: 
+                A common question when working with a BSP or kernel is:
                 "What changes have been applied to this tree?"
             </para>
 
             <para>
                 In projects that have a collection of directories that
-                contain patches to the kernel, it is possible to inspect or "grep" the contents 
-                of the directories to get a general feel for the changes. 
+                contain patches to the kernel, it is possible to inspect or "grep" the contents
+                of the directories to get a general feel for the changes.
                 This sort of patch inspection is not an efficient way to determine what has been done to the
                 kernel.
-                The reason it is inefficient is because there are many optional patches that are 
+                The reason it is inefficient is because there are many optional patches that are
                 selected based on the kernel type and the feature description.
                 Additionally, patches could exist in directories that are not included in the search.
             </para>
 
             <para>
                 A more efficient way to determine what has changed in the kernel is to use
-                Git and inspect or search the kernel tree. 
-                This method gives you a full view of not only the source code modifications, 
+                Git and inspect or search the kernel tree.
+                This method gives you a full view of not only the source code modifications,
                 but also provides the reasons for the changes.
             </para>
 
@@ -276,11 +277,11 @@
                 <para>
                     Following are a few examples that show how to use Git to examine changes.
                     Because the Yocto Project Git repository does not break existing Git
-                    functionality and because there exists many permutations of these types of 
+                    functionality and because there exists many permutations of these types of
                     commands, there are many more methods to discover changes.
                     <note>
-                        Unless you provide a commit range 
-                        (&lt;kernel-type&gt;..&lt;bsp&gt;-&lt;kernel-type&gt;), <filename>kernel.org</filename> history 
+                        Unless you provide a commit range
+                        (&lt;kernel-type&gt;..&lt;bsp&gt;-&lt;kernel-type&gt;), <filename>kernel.org</filename> history
                         is blended with Yocto Project changes.
                     </note>
                     <literallayout class='monospaced'>
@@ -300,27 +301,27 @@
 
      # determine the change history of a particular file
      &gt; git whatchanged &lt;path to file&gt;
-   
+
      # determine the commits which touch each line in a file
      &gt; git blame &lt;path to file&gt;
                     </literallayout>
                 </para>
             </section>
- 
+
             <section id='show-a-particular-feature-or-branch-change'>
                 <title>Show a Particular Feature or Branch Change</title>
 
                 <para>
-                    Developers use tags in the Yocto Project kernel tree to divide changes for significant 
-                    features or branches. 
-                    Once you know a particular tag, you can use Git commands 
+                    Developers use tags in the Yocto Project kernel tree to divide changes for significant
+                    features or branches.
+                    Once you know a particular tag, you can use Git commands
                     to show changes associated with the tag and find the branches that contain
-                    the feature.  
+                    the feature.
                     <note>
-                        Because BSP branch, <filename>kernel.org</filename>, and feature tags are all 
+                        Because BSP branch, <filename>kernel.org</filename>, and feature tags are all
                         present, there could be many tags.
                     </note>
-                    The <filename>git show &lt;tag&gt;</filename> command shows changes that are tagged by 
+                    The <filename>git show &lt;tag&gt;</filename> command shows changes that are tagged by
                     a feature.
                     Here is an example that shows changes tagged by the <filename>systemtap</filename>
                     feature:
@@ -338,7 +339,7 @@
 
                 <para>
                     You can use many other comparisons to isolate BSP and kernel changes.
-                    For example, you can compare against <filename>kernel.org</filename> tags 
+                    For example, you can compare against <filename>kernel.org</filename> tags
                     such as the <filename>v3.4</filename> tag.
                 </para>
             </section>
@@ -349,29 +350,29 @@
 
             <para>
                 Another common operation is to build a BSP supplied by the Yocto Project, make some
-                changes, rebuild, and then test. 
+                changes, rebuild, and then test.
                 Those local changes often need to be exported, shared or otherwise maintained.
             </para>
 
             <para>
                 Since the Yocto Project kernel source tree is backed by Git, this activity is
-                much easier as compared to with previous releases. 
-                Because Git tracks file modifications, additions and deletions, it is easy 
+                much easier as compared to with previous releases.
+                Because Git tracks file modifications, additions and deletions, it is easy
                 to modify the code and later realize that you need to save the changes.
-                It is also easy to determine what has changed. 
+                It is also easy to determine what has changed.
                 This method also provides many tools to commit, undo and export those modifications.
             </para>
 
             <para>
-                This section and its sub-sections, describe general application of Git's 
-                <filename>push</filename> and <filename>pull</filename> commands, which are used to 
-                get your changes upstream or source your code from an upstream repository.  
-                The Yocto Project provides scripts that help you work in a collaborative development 
-                environment.  
+                This section and its sub-sections, describe general application of Git's
+                <filename>push</filename> and <filename>pull</filename> commands, which are used to
+                get your changes upstream or source your code from an upstream repository.
+                The Yocto Project provides scripts that help you work in a collaborative development
+                environment.
                 For information on these scripts, see the
-                "<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change 
-                Upstream and Request a Pull</ulink>" and   
-                "<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-patch'>Using Email to Submit a Patch</ulink>" 
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change
+                Upstream and Request a Pull</ulink>" and
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-patch'>Using Email to Submit a Patch</ulink>"
                 sections in the Yocto Project Development Manual.
             </para>
 
@@ -379,7 +380,7 @@
                 There are many ways to save kernel modifications.
                 The technique employed
                 depends on the destination for the patches:
-   
+
                 <itemizedlist>
                     <listitem><para>Bulk storage</para></listitem>
                     <listitem><para>Internal sharing either through patches or by using Git</para></listitem>
@@ -390,7 +391,7 @@
             </para>
 
             <para>
-                Because of the following list of issues, the destination of the patches also influences 
+                Because of the following list of issues, the destination of the patches also influences
                 the method for gathering them:
 
                 <itemizedlist>
@@ -404,24 +405,24 @@
                 <title>Bulk Export</title>
 
                 <para>
-                    This section describes how you can "bulk" export changes that have not 
-                    been separated or divided. 
-                    This situation works well when you are simply storing patches outside of the kernel 
-                    source repository, either permanently or temporarily, and you are not committing 
+                    This section describes how you can "bulk" export changes that have not
+                    been separated or divided.
+                    This situation works well when you are simply storing patches outside of the kernel
+                    source repository, either permanently or temporarily, and you are not committing
                     incremental changes during development.
                     <note>
                         This technique is not appropriate for full integration of upstream submission
                         because changes are not properly divided and do not provide an avenue for per-change
-                        commit messages.  
-                        Therefore, this example assumes that changes have not been committed incrementally 
+                        commit messages.
+                        Therefore, this example assumes that changes have not been committed incrementally
                         during development and that you simply must gather and export them.
                     </note>
                     <literallayout class='monospaced'>
      # bulk export of ALL modifications without separation or division
-     # of the changes 
+     # of the changes
 
      $ git add .
-     $ git commit -s -a -m &lt;msg&gt; 
+     $ git commit -s -a -m &lt;msg&gt;
         or
      $ git commit -s -a # and interact with $EDITOR
                     </literallayout>
@@ -446,8 +447,8 @@
                 <para>
                     This section describes how to save modifications when you are making incremental
                     commits or practicing planned sharing.
-                    The examples in this section assume that you have incrementally committed 
-                    changes to the tree during development and now need to export them.  
+                    The examples in this section assume that you have incrementally committed
+                    changes to the tree during development and now need to export them.
                     The sections that follow
                     describe how you can export your changes internally through either patches or by
                     using Git commands.
@@ -455,7 +456,7 @@
 
                 <para>
                     During development, the following commands are of interest.
-                    For full Git documentation, refer to the Git documentation at  
+                    For full Git documentation, refer to the Git documentation at
                     <ulink url='http://github.com'></ulink>.
 
                     <literallayout class='monospaced'>
@@ -475,15 +476,15 @@
                 </para>
 
                 <para>
-                    Distributed development with Git is possible when you use a universally 
+                    Distributed development with Git is possible when you use a universally
                     agreed-upon unique commit identifier (set by the creator of the commit) that maps to a
-                    specific change set with a specific parent.  
+                    specific change set with a specific parent.
                     This identifier is created for you when
                     you create a commit, and is re-created when you amend, alter or re-apply
-                    a commit.  
+                    a commit.
                     As an individual in isolation, this is of no interest.
                     However, if you
-                    intend to share your tree with normal Git <filename>push</filename> and 
+                    intend to share your tree with normal Git <filename>push</filename> and
                     <filename>pull</filename> operations for
                     distributed development, you should consider the ramifications of changing a
                     commit that you have already shared with others.
@@ -491,7 +492,7 @@
 
                 <para>
                     Assuming that the changes have not been pushed upstream, or pulled into
-                    another repository, you can update both the commit content and commit messages 
+                    another repository, you can update both the commit content and commit messages
                     associated with development by using the following commands:
 
                     <literallayout class='monospaced'>
@@ -501,7 +502,7 @@
                     </literallayout>
                 </para>
 
-                <para>   
+                <para>
                     Again, assuming that the changes have not been pushed upstream, and that
                     no pending works-in-progress exist (use <filename>git status</filename> to check), then
                     you can revert (undo) commits by using the following commands:
@@ -520,12 +521,12 @@
                 <para>
                     You can create branches, "cherry-pick" changes, or perform any number of Git
                     operations until the commits are in good order for pushing upstream
-                    or for pull requests. 
-                    After a <filename>push</filename> or <filename>pull</filename> command, 
+                    or for pull requests.
+                    After a <filename>push</filename> or <filename>pull</filename> command,
                     commits are normally considered
                     "permanent" and you should not modify them.
                     If the commits need to be changed, you can incrementally do so with new commits.
-                    These practices follow standard Git workflow and the <filename>kernel.org</filename> best 
+                    These practices follow standard Git workflow and the <filename>kernel.org</filename> best
                     practices, which is recommended.
                     <note>
                         It is recommended to tag or branch before adding changes to a Yocto Project
@@ -534,26 +535,26 @@
                         reference point to facilitate locating and exporting local changes.
                     </note>
                 </para>
-          
+
                 <section id='export-internally-via-patches'>
                     <title>Exporting Changes Internally by Using Patches</title>
 
                     <para>
                         This section describes how you can extract committed changes from a working directory
                         by exporting them as patches.
-                        Once the changes have been extracted, you can use the patches for upstream submission, 
+                        Once the changes have been extracted, you can use the patches for upstream submission,
                         place them in a Yocto Project template for automatic kernel patching,
                         or apply them in many other common uses.
                     </para>
 
                     <para>
                         This example shows how to create a directory with sequentially numbered patches.
-                        Once the directory is created, you can apply it to a repository using the 
-                        <filename>git am</filename> command to reproduce the original commit and all 
+                        Once the directory is created, you can apply it to a repository using the
+                        <filename>git am</filename> command to reproduce the original commit and all
                         the related information such as author, date, commit log, and so forth.
                         <note>
-                            The new commit identifiers (ID) will be generated upon re-application.  
-                            This action reflects that the commit is now applied to an underlying commit 
+                            The new commit identifiers (ID) will be generated upon re-application.
+                            This action reflects that the commit is now applied to an underlying commit
                             with a different ID.
                         </note>
                         <literallayout class='monospaced'>
@@ -580,19 +581,19 @@
      $ git format-patch -o &lt;save dir&gt; &lt;commit id&gt;
      $ git format-patch -o &lt;save dir&gt; &lt;rev-list&gt;
                         </literallayout>
-                    </para> 
-                </section> 
+                    </para>
+                </section>
 
                 <section id='export-internally-via-git'>
                     <title>Exporting Changes Internally by Using Git</title>
 
                     <para>
-                        This section describes how you can export changes from a working directory 
+                        This section describes how you can export changes from a working directory
                         by pushing the changes into a master repository or by making a pull request.
-                        Once you have pushed the changes to the master repository, you can then 
+                        Once you have pushed the changes to the master repository, you can then
                         pull those same changes into a new kernel build at a later time.
                     </para>
- 
+
                     <para>
                         Use this command form to push the changes:
                         <literallayout class='monospaced'>
@@ -603,7 +604,7 @@
 
                     <para>
                         For example, the following command pushes the changes from your local branch
-                        <filename>yocto/standard/common-pc/base</filename> to the remote branch with the same name 
+                        <filename>yocto/standard/common-pc/base</filename> to the remote branch with the same name
                         in the master repository <filename>//git.mycompany.com/pub/git/kernel-3.4</filename>.
                         <literallayout class='monospaced'>
      $ git push ssh://git.mycompany.com/pub/git/kernel-3.4 \
@@ -612,7 +613,7 @@
                     </para>
 
                     <para>
-                        A pull request entails using the <filename>git request-pull</filename> command to compose 
+                        A pull request entails using the <filename>git request-pull</filename> command to compose
                         an email to the
                         maintainer requesting that a branch be pulled into the master repository, see
                         <ulink url='http://github.com/guides/pull-requests'></ulink> for an example.
@@ -621,7 +622,7 @@
                             changes, but are not covered in this document.
                         </note>
                     </para>
-                </section> 
+                </section>
             </section>
 
             <section id='export-for-external-upstream-submission'>
@@ -635,12 +636,12 @@
                     This method allows easy review and integration of the changes.
                     <note>
                         Before sending patches for review be sure you understand the
-                        community standards for submitting and documenting changes and follow their best practices.  
+                        community standards for submitting and documenting changes and follow their best practices.
                         For example, kernel patches should follow standards such as:
                         <itemizedlist>
                             <listitem><para>
                                 <ulink url='http://linux.yyz.us/patch-format.html'></ulink></para></listitem>
-                            <listitem><para>Documentation/SubmittingPatches (in any linux 
+                            <listitem><para>Documentation/SubmittingPatches (in any linux
                                 kernel source tree)</para></listitem>
                         </itemizedlist>
                     </note>
@@ -650,30 +651,30 @@
                     The messages used to commit changes are a large part of these standards.
                     Consequently, be sure that the headers for each commit have the required information.
                     For information on how to follow the Yocto Project commit message standards, see the
-                    "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a 
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a
                     Change</ulink>" section in the Yocto Project Development Manual.
                 </para>
 
                 <para>
                     If the initial commits were not properly documented or do not meet those standards,
-                    you can re-base by using the <filename>git rebase -i</filename> command to 
+                    you can re-base by using the <filename>git rebase -i</filename> command to
                     manipulate the commits and
-                    get them into the required format. 
+                    get them into the required format.
                     Other techniques such as branching and cherry-picking commits are also viable options.
                 </para>
 
                 <para>
-                    Once you complete the commits, you can generate the email that sends the patches 
-                    to the maintainer(s) or lists that review and integrate changes. 
-                    The command <filename>git send-email</filename> is commonly used to ensure 
-                    that patches are properly 
+                    Once you complete the commits, you can generate the email that sends the patches
+                    to the maintainer(s) or lists that review and integrate changes.
+                    The command <filename>git send-email</filename> is commonly used to ensure
+                    that patches are properly
                     formatted for easy application and avoid mailer-induced patch damage.
                 </para>
 
                 <para>
                     The following is an example of dumping patches for external submission:
                     <literallayout class='monospaced'>
-     # dump the last 4 commits 
+     # dump the last 4 commits
      $ git format-patch --thread -n -o ~/rr/ HEAD^^^^
      $ git send-email --compose --subject '[RFC 0/N] &lt;patch series summary&gt;' \
       --to foo@yoctoproject.org --to bar@yoctoproject.org \
@@ -689,17 +690,17 @@
 
                 <para>
                     When you want to export changes for import into another
-                    Source Code Manager (SCM), you can use any of the previously discussed 
+                    Source Code Manager (SCM), you can use any of the previously discussed
                     techniques.
-                    However, if the patches are manually applied to a secondary tree and then 
-                    that tree is checked into the SCM, you can lose change information such as 
+                    However, if the patches are manually applied to a secondary tree and then
+                    that tree is checked into the SCM, you can lose change information such as
                     commit logs.
                     This process is not recommended.
                 </para>
 
                 <para>
                     Many SCMs can directly import Git commits, or can translate Git patches so that
-                    information is not lost. 
+                    information is not lost.
                     Those facilities are SCM-dependent and you should use them whenever possible.
                 </para>
             </section>
@@ -709,15 +710,15 @@
             <title>Working with the Yocto Project Kernel in Another SCM</title>
 
             <para>
-                This section describes kernel development in an SCM other than Git, 
+                This section describes kernel development in an SCM other than Git,
                 which is not the same as exporting changes to another SCM described earlier.
-                For this scenario, you use the OpenEmbedded build system to 
+                For this scenario, you use the OpenEmbedded build system to
                 develop the kernel in a different SCM.
                 The following must be true for you to accomplish this:
                 <itemizedlist>
                     <listitem><para>The delivered Yocto Project kernel must be exported into the second
                         SCM.</para></listitem>
-                    <listitem><para>Development must be exported from that secondary SCM into a 
+                    <listitem><para>Development must be exported from that secondary SCM into a
                         format that can be used by the OpenEmbedded build system.</para></listitem>
                 </itemizedlist>
             </para>
@@ -727,7 +728,7 @@
 
                 <para>
                     Depending on the SCM, it might be possible to export the entire Yocto Project
-                    kernel Git repository, branches and all, into a new environment. 
+                    kernel Git repository, branches and all, into a new environment.
                     This method is preferred because it has the most flexibility and potential to maintain
                     the meta data associated with each commit.
                 </para>
@@ -749,11 +750,11 @@
                 </para>
 
                 <para>
-                    You could now relocate the CVS repository and use it in a centralized manner. 
+                    You could now relocate the CVS repository and use it in a centralized manner.
                 </para>
 
                 <para>
-                    The following commands illustrate how you can condense and merge two BSPs into a 
+                    The following commands illustrate how you can condense and merge two BSPs into a
                     second SCM:
                     <literallayout class='monospaced'>
      $ git checkout yocto/standard/common-pc/base
@@ -767,7 +768,7 @@
 
             <section id='importing-changes-for-build'>
                 <title>Importing Changes for the Build</title>
- 
+
                 <para>
                     Once development has reached a suitable point in the second development
                     environment, you need to export the changes as patches.
@@ -781,12 +782,12 @@
             <title>Creating a BSP Based on an Existing Similar BSP</title>
 
             <para>
-                This section overviews the process of creating a BSP based on an 
+                This section overviews the process of creating a BSP based on an
                 existing similar BSP.
-                The information is introductory in nature and does not provide step-by-step examples. 
-                For detailed information on how to create a BSP given an existing similar BSP, see
-                the "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-bsp-appendix'>BSP Development 
-                Example</ulink>" appendix in the Yocto Project Development Manual, or see the 
+                The information is introductory in nature and does not provide step-by-step examples.
+                For detailed information on how to create a new BSP, see
+                the "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" section in the
+                Yocto Project Board Support Package (BSP) Developer's Guide, or see the
                 <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>Transcript:_creating_one_generic_Atom_BSP_from_another</ulink>
                 wiki page.
             </para>
@@ -794,42 +795,43 @@
             <para>
                 The basic steps you need to follow are:
                 <orderedlist>
-                    <listitem><para><emphasis>Make sure you have set up a local source directory:</emphasis>
-                        You must create a local <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>source
-                        directory</ulink> by either creating a Git repository (recommended) or 
+                    <listitem><para><emphasis>Make sure you have set up a local Source Directory:</emphasis>
+                        You must create a local
+                        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+                        by either creating a Git repository (recommended) or
                         extracting a Yocto Project release tarball.</para></listitem>
                     <listitem><para><emphasis>Choose an existing BSP available with the Yocto Project:</emphasis>
-                        Try to map your board features as closely to the features of a BSP that is  
-                        already supported and exists in the Yocto Project.  
-                        Starting with something as close as possible to your board makes developing 
-                        your BSP easier.  
-                        You can find all the BSPs that are supported and ship with the Yocto Project 
-                        on the Yocto Project's Download page at 
+                        Try to map your board features as closely to the features of a BSP that is
+                        already supported and exists in the Yocto Project.
+                        Starting with something as close as possible to your board makes developing
+                        your BSP easier.
+                        You can find all the BSPs that are supported and ship with the Yocto Project
+                        on the Yocto Project's Download page at
                         <ulink url='&YOCTO_HOME_URL;/download'></ulink>.</para></listitem>
                     <listitem><para><emphasis>Be sure you have the Base BSP:</emphasis>
-                        You need to either have a local Git repository of the base BSP set up or 
+                        You need to either have a local Git repository of the base BSP set up or
                         have downloaded and extracted the files from a release BSP tarball.
                         Either method gives you access to the BSP source files.</para></listitem>
-                    <listitem><para><emphasis>Make a copy of the existing BSP, thus isolating your new 
+                    <listitem><para><emphasis>Make a copy of the existing BSP, thus isolating your new
                         BSP work:</emphasis>
                         Copying the existing BSP file structure gives you a new area in which to work.</para></listitem>
                     <listitem><para><emphasis>Make configuration and recipe changes to your new BSP:</emphasis>
                         Configuration changes involve the files in the BSP's <filename>conf</filename>
-                        directory. 
-                        Changes include creating a machine-specific configuration file and editing the 
-                        <filename>layer.conf</filename> file.  
+                        directory.
+                        Changes include creating a machine-specific configuration file and editing the
+                        <filename>layer.conf</filename> file.
                         The configuration changes identify the kernel you will be using.
-                        Recipe changes include removing, modifying, or adding new recipe files that 
+                        Recipe changes include removing, modifying, or adding new recipe files that
                         instruct the build process on what features to include in the image.</para></listitem>
                     <listitem><para><emphasis>Prepare for the build:</emphasis>
                         Before you actually initiate the build, you need to set up the build environment
-                        by sourcing the environment initialization script.  
-                        After setting up the environment, you need to make some build configuration 
+                        by sourcing the environment initialization script.
+                        After setting up the environment, you need to make some build configuration
                         changes to the <filename>local.conf</filename> and <filename>bblayers.conf</filename>
                         files.</para></listitem>
                     <listitem><para><emphasis>Build the image:</emphasis>
-                        The OpenEmbedded build system uses BitBake to create the image. 
-                        You need to decide on the type of image you are going to build (e.g. minimal, base, 
+                        The OpenEmbedded build system uses BitBake to create the image.
+                        You need to decide on the type of image you are going to build (e.g. minimal, base,
                         core, sato, and so forth) and then start the build using the <filename>bitbake</filename>
                         command.</para></listitem>
                 </orderedlist>
@@ -849,8 +851,8 @@
             </para>
 
             <para>
-                You can use the above Git command to report modified, removed, or added files. 
-                You should commit those changes to the tree regardless of whether they will be saved, 
+                You can use the above Git command to report modified, removed, or added files.
+                You should commit those changes to the tree regardless of whether they will be saved,
                 exported, or used.
                 Once you commit the changes you need to rebuild the kernel.
             </para>

documentation/kernel-manual/kernel-manual.xml

@@ -2,7 +2,7 @@
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
 [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
 
-<book id='kernel-manual' lang='en' 
+<book id='kernel-manual' lang='en'
       xmlns:xi="http://www.w3.org/2003/XInclude"
       xmlns="http://docbook.org/ns/docbook"
       >
@@ -10,13 +10,13 @@
 
         <mediaobject>
             <imageobject>
-                <imagedata fileref='figures/kernel-title.png' 
-                    format='SVG' 
+                <imagedata fileref='figures/kernel-title.png'
+                    format='SVG'
                     align='left' scalefit='1' width='100%'/>
-            </imageobject>    
+            </imageobject>
         </mediaobject>
 
-        <title></title> 
+        <title></title>
 
         <authorgroup>
             <author>
@@ -56,9 +56,14 @@
             </revision>
             <revision>
                 <revnumber>1.3</revnumber>
-                <date>Sometime in 2012</date>
+                <date>October 2012</date>
                 <revremark>Released with the Yocto Project 1.3 Release.</revremark>
             </revision>
+            <revision>
+                <revnumber>1.4</revnumber>
+                <date>Sometime in 2013</date>
+                <revremark>Released with the Yocto Project 1.4 Release.</revremark>
+            </revision>
         </revhistory>
 
     <copyright>
@@ -68,7 +73,7 @@
 
     <legalnotice>
       <para>
-        Permission is granted to copy, distribute and/or modify this document under 
+        Permission is granted to copy, distribute and/or modify this document under
         the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
       </para>
       <note>
@@ -94,6 +99,6 @@
 -->
 
 </book>
-<!-- 
-vim: expandtab tw=80 ts=4 
+<!--
+vim: expandtab tw=80 ts=4
 -->