bitbake: fetch2: Change git fetcher not to destroy old references

It looks like we're about to see a lot of changes in branch names in repos. If
we have the prune option here, those old names are lost, the changes propagate
to our source mirrors and our old releases break.

We have the force option so any replaced references should be replaced, its only
orphaned branches which will now be preserved.

I believe this behaviour will cause us fewer problems given the changes that
look likely to happen.

(Bitbake rev: 1df4fb1c9bf2fde0b274374bff1235c4b1f7ac79)

Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

bitbake/bin/bitbake

@@ -38,7 +38,7 @@ from bb.main import bitbake_main, BitBakeConfigParameters, BBMainException
 if sys.getfilesystemencoding() != "utf-8":
     sys.exit("Please use a locale setting which supports UTF-8 (such as LANG=en_US.UTF-8).\nPython can't change the filesystem locale after loading so we need a UTF-8 when Python starts or things won't work.")
 
-__version__ = "1.37.0"
+__version__ = "1.38.0"
 
 if __name__ == "__main__":
     if __version__ != bb.__version__:

bitbake/bin/bitbake-diffsigs

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 
-# bitbake-diffsigs
+# bitbake-diffsigs / bitbake-dumpsig
-# BitBake task signature data comparison utility
+# BitBake task signature data dump and comparison utility
 #
 # Copyright (C) 2012-2013, 2017 Intel Corporation
 #
@@ -21,7 +21,6 @@
 import os
 import sys
 import warnings
-import fnmatch
 import argparse
 import logging
 import pickle
@@ -32,7 +31,10 @@ import bb.tinfoil
 import bb.siggen
 import bb.msg
 
-logger = bb.msg.logger_create('bitbake-diffsigs')
+myname = os.path.basename(sys.argv[0])
+logger = bb.msg.logger_create(myname)
+
+is_dump = myname == 'bitbake-dumpsig'
 
 def find_siginfo(tinfoil, pn, taskname, sigs=None):
     result = None
@@ -59,8 +61,8 @@ def find_siginfo(tinfoil, pn, taskname, sigs=None):
         sys.exit(2)
     return result
 
-def find_compare_task(bbhandler, pn, taskname, sig1=None, sig2=None, color=False):
+def find_siginfo_task(bbhandler, pn, taskname, sig1=None, sig2=None):
-    """ Find the most recent signature files for the specified PN/task and compare them """
+    """ Find the most recent signature files for the specified PN/task """
 
     if not taskname.startswith('do_'):
         taskname = 'do_%s' % taskname
@@ -79,73 +81,81 @@ def find_compare_task(bbhandler, pn, taskname, sig1=None, sig2=None, color=False
         latestfiles = [sigfiles[sig1], sigfiles[sig2]]
     else:
         filedates = find_siginfo(bbhandler, pn, taskname)
-        latestfiles = sorted(filedates.keys(), key=lambda f: filedates[f])[-3:]
+        latestfiles = sorted(filedates.keys(), key=lambda f: filedates[f])[-2:]
         if not latestfiles:
             logger.error('No sigdata files found matching %s %s' % (pn, taskname))
             sys.exit(1)
-        elif len(latestfiles) < 2:
-            logger.error('Only one matching sigdata file found for the specified task (%s %s)' % (pn, taskname))
-            sys.exit(1)
 
-    # Define recursion callback
+    return latestfiles
-    def recursecb(key, hash1, hash2):
-        hashes = [hash1, hash2]
-        hashfiles = find_siginfo(bbhandler, key, None, hashes)
 
-        recout = []
-        if len(hashfiles) == 0:
-            recout.append("Unable to find matching sigdata for %s with hashes %s or %s" % (key, hash1, hash2))
-        elif not hash1 in hashfiles:
-            recout.append("Unable to find matching sigdata for %s with hash %s" % (key, hash1))
-        elif not hash2 in hashfiles:
-            recout.append("Unable to find matching sigdata for %s with hash %s" % (key, hash2))
-        else:
-            out2 = bb.siggen.compare_sigfiles(hashfiles[hash1], hashfiles[hash2], recursecb, color=color)
-            for change in out2:
-                for line in change.splitlines():
-                    recout.append('  ' + line)
 
-        return recout
+# Define recursion callback
+def recursecb(key, hash1, hash2):
+    hashes = [hash1, hash2]
+    hashfiles = find_siginfo(tinfoil, key, None, hashes)
 
-    # Recurse into signature comparison
+    recout = []
-    logger.debug("Signature file (previous): %s" % latestfiles[-2])
+    if len(hashfiles) == 0:
-    logger.debug("Signature file (latest): %s" % latestfiles[-1])
+        recout.append("Unable to find matching sigdata for %s with hashes %s or %s" % (key, hash1, hash2))
-    output = bb.siggen.compare_sigfiles(latestfiles[-2], latestfiles[-1], recursecb, color=color)
+    elif not hash1 in hashfiles:
-    if output:
+        recout.append("Unable to find matching sigdata for %s with hash %s" % (key, hash1))
-        print('\n'.join(output))
+    elif not hash2 in hashfiles:
-    sys.exit(0)
+        recout.append("Unable to find matching sigdata for %s with hash %s" % (key, hash2))
+    else:
+        out2 = bb.siggen.compare_sigfiles(hashfiles[hash1], hashfiles[hash2], recursecb, color=color)
+        for change in out2:
+            for line in change.splitlines():
+                recout.append('  ' + line)
 
+    return recout
 
 
 parser = argparse.ArgumentParser(
-    description="Compares siginfo/sigdata files written out by BitBake")
+    description=("Dumps" if is_dump else "Compares") + " siginfo/sigdata files written out by BitBake")
 
-parser.add_argument('-d', '--debug',
+parser.add_argument('-D', '--debug',
                     help='Enable debug output',
                     action='store_true')
 
-parser.add_argument('--color',
+if is_dump:
-        help='Colorize output (where %(metavar)s is %(choices)s)',
+    parser.add_argument("-t", "--task",
-        choices=['auto', 'always', 'never'], default='auto', metavar='color')
+            help="find the signature data file for the last run of the specified task",
+            action="store", dest="taskargs", nargs=2, metavar=('recipename', 'taskname'))
 
-parser.add_argument("-t", "--task",
+    parser.add_argument("sigdatafile1",
-        help="find the signature data files for last two runs of the specified task and compare them",
+            help="Signature file to dump. Not used when using -t/--task.",
-        action="store", dest="taskargs", nargs=2, metavar=('recipename', 'taskname'))
+            action="store", nargs='?', metavar="sigdatafile")
+else:
+    parser.add_argument('-c', '--color',
+            help='Colorize the output (where %(metavar)s is %(choices)s)',
+            choices=['auto', 'always', 'never'], default='auto', metavar='color')
 
-parser.add_argument("-s", "--signature",
+    parser.add_argument('-d', '--dump',
-        help="With -t/--task, specify the signatures to look for instead of taking the last two",
+            help='Dump the last signature data instead of comparing (equivalent to using bitbake-dumpsig)',
-        action="store", dest="sigargs", nargs=2, metavar=('fromsig', 'tosig'))
+            action='store_true')
 
-parser.add_argument("sigdatafile1",
+    parser.add_argument("-t", "--task",
-        help="First signature file to compare (or signature file to dump, if second not specified). Not used when using -t/--task.",
+            help="find the signature data files for the last two runs of the specified task and compare them",
-        action="store", nargs='?')
+            action="store", dest="taskargs", nargs=2, metavar=('recipename', 'taskname'))
 
-parser.add_argument("sigdatafile2",
+    parser.add_argument("-s", "--signature",
-        help="Second signature file to compare",
+            help="With -t/--task, specify the signatures to look for instead of taking the last two",
-        action="store", nargs='?')
+            action="store", dest="sigargs", nargs=2, metavar=('fromsig', 'tosig'))
 
+    parser.add_argument("sigdatafile1",
+            help="First signature file to compare (or signature file to dump, if second not specified). Not used when using -t/--task.",
+            action="store", nargs='?')
+
+    parser.add_argument("sigdatafile2",
+            help="Second signature file to compare",
+            action="store", nargs='?')
 
 options = parser.parse_args()
+if is_dump:
+    options.color = 'never'
+    options.dump = True
+    options.sigdatafile2 = None
+    options.sigargs = None
 
 if options.debug:
     logger.setLevel(logging.DEBUG)
@@ -155,17 +165,32 @@ color = (options.color == 'always' or (options.color == 'auto' and sys.stdout.is
 if options.taskargs:
     with bb.tinfoil.Tinfoil() as tinfoil:
         tinfoil.prepare(config_only=True)
-        if options.sigargs:
+        if not options.dump and options.sigargs:
-            find_compare_task(tinfoil, options.taskargs[0], options.taskargs[1], options.sigargs[0], options.sigargs[1], color=color)
+            files = find_siginfo_task(tinfoil, options.taskargs[0], options.taskargs[1], options.sigargs[0], options.sigargs[1])
         else:
-            find_compare_task(tinfoil, options.taskargs[0], options.taskargs[1], color=color)
+            files = find_siginfo_task(tinfoil, options.taskargs[0], options.taskargs[1])
+
+        if options.dump:
+            logger.debug("Signature file: %s" % files[-1])
+            output = bb.siggen.dump_sigfile(files[-1])
+        else:
+            if len(files) < 2:
+                logger.error('Only one matching sigdata file found for the specified task (%s %s)' % (options.taskargs[0], options.taskargs[1]))
+                sys.exit(1)
+
+            # Recurse into signature comparison
+            logger.debug("Signature file (previous): %s" % files[-2])
+            logger.debug("Signature file (latest): %s" % files[-1])
+            output = bb.siggen.compare_sigfiles(files[-2], files[-1], recursecb, color=color)
 else:
     if options.sigargs:
         logger.error('-s/--signature can only be used together with -t/--task')
         sys.exit(1)
     try:
-        if options.sigdatafile1 and options.sigdatafile2:
+        if not options.dump and options.sigdatafile1 and options.sigdatafile2:
-            output = bb.siggen.compare_sigfiles(options.sigdatafile1, options.sigdatafile2, color=color)
+            with bb.tinfoil.Tinfoil() as tinfoil:
+                tinfoil.prepare(config_only=True)
+                output = bb.siggen.compare_sigfiles(options.sigdatafile1, options.sigdatafile2, recursecb, color=color)
         elif options.sigdatafile1:
             output = bb.siggen.dump_sigfile(options.sigdatafile1)
         else:
@@ -179,5 +204,5 @@ else:
         logger.error('Invalid signature data - ensure you are specifying sigdata/siginfo files')
         sys.exit(1)
 
-    if output:
+if output:
-        print('\n'.join(output))
+    print('\n'.join(output))

bitbake/bin/bitbake-dumpsig

@@ -1,94 +0,0 @@
-#!/usr/bin/env python3
-
-# bitbake-dumpsig
-# BitBake task signature dump utility
-#
-# Copyright (C) 2013 Intel Corporation
-#
-# 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 os
-import sys
-import warnings
-import optparse
-import logging
-import pickle
-
-sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(sys.argv[0])), 'lib'))
-
-import bb.tinfoil
-import bb.siggen
-import bb.msg
-
-logger = bb.msg.logger_create('bitbake-dumpsig')
-
-def find_siginfo_task(bbhandler, pn, taskname):
-    """ Find the most recent signature file for the specified PN/task """
-
-    if not hasattr(bb.siggen, 'find_siginfo'):
-        logger.error('Metadata does not support finding signature data files')
-        sys.exit(1)
-
-    if not taskname.startswith('do_'):
-        taskname = 'do_%s' % taskname
-
-    filedates = bb.siggen.find_siginfo(pn, taskname, None, bbhandler.config_data)
-    latestfiles = sorted(filedates.keys(), key=lambda f: filedates[f])[-1:]
-    if not latestfiles:
-        logger.error('No sigdata files found matching %s %s' % (pn, taskname))
-        sys.exit(1)
-
-    return latestfiles[0]
-
-parser = optparse.OptionParser(
-    description = "Dumps siginfo/sigdata files written out by BitBake",
-    usage = """
-  %prog -t recipename taskname
-  %prog sigdatafile""")
-
-parser.add_option("-D", "--debug",
-        help = "enable debug",
-        action = "store_true", dest="debug", default = False)
-
-parser.add_option("-t", "--task",
-        help = "find the signature data file for the specified task",
-        action="store", dest="taskargs", nargs=2, metavar='recipename taskname')
-
-options, args = parser.parse_args(sys.argv)
-
-if options.debug:
-    logger.setLevel(logging.DEBUG)
-
-if options.taskargs:
-    tinfoil = bb.tinfoil.Tinfoil()
-    tinfoil.prepare(config_only = True)
-    file = find_siginfo_task(tinfoil, options.taskargs[0], options.taskargs[1])
-    logger.debug("Signature file: %s" % file)
-elif len(args) == 1:
-    parser.print_help()
-    sys.exit(0)
-else:
-    file = args[1]
-
-try:
-    output = bb.siggen.dump_sigfile(file)
-except IOError as e:
-    logger.error(str(e))
-    sys.exit(1)
-except (pickle.UnpicklingError, EOFError):
-    logger.error('Invalid signature data - ensure you are specifying a sigdata/siginfo file')
-    sys.exit(1)
-
-if output:
-    print('\n'.join(output))

bitbake/bin/bitbake-dumpsig

@@ -0,0 +1 @@
+bitbake-diffsigs

bitbake/bin/bitbake-worker

@@ -192,9 +192,6 @@ def fork_off_task(cfg, data, databuilder, workerdata, fn, task, taskname, append
             global worker_pipe_lock
             pipein.close()
 
-            signal.signal(signal.SIGTERM, sigterm_handler)
-            # Let SIGHUP exit as SIGTERM
-            signal.signal(signal.SIGHUP, sigterm_handler)
             bb.utils.signal_on_parent_exit("SIGTERM")
 
             # Save out the PID so that the event can include it the
@@ -209,6 +206,11 @@ def fork_off_task(cfg, data, databuilder, workerdata, fn, task, taskname, append
             # This ensures signals sent to the controlling terminal like Ctrl+C
             # don't stop the child processes.
             os.setsid()
+
+            signal.signal(signal.SIGTERM, sigterm_handler)
+            # Let SIGHUP exit as SIGTERM
+            signal.signal(signal.SIGHUP, sigterm_handler)
+
             # No stdin
             newsi = os.open(os.devnull, os.O_RDWR)
             os.dup2(newsi, sys.stdin.fileno())

bitbake/bin/toaster

@@ -18,11 +18,12 @@
 # along with this program. If not, see http://www.gnu.org/licenses/.
 
 HELP="
-Usage: source toaster start|stop [webport=<address:port>] [noweb] [nobuild]
+Usage: source toaster start|stop [webport=<address:port>] [noweb] [nobuild] [toasterdir]
     Optional arguments:
         [nobuild] Setup the environment for capturing builds with toaster but disable managed builds
         [noweb] Setup the environment for capturing builds with toaster but don't start the web server
         [webport] Set the development server (default: localhost:8000)
+        [toasterdir] Set absolute path to be used as TOASTER_DIR (default: BUILDDIR/../)
 "
 
 custom_extention()
@@ -160,7 +161,9 @@ fi
 
 export BBBASEDIR=`dirname $TOASTER`/..
 MANAGE="python3 $BBBASEDIR/lib/toaster/manage.py"
-OE_ROOT=`dirname $TOASTER`/../..
+if [ -z "$OE_ROOT" ]; then
+    OE_ROOT=`dirname $TOASTER`/../..
+fi
 
 # this is the configuraton file we are using for toaster
 # we are using the same logic that oe-setup-builddir uses
@@ -186,6 +189,7 @@ unset OE_ROOT
 WEBSERVER=1
 export TOASTER_BUILDSERVER=1
 ADDR_PORT="localhost:8000"
+TOASTERDIR=`dirname $BUILDDIR`
 unset CMD
 for param in $*; do
     case $param in
@@ -211,6 +215,9 @@ for param in $*; do
                 ADDR_PORT="localhost:$PORT"
             fi
     ;;
+    toasterdir=*)
+            TOASTERDIR="${param#*=}"
+    ;;
     --help)
             echo "$HELP"
             return 0
@@ -241,7 +248,7 @@ fi
 # 2) the build dir (in build)
 # 3) the sqlite db if that is being used.
 # 4) pid's we need to clean up on exit/shutdown
-export TOASTER_DIR=`dirname $BUILDDIR`
+export TOASTER_DIR=$TOASTERDIR
 export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE TOASTER_DIR"
 
 # Determine the action. If specified by arguments, fine, if not, toggle it

bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml

@@ -588,6 +588,14 @@
                         The name of the path in which to place the checkout.
                         By default, the path is <filename>git/</filename>.
                         </para></listitem>
+                    <listitem><para><emphasis>"usehead":</emphasis>
+                        Enables local <filename>git://</filename> URLs to use the
+                        current branch HEAD as the revision for use with
+                        <filename>AUTOREV</filename>.
+                        The "usehead" parameter implies no branch and only works
+                        when the transfer protocol is
+                        <filename>file://</filename>.
+                        </para></listitem>
                 </itemizedlist>
                 Here are some example URLs:
                 <literallayout class='monospaced'>

bitbake/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml

@@ -502,7 +502,7 @@
         </section>
 
         <section id='unsetting-variables'>
-            <title>Unseting variables</title>
+            <title>Unsetting variables</title>
 
             <para>
                 It is possible to completely remove a variable or a variable flag

bitbake/doc/bitbake-user-manual/bitbake-user-manual.xml

@@ -56,7 +56,7 @@
 -->
 
         <copyright>
-            <year>2004-2017</year>
+            <year>2004-2018</year>
             <holder>Richard Purdie</holder>
             <holder>Chris Larson</holder>
             <holder>and Phil Blundell</holder>

bitbake/lib/bb/COW.py

@@ -150,7 +150,7 @@ class COWDictMeta(COWMeta):
                 yield value
             if type == "items":
                 yield (key, value)
-        raise StopIteration()
+        return
 
     def iterkeys(cls):
         return cls.iter("keys")

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.37.0"
+__version__ = "1.38.0"
 
 import sys
 if sys.version_info < (3, 4, 0):

bitbake/lib/bb/checksum.py

@@ -97,6 +97,8 @@ class FileChecksumCache(MultiProcessCache):
 
         def checksum_dir(pth):
             # Handle directories recursively
+            if pth == "/":
+                bb.fatal("Refusing to checksum /")
             dirchecksums = []
             for root, dirs, files in os.walk(pth):
                 for name in files:

bitbake/lib/bb/cooker.py

@@ -175,18 +175,31 @@ class BBCooker:
 
         self.configuration = configuration
 
+        bb.debug(1, "BBCooker starting %s" % time.time())
+        sys.stdout.flush()
+
         self.configwatcher = pyinotify.WatchManager()
+        bb.debug(1, "BBCooker pyinotify1 %s" % time.time())
+        sys.stdout.flush()
+
         self.configwatcher.bbseen = []
         self.configwatcher.bbwatchedfiles = []
         self.confignotifier = pyinotify.Notifier(self.configwatcher, self.config_notifications)
+        bb.debug(1, "BBCooker pyinotify2 %s" % time.time())
+        sys.stdout.flush()
         self.watchmask = pyinotify.IN_CLOSE_WRITE | pyinotify.IN_CREATE | pyinotify.IN_DELETE | \
                          pyinotify.IN_DELETE_SELF | pyinotify.IN_MODIFY | pyinotify.IN_MOVE_SELF | \
                          pyinotify.IN_MOVED_FROM | pyinotify.IN_MOVED_TO
         self.watcher = pyinotify.WatchManager()
+        bb.debug(1, "BBCooker pyinotify3 %s" % time.time())
+        sys.stdout.flush()
         self.watcher.bbseen = []
         self.watcher.bbwatchedfiles = []
         self.notifier = pyinotify.Notifier(self.watcher, self.notifications)
 
+        bb.debug(1, "BBCooker pyinotify complete %s" % time.time())
+        sys.stdout.flush()
+
         # If being called by something like tinfoil, we need to clean cached data
         # which may now be invalid
         bb.parse.clear_cache()
@@ -196,6 +209,9 @@ class BBCooker:
 
         self.initConfigurationData()
 
+        bb.debug(1, "BBCooker parsed base configuration %s" % time.time())
+        sys.stdout.flush()
+
         # we log all events to a file if so directed
         if self.configuration.writeeventlog:
             # register the log file writer as UI Handler
@@ -233,6 +249,9 @@ class BBCooker:
         # Let SIGHUP exit as SIGTERM
         signal.signal(signal.SIGHUP, self.sigterm_exception)
 
+        bb.debug(1, "BBCooker startup complete %s" % time.time())
+        sys.stdout.flush()
+
     def process_inotify_updates(self):
         for n in [self.confignotifier, self.notifier]:
             if n.check_events(timeout=0):

bitbake/lib/bb/fetch2/__init__.py

@@ -1457,7 +1457,7 @@ class FetchMethod(object):
                 else:
                     cmd = 'rpm2cpio.sh %s | cpio -id' % (file)
             elif file.endswith('.deb') or file.endswith('.ipk'):
-                output = subprocess.check_output('ar -t %s' % file, preexec_fn=subprocess_setup, shell=True)
+                output = subprocess.check_output(['ar', '-t', file], preexec_fn=subprocess_setup)
                 datafile = None
                 if output:
                     for line in output.decode().splitlines():

bitbake/lib/bb/fetch2/clearcase.py

@@ -69,7 +69,6 @@ from   bb.fetch2 import FetchMethod
 from   bb.fetch2 import FetchError
 from   bb.fetch2 import runfetchcmd
 from   bb.fetch2 import logger
-from   distutils import spawn
 
 class ClearCase(FetchMethod):
     """Class to fetch urls via 'clearcase'"""
@@ -107,7 +106,7 @@ class ClearCase(FetchMethod):
         else:
             ud.module = ""
 
-        ud.basecmd = d.getVar("FETCHCMD_ccrc") or spawn.find_executable("cleartool") or spawn.find_executable("rcleartool")
+        ud.basecmd = d.getVar("FETCHCMD_ccrc") or "/usr/bin/env cleartool || rcleartool"
 
         if d.getVar("SRCREV") == "INVALID":
           raise FetchError("Set a valid SRCREV for the clearcase fetcher in your recipe, e.g. SRCREV = \"/main/LATEST\" or any other label of your choice.")

bitbake/lib/bb/fetch2/git.py

@@ -354,13 +354,12 @@ class Git(FetchMethod):
             if not self._contains_ref(ud, d, name, ud.clonedir):
                 needupdate = True
         if needupdate:
-            try: 
+            output = runfetchcmd("%s remote" % ud.basecmd, d, quiet=True, workdir=ud.clonedir)
-                runfetchcmd("%s remote rm origin" % ud.basecmd, d, workdir=ud.clonedir)
+            if "origin" in output:
-            except bb.fetch2.FetchError:
+              runfetchcmd("%s remote rm origin" % ud.basecmd, d, workdir=ud.clonedir)
-                logger.debug(1, "No Origin")
 
             runfetchcmd("%s remote add --mirror=fetch origin %s" % (ud.basecmd, repourl), d, workdir=ud.clonedir)
-            fetch_cmd = "LANG=C %s fetch -f --prune --progress %s refs/*:refs/*" % (ud.basecmd, repourl)
+            fetch_cmd = "LANG=C %s fetch -f --progress %s refs/*:refs/*" % (ud.basecmd, repourl)
             if ud.proto.lower() != 'file':
                 bb.fetch2.check_network_access(d, fetch_cmd, ud.url)
             progresshandler = GitProgressHandler(d)

bitbake/lib/bb/fetch2/npm.py

@@ -32,7 +32,6 @@ from   bb.fetch2 import runfetchcmd
 from   bb.fetch2 import logger
 from   bb.fetch2 import UnpackError
 from   bb.fetch2 import ParameterError
-from   distutils import spawn
 
 def subprocess_setup():
     # Python installs a SIGPIPE handler by default. This is usually not what

bitbake/lib/bb/main.py

@@ -405,9 +405,6 @@ def setup_bitbake(configParams, configuration, extrafeatures=None):
         # In status only mode there are no logs and no UI
         logger.addHandler(handler)
 
-    # Clear away any spurious environment variables while we stoke up the cooker
-    cleanedvars = bb.utils.clean_environment()
-
     if configParams.server_only:
         featureset = []
         ui_module = None
@@ -423,6 +420,10 @@ def setup_bitbake(configParams, configuration, extrafeatures=None):
 
     server_connection = None
 
+    # Clear away any spurious environment variables while we stoke up the cooker
+    # (done after import_extension_module() above since for example import gi triggers env var usage)
+    cleanedvars = bb.utils.clean_environment()
+
     if configParams.remote_server:
         # Connect to a remote XMLRPC server
         server_connection = bb.server.xmlrpcclient.connectXMLRPC(configParams.remote_server, featureset,
@@ -447,7 +448,7 @@ def setup_bitbake(configParams, configuration, extrafeatures=None):
                 else:
                     logger.info("Reconnecting to bitbake server...")
                     if not os.path.exists(sockname):
-                        print("Previous bitbake instance shutting down?, waiting to retry...")
+                        logger.info("Previous bitbake instance shutting down?, waiting to retry...")
                         i = 0
                         lock = None
                         # Wait for 5s or until we can get the lock

bitbake/lib/bb/runqueue.py

@@ -1371,6 +1371,12 @@ class RunQueue:
                 bb.event.fire(bb.event.DepTreeGenerated(depgraph), self.cooker.data)
 
         if self.state is runQueueSceneInit:
+            if not self.dm_event_handler_registered:
+                 res = bb.event.register(self.dm_event_handler_name,
+                                         lambda x: self.dm.check(self) if self.state in [runQueueSceneRun, runQueueRunning, runQueueCleanUp] else False,
+                                         ('bb.event.HeartbeatEvent',))
+                 self.dm_event_handler_registered = True
+
             dump = self.cooker.configuration.dump_signatures
             if dump:
                 self.rqdata.init_progress_reporter.finish()
@@ -1387,11 +1393,6 @@ class RunQueue:
                 self.rqexe = RunQueueExecuteScenequeue(self)
 
         if self.state is runQueueSceneRun:
-            if not self.dm_event_handler_registered:
-                 res = bb.event.register(self.dm_event_handler_name,
-                                         lambda x: self.dm.check(self) if self.state in [runQueueSceneRun, runQueueRunning, runQueueCleanUp] else False,
-                                         ('bb.event.HeartbeatEvent',))
-                 self.dm_event_handler_registered = True
             retval = self.rqexe.execute()
 
         if self.state is runQueueRunInit:

bitbake/lib/bb/server/process.py

@@ -130,6 +130,7 @@ class ProcessServer(multiprocessing.Process):
         bb.utils.set_process_name("Cooker")
 
         ready = []
+        newconnections = []
 
         self.controllersock = False
         fds = [self.sock]
@@ -138,37 +139,48 @@ class ProcessServer(multiprocessing.Process):
         print("Entering server connection loop")
 
         def disconnect_client(self, fds):
-            if not self.haveui:
-                return
             print("Disconnecting Client")
-            fds.remove(self.controllersock)
+            if self.controllersock:
-            fds.remove(self.command_channel)
+                fds.remove(self.controllersock)
-            bb.event.unregister_UIHhandler(self.event_handle, True)
+                self.controllersock.close()
-            self.command_channel_reply.writer.close()
+                self.controllersock = False
-            self.event_writer.writer.close()
+            if self.haveui:
-            del self.event_writer
+                fds.remove(self.command_channel)
-            self.controllersock.close()
+                bb.event.unregister_UIHhandler(self.event_handle, True)
-            self.controllersock = False
+                self.command_channel_reply.writer.close()
-            self.haveui = False
+                self.event_writer.writer.close()
-            self.lastui = time.time()
+                self.command_channel.close()
-            self.cooker.clientComplete()
+                self.command_channel = False
-            if self.timeout is None:
+                del self.event_writer
+                self.lastui = time.time()
+                self.cooker.clientComplete()
+                self.haveui = False
+            ready = select.select(fds,[],[],0)[0]
+            if newconnections:
+                print("Starting new client")
+                conn = newconnections.pop(-1)
+                fds.append(conn)
+                self.controllersock = conn
+            elif self.timeout is None and not ready:
                 print("No timeout, exiting.")
                 self.quit = True
 
         while not self.quit:
             if self.sock in ready:
-                self.controllersock, address = self.sock.accept()
+                while select.select([self.sock],[],[],0)[0]:
-                if self.haveui:
+                    controllersock, address = self.sock.accept()
-                    print("Dropping connection attempt as we have a UI %s" % (str(ready)))
+                    if self.controllersock:
-                    self.controllersock.close()
+                        print("Queuing %s (%s)" % (str(ready), str(newconnections)))
-                else:
+                        newconnections.append(controllersock)
-                    print("Accepting %s" % (str(ready)))
+                    else:
-                    fds.append(self.controllersock)
+                        print("Accepting %s (%s)" % (str(ready), str(newconnections)))
+                        self.controllersock = controllersock
+                        fds.append(controllersock)
             if self.controllersock in ready:
                 try:
-                    print("Connecting Client")
+                    print("Processing Client")
                     ui_fds = recvfds(self.controllersock, 3)
+                    print("Connecting Client")
 
                     # Where to write events to
                     writer = ConnectionWriter(ui_fds[0])
@@ -239,6 +251,12 @@ class ProcessServer(multiprocessing.Process):
         while not lock:
             with bb.utils.timeout(3):
                 lock = bb.utils.lockfile(lockfile, shared=False, retry=False, block=True)
+                if lock:
+                    # We hold the lock so we can remove the file (hide stale pid data)
+                    bb.utils.remove(lockfile)
+                    bb.utils.unlockfile(lock)
+                    return
+
                 if not lock:
                     # Some systems may not have lsof available
                     procs = None
@@ -259,10 +277,6 @@ class ProcessServer(multiprocessing.Process):
                     if procs:
                         msg += ":\n%s" % str(procs)
                     print(msg)
-                    return
-        # We hold the lock so we can remove the file (hide stale pid data)
-        bb.utils.remove(lockfile)
-        bb.utils.unlockfile(lock)
 
     def idle_commands(self, delay, fds=None):
         nextsleep = delay
@@ -396,7 +410,10 @@ class BitBakeServer(object):
         self.bitbake_lock.close()
 
         ready = ConnectionReader(self.readypipe)
-        r = ready.poll(30)
+        r = ready.poll(5)
+        if not r:
+            bb.note("Bitbake server didn't start within 5 seconds, waiting for 90")
+            r = ready.poll(90)
         if r:
             r = ready.get()
         if not r or r != "ready":
@@ -406,28 +423,40 @@ class BitBakeServer(object):
                 logstart_re = re.compile(self.start_log_format % ('([0-9]+)', '([0-9-]+ [0-9:.]+)'))
                 started = False
                 lines = []
+                lastlines = []
                 with open(logfile, "r") as f:
                     for line in f:
                         if started:
                             lines.append(line)
                         else:
+                            lastlines.append(line)
                             res = logstart_re.match(line.rstrip())
                             if res:
                                 ldatetime = datetime.datetime.strptime(res.group(2), self.start_log_datetime_format)
                                 if ldatetime >= startdatetime:
                                     started = True
                                     lines.append(line)
+                        if len(lastlines) > 60:
+                            lastlines = lastlines[-60:]
                 if lines:
-                    if len(lines) > 10:
+                    if len(lines) > 60:
-                        bb.error("Last 10 lines of server log for this session (%s):\n%s" % (logfile, "".join(lines[-10:])))
+                        bb.error("Last 60 lines of server log for this session (%s):\n%s" % (logfile, "".join(lines[-60:])))
                     else:
                         bb.error("Server log for this session (%s):\n%s" % (logfile, "".join(lines)))
+                elif lastlines:
+                        bb.error("Server didn't start, last 60 loglines (%s):\n%s" % (logfile, "".join(lastlines)))
+            else:
+                bb.error("%s doesn't exist" % logfile)
+
             raise SystemExit(1)
+
         ready.close()
         os.close(self.readypipein)
 
     def _startServer(self):
         print(self.start_log_format % (os.getpid(), datetime.datetime.now().strftime(self.start_log_datetime_format)))
+        sys.stdout.flush()
+
         server = ProcessServer(self.bitbake_lock, self.sock, self.sockname)
         self.configuration.setServerRegIdleCallback(server.register_idle_function)
         writer = ConnectionWriter(self.readypipein)
@@ -443,6 +472,8 @@ class BitBakeServer(object):
         server.server_timeout = self.configuration.server_timeout
         server.xmlrpcinterface = self.configuration.xmlrpcinterface
         print("Started bitbake server pid %d" % os.getpid())
+        sys.stdout.flush()
+
         server.start()
 
 def connectProcessServer(sockname, featureset):
@@ -451,16 +482,24 @@ def connectProcessServer(sockname, featureset):
     # AF_UNIX has path length issues so chdir here to workaround
     cwd = os.getcwd()
 
-    try:
-        os.chdir(os.path.dirname(sockname))
-        sock.connect(os.path.basename(sockname))
-    finally:
-        os.chdir(cwd)
-
     readfd = writefd = readfd1 = writefd1 = readfd2 = writefd2 = None
     eq = command_chan_recv = command_chan = None
 
+    sock.settimeout(10)
+
     try:
+        try:
+            os.chdir(os.path.dirname(sockname))
+            finished = False
+            while not finished:
+                try:
+                    sock.connect(os.path.basename(sockname))
+                    finished = True
+                except IOError as e:
+                    if e.errno == errno.EWOULDBLOCK:
+                        pass
+        finally:
+            os.chdir(cwd)
 
         # Send an fd for the remote to write events to
         readfd, writefd = os.pipe()
@@ -489,7 +528,8 @@ def connectProcessServer(sockname, featureset):
             command_chan.close()
         for i in [writefd, readfd1, writefd2]:
             try:
-                os.close(i)
+                if i:
+                    os.close(i)
             except OSError:
                 pass
         sock.close()

bitbake/lib/bb/tests/fetch.py

@@ -861,12 +861,12 @@ class FetchLatestVersionTest(FetcherTest):
         ("dtc", "git://git.qemu.org/dtc.git", "65cc4d2748a2c2e6f27f1cf39e07a5dbabd80ebf", "")
             : "1.4.0",
         # combination version pattern
-        ("sysprof", "git://git.gnome.org/sysprof", "cd44ee6644c3641507fb53b8a2a69137f2971219", "")
+        ("sysprof", "git://gitlab.gnome.org/GNOME/sysprof;protocol=https", "cd44ee6644c3641507fb53b8a2a69137f2971219", "")
             : "1.2.0",
         ("u-boot-mkimage", "git://git.denx.de/u-boot.git;branch=master;protocol=git", "62c175fbb8a0f9a926c88294ea9f7e88eb898f6c", "")
             : "2014.01",
         # version pattern "yyyymmdd"
-        ("mobile-broadband-provider-info", "git://git.gnome.org/mobile-broadband-provider-info", "4ed19e11c2975105b71b956440acdb25d46a347d", "")
+        ("mobile-broadband-provider-info", "git://gitlab.gnome.org/GNOME/mobile-broadband-provider-info;protocol=https", "4ed19e11c2975105b71b956440acdb25d46a347d", "")
             : "20120614",
         # packages with a valid UPSTREAM_CHECK_GITTAGREGEX
         ("xf86-video-omap", "git://anongit.freedesktop.org/xorg/driver/xf86-video-omap", "ae0394e687f1a77e966cf72f895da91840dffb8f", "(?P<pver>(\d+\.(\d\.?)*))")
@@ -900,8 +900,8 @@ class FetchLatestVersionTest(FetcherTest):
         # packages with valid UPSTREAM_CHECK_URI and UPSTREAM_CHECK_REGEX
         ("cups", "http://www.cups.org/software/1.7.2/cups-1.7.2-source.tar.bz2", "https://github.com/apple/cups/releases", "(?P<name>cups\-)(?P<pver>((\d+[\.\-_]*)+))\-source\.tar\.gz")
             : "2.0.0",
-        ("db", "http://download.oracle.com/berkeley-db/db-5.3.21.tar.gz", "http://www.oracle.com/technetwork/products/berkeleydb/downloads/index-082944.html", "http://download.oracle.com/otn/berkeley-db/(?P<name>db-)(?P<pver>((\d+[\.\-_]*)+))\.tar\.gz")
+        ("db", "http://download.oracle.com/berkeley-db/db-5.3.21.tar.gz", "http://ftp.debian.org/debian/pool/main/d/db5.3/", "(?P<name>db5\.3_)(?P<pver>\d+(\.\d+)+).+\.orig\.tar\.xz")
-            : "6.1.19",
+            : "5.3.10",
     }
 
     @skipIfNoNetwork()

bitbake/lib/bb/utils.py

@@ -524,12 +524,17 @@ def md5_file(filename):
     """
     Return the hex string representation of the MD5 checksum of filename.
     """
-    import hashlib
+    import hashlib, mmap
-    m = hashlib.md5()
 
     with open(filename, "rb") as f:
-        for line in f:
+        m = hashlib.md5()
-            m.update(line)
+        try:
+            with mmap.mmap(f.fileno(), 0, access=mmap.ACCESS_READ) as mm:
+                for chunk in iter(lambda: mm.read(8192), b''):
+                    m.update(chunk)
+        except ValueError:
+            # You can't mmap() an empty file so silence this exception
+            pass
     return m.hexdigest()
 
 def sha256_file(filename):
@@ -1285,7 +1290,7 @@ def edit_metadata_file(meta_file, variables, varfunc):
     return updated
 
 
-def edit_bblayers_conf(bblayers_conf, add, remove):
+def edit_bblayers_conf(bblayers_conf, add, remove, edit_cb=None):
     """Edit bblayers.conf, adding and/or removing layers
     Parameters:
         bblayers_conf: path to bblayers.conf file to edit
@@ -1293,6 +1298,8 @@ def edit_bblayers_conf(bblayers_conf, add, remove):
             list to add nothing
         remove: layer path (or list of layer paths) to remove; None or
             empty list to remove nothing
+        edit_cb: optional callback function that will be called after
+            processing adds/removes once per existing entry.
     Returns a tuple:
         notadded: list of layers specified to be added but weren't
             (because they were already in the list)
@@ -1356,6 +1363,17 @@ def edit_bblayers_conf(bblayers_conf, add, remove):
                     bblayers.append(addlayer)
             del addlayers[:]
 
+        if edit_cb:
+            newlist = []
+            for layer in bblayers:
+                res = edit_cb(layer, canonicalise_path(layer))
+                if res != layer:
+                    newlist.append(res)
+                    updated = True
+                else:
+                    newlist.append(layer)
+            bblayers = newlist
+
         if updated:
             if op == '+=' and not bblayers:
                 bblayers = None

bitbake/lib/bblayers/layerindex.py

@@ -133,7 +133,7 @@ class LayerIndexPlugin(ActionPlugin):
         layerdir = os.path.join(repodir, subdir)
         if not os.path.exists(repodir):
             if fetch_layer:
-                result = subprocess.call('git clone %s %s' % (url, repodir), shell = True)
+                result = subprocess.call(['git', 'clone', url, repodir])
                 if result:
                     logger.error("Failed to download %s" % url)
                     return None, None

bitbake/lib/toaster/bldcontrol/localhostbecontroller.py

@@ -217,9 +217,21 @@ class LocalhostBEController(BuildEnvironmentController):
         self.setCloneStatus(bitbake,'complete',clone_total,clone_count)
         logger.debug("localhostbecontroller: current layer list %s " % pformat(layerlist))
 
-        if self.pokydirname is None and os.path.exists(os.path.join(self.be.sourcedir, "oe-init-build-env")):
+        # Resolve self.pokydirname if not resolved yet, consider the scenario
-            logger.debug("localhostbecontroller: selected poky dir name %s" % self.be.sourcedir)
+        # where all layers are local, that's the else clause
-            self.pokydirname = self.be.sourcedir
+        if self.pokydirname is None:
+            if os.path.exists(os.path.join(self.be.sourcedir, "oe-init-build-env")):
+                logger.debug("localhostbecontroller: selected poky dir name %s" % self.be.sourcedir)
+                self.pokydirname = self.be.sourcedir
+            else:
+                # Alternatively, scan local layers for relative "oe-init-build-env" location
+                for layer in layers:
+                    if os.path.exists(os.path.join(layer.layer_version.layer.local_source_dir,"..","oe-init-build-env")):
+                        logger.debug("localhostbecontroller, setting pokydirname to %s" % (layer.layer_version.layer.local_source_dir))
+                        self.pokydirname = os.path.join(layer.layer_version.layer.local_source_dir,"..")
+                        break
+                else:
+                    logger.error("pokydirname is not set, you will run into trouble!")
 
         # 5. create custom layer and add custom recipes to it
         for target in targets:
@@ -339,8 +351,21 @@ class LocalhostBEController(BuildEnvironmentController):
         # clean the Toaster to build environment
         env_clean = 'unset BBPATH;' # clean BBPATH for <= YP-2.4.0
 
-        # run bitbake server from the clone
+        # run bitbake server from the clone if available
+        # otherwise pick it from the PATH
         bitbake = os.path.join(self.pokydirname, 'bitbake', 'bin', 'bitbake')
+        if not os.path.exists(bitbake):
+            logger.info("Bitbake not available under %s, will try to use it from PATH" %
+                        self.pokydirname)
+            for path in os.environ["PATH"].split(os.pathsep):
+                if os.path.exists(os.path.join(path, 'bitbake')):
+                    bitbake = os.path.join(path, 'bitbake')
+                    logger.info("Found Bitbake at: %s" % path)
+                    break
+            else:
+                logger.error("Looks like Bitbake is not available, please fix your environment")
+
+        # run bitbake server from the clone
         toasterlayers = os.path.join(builddir,"conf/toaster-bblayers.conf")
         self._shellcmd('%s bash -c \"source %s %s; BITBAKE_UI="knotty" %s --read %s --read %s '
                        '--server-only -B 0.0.0.0:0\"' % (env_clean, oe_init,

bitbake/lib/toaster/bldcontrol/management/commands/checksettings.py

@@ -74,8 +74,9 @@ class Command(BaseCommand):
                         print("Loading default settings")
                         call_command("loaddata", "settings")
                         template_conf = os.environ.get("TEMPLATECONF", "")
+                        custom_xml_only = os.environ.get("CUSTOM_XML_ONLY")
 
-                        if ToasterSetting.objects.filter(name='CUSTOM_XML_ONLY').count() > 0:
+                        if ToasterSetting.objects.filter(name='CUSTOM_XML_ONLY').count() > 0 or (not custom_xml_only == None):
                             # only use the custom settings
                             pass
                         elif "poky" in template_conf:

bitbake/lib/toaster/orm/fixtures/oe-core.xml

@@ -8,9 +8,9 @@
 
   <!-- Bitbake versions which correspond to the metadata release -->
   <object model="orm.bitbakeversion" pk="1">
-    <field type="CharField" name="name">rocko</field>
+    <field type="CharField" name="name">sumo</field>
     <field type="CharField" name="giturl">git://git.openembedded.org/bitbake</field>
-    <field type="CharField" name="branch">1.36</field>
+    <field type="CharField" name="branch">1.38</field>
   </object>
   <object model="orm.bitbakeversion" pk="2">
     <field type="CharField" name="name">HEAD</field>
@@ -22,14 +22,19 @@
     <field type="CharField" name="giturl">git://git.openembedded.org/bitbake</field>
     <field type="CharField" name="branch">master</field>
   </object>
+  <object model="orm.bitbakeversion" pk="4">
+    <field type="CharField" name="name">rocko</field>
+    <field type="CharField" name="giturl">git://git.openembedded.org/bitbake</field>
+    <field type="CharField" name="branch">1.36</field>
+  </object>
 
   <!-- Releases available -->
   <object model="orm.release" pk="1">
     <field type="CharField" name="name">rocko</field>
-    <field type="CharField" name="description">Openembedded Rocko</field>
+    <field type="CharField" name="description">Openembedded Sumo</field>
     <field rel="ManyToOneRel" to="orm.bitbakeversion" name="bitbake_version">1</field>
-    <field type="CharField" name="branch_name">rocko</field>
+    <field type="CharField" name="branch_name">sumo</field>
-    <field type="TextField" name="helptext">Toaster will run your builds using the tip of the &lt;a href=\"http://cgit.openembedded.org/openembedded-core/log/?h=rocko\"&gt;OpenEmbedded Rocko&lt;/a&gt; branch.</field>
+    <field type="TextField" name="helptext">Toaster will run your builds using the tip of the &lt;a href=\"http://cgit.openembedded.org/openembedded-core/log/?h=sumo\"&gt;OpenEmbedded Sumo&lt;/a&gt; branch.</field>
   </object>
   <object model="orm.release" pk="2">
     <field type="CharField" name="name">local</field>
@@ -45,6 +50,13 @@
     <field type="CharField" name="branch_name">master</field>
     <field type="TextField" name="helptext">Toaster will run your builds using the tip of the &lt;a href=\"http://cgit.openembedded.org/openembedded-core/log/\"&gt;OpenEmbedded master&lt;/a&gt; branch.</field>
   </object>
+  <object model="orm.release" pk="4">
+    <field type="CharField" name="name">rocko</field>
+    <field type="CharField" name="description">Openembedded Rocko</field>
+    <field rel="ManyToOneRel" to="orm.bitbakeversion" name="bitbake_version">1</field>
+    <field type="CharField" name="branch_name">rocko</field>
+    <field type="TextField" name="helptext">Toaster will run your builds using the tip of the &lt;a href=\"http://cgit.openembedded.org/openembedded-core/log/?h=rocko\"&gt;OpenEmbedded Rocko&lt;/a&gt; branch.</field>
+  </object>
 
   <!-- Default layers for each release -->
   <object model="orm.releasedefaultlayer" pk="1">
@@ -59,6 +71,10 @@
     <field rel="ManyToOneRel" to="orm.release" name="release">3</field>
     <field type="CharField" name="layer_name">openembedded-core</field>
   </object>
+  <object model="orm.releasedefaultlayer" pk="4">
+    <field rel="ManyToOneRel" to="orm.release" name="release">4</field>
+    <field type="CharField" name="layer_name">openembedded-core</field>
+  </object>
 
 
   <!-- Layer for the Local release -->

bitbake/lib/toaster/orm/fixtures/poky.xml

@@ -8,9 +8,9 @@
 
   <!-- Bitbake versions which correspond to the metadata release -->
   <object model="orm.bitbakeversion" pk="1">
-    <field type="CharField" name="name">rocko</field>
+    <field type="CharField" name="name">sumo</field>
     <field type="CharField" name="giturl">git://git.yoctoproject.org/poky</field>
-    <field type="CharField" name="branch">rocko</field>
+    <field type="CharField" name="branch">sumo</field>
     <field type="CharField" name="dirpath">bitbake</field>
   </object>
   <object model="orm.bitbakeversion" pk="2">
@@ -25,15 +25,21 @@
     <field type="CharField" name="branch">master</field>
     <field type="CharField" name="dirpath">bitbake</field>
   </object>
+  <object model="orm.bitbakeversion" pk="4">
+    <field type="CharField" name="name">rocko</field>
+    <field type="CharField" name="giturl">git://git.yoctoproject.org/poky</field>
+    <field type="CharField" name="branch">rocko</field>
+    <field type="CharField" name="dirpath">bitbake</field>
+  </object>
 
 
   <!-- Releases available -->
   <object model="orm.release" pk="1">
-    <field type="CharField" name="name">rocko</field>
+    <field type="CharField" name="name">sumo</field>
-    <field type="CharField" name="description">Yocto Project 2.4 "Rocko"</field>
+    <field type="CharField" name="description">Yocto Project 2.5 "Sumo"</field>
     <field rel="ManyToOneRel" to="orm.bitbakeversion" name="bitbake_version">1</field>
-    <field type="CharField" name="branch_name">rocko</field>
+    <field type="CharField" name="branch_name">sumo</field>
-    <field type="TextField" name="helptext">Toaster will run your builds using the tip of the &lt;a href="http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=rocko"&gt;Yocto Project Rocko branch&lt;/a&gt;.</field>
+    <field type="TextField" name="helptext">Toaster will run your builds using the tip of the &lt;a href="http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=sumo"&gt;Yocto Project Sumo branch&lt;/a&gt;.</field>
   </object>
   <object model="orm.release" pk="2">
     <field type="CharField" name="name">local</field>
@@ -49,6 +55,13 @@
     <field type="CharField" name="branch_name">master</field>
     <field type="TextField" name="helptext">Toaster will run your builds using the tip of the &lt;a href="http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/"&gt;Yocto Project Master branch&lt;/a&gt;.</field>
   </object>
+  <object model="orm.release" pk="4">
+    <field type="CharField" name="name">rocko</field>
+    <field type="CharField" name="description">Yocto Project 2.4 "Rocko"</field>
+    <field rel="ManyToOneRel" to="orm.bitbakeversion" name="bitbake_version">1</field>
+    <field type="CharField" name="branch_name">rocko</field>
+    <field type="TextField" name="helptext">Toaster will run your builds using the tip of the &lt;a href="http://git.yoctoproject.org/cgit/cgit.cgi/poky/log/?h=rocko"&gt;Yocto Project Rocko branch&lt;/a&gt;.</field>
+  </object>
 
   <!-- Default project layers for each release -->
   <object model="orm.releasedefaultlayer" pk="1">
@@ -87,6 +100,18 @@
     <field rel="ManyToOneRel" to="orm.release" name="release">3</field>
     <field type="CharField" name="layer_name">meta-yocto-bsp</field>
   </object>
+  <object model="orm.releasedefaultlayer" pk="10">
+    <field rel="ManyToOneRel" to="orm.release" name="release">4</field>
+    <field type="CharField" name="layer_name">openembedded-core</field>
+  </object>
+  <object model="orm.releasedefaultlayer" pk="11">
+    <field rel="ManyToOneRel" to="orm.release" name="release">4</field>
+    <field type="CharField" name="layer_name">meta-poky</field>
+  </object>
+  <object model="orm.releasedefaultlayer" pk="12">
+    <field rel="ManyToOneRel" to="orm.release" name="release">4</field>
+    <field type="CharField" name="layer_name">meta-yocto-bsp</field>
+  </object>
 
   <!-- Default layers provided by poky
        openembedded-core
@@ -105,7 +130,7 @@
     <field rel="ManyToOneRel" to="orm.layer" name="layer">1</field>
     <field type="IntegerField" name="layer_source">0</field>
     <field rel="ManyToOneRel" to="orm.release" name="release">1</field>
-    <field type="CharField" name="branch">rocko</field>
+    <field type="CharField" name="branch">sumo</field>
     <field type="CharField" name="dirpath">meta</field>
   </object>
   <object model="orm.layer_version" pk="2">
@@ -123,6 +148,13 @@
     <field type="CharField" name="branch">master</field>
     <field type="CharField" name="dirpath">meta</field>
   </object>
+  <object model="orm.layer_version" pk="4">
+    <field rel="ManyToOneRel" to="orm.layer" name="layer">1</field>
+    <field type="IntegerField" name="layer_source">0</field>
+    <field rel="ManyToOneRel" to="orm.release" name="release">4</field>
+    <field type="CharField" name="branch">rocko</field>
+    <field type="CharField" name="dirpath">meta</field>
+  </object>
 
   <object model="orm.layer" pk="2">
     <field type="CharField" name="name">meta-poky</field>
@@ -132,14 +164,14 @@
     <field type="CharField" name="vcs_web_tree_base_url">http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%</field>
     <field type="CharField" name="vcs_web_file_base_url">http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%</field>
   </object>
-  <object model="orm.layer_version" pk="4">
+  <object model="orm.layer_version" pk="5">
     <field rel="ManyToOneRel" to="orm.layer" name="layer">2</field>
     <field type="IntegerField" name="layer_source">0</field>
     <field rel="ManyToOneRel" to="orm.release" name="release">1</field>
-    <field type="CharField" name="branch">rocko</field>
+    <field type="CharField" name="branch">sumo</field>
     <field type="CharField" name="dirpath">meta-poky</field>
   </object>
-  <object model="orm.layer_version" pk="5">
+  <object model="orm.layer_version" pk="6">
     <field rel="ManyToOneRel" to="orm.layer" name="layer">2</field>
     <field type="IntegerField" name="layer_source">0</field>
     <field rel="ManyToOneRel" to="orm.release" name="release">2</field>
@@ -147,13 +179,20 @@
     <field type="CharField" name="commit">HEAD</field>
     <field type="CharField" name="dirpath">meta-poky</field>
   </object>
-  <object model="orm.layer_version" pk="6">
+  <object model="orm.layer_version" pk="7">
     <field rel="ManyToOneRel" to="orm.layer" name="layer">2</field>
     <field type="IntegerField" name="layer_source">0</field>
     <field rel="ManyToOneRel" to="orm.release" name="release">3</field>
     <field type="CharField" name="branch">master</field>
     <field type="CharField" name="dirpath">meta-poky</field>
   </object>
+  <object model="orm.layer_version" pk="8">
+    <field rel="ManyToOneRel" to="orm.layer" name="layer">2</field>
+    <field type="IntegerField" name="layer_source">0</field>
+    <field rel="ManyToOneRel" to="orm.release" name="release">4</field>
+    <field type="CharField" name="branch">rocko</field>
+    <field type="CharField" name="dirpath">meta-poky</field>
+  </object>
 
   <object model="orm.layer" pk="3">
     <field type="CharField" name="name">meta-yocto-bsp</field>
@@ -163,14 +202,14 @@
     <field type="CharField" name="vcs_web_tree_base_url">http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%</field>
     <field type="CharField" name="vcs_web_file_base_url">http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/%path%?h=%branch%</field>
   </object>
-  <object model="orm.layer_version" pk="7">
+  <object model="orm.layer_version" pk="9">
     <field rel="ManyToOneRel" to="orm.layer" name="layer">3</field>
     <field type="IntegerField" name="layer_source">0</field>
     <field rel="ManyToOneRel" to="orm.release" name="release">1</field>
-    <field type="CharField" name="branch">rocko</field>
+    <field type="CharField" name="branch">sumo</field>
     <field type="CharField" name="dirpath">meta-yocto-bsp</field>
   </object>
-  <object model="orm.layer_version" pk="8">
+  <object model="orm.layer_version" pk="10">
     <field rel="ManyToOneRel" to="orm.layer" name="layer">3</field>
     <field type="IntegerField" name="layer_source">0</field>
     <field rel="ManyToOneRel" to="orm.release" name="release">2</field>
@@ -178,11 +217,18 @@
     <field type="CharField" name="commit">HEAD</field>
     <field type="CharField" name="dirpath">meta-yocto-bsp</field>
   </object>
-  <object model="orm.layer_version" pk="9">
+  <object model="orm.layer_version" pk="11">
     <field rel="ManyToOneRel" to="orm.layer" name="layer">3</field>
     <field type="IntegerField" name="layer_source">0</field>
     <field rel="ManyToOneRel" to="orm.release" name="release">3</field>
     <field type="CharField" name="branch">master</field>
     <field type="CharField" name="dirpath">meta-yocto-bsp</field>
   </object>
+  <object model="orm.layer_version" pk="12">
+    <field rel="ManyToOneRel" to="orm.layer" name="layer">3</field>
+    <field type="IntegerField" name="layer_source">0</field>
+    <field rel="ManyToOneRel" to="orm.release" name="release">4</field>
+    <field type="CharField" name="branch">rocko</field>
+    <field type="CharField" name="dirpath">meta-yocto-bsp</field>
+  </object>
 </django-objects>

bitbake/lib/toaster/orm/models.py

@@ -1663,6 +1663,9 @@ class CustomImageRecipe(Recipe):
 
         path_schema_two = self.base_recipe.file_path
 
+        path_schema_three = "%s/%s" % (self.base_recipe.layer_version.layer.local_source_dir,
+                                     self.base_recipe.file_path)
+
         if os.path.exists(path_schema_one):
             return path_schema_one
 
@@ -1670,6 +1673,10 @@ class CustomImageRecipe(Recipe):
         if os.path.exists(path_schema_two):
             return path_schema_two
 
+        # Or a local path if all layers are local
+        if os.path.exists(path_schema_three):
+            return path_schema_three
+
         return None
 
     def generate_recipe_file_contents(self):

bitbake/lib/toaster/toastergui/static/js/layerdetails.js

@@ -359,7 +359,8 @@ function layerDetailsPageInit (ctx) {
     if ($(this).is("dt")) {
       var dd = $(this).next("dd");
       if (!dd.children("form:visible")|| !dd.find(".current-value").html()){
-        if (ctx.layerVersion.layer_source == ctx.layerSourceTypes.TYPE_IMPORTED){
+        if (ctx.layerVersion.layer_source == ctx.layerSourceTypes.TYPE_IMPORTED ||
+            ctx.layerVersion.layer_source == ctx.layerSourceTypes.TYPE_LOCAL) {
         /* There's no current value and the layer is editable
          * so show the "Not set" and hide the delete icon
          */

bitbake/lib/toaster/toastergui/templates/newproject.html

@@ -54,12 +54,12 @@
                     <span class="help-block">{{release.helptext|safe}}</span>
                   </div>
                 {% endfor %}
+                </div>
+              </div>
             {% else %}
               <input type="hidden" name="projectversion" value="{{releases.0.id}}"/>
             {% endif %}
                 </div>
-              </div>
-            </fieldset>
         {% endif %}
             <div class="top-air">
               <input type="submit" id="create-project-button" class="btn btn-primary btn-lg" value="Create project"/>

bitbake/lib/toaster/toastergui/templates/recipe.html

@@ -176,7 +176,7 @@
                     <td>{{task.get_executed_display}}</td>
 
                     <td>{{task.get_outcome_display}} 
-                        {% if task.outcome = task.OUTCOME_FAILED %}
+                        {% if task.outcome == task.OUTCOME_FAILED %}
                             <a href="{% url 'build_artifact' build.pk "tasklogfile" task.pk %}">
                                 <span class="glyphicon glyphicon-download-alt
                                     get-help" title="Download task log

bitbake/lib/toaster/toastergui/widgets.py

@@ -511,13 +511,18 @@ class MostRecentBuildsView(View):
                 buildrequest_id = build_obj.buildrequest.pk
             build['buildrequest_id'] = buildrequest_id
 
-            build['recipes_parsed_percentage'] = \
+            if build_obj.recipes_to_parse > 0:
-                int((build_obj.recipes_parsed /
+                build['recipes_parsed_percentage'] = \
-                     build_obj.recipes_to_parse) * 100)
+                    int((build_obj.recipes_parsed /
-
+                         build_obj.recipes_to_parse) * 100)
-            build['repos_cloned_percentage'] = \
+            else:
-                int((build_obj.repos_cloned /
+                build['recipes_parsed_percentage'] = 0
-                     build_obj.repos_to_clone) * 100)
+            if build_obj.repos_to_clone > 0:
+                build['repos_cloned_percentage'] = \
+                    int((build_obj.repos_cloned /
+                         build_obj.repos_to_clone) * 100)
+            else:
+                build['repos_cloned_percentage'] = 0
 
             tasks_complete_percentage = 0
             if build_obj.outcome in (Build.SUCCEEDED, Build.FAILED):

documentation/Makefile

@@ -48,7 +48,7 @@
 # Examples:
 #
 #     make DOC=bsp-guide
-#     make html DOC=yocto-project-qs
+#     make html DOC=brief-yoctoprojectqs
 #     make pdf DOC=ref-manual
 #     make DOC=dev-manual BRANCH=edison
 #     make DOC=mega-manual BRANCH=denzil
@@ -56,7 +56,7 @@
 # The first example generates the HTML and Eclipse help 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.  So, the
-# 'make DOC=yocto-project-qs' command would be equivalent. The third example
+# 'make DOC=brief-yoctoprojectqs' command would be equivalent. The third example
 # generates just the PDF version of the Yocto Project Reference Manual.
 # The fourth example generates the HTML 'edison' version and (if available)
 # the Eclipse help version of the YP Development Tasks Manual.  The last example
@@ -90,8 +90,8 @@ XSLTOPTS = --stringparam html.stylesheet brief-yoctoprojectqs-style.css \
            --stringparam  section.autolabel 0 \
            --stringparam  section.label.includes.component.label 0 \
            --xinclude
-ALLPREQ = html tarball
+ALLPREQ = html eclipse tarball
-TARFILES = brief-yoctoprojectqs-style.css brief-yoctoprojectqs.html figures/ypqs-title.png \
+TARFILES = brief-yoctoprojectqs-style.css brief-yoctoprojectqs.html figures/bypqs-title.png \
            figures/yocto-project-transp.png
 MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
 FIGURES = figures
@@ -99,25 +99,13 @@ STYLESHEET = $(DOC)/*.css
 
 endif
 
-ifeq ($(DOC),getting-started)
+ifeq ($(DOC),overview-manual)
 XSLTOPTS = --xinclude
 ALLPREQ = html eclipse tarball
-TARFILES = getting-started-style.css getting-started.html figures/getting-started-title.png \
+TARFILES = overview-manual-style.css overview-manual.html figures/overview-manual-title.png \
            figures/git-workflow.png figures/source-repos.png figures/index-downloads.png \
            figures/yp-download.png figures/YP-flow-diagram.png figures/key-dev-elements.png \
-           figures/poky-reference-distribution.png \
+           figures/poky-reference-distribution.png figures/cross-development-toolchains.png \
-           eclipse
-MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
-FIGURES = figures
-STYLESHEET = $(DOC)/*.css
-
-endif
-
-ifeq ($(DOC),concepts-manual)
-XSLTOPTS = --xinclude
-ALLPREQ = html eclipse tarball
-TARFILES = concepts-manual-style.css concepts-manual.html figures/concepts-manual-title.png \
-           figures/cross-development-toolchains.png figures/yocto-environment-ref.png \
            figures/user-configuration.png figures/layer-input.png figures/source-input.png \
            figures/package-feeds.png figures/patching.png figures/source-fetching.png \
            figures/configuration-compile-autoreconf.png figures/analysis-for-package-splitting.png \
@@ -186,22 +174,6 @@ STYLESHEET = $(DOC)/*.css
 
 endif
 
-ifeq ($(DOC),yocto-project-qs)
-XSLTOPTS = --stringparam html.stylesheet qs-style.css \
-           --stringparam  chapter.autolabel 1 \
-           --stringparam  section.autolabel 1 \
-           --stringparam  section.label.includes.component.label 1 \
-           --xinclude
-ALLPREQ = html eclipse tarball
-
-TARFILES = yocto-project-qs.html qs-style.css \
-           figures/yocto-project-transp.png figures/ypqs-title.png \
-           eclipse
-MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
-FIGURES = figures
-STYLESHEET = $(DOC)/*.css
-endif
-
 ifeq ($(DOC),mega-manual)
 XSLTOPTS = --stringparam html.stylesheet mega-style.css \
            --stringparam  chapter.autolabel 1 \
@@ -280,7 +252,7 @@ TARFILES = mega-manual.html mega-style.css \
         figures/sched-wakeup-profile.png figures/sysprof-callers.png \
         figures/sysprof-copy-from-user.png figures/sysprof-copy-to-user.png \
         figures/cross-development-toolchains.png \
-	figures/yocto-environment-ref.png figures/user-configuration.png \
+	figures/user-configuration.png \
         figures/source-input.png figures/package-feeds.png \
         figures/layer-input.png figures/images.png figures/sdk.png \
 	figures/source-fetching.png figures/patching.png \
@@ -295,8 +267,8 @@ TARFILES = mega-manual.html mega-style.css \
 	figures/sdk-environment.png figures/sdk-installed-standard-sdk-directory.png \
 	figures/sdk-devtool-add-flow.png figures/sdk-installed-extensible-sdk-directory.png \
 	figures/sdk-devtool-modify-flow.png figures/sdk-eclipse-dev-flow.png \
-	figures/sdk-devtool-upgrade-flow.png figures/bitbake-build-flow.png figures/ypqs-title.png \
+	figures/sdk-devtool-upgrade-flow.png figures/bitbake-build-flow.png figures/bypqs-title.png \
-	figures/getting-started-title.png figures/concepts-manual-title.png
+	figures/overview-manual-title.png figures/sdk-autotools-flow.png figures/sdk-makefile-flow.png
 	endif
 
 MANUALS = $(DOC)/$(DOC).html
@@ -323,7 +295,7 @@ TARFILES = sdk-manual.html sdk-style.css figures/sdk-title.png \
            figures/sdk-environment.png figures/sdk-installed-standard-sdk-directory.png \
 	   figures/sdk-installed-extensible-sdk-directory.png figures/sdk-devtool-add-flow.png \
 	   figures/sdk-devtool-modify-flow.png figures/sdk-eclipse-dev-flow.png \
-	   figures/sdk-devtool-upgrade-flow.png \
+	   figures/sdk-devtool-upgrade-flow.png figures/sdk-autotools-flow.png figures/sdk-makefile-flow.png \
            eclipse
 MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
 FIGURES = figures
@@ -399,9 +371,9 @@ XSL_XHTML_URI = $(XSL_BASE_URI)/xhtml/docbook.xsl
 all: $(ALLPREQ)
 
 pdf:
-ifeq ($(DOC),yocto-project-qs brief-yoctoprojectqs)
+ifeq ($(DOC),brief-yoctoprojectqs)
 	@echo " "
-	@echo "ERROR: You cannot generate yocto-project-qs or brief-yoctoprojectqs PDF files."
+	@echo "ERROR: You cannot generate a PDF file for brief-yoctoprojectqs."
 	@echo " "
 
 else ifeq ($(DOC),mega-manual)
@@ -445,19 +417,18 @@ eclipse: eclipse-generate eclipse-resolve-links
 .PHONY : eclipse-generate eclipse-resolve-links
 
 eclipse-generate:
-ifeq ($(filter $(DOC), concepts-manual getting-started sdk-manual bsp-guide dev-manual kernel-dev profile-manual ref-manual yocto-project-qs),)
+ifeq ($(filter $(DOC), overview-manual sdk-manual bsp-guide dev-manual kernel-dev profile-manual ref-manual brief-yoctoprojectqs),)
 	@echo " "
 	@echo "ERROR: You can only create eclipse documentation"
 	@echo "       of the following documentation parts:"
-	@echo "       - concepts-manual"
+	@echo "       - overview-manual"
-	@echo "       - getting-started"
 	@echo "       - sdk-manual"
 	@echo "       - bsp-guide"
 	@echo "       - dev-manual"
 	@echo "       - kernel-dev"
 	@echo "       - profile-manual"
 	@echo "       - ref-manual"
-	@echo "       - yocto-project-qs"
+	@echo "       - brief-yoctoprojectqs"
 	@echo " "
 else
 	@echo " "

documentation/brief-yoctoprojectqs/brief-yoctoprojectqs-eclipse-customization.xsl

@@ -16,13 +16,13 @@
 
 -->
 
-  <xsl:import href="yocto-project-qs-titlepage.xsl"/>
+  <xsl:import href="brief-yoctoprojectqs-titlepage.xsl"/>
 
   <xsl:param name="chunker.output.indent" select="'yes'"/>
   <xsl:param name="chunk.quietly" select="1"/>
   <xsl:param name="use.id.as.filename" select="1"/>
   <xsl:param name="ulink.target" select="'_self'" />
-  <xsl:param name="base.dir" select="'html/yocto-project-qs/'"/>
+  <xsl:param name="base.dir" select="'html/brief-yoctoprojectqs/'"/>
   <xsl:param name="chunk.section.depth" select="0"/>
   <xsl:param name="html.stylesheet" select="'../book.css'"/>
   <xsl:param name="eclipse.manifest" select="0"/>
@@ -32,3 +32,4 @@
   <xsl:param name="generate.toc" select="'article nop'"></xsl:param>
   <xsl:param name="html.stylesheet" select="'style.css'" />
 </xsl:stylesheet>
+

documentation/brief-yoctoprojectqs/brief-yoctoprojectqs-style.css

@@ -118,7 +118,7 @@ h6 {
   background-color: transparent;
   background-repeat: no-repeat;
   padding-top: 256px;
-  background-image: url("figures/ypqs-title.png");
+  background-image: url("figures/bypqs-title.png");
   background-position: left top;
   margin-top: -256px;
   padding-right: 50px;

documentation/brief-yoctoprojectqs/brief-yoctoprojectqs.xml

@@ -4,7 +4,7 @@
 
 <article id='brief-yocto-project-qs-intro'>
     <articleinfo>
-        <title>My First Yocto Project Build</title>
+        <title>Yocto Project Quick Build</title>
 
         <copyright>
             <year>&COPYRIGHT_YEAR;</year>
@@ -16,28 +16,6 @@
                 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><title>Manual Notes</title>
-                <itemizedlist>
-                    <listitem><para>
-                        For the latest version of this document associated with
-                        this Yocto Project release
-                        (version &YOCTO_DOC_VERSION;), see the "My First
-                        Yocto Project Build" from the
-                        <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>.
-                        </para></listitem>
-                    <listitem><para>
-                        This paper is written for the &YOCTO_DOC_VERSION;.
-                        For later releases of the Yocto Project (if they exist),
-                        go to the
-                        <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
-                        and use the drop-down "Active Releases" button
-                        and choose the Yocto Project version for which you want
-                        the manual.
-                        </para></listitem>
-                </itemizedlist>
-            </note>
--->
         </legalnotice>
 
 
@@ -55,6 +33,8 @@
             Welcome!
             This short document steps you through the process for a typical
             image build using the Yocto Project.
+            The document also introduces how to configure a build for specific
+            hardware.
             You will use Yocto Project to build a reference embedded OS
             called Poky.
             <note>
@@ -74,7 +54,7 @@
         <para>
             If you want more conceptual or background information on the
             Yocto Project, see the
-            <ulink url='&YOCTO_DOCS_GS_URL;'>Getting Started With Yocto Project Manual</ulink>.
+            <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>.
         </para>
     </section>
 
@@ -82,7 +62,9 @@
         <title>Compatible Linux Distribution</title>
 
         <para>
-            Make sure your build system meets the following requirements:
+            Make sure your
+            <ulink url='&YOCTO_DOCS_REF_URL;#hardware-build-system-term'>build host</ulink>
+            meets the following requirements:
             <itemizedlist>
                 <listitem><para>
                     50 Gbytes of free disk space
@@ -118,11 +100,11 @@
     </section>
 
     <section id='brief-build-system-packages'>
-        <title>Build System Packages</title>
+        <title>Build Host Packages</title>
 
         <para>
             You must install essential host packages on your
-            development host.
+            build host.
             The following command installs the host packages based on an
             Ubuntu distribution:
             <note>
@@ -143,31 +125,55 @@
         <para>
             Once you complete the setup instructions for your machine,
             you need to get a copy of the Poky repository on your build
-            system.
+            host.
             Use the following commands to clone the Poky
             repository and then checkout the &DISTRO_REL_TAG; release:
             <literallayout class='monospaced'>
      $ git clone git://git.yoctoproject.org/poky
      Cloning into 'poky'...
-     remote: Counting objects: 361782, done.
+     remote: Counting objects: 431956, done.
-     remote: Compressing objects: 100% (87100/87100), done.
+     remote: Compressing objects: 100% (101918/101918), done.
-     remote: Total 361782 (delta 268619), reused 361439 (delta 268277)
+     remote: Total 431956 (delta 322982), reused 431910 (delta 322936)
-     Receiving objects: 100% (361782/361782), 131.94 MiB | 6.88 MiB/s, done.
+     Receiving objects: 100% (431956/431956), 153.76 MiB | 6.86 MiB/s, done.
-     Resolving deltas: 100% (268619/268619), done.
+     Resolving deltas: 100% (322982/322982), done.
      Checking connectivity... done.
-     $ git checkout tags/yocto-2.5 -b my-yocto-2.5
             </literallayout>
-            The previous Git checkout command creates a local branch
+            Move to the poky directory and take a look at the tags:
-            named my-&DISTRO_REL_TAG;. The files available to you in that
+            <literallayout class='monospaced'>
-            branch exactly match the repository's files in the
+     $ cd poky
-            "&DISTRO_NAME_NO_CAP;" development branch at the time of the
+     $ git fetch --tags
-            Yocto Project &DISTRO; release.
+     $ git tag
+     1.1_M1.final
+     1.1_M1.rc1
+     1.1_M1.rc2
+     1.1_M2.final
+     1.1_M2.rc1
+        .
+        .
+        .
+     yocto-2.5.2
+     yocto-2.5.3
+     yocto-2.6
+     yocto-2.6.1
+     yocto_1.5_M5.rc8
+            </literallayout>
+            For this example, check out the branch based on the
+            yocto-&DISTRO; release:
+            <literallayout class='monospaced'>
+     $ git checkout tags/yocto-&DISTRO; -b my-yocto-&DISTRO;
+     Switched to a new branch 'my-yocto-&DISTRO;'
+            </literallayout>
+            The previous Git checkout command creates a local branch named
+            my-yocto-&DISTRO;.
+            The files available to you in that branch exactly match the
+            repository's files in the "&DISTRO_NAME_NO_CAP;" development
+            branch at the time of the Yocto Project yocto-&DISTRO; release.
         </para>
 
         <para>
             For more options and information about accessing Yocto
             Project related repositories, see the
-            "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>"
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>"
             section in the Yocto Project Development Tasks Manual.
         </para>
     </section>
@@ -177,8 +183,8 @@
 
         <para>
             Use the following steps to build your image.
-            The OpenEmbedded build system creates an entire Linux
+            The build process creates an entire Linux distribution, including
-            distribution, including the toolchain, from source.
+            the toolchain, from source.
             <note>
                 <itemizedlist>
                     <listitem><para>
@@ -207,7 +213,7 @@
                     <emphasis>Initialize the Build Environment:</emphasis>
                     Run the
                     <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
-                    environment setup script to define the OpenEmbedded
+                    environment setup script to define Yocto Project's
                     build environment on your build host.
                     <literallayout class='monospaced'>
      $ source &OE_INIT_FILE;
@@ -222,7 +228,7 @@
                     Later, when the build completes, the Build Directory
                     contains all the files created during the build.
                     </para></listitem>
-                <listitem><para>
+                <listitem><para id='conf-file-step'>
                     <emphasis>Examine Your Local Configuration File:</emphasis>
                     When you set up the build environment, a local
                     configuration file named
@@ -243,13 +249,13 @@
                         <literallayout class='monospaced'>
      SSTATE_MIRRORS = "\
      file://.* http://sstate.yoctoproject.org/dev/PATH;downloadfilename=PATH \n \
-     file://.* http://sstate.yoctoproject.org/2.3/PATH;downloadfilename=PATH \n \
+     file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION_MINUS_ONE;/PATH;downloadfilename=PATH \n \
-     file://.* http://sstate.yoctoproject.org/2.4/PATH;downloadfilename=PATH \n \
+     file://.* http://sstate.yoctoproject.org/&YOCTO_DOC_VERSION;/PATH;downloadfilename=PATH \n \
      "
                         </literallayout>
                         The previous examples showed how to add sstate
-                        paths for Yocto Project 2.3, 2.4, and a development
+                        paths for Yocto Project &YOCTO_DOC_VERSION_MINUS_ONE;,
-                        area.
+                        &YOCTO_DOC_VERSION;, and a development area.
                         For a complete index of sstate locations, see
                         <ulink url='http://sstate.yoctoproject.org/'></ulink>.
                     </tip>
@@ -264,9 +270,9 @@
                     </literallayout>
                     For information on using the
                     <filename>bitbake</filename> command, see the
-                    "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#usingpoky-components-bitbake'>BitBake</ulink>"
+                    "<ulink url='&YOCTO_DOCS_OM_URL;#usingpoky-components-bitbake'>BitBake</ulink>"
-                    section in the Yocto Project Overview Manual, or
+                    section in the Yocto Project Overview and Concepts Manual,
-                    see the
+                    or see the
                     "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-command'>BitBake Command</ulink>"
                     section in the BitBake User Manual.
                     </para></listitem>
@@ -292,6 +298,147 @@
         </para>
     </section>
 
+    <section id='customizing-your-build-for-specific-hardware'>
+        <title>Customizing Your Build for Specific Hardware</title>
+
+        <para>
+            So far, all you have done is quickly built an image suitable
+            for emulation only.
+            This section shows you how to customize your build for specific
+            hardware by adding a hardware layer into the Yocto Project
+            development environment.
+        </para>
+
+        <para>
+            In general, layers are repositories that contain related sets of
+            instructions and configurations that tell the Yocto Project what
+            to do.
+            Isolating related metadata into functionally specific layers
+            facilitates modular development and makes it easier to reuse the
+            layer metadata.
+            <note>
+                By convention, layer names start with the string "meta-".
+            </note>
+        </para>
+
+        <para>
+            Follow these steps to add a hardware layer:
+            <orderedlist>
+                <listitem><para>
+                    <emphasis>Find a Layer:</emphasis>
+                    Lots of hardware layers exist.
+                    The Yocto Project
+                    <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>
+                    has many hardware layers.
+                    This example adds the
+                    <ulink url='https://github.com/kraj/meta-altera'>meta-altera</ulink>
+                    hardware layer.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Clone the Layer</emphasis>
+                    Use Git to make a local copy of the layer on your machine.
+                    You can put the copy in the top level of the copy of the
+                    Poky repository created earlier:
+                    <literallayout class='monospaced'>
+     $ cd ~/poky
+     $ git clone https://github.com/kraj/meta-altera.git
+     Cloning into 'meta-altera'...
+     remote: Counting objects: 25170, done.
+     remote: Compressing objects: 100% (350/350), done.
+     remote: Total 25170 (delta 645), reused 719 (delta 538), pack-reused 24219
+     Receiving objects: 100% (25170/25170), 41.02 MiB | 1.64 MiB/s, done.
+     Resolving deltas: 100% (13385/13385), done.
+     Checking connectivity... done.
+                    </literallayout>
+                    The hardware layer now exists with other layers inside
+                    the Poky reference repository on your build host as
+                    <filename>meta-altera</filename> and contains all the
+                    metadata needed to support hardware from Altera, which
+                    is owned by Intel.
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Change the Configuration to Build for a Specific Machine:</emphasis>
+                    The
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+                    variable in the <filename>local.conf</filename> file
+                    specifies the machine for the build.
+                    For this example, set the <filename>MACHINE</filename>
+                    variable to "cyclone5".
+                    These configurations are used:
+                    <ulink url='https://github.com/kraj/meta-altera/blob/master/conf/machine/cyclone5.conf'></ulink>.
+                    <note>
+                        See the
+                        "<link linkend='conf-file-step'>Examine Your Local Configuration File</link>"
+                        step earlier for more information on configuring the
+                        build.
+                    </note>
+                    </para></listitem>
+                <listitem><para>
+                    <emphasis>Add Your Layer to the Layer Configuration File:</emphasis>
+                    Before you can use a layer during a build, you must add it
+                    to your <filename>bblayers.conf</filename> file, which
+                    is found in the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory's</ulink>
+                    <filename>conf</filename> directory.</para>
+
+                    <para>Use the <filename>bitbake-layers add-layer</filename>
+                    command to add the layer to the configuration file:
+                    <literallayout class='monospaced'>
+     $ cd ~/poky/build
+     $ bitbake-layers add-layer ../meta-altera
+     NOTE: Starting bitbake server...
+     Parsing recipes: 100% |##################################################################| Time: 0:00:32
+     Parsing of 918 .bb files complete (0 cached, 918 parsed). 1401 targets, 123 skipped, 0 masked, 0 errors.
+                    </literallayout>
+                    You can find more information on adding layers in the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#adding-a-layer-using-the-bitbake-layers-script'>Adding a Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
+                    section.
+                    </para></listitem>
+            </orderedlist>
+            Completing these steps has added the
+            <filename>meta-altera</filename> layer to your Yocto Project
+            development environment and configured it to build for the
+            "cyclone5" machine.
+            <note>
+                The previous steps are for demonstration purposes only.
+                If you were to attempt to build an image for the
+                "cyclone5" build, you should read the Altera
+                <filename>README</filename>.
+            </note>
+        </para>
+    </section>
+
+    <section id='creating-your-own-general-layer'>
+        <title>Creating Your Own General Layer</title>
+
+        <para>
+            Maybe you have an application or specific set of behaviors you
+            need to isolate.
+            You can create your own general layer using the
+            <filename>bitbake-layers create-layer</filename> command.
+            The tool automates layer creation by setting up a
+            subdirectory with a <filename>layer.conf</filename>
+            configuration file, a <filename>recipes-example</filename>
+            subdirectory that contains an <filename>example.bb</filename>
+            recipe, a licensing file, and a <filename>README</filename>.
+        </para>
+
+        <para>
+            The following commands run the tool to create a layer named
+            <filename>meta-mylayer</filename> in the
+            <filename>poky</filename> directory:
+            <literallayout class='monospaced'>
+     $ cd ~/poky
+     $ bitbake-layers create-layer meta-mylayer
+     NOTE: Starting bitbake server...
+     Add your new layer with 'bitbake-layers add-layer meta-mylayer'
+            </literallayout>
+            For more information on layers and how to create them, see the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
+            section in the Yocto Project Development Tasks Manual.
+        </para>
+    </section>
+
     <section id='brief-where-to-go-next'>
         <title>Where To Go Next</title>
 
@@ -321,6 +468,17 @@
                     introductory and fundamental concepts are useful for
                     the beginner.
                     </para></listitem>
+                <listitem><para>
+                    <emphasis>Yocto Project Overview and Concepts Manual:</emphasis>
+                    The
+                    <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>
+                    is a great place to start to learn about the
+                    Yocto Project.
+                    This manual introduces you to the Yocto Project and its
+                    development environment.
+                    The manual also provides conceptual information for
+                    various aspects of the Yocto Project.
+                    </para></listitem>
                 <listitem><para>
                     <emphasis>Yocto Project Wiki:</emphasis>
                     The

documentation/bsp-guide/bsp-guide.xml

@@ -118,9 +118,24 @@
             </revision>
             <revision>
                 <revnumber>2.5</revnumber>
-                <date>April 2018</date>
+                <date>May 2018</date>
                 <revremark>Released with the Yocto Project 2.5 Release.</revremark>
             </revision>
+            <revision>
+                <revnumber>2.5.1</revnumber>
+                <date>September 2018</date>
+                <revremark>The initial document released with the Yocto Project 2.5.1 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>2.5.2</revnumber>
+                <date>January 2019</date>
+                <revremark>The initial document released with the Yocto Project 2.5.2 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>2.5.3</revnumber>
+                <date>&REL_MONTH_YEAR;</date>
+                <revremark>The initial document released with the Yocto Project 2.5.3 Release.</revremark>
+            </revision>
         </revhistory>
 
     <copyright>
@@ -137,28 +152,40 @@
                <itemizedlist>
                    <listitem><para>
                        This version of the
-                       <emphasis>Yocto Project Board Support Package Developer's Guide</emphasis>
+                       <emphasis>Yocto Project Board Support Package (BSP) Developer's Guide</emphasis>
                        is for the &YOCTO_DOC_VERSION; release of the
                        Yocto Project.
                        To be sure you have the latest version of the manual
-                       for this release, use the manual from the
+                       for this release, go to the
-                       <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>.
-                       </para></listitem>
-                   <listitem><para>
-                       For manuals associated with other releases of the Yocto
-                       Project, go to the
                        <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
-                       and use the drop-down "Active Releases" button
+                       and select the manual from that site.
-                       and choose the manual associated with the desired
+                       Manuals from the site are more up-to-date than manuals
-                       Yocto Project.
+                       derived from the Yocto Project released TAR files.
                        </para></listitem>
                    <listitem><para>
-                        To report any inaccuracies or problems with this
+                       If you located this manual through a web search, the
-                        manual, send an email to the Yocto Project
+                       version of the manual might not be the one you want
-                        discussion group at
+                       (e.g. the search might have returned a manual much
-                        <filename>yocto@yoctoproject.com</filename> or log into
+                       older than the Yocto Project version with which you
-                        the freenode <filename>#yocto</filename> channel.
+                       are working).
-                        </para></listitem>
+                       You can see all Yocto Project major releases by
+                       visiting the
+                       <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
+                       page.
+                       If you need a version of this manual for a different
+                       Yocto Project release, visit the
+                       <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
+                       and select the manual set by using the
+                       "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
+                       pull-down menus.
+                       </para></listitem>
+                   <listitem><para>
+                       To report any inaccuracies or problems with this
+                       manual, send an email to the Yocto Project
+                       discussion group at
+                       <filename>yocto@yoctoproject.com</filename> or log into
+                       the freenode <filename>#yocto</filename> channel.
+                       </para></listitem>
                </itemizedlist>
            </note>
     </legalnotice>

documentation/bsp-guide/bsp.xml

@@ -56,9 +56,9 @@
         To help understand the BSP layer concept, consider the BSPs that the
         Yocto Project supports and provides with each release.
         You can see the layers in the
-        <ulink url='&YOCTO_DOCS_GS_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>
+        <ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>
         through a web interface at
-        <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>.
+        <ulink url='&YOCTO_GIT_URL;'></ulink>.
         If you go to that interface, you will find a list of repositories
         under "Yocto Metadata Layers".
         <note>
@@ -93,8 +93,8 @@
         section.
         For more information on how to set up a local copy of source files
         from a Git repository, see the
-        "<ulink url='&YOCTO_DOCS_DEV_URL;#working-with-yocto-project-source-files'>Working With Yocto Project Source Files</ulink>"
+        "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>"
-        section also in the Yocto Project Development Tasks Manual.
+        section in the Yocto Project Development Tasks Manual.
     </para>
 
     <para>
@@ -187,7 +187,7 @@
                 <emphasis>Set Up the Build Environment:</emphasis>
                 Be sure you are set up to use BitBake in a shell.
                 See the
-                "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Setting Up the Development Host to Use the Yocto Project</ulink>"
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Preparing the Build Host</ulink>"
                 section in the Yocto Project Development Tasks Manual for information
                 on how to get a build host ready that is either a native
                 Linux machine or a machine that uses CROPS.
@@ -340,7 +340,7 @@
         It is also intended that it will be be simple to extract
         information and convert it to other formats if required.
         The OpenEmbedded build system, through its standard
-        <ulink url='&YOCTO_DOCS_GS_URL;#the-yocto-project-layer-model'>layers mechanism</ulink>,
+        <ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>layers mechanism</ulink>,
         can directly accept the format described as a layer.
         The BSP layer captures all the hardware-specific details
         in one place using a standard format, which is useful
@@ -953,7 +953,7 @@
         <para>
             You can find more information on what your append file
             should contain in the
-            "<ulink url='&YOCTO_DOCS_KERNEL_URL;#creating-the-append-file'>Creating the Append File</ulink>"
+            "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#creating-the-append-file'>Creating the Append File</ulink>"
             section in the Yocto Project Linux Kernel Development
             Manual.
         </para>
@@ -1012,7 +1012,7 @@
                 to Support Development Using the Yocto
                 Project</emphasis>:
                 See the
-                "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Setting Up the Development Host to Use the Yocto Project</ulink>"
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Preparing the Build Host</ulink>"
                 section in the Yocto Project Development Tasks
                 Manual for options on how to get a system ready
                 to use the Yocto Project.
@@ -1056,8 +1056,8 @@
                 information for the project that the
                 OpenEmbedded build system knows about.
                 For more information on layers, see the
-                "<ulink url='&YOCTO_DOCS_GS_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
+                "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
-                section in the Getting Started With Yocto Project
+                section in the Yocto Project Overview and Concepts
                 Manual.
                 You can also reference the
                 "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
@@ -1283,7 +1283,7 @@
                     is found in <filename>poky/meta</filename>
                     directory of the
                     <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
-                    or in the OpenEmbedded Core Layer
+                    or in the OpenEmbedded-Core Layer
                     (<filename>openembedded-core</filename>) at
                     <ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>.
                     </para>
@@ -1303,7 +1303,7 @@
                     <para>Within any particular
                     <filename>recipes-*</filename> category, the
                     layout should match what is found in the
-                    OpenEmbedded Core Git repository
+                    OpenEmbedded-Core Git repository
                     (<filename>openembedded-core</filename>)
                     or the Source Directory (<filename>poky</filename>).
                     In other words, make sure you place related
@@ -1338,7 +1338,7 @@
                     <filename>meta-</filename><replaceable>bsp_root_name</replaceable>
                     directory.
                     See the
-                    <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README'><filename>README</filename></ulink>
+                    <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README.md'><filename>README.md</filename></ulink>
                     file for the Raspberry Pi BSP in the
                     <filename>meta-raspberrypi</filename> BSP layer
                     as an example.</para>
@@ -1507,7 +1507,7 @@
                     its scalability.
                     See the <filename>Yocto Linux Kernel</filename>
                     category in the
-                    <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Source Repositories</ulink>
+                    <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>
                     for these kernels.
                     </para></listitem>
             </itemizedlist>
@@ -1687,9 +1687,10 @@
                 Thus, the build system can build the corresponding
                 recipe and include the component in the image.
                 See the
-                "<ulink url='&YOCTO_DOCS_CM_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>"
-                section in the Yocto Project Concepts Manual for
+                section in the Yocto Project Development Tasks
-                details on how to use these variables.</para>
+                Manual for details on how to use these variables.
+                </para>
 
                 <para>If you build as you normally would, without
 	        specifying any recipes in the
@@ -1746,25 +1747,20 @@
     <title>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</title>
 
     <para>
-        [INTRODUCE THE PROCEDURE AND LINK BACK TO <link linkend='bsp-layers'>BSP layer</link>.
+        The <filename>bitbake-layers create-layer</filename> script
-        IF THERE IS A LAUNDRY LIST OF ITEMS THAT NEED DEFINITION OR GET SET
+        automates creating a BSP layer.
-        UP AS A RESULT OF THIS PROCEDURE, LIST THEM HERE.]
+        What makes a layer a "BSP layer", is the presence of a machine
-        <itemizedlist>
+        configuration file.
-            <listitem><para>[PARAMETER 1]</para></listitem>
+        Additionally, a BSP layer usually has a kernel recipe
-            <listitem><para>[PARAMETER 2]</para></listitem>
+        or an append file that leverages off an existing kernel recipe.
-            <listitem><para>[PARAMETER 3]</para></listitem>
+        The primary requirement, however, is the machine configuration.
-            <listitem><para>[PARAMETER 4]</para></listitem>
-            <listitem><para>[PARAMETER 5]</para></listitem>
-            <listitem><para>[PARAMETER 6]</para></listitem>
-            <listitem><para>[PARAMETER 7]</para></listitem>
-        </itemizedlist>
     </para>
 
     <para>
-        The following procedure creates a BSP layer:
+        Use these steps to create a BSP layer:
         <itemizedlist>
             <listitem><para>
-                <emphasis>Create General Layer:</emphasis>
+                <emphasis>Create a General Layer:</emphasis>
                 Use the <filename>bitbake-layers</filename> script with the
                 <filename>create-layer</filename> subcommand to create a
                 new general layer.
@@ -1774,25 +1770,41 @@
                 section in the Yocto Project Development Tasks Manual.
                 </para></listitem>
             <listitem><para>
-                <emphasis>Create a Machine Configuration File:</emphasis>
+                <emphasis>Create a Layer Configuration File:</emphasis>
-                Create a <filename>conf/machine/&gt;machine&lt;.conf</filename>
+                Every layer needs a layer configuration file.
+                This configuration file establishes locations for the
+                layer's recipes, priorities for the layer, and so forth.
+                You can find examples of <filename>layer.conf</filename>
+                files in the Yocto Project
+                <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>.
+                To get examples of what you need in your configuration
+                file, locate a layer (e.g. "meta-ti") and examine the
+                <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-ti/tree/conf/layer.conf'></ulink>
                 file.
-                See <filename>meta-yocto-bsp/conf/machine</filename> for sample
+                </para></listitem>
-                <filename>&gt;machine.conf&lt;</filename> files.
+            <listitem><para>
-                Other samples exist from other vendors such as
+                <emphasis>Create a Machine Configuration File:</emphasis>
-                <filename>meta-intel</filename>, <filename>meta-ti</filename>,
+                Create a <filename>conf/machine/</filename><replaceable>bsp_root_name</replaceable><filename>.conf</filename>
-                and <filename>meta-freescale</filename> that have more specific machine
+                file.
+                See
+                <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp/conf/machine'><filename>meta-yocto-bsp/conf/machine</filename></ulink>
+                for sample
+                <replaceable>bsp_root_name</replaceable><filename>.conf</filename>
+                files.
+                Other samples such as
+                <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-ti/tree/conf/machine'><filename>meta-ti</filename></ulink>
+                and
+                <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-freescale/tree/conf/machine'><filename>meta-freescale</filename></ulink>
+                exist from other vendors that have more specific machine
                 and tuning examples.
                 </para></listitem>
             <listitem><para>
                 <emphasis>Create a Kernel Recipe:</emphasis>
                 Create a kernel recipe in <filename>recipes-kernel/linux</filename>
-                either using a linux-yocto kernel with a <filename>.bbappend</filename>
+                by either using a kernel append file or a new custom kernel
-                file or a new custom kernel recipe file (i.e. <filename>.bb</filename>
+                recipe file (e.g. <filename>yocto-linux_4.12.bb</filename>).
-                file).
                 The BSP layers mentioned in the previous step also contain different
                 kernel examples.
-                You can start with the linux-yocto or use a custom kernel.
                 See the
                 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#modifying-an-existing-recipe'>Modifying an Existing Recipe</ulink>"
                 section in the Yocto Project Linux Kernel Development Manual
@@ -1802,43 +1814,456 @@
     </para>
 
     <para>
-        [THERE IS MORE INFORMATION THAT NEEDS TO BE FILLED IN HERE. THIS NEEDS TO
+        The remainder of this section provides a description of
-        BE PROVIDED BY ENGINEERS.]
+        the Yocto Project reference BSP for Beaglebone, which
+        resides in the
+        <ulink url='&YOCTO_DOCS_REF_URL;#term-container-layer'>Container Layer</ulink>
+        (i.e.
+        <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp'><filename>meta-yocto-bsp</filename></ulink>).
     </para>
 
-    <para>
+    <section id='bsp-layer-configuration-example'>
-        The remainder of this section presents an example that uses
+        <title>BSP Layer Configuration Example</title>
-        <filename>myarm</filename> as the machine name and <filename>qemu</filename>
-        as the machine architecture.
-        Of the available architectures, <filename>qemu</filename> is the only architecture
-        that causes the script to prompt you further for an actual architecture.
-        In every other way, this architecture is representative of how creating a BSP for
-        an actual machine would work.
-        The reason the example uses this architecture is because it is an emulated architecture
-        and can easily be followed without requiring actual hardware.
-    </para>
 
-    <para>
+        <para>
-        Following is a complete example:
+            The layer's <filename>conf</filename> directory
-        <literallayout class='monospaced'>
+            contains the <filename>layer.conf</filename>
-     [INSERT EXAMPLE - NEED EXAMPLE]
+            configuration file.
-        </literallayout>
+            In this example, the
-    </para>
+            <filename>conf/layer.conf</filename> is the
+            following:
+            <literallayout class='monospaced'>
+     # We have a conf and classes directory, add to BBPATH
+     BBPATH .= ":${LAYERDIR}"
 
-    <para>
+     # We have recipes-* directories, add to BBFILES
-        Once the BSP Layer is created, you must add it to your
+     BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
-        <filename>bblayers.conf</filename> file.
+                 ${LAYERDIR}/recipes-*/*/*.bbappend"
-        Here is an example:
+
-        <literallayout class='monospaced'>
+     BBFILE_COLLECTIONS += "yoctobsp"
-     BBLAYERS = ? " \
+     BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/"
-        /usr/local/src/yocto/meta \
+     BBFILE_PRIORITY_yoctobsp = "5"
-        /usr/local/src/yocto/meta-poky \
+     LAYERVERSION_yoctobsp = "4"
-        /usr/local/src/yocto/meta-yocto-bsp \
+     LAYERSERIES_COMPAT_yoctobsp = "&DISTRO_NAME_NO_CAP;"
-        /usr/local/src/yocto/meta-myarm \
+            </literallayout>
-        "
+            The variables used in this file configure the
-        </literallayout>
+            layer.
-        Adding the layer to this file allows the build system to build the BSP and
+            A good way to learn about layer configuration
-        find the layer along with other Metadata it needs.
+            files is to examine various files for BSP from
-    </para>
+            the
+            <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>.
+        </para>
+
+        <para>
+            For a detailed description of this particular
+            layer configuration file, see
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-layer-config-file-description'>step 3</ulink>
+            in the discussion that describes how to create
+            layers in the Yocto Project Development Tasks Manual.
+        </para>
+    </section>
+
+    <section id='bsp-machine-configuration-example'>
+        <title>BSP Machine Configuration Example</title>
+
+        <para>
+            As mentioned earlier in this section, the existence
+            of a machine configuration file is what makes a
+            layer a BSP layer as compared to a general or
+            kernel layer.
+        </para>
+
+        <para>
+            Machine configuration files exist in the
+            <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename>
+            directory of the layer:
+            <literallayout class='monospaced'>
+     <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine</replaceable><filename>.conf</filename>
+            </literallayout>
+            For example, the machine configuration file for the
+            <ulink url='http://beagleboard.org/bone'>BeagleBone and BeagleBone Black development boards</ulink>
+            is located in the container layer
+            <filename>poky/meta-yocto-bsp/conf/machine</filename>
+            and is named <filename>beaglebone-yocto.conf</filename>:
+            <literallayout class='monospaced'>
+     #@TYPE: Machine
+     #@NAME: Beaglebone-yocto machine
+     #@DESCRIPTION: Reference machine configuration for http://beagleboard.org/bone and http://beagleboard.org/black boards
+
+     PREFERRED_PROVIDER_virtual/xserver ?= "xserver-xorg"
+     XSERVER ?= "xserver-xorg \
+                xf86-video-modesetting \
+                "
+
+     MACHINE_EXTRA_RRECOMMENDS = "kernel-modules kernel-devicetree"
+
+     EXTRA_IMAGEDEPENDS += "u-boot"
+
+     DEFAULTTUNE ?= "cortexa8hf-neon"
+     include conf/machine/include/tune-cortexa8.inc
+
+     IMAGE_FSTYPES += "tar.bz2 jffs2 wic wic.bmap"
+     EXTRA_IMAGECMD_jffs2 = "-lnp "
+     WKS_FILE ?= "beaglebone-yocto.wks"
+     IMAGE_INSTALL_append = " kernel-devicetree kernel-image-zimage"
+     do_image_wic[depends] += "mtools-native:do_populate_sysroot dosfstools-native:do_populate_sysroot"
+
+     SERIAL_CONSOLES = "115200;ttyO0"
+
+     PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
+     PREFERRED_VERSION_linux-yocto ?= "4.12%"
+
+     KERNEL_IMAGETYPE = "zImage"
+     KERNEL_DEVICETREE = "am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb"
+     KERNEL_EXTRA_ARGS += "LOADADDR=${UBOOT_ENTRYPOINT}"
+
+     SPL_BINARY = "MLO"
+     UBOOT_SUFFIX = "img"
+     UBOOT_MACHINE = "am335x_boneblack_config"
+     UBOOT_ENTRYPOINT = "0x80008000"
+     UBOOT_LOADADDRESS = "0x80008000"
+
+     MACHINE_FEATURES = "usbgadget usbhost vfat alsa"
+
+     IMAGE_BOOT_FILES ?= "u-boot.${UBOOT_SUFFIX} MLO"
+            </literallayout>
+            The variables used to configure the machine define
+            machine-specific properties.
+            For example, machine-dependent packages, machine
+            tunings, the type of kernel to build, and
+            U-Boot configurations.
+        </para>
+
+        <para>
+            The following list provides some explanation
+            for the statements found in the example reference
+            machine configuration file for the BeagleBone
+            development boards.
+            Realize that much more can be defined as part of
+            a machines configuration file.
+            In general, you can learn about related variables
+            that this example does not have by locating the
+            variables in the
+            "<ulink url='&YOCTO_DOCS_REF_URL;#ref-variables-glos'>Yocto Project Variables Glossary</ulink>"
+            in the Yocto Project Reference Manual.
+            <itemizedlist>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER_virtual/xserver</filename></ulink>:
+                    The recipe that provides "virtual/xserver" when
+                    more than one provider is found.
+                    In this case, the recipe that provides
+                    "virtual/xserver" is "xserver-xorg", which
+                    exists in
+                    <filename>poky/meta/recipes-graphics/xserver-xorg</filename>.
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-XSERVER'><filename>XSERVER</filename></ulink>:
+                    The packages that should be installed to provide
+                    an X server and drivers for the machine.
+                    In this example, the "xserver-xorg" and
+                    "xf86-video-modesetting" are installed.
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>:
+                    A list of machine-dependent packages
+                    not essential for booting the image.
+                    Thus, the build does not fail if the packages
+                    do not exist.
+                    However, the packages are required for a
+                    fully-featured image.
+                    <note><title>Tip</title>
+                        Many <filename>MACHINE*</filename> variables
+                        exist that help you configure a particular
+                        piece of hardware.
+                    </note>
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGEDEPENDS'><filename>EXTRA_IMAGEDEPENDS</filename></ulink>:
+                    Recipes to build that do not provide packages
+                    for installing into the root filesystem
+                    but building the image depends on the
+                    recipes.
+                    Sometimes a recipe is required to build
+                    the final image but is not needed in the
+                    root filesystem.
+                    In this case, the U-Boot recipe must be
+                    built for the image.
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></ulink>:
+                    Machines use tunings to optimize machine,
+                    CPU, and application performance.
+                    These features, which are collectively known
+                    as "tuning features", exist in the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OpenEmbedded-Core (OE-Core)</ulink>
+                    layer (e.g.
+                    <filename>poky/meta/conf/machine/include</filename>).
+                    In this example, the default tunning file is
+                    "cortexa8hf-neon".
+                    <note>
+                        The <filename>include</filename> statement
+                        that pulls in the
+                        <filename>conf/machine/include/tune-cortexa8.inc</filename>
+                        file provides many tuning possibilities.
+                    </note>
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>:
+                    The formats the OpenEmbedded build system
+                    uses during the build when creating the
+                    root filesystem.
+                    In this example, four types of images are
+                    supported.
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGECMD'><filename>EXTRA_IMAGECMD</filename></ulink>:
+                    Specifies additional options for image
+                    creation commands.
+                    In this example, the "-lnp " option is used
+                    when creating the
+                    <ulink url='https://en.wikipedia.org/wiki/JFFS2'>JFFS2</ulink>
+                    image.
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-WKS_FILE'><filename>WKS_FILE</filename></ulink>:
+                    The location of the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#ref-kickstart'>Wic kickstart</ulink>
+                    file used by the OpenEmbedded build system to
+                    create a partitioned image (image.wic).
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>:
+                    Specifies packages to install into an image
+                    through the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink>
+                    class.
+                    Recipes use the <filename>IMAGE_INSTALL</filename>
+                    variable.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>do_image_wic[depends]</filename>:
+                    A task that is constructed during the build.
+                    In this example, the task depends on specific tools
+                    in order to create the sysroot when buiding a Wic
+                    image.
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></ulink>:
+                    Defines a serial console (TTY) to enable using
+                    getty.
+                    In this case, the baud rate is "115200" and the
+                    device name is "ttyO0".
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER_virtual/kernel</filename></ulink>:
+                    Specifies the recipe that provides
+                    "virtual/kernel" when more than one provider
+                    is found.
+                    In this case, the recipe that provides
+                    "virtual/kernel" is "linux-yocto", which
+                    exists in the layer's
+                    <filename>recipes-kernel/linux</filename> directory.
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION_linux-yocto</filename></ulink>:
+                    Defines the version of the recipe used
+                    to build the kernel, which is "4.12" in this
+                    case.
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></ulink>:
+                    The type of kernel to build for the device.
+                    In this case, the OpenEmbedded build system
+                    creates a "zImage" image type.
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_DEVICETREE'><filename>KERNEL_DEVICETREE</filename></ulink>:
+                    The name of the generated Linux kernel device
+                    tree (i.e. the <filename>.dtb</filename>) file.
+                    All the device trees for the various BeagleBone
+                    devices are included.
+<!--
+                    You have to include some *.inc files according to the definition of KERNEL_DEVICETREE.
+                    I don't see where these are being provided.
+-->
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_EXTRA_ARGS'><filename>KERNEL_EXTRA_ARGS</filename></ulink>:
+                    Additional <filename>make</filename>
+                    command-line arguments the OpenEmbedded build
+                    system passes on when compiling the kernel.
+                    In this example, "LOADADDR=${UBOOT_ENTRYPOINT}"
+                    is passed as a command-line argument.
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-SPL_BINARY'><filename>SPL_BINARY</filename></ulink>:
+                    Defines the Secondary Program Loader (SPL) binary
+                    type.
+                    In this case, the SPL binary is set to
+                    "MLO", which stands for Multimedia card LOader.
+                    </para>
+
+                    <para>The BeagleBone development board requires an
+                    SPL to boot and that SPL file type must be MLO.
+                    Consequently, the machine configuration needs to
+                    define <filename>SPL_BINARY</filename> as "MLO".
+                    <note>
+                        For more information on how the SPL variables
+                        are used, see the
+                        <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/recipes-bsp/u-boot/u-boot.inc'><filename>u-boot.inc</filename></ulink>
+                        include file.
+                    </note>
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_ENTRYPOINT'><filename>UBOOT_*</filename></ulink>:
+                    Defines various U-Boot configurations needed
+                    to build a U-Boot image.
+                    In this example, a U-Boot image is required
+                    to boot the BeagleBone device.
+                    See the following variables for more information:
+                    <itemizedlist>
+                        <listitem><para>
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_SUFFIX'><filename>UBOOT_SUFFIX</filename></ulink>:
+                            Points to the generated U-Boot extension.
+                            </para></listitem>
+                        <listitem><para>
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></ulink>:
+                            Specifies the value passed on the make command line when building a U-Boot image.
+                            </para></listitem>
+                        <listitem><para>
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_ENTRYPOINT'><filename>UBOOT_ENTRYPOINT</filename></ulink>:
+                            Specifies the entry point for the U-Boot image.
+                            </para></listitem>
+                        <listitem><para>
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_LOADADDRESS'><filename>UBOOT_LOADADDRESS</filename></ulink>:
+                            Specifies the load address for the U-Boot image.
+                            </para></listitem>
+                    </itemizedlist>
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></ulink>:
+                    Specifies the list of hardware features the
+                    BeagleBone device is capable of supporting.
+                    In this case, the device supports
+                    "usbgadget usbhost vfat alsa".
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_BOOT_FILES'><filename>IMAGE_BOOT_FILES</filename></ulink>:
+                    Files installed into the device's boot partition
+                    when preparing the image using the Wic tool
+                    with the <filename>bootimg-partition</filename>
+                    source plugin.
+                    In this case, the "u-boot.${UBOOT_SUFFIX}" and
+                    "MLO" files are installed.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='bsp-kernel-recipe-example'>
+        <title>BSP Kernel Recipe Example</title>
+
+        <para>
+            The kernel recipe used to build the kernel image
+            for the BeagleBone device was established in the
+            machine configuration:
+            <literallayout class='monospaced'>
+     PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
+     PREFERRED_VERSION_linux-yocto ?= "4.12%"
+            </literallayout>
+            The <filename>meta-yocto-bsp/recipes-kernel/linux</filename>
+            directory in the layer contains metadata used
+            to build the kernel.
+            In this case, a kernel append file is used to
+            override an established kernel recipe, which is
+            located in
+            <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/recipes-kernel/linux'></ulink>
+            and named
+            <filename>linux-yocto_4.12.bb</filename>.
+        </para>
+
+        <para>
+            Following is the contents of the append file:
+            <literallayout class='monospaced'>
+     KBRANCH_genericx86  = "standard/base"
+     KBRANCH_genericx86-64  = "standard/base"
+
+     KMACHINE_genericx86 ?= "common-pc"
+     KMACHINE_genericx86-64 ?= "common-pc-64"
+     KBRANCH_edgerouter = "standard/edgerouter"
+     KBRANCH_beaglebone-yocto = "standard/beaglebone"
+     KMACHINE_beaglebone-yocto = "beaglebone"
+     KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb"
+
+     SRCREV_machine_genericx86    ?= "1c4ad569af3e23a77994235435040e322908687f"
+     SRCREV_machine_genericx86-64 ?= "1c4ad569af3e23a77994235435040e322908687f"
+     SRCREV_machine_edgerouter ?= "257f843ea367744620f1d92910afd2f454e31483"
+     SRCREV_machine_beaglebone-yocto ?= "257f843ea367744620f1d92910afd2f454e31483"
+     SRCREV_machine_mpc8315e-rdb ?= "014560874f9eb2a86138c9cc35046ff1720485e1"
+
+
+     COMPATIBLE_MACHINE_genericx86 = "genericx86"
+     COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64"
+     COMPATIBLE_MACHINE_edgerouter = "edgerouter"
+     COMPATIBLE_MACHINE_beaglebone-yocto = "beaglebone-yocto"
+     COMPATIBLE_MACHINE_mpc8315e-rdb = "mpc8315e-rdb"
+
+     LINUX_VERSION_genericx86 = "4.12.20"
+     LINUX_VERSION_genericx86-64 = "4.12.20"
+     LINUX_VERSION_edgerouter = "4.12.19"
+     LINUX_VERSION_beaglebone-yocto = "4.12.19"
+     LINUX_VERSION_mpc8315e-rdb = "4.12.19"
+            </literallayout>
+            This particular append file works for all the
+            machines that are part of the
+            <filename>meta-yocto-bsp</filename> container
+            layer.
+            The relevant statements are appended with
+            the "beaglebone-yocto" string.
+            The OpenEmbedded build system uses these
+            statements to override similar statements
+            in the kernel recipe:
+            <itemizedlist>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>:
+                    Identifies the kernel branch that is validated,
+                    patched, and configured during the build.
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>:
+                    Identifies the machine name as known by the
+                    kernel, which is sometimes a different name
+                    than what is known by the OpenEmbedded build
+                    system.
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>:
+                    Identifies the revision of the source code used
+                    to build the image.
+<!--
+                    You find out about that point in the kernel source tree by
+                    doing the following command:
+
+                    git log &dash;&dash;decorate 257f843ea367744620f1d92910afd2f454e31483
+
+                    Returns information about the commit, which is usually
+                    that it is a merge point for a stable kernel release.
+-->
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>:
+                    A regular expression that resolves to one or
+                    more target machines with which the recipe
+                    is compatible.
+                    </para></listitem>
+                <listitem><para>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>:
+                    The Linux version from kernel.org used by
+                    the OpenEmbedded build system to build the
+                    kernel image.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
 </section>
 </chapter>

documentation/concepts-manual/concepts-manual-customization.xsl

@@ -1,27 +0,0 @@
-<?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://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
-
-<!--
-
-  <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/xhtml/docbook.xsl" />
-
-  <xsl:import href="http://docbook.sourceforge.net/release/xsl/1.76.1/xhtml/docbook.xsl" />
-
--->
-
-  <xsl:include href="../template/permalinks.xsl"/>
-  <xsl:include href="../template/section.title.xsl"/>
-  <xsl:include href="../template/component.title.xsl"/>
-  <xsl:include href="../template/division.title.xsl"/>
-  <xsl:include href="../template/formal.object.heading.xsl"/>
-
-  <xsl:param name="html.stylesheet" select="'concepts-manual-style.css'" />
-  <xsl:param name="chapter.autolabel" select="1" />
-  <xsl:param name="appendix.autolabel" select="A" />
-  <xsl:param name="section.autolabel" select="1" />
-  <xsl:param name="section.label.includes.component.label" select="1" />
-  <xsl:param name="generate.id.attributes" select="1" />
-
-</xsl:stylesheet>

documentation/concepts-manual/concepts-manual-eclipse-customization.xsl

@@ -1,35 +0,0 @@
-<?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://downloads.yoctoproject.org/mirror/docbook-mirror/docbook-xsl-1.76.1/eclipse/eclipse3.xsl" />
-
-<!--
-
-  <xsl:import href="../template/1.76.1/docbook-xsl-1.76.1/eclipse/eclipse3.xsl" />
-
-  <xsl:import
-	  href="http://docbook.sourceforge.net/release/xsl/1.76.1/eclipse/eclipse3.xsl" />
-
--->
-
-  <xsl:param name="chunker.output.indent" select="'yes'"/>
-  <xsl:param name="chunk.quietly" select="1"/>
-  <xsl:param name="chunk.first.sections" select="1"/>
-  <xsl:param name="chunk.section.depth" select="10"/>
-  <xsl:param name="use.id.as.filename" select="1"/>
-  <xsl:param name="ulink.target" select="'_self'" />
-  <xsl:param name="base.dir" select="'html/concepts-manual/'"/>
-  <xsl:param name="html.stylesheet" select="'../book.css'"/>
-  <xsl:param name="eclipse.manifest" select="0"/>
-  <xsl:param name="create.plugin.xml" select="0"/>
-  <xsl:param name="suppress.navigation" select="1"/>
-  <xsl:param name="generate.index" select="0"/>
-  <xsl:param name="chapter.autolabel" select="1" />
-  <xsl:param name="appendix.autolabel" select="1" />
-  <xsl:param name="section.autolabel" select="1" />
-  <xsl:param name="section.label.includes.component.label" select="1" />
-</xsl:stylesheet>

documentation/concepts-manual/concepts-manual-intro.xml

@@ -1,87 +0,0 @@
-<!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='concepts-manual-intro'>
-
-<title>The Yocto Project Concepts Manual</title>
-    <section id='concepts-overview-welcome'>
-        <title>Welcome</title>
-
-        <para>
-            Welcome to the Yocto Project Concepts Manual!
-            This manual provides conceptual information that helps you
-            better understand the Yocto Project.
-            You can learn about Yocto Project components,
-            cross-development toolchain generation, shared-state cache,
-            and many other concepts.
-        </para>
-
-        <para>
-            This manual does not give you the following:
-            <itemizedlist>
-                <listitem><para>
-                    <emphasis>Complete Step-by-step Instructions for Development Tasks:</emphasis>
-                    Instructional procedures reside in other manuals within
-                    the Yocto Project documentation set.
-                    For example, the
-                    <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Tasks Manual</ulink>
-                    provides examples on how to perform various development
-                    tasks.
-                    As another example, the
-                    <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
-                    manual contains detailed instructions on how to install an
-                    SDK, which is used to develop applications for target
-                    hardware.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Reference Material:</emphasis>
-                    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>.
-                    As another example, the
-                    <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>
-                    contains reference information on BSPs.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Getting Started Material:</emphasis>
-                    This type of material resides in the
-                    <ulink url='&YOCTO_DOCS_GS_URL;'>Getting Started With Yocto Project Manual</ulink>.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Detailed Public Information Not Specific to the
-                    Yocto Project:</emphasis>
-                    For example, exhaustive information on how to use Git
-                    is better covered with Internet searches and official
-                    Git Documentation than through the Yocto Project
-                    documentation.
-                    </para></listitem>
-            </itemizedlist>
-        </para>
-    </section>
-
-    <section id='concepts-overview-other-information'>
-        <title>Other Information</title>
-
-        <para>
-            Because this manual presents information for many different
-            concepts, supplemental information is recommended for full
-            comprehension.
-            For additional introductory information on the Yocto Project, see
-            the <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>.
-            You can find an introductory to using the Yocto Project by working
-            through the
-            <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
-        </para>
-
-        <para>
-            For a comprehensive list of links and other documentation, see the
-            "<ulink url='&YOCTO_DOCS_REF_URL;#resources-links-and-related-documentation'>Links and Related Documentation</ulink>"
-            section in the Yocto Project Reference Manual.
-        </para>
-    </section>
-</chapter>
-<!--
-vim: expandtab tw=80 ts=4
--->

documentation/concepts-manual/concepts-manual.xml

@@ -1,92 +0,0 @@
-<!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='concepts-manual' lang='en'
-      xmlns:xi="http://www.w3.org/2003/XInclude"
-      xmlns="http://docbook.org/ns/docbook"
-      >
-    <bookinfo>
-
-        <mediaobject>
-            <imageobject>
-                <imagedata fileref='figures/concepts-manual-title.png'
-                    format='SVG'
-                    align='left' scalefit='1' width='100%'/>
-            </imageobject>
-        </mediaobject>
-
-        <title>
-            Yocto Project Concepts Manual
-        </title>
-
-        <authorgroup>
-            <author>
-                <firstname>Scott</firstname> <surname>Rifenbark</surname>
-                <affiliation>
-                    <orgname>Scotty's Documentation Services, INC</orgname>
-                </affiliation>
-                <email>srifenbark@gmail.com</email>
-            </author>
-        </authorgroup>
-
-        <revhistory>
-            <revision>
-                <revnumber>2.5</revnumber>
-                <date>April 2018</date>
-                <revremark>The initial document released with the Yocto Project 2.5 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><title>Manual Notes</title>
-               <itemizedlist>
-                   <listitem><para>
-                       This version of the
-                       <emphasis>Yocto Project Concepts Manual</emphasis>
-                       is for the &YOCTO_DOC_VERSION; release of the
-                       Yocto Project.
-                       To be sure you have the latest version of the manual
-                       for this release, use the manual from the
-                       <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>.
-                       </para></listitem>
-                   <listitem><para>
-                       For manuals associated with other releases of the Yocto
-                       Project, go to the
-                       <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
-                       and use the drop-down "Active Releases" button
-                       and choose the manual associated with the desired
-                       Yocto Project.
-                       </para></listitem>
-                   <listitem><para>
-                        To report any inaccuracies or problems with this
-                        manual, send an email to the Yocto Project
-                        discussion group at
-                        <filename>yocto@yoctoproject.com</filename> or log into
-                        the freenode <filename>#yocto</filename> channel.
-                        </para></listitem>
-               </itemizedlist>
-           </note>
-    </legalnotice>
-
-    </bookinfo>
-
-    <xi:include href="concepts-manual-intro.xml"/>
-
-    <xi:include href="concepts-manual-concepts.xml"/>
-
-</book>
-<!--
-vim: expandtab tw=80 ts=4
--->

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

@@ -16,33 +16,29 @@
             The manual groups related procedures into higher-level sections.
             Procedures can consist of high-level steps or low-level steps
             depending on the topic.
-            You can find conceptual information related to a procedure by
-            following appropriate links to the Yocto Project Reference
-            Manual.
         </para>
 
         <para>
             The following list describes what you can get from this manual:
             <itemizedlist>
                 <listitem><para>
-                    <emphasis>Setup Procedures:</emphasis>
+                    Procedures that help you get going with the Yocto Project.
-                    Procedures that show you how to set
+                    For example, procedures that show you how to set up
-                    up a Yocto Project Development environment and how
+                    a build host and work with the Yocto Project
-                    to accomplish the change workflow through logging
+                    source repositories.
-                    defects and submitting changes.
                     </para></listitem>
                 <listitem><para>
-                    <emphasis>Emulation Procedures:</emphasis>
+                    Procedures that show you how to submit changes to the
-                    Procedures that show you how to use the
+                    Yocto Project.
-                    Yocto Project integrated QuickEMUlator (QEMU), which lets
+                    Changes can be improvements, new features, or bug
-                    you simulate running on hardware an image you have built
+                    fixes.
-                    using the OpenEmbedded build system.
                     </para></listitem>
                 <listitem><para>
-                    <emphasis>Common Procedures:</emphasis>
                     Procedures related to "everyday" tasks you perform while
                     developing images and applications using the Yocto
                     Project.
+                    For example, procedures to create a layer, customize an
+                    image, write a new recipe, and so forth.
                     </para></listitem>
             </itemizedlist>
         </para>
@@ -51,7 +47,7 @@
             This manual will not give you the following:
             <itemizedlist>
                 <listitem><para>
-                    <emphasis>Redundant Step-by-step Instructions:</emphasis>
+                    Redundant Step-by-step Instructions:
                     For example, the
                     <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
                     manual contains detailed instructions on how to install an
@@ -59,14 +55,15 @@
                     hardware.
                     </para></listitem>
                 <listitem><para>
-                    <emphasis>Reference or Conceptual Material:</emphasis>
+                    Reference or Conceptual Material:
-                    This type of material resides in an appropriate reference manual.
+                    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>
-                    <emphasis>Detailed Public Information Not Specific to the
+                    Detailed Public Information Not Specific to the
-                    Yocto Project:</emphasis>
+                    Yocto Project:
                     For example, exhaustive information on how to use the
                     Source Control Manager Git is better covered with Internet
                     searches and official Git Documentation than through the
@@ -85,9 +82,10 @@
             comprehension.
             For introductory information on the Yocto Project, see the
             <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>.
-            You can find an introductory to using the Yocto Project by working
+            If you want to build an image with no knowledge of Yocto Project
-            through the
+            as a way of quickly testing it out, see the
-            <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
+            <ulink url='&YOCTO_DOCS_BRIEF_URL;'>Yocto Project Quick Build</ulink>
+            document.
         </para>
 
         <para>

documentation/dev-manual/dev-manual-newbie.xml

@@ -1,990 +0,0 @@
-<!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='dev-manual-newbie'>
-
-<title>The Yocto Project Open Source Development Environment</title>
-
-<section id="usingpoky-changes-collaborate">
-    <title>Setting Up a Team Yocto Project Development Environment</title>
-
-    <para>
-        It might not be immediately clear how you can use the Yocto
-        Project in a team development environment, or scale it for a large
-        team of developers.
-        One of the strengths of the Yocto Project is that it is extremely
-        flexible.
-        Thus, you can adapt it to many different use cases and scenarios.
-        However, these characteristics can cause a struggle if you are trying
-        to create a working setup that scales across a large team.
-    </para>
-
-    <para>
-        To help you understand how to set up this type of environment,
-        this section presents a procedure that gives you the information
-        to learn how to get the results you want.
-        The procedure is high-level and presents some of the project's most
-        successful experiences, practices, solutions, and available
-        technologies that work well.
-        Keep in mind, the procedure here is a starting point.
-        You can build off it and customize it to fit any
-        particular working environment and set of practices.
-        <orderedlist>
-            <listitem><para>
-                <emphasis>Determine Who is Going to be Developing:</emphasis>
-                You need to understand who is going to be doing anything
-                related to the Yocto Project and what their roles would be.
-                Making this determination is essential to completing the
-                steps two and three, which are to get your equipment together
-                and set up your development environment's hardware topology.
-                </para>
-
-                <para>The following roles exist:
-                <itemizedlist>
-                    <listitem><para>
-                        <emphasis>Application Development:</emphasis>
-                        These types of developers do application level work
-                        on top of an existing software stack.
-                        </para></listitem>
-                    <listitem><para>
-                        <emphasis>Core System Development:</emphasis>
-                        These types of developers work on the contents of the
-                        operating system image itself.
-                        </para></listitem>
-                    <listitem><para>
-                        <emphasis>Build Engineer:</emphasis>
-                        This type of developer manages Autobuilders and
-                        releases.
-                        Not all environments need a Build Engineer.
-                        </para></listitem>
-                    <listitem><para>
-                        <emphasis>Test Engineer:</emphasis>
-                        This type of developer creates and manages automated
-                        tests needed to ensure all application and core
-                        system development meets desired quality standards.
-                        </para></listitem>
-                </itemizedlist>
-                </para></listitem>
-            <listitem><para>
-                <emphasis>Gather the Hardware:</emphasis>
-                Based on the size and make-up of the team, get the hardware
-                together.
-                Any development, build, or test engineer should be using
-                a system that is running a supported Linux distribution.
-                Systems, in general, should be high performance (e.g. dual,
-                six-core Xeons with 24 Gbytes of RAM and plenty of disk space).
-                You can help ensure efficiency by having any machines used
-                for testing or that run Autobuilders be as high performance
-                as possible.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>Understand the Hardware Topology of the Environment:</emphasis>
-                Now that you know how many developers and support engineers
-                are required, you can understand the topology of the
-                hardware environment.
-                The following figure shows a moderately sized Yocto Project
-                development environment.
-
-                <para role="writernotes">
-                Need figure.</para>
-
-                </para></listitem>
-            <listitem><para>
-                <emphasis>Use Git as Your Source Control Manager (SCM):</emphasis>
-                Keeping your
-                <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
-                and any software you are developing under the
-                control of an SCM system that is compatible
-                with the OpenEmbedded build system is advisable.
-                Of the SCMs BitBake supports, the
-                Yocto Project team strongly recommends using
-                <ulink url='&YOCTO_DOCS_GS_URL;#git'>Git</ulink>.
-                Git is a distributed system that is easy to backup,
-                allows you to work remotely, and then connects back to the
-                infrastructure.
-                <note>
-                    For information about BitBake, see the
-                    <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
-                </note></para>
-
-                <para>It is relatively easy to set up Git services and create
-                infrastructure like
-                <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>,
-                which is based on server software called
-                <filename>gitolite</filename> with <filename>cgit</filename>
-                being used to generate the web interface that lets you view the
-                repositories.
-                The <filename>gitolite</filename> software identifies users
-                using SSH keys and allows branch-based
-                access controls to repositories that you can control as little
-                or as much as necessary.
-
-                <note>
-                   The setup of these services is beyond the scope of this
-                   manual.
-                   However, sites such as these exist that describe how to
-                   perform setup:
-                   <itemizedlist>
-                       <listitem><para>
-                           <ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>:
-                           Describes how to install <filename>gitolite</filename>
-                           on the server.
-                           </para></listitem>
-                       <listitem><para>
-                           <ulink url='http://sitaramc.github.com/gitolite/master-toc.html'>The <filename>gitolite</filename> master index</ulink>:
-                            All topics for <filename>gitolite</filename>.
-                            </para></listitem>
-                        <listitem><para>
-                            <ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>:
-                            Documentation on how to create interfaces and frontends
-                            for Git.
-                            </para></listitem>
-                    </itemizedlist>
-                </note>
-                </para></listitem>
-            <listitem><para>
-                <emphasis>Set up the Application Development Machines:</emphasis>
-                As mentioned earlier, application developers are creating
-                applications on top of existing software stacks.
-                Following are some best practices for setting up machines
-                that do application development:
-                <itemizedlist>
-                    <listitem><para>
-                        Use a pre-built toolchain that
-                        contains the software stack itself.
-                        Then, develop the application code on top of the
-                        stack.
-                        This method works well for small numbers of relatively
-                        isolated applications.
-                        </para></listitem>
-                    <listitem><para>
-                        When possible, use the Yocto Project
-                        plug-in for the
-                        <trademark class='trade'>Eclipse</trademark> IDE
-                        and SDK development practices.
-                        For more information, see the
-                        "<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>"
-                        manual.
-                        </para></listitem>
-                    <listitem><para>
-                        Keep your cross-development toolchains updated.
-                        You can do this through provisioning either as new
-                        toolchain downloads or as updates through a package
-                        update mechanism using <filename>opkg</filename>
-                        to provide updates to an existing toolchain.
-                        The exact mechanics of how and when to do this are a
-                        question for local policy.
-                        </para></listitem>
-                    <listitem><para>
-                        Use multiple toolchains installed locally
-                        into different locations to allow development across
-                        versions.
-                        </para></listitem>
-                </itemizedlist>
-                </para></listitem>
-            <listitem><para>
-                <emphasis>Set up the Core Development Machines:</emphasis>
-                As mentioned earlier, these types of developers work on the
-                contents of the operating system itself.
-                Following are some best practices for setting up machines
-                used for developing images:
-                <itemizedlist>
-                    <listitem><para>
-                        Have the Yocto Project build system itself available on
-                        the developer workstations so developers can run their own
-                        builds and directly rebuild the software stack.
-                        </para></listitem>
-                    <listitem><para>
-                        Keep the core system unchanged as much as
-                        possible and do your work in layers on top of the
-                        core system.
-                        Doing so gives you a greater level of portability when
-                        upgrading to new versions of the core system or Board
-                        Support Packages (BSPs).
-                        </para></listitem>
-                    <listitem><para>
-                        Share layers amongst the developers of a
-                        particular project and contain the policy configuration
-                        that defines the project.
-                        </para></listitem>
-                </itemizedlist>
-                </para></listitem>
-            <listitem><para>
-                <emphasis>Set up an Autobuilder:</emphasis>
-                Autobuilders are often the core of the development
-                environment.
-                It is here that changes from individual developers are brought
-                together and centrally tested and subsequent decisions about
-                releases can be made.
-                Autobuilders also allow for "continuous integration" style
-                testing of software components and regression identification
-                and tracking.</para>
-
-                <para>See "<ulink url='http://autobuilder.yoctoproject.org'>Yocto Project Autobuilder</ulink>"
-                for more information and links to buildbot.
-                The Yocto Project team has found this implementation
-                works well in this role.
-                A public example of this is the Yocto Project
-                Autobuilders, which we use to test the overall health of the
-                project.</para>
-
-                <para>The features of this system are:
-                <itemizedlist>
-                    <listitem><para>
-                         Highlights when commits break the build.
-                         </para></listitem>
-                    <listitem><para>
-                        Populates an sstate cache from which
-                        developers can pull rather than requiring local
-                        builds.
-                        </para></listitem>
-                    <listitem><para>
-                        Allows commit hook triggers,
-                        which trigger builds when commits are made.
-                        </para></listitem>
-                    <listitem><para>
-                        Allows triggering of automated image booting
-                        and testing under the QuickEMUlator (QEMU).
-                        </para></listitem>
-                    <listitem><para>
-                        Supports incremental build testing and
-                        from-scratch builds.
-                        </para></listitem>
-                    <listitem><para>
-                        Shares output that allows developer
-                        testing and historical regression investigation.
-                        </para></listitem>
-                    <listitem><para>
-                        Creates output that can be used for releases.
-                        </para></listitem>
-                    <listitem><para>
-                        Allows scheduling of builds so that resources
-                        can be used efficiently.
-                        </para></listitem>
-               </itemizedlist>
-               </para></listitem>
-           <listitem><para>
-               <emphasis>Set up Test Machines:</emphasis>
-               Use a small number of shared, high performance systems
-               for testing purposes.
-               Developers can use these systems for wider, more
-               extensive testing while they continue to develop
-               locally using their primary development system.
-               </para></listitem>
-           <listitem><para>
-               <emphasis>Document Policies and Change Flow:</emphasis>
-               The Yocto Project itself uses a hierarchical structure and a
-                pull model.
-                Scripts exist to create and send pull requests
-                (i.e. <filename>create-pull-request</filename> and
-                <filename>send-pull-request</filename>).
-                This model is in line with other open source projects where
-                maintainers are responsible for specific areas of the project
-                and a single maintainer handles the final "top-of-tree" merges.
-                <note>
-                    You can also use a more collective push model.
-                    The <filename>gitolite</filename> software supports both the
-                    push and pull models quite easily.
-                </note></para>
-
-                <para>As with any development environment, it is important
-                to document the policy used as well as any main project
-                guidelines so they are understood by everyone.
-                It is also a good idea to have well structured
-                commit messages, which are usually a part of a project's
-                guidelines.
-                Good commit messages are essential when looking back in time and
-                trying to understand why changes were made.</para>
-
-                <para>If you discover that changes are needed to the core
-                layer of the project, it is worth sharing those with the
-                community as soon as possible.
-                Chances are if you have discovered the need for changes,
-                someone else in the community needs them also.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>Development Environment Summary:</emphasis>
-                Aside from the previous steps, some best practices exist
-                within the Yocto Project development environment.
-                Consider the following:
-                <itemizedlist>
-                    <listitem><para>
-                        Use
-                        <ulink url='&YOCTO_DOCS_GS_URL;#git'>Git</ulink>
-                        as the source control system.
-                        </para></listitem>
-                    <listitem><para>
-                        Maintain your Metadata in layers that make sense
-                        for your situation.
-                        See the "<link linkend='understanding-and-creating-layers'>Understanding
-                        and Creating Layers</link>" section for more information on
-                        layers.
-                        </para></listitem>
-                    <listitem><para>
-                        Separate the project's Metadata and code by using
-                        separate Git repositories.
-                        See the
-                        "<ulink url='&YOCTO_DOCS_GS_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
-                        section for information on these repositories.
-                        See the
-                        "<link linkend='working-with-yocto-project-source-files'>Working With Yocto Project Source Files</link>"
-                        section for information on how to set up local Git
-                        repositories for related upstream Yocto Project
-                        Git repositories.
-                        </para></listitem>
-                    <listitem><para>
-                        Set up the directory for the shared state cache
-                        (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>)
-                        where it makes sense.
-                        For example, set up the sstate cache on a system used
-                        by developers in the same organization and share the
-                        same source directories on their machines.
-                        </para></listitem>
-                    <listitem><para>
-                        Set up an Autobuilder and have it populate the
-                        sstate cache and source directories.
-                        </para></listitem>
-                    <listitem><para>
-                        The Yocto Project community encourages you
-                        to send patches to the project to fix bugs or add features.
-                        If you do submit patches, follow the project commit
-                        guidelines for writing good commit messages.
-                        See the "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
-                        section.
-                        </para></listitem>
-                    <listitem><para>
-                        Send changes to the core sooner than later
-                        as others are likely to run into the same issues.
-                        For some guidance on mailing lists to use, see the list in the
-                        "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
-                        section.
-                        For a description of the available mailing lists, see the
-                        "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
-                        section in the Yocto Project Reference Manual.
-                        </para></listitem>
-                </itemizedlist>
-                </para></listitem>
-        </orderedlist>
-    </para>
-</section>
-
-<section id='submitting-a-defect-against-the-yocto-project'>
-    <title>Submitting a Defect Against the Yocto Project</title>
-
-    <para>
-        Use the Yocto Project implementation of
-        <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink>
-        to submit a defect (bug) against the Yocto Project.
-        For additional information on this implementation of Bugzilla see the
-        "<ulink url='&YOCTO_DOCS_REF_URL;#resources-bugtracker'>Yocto Project Bugzilla</ulink>"
-        section in the Yocto Project Reference Manual.
-        For more detail on any of the following steps, see the Yocto Project
-        <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>Bugzilla wiki page</ulink>.
-    </para>
-
-    <para>
-        Use the following general steps to submit a bug"
-
-        <orderedlist>
-            <listitem><para>
-                Open the Yocto Project implementation of
-                <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink>.
-                </para></listitem>
-            <listitem><para>
-                Click "File a Bug" to enter a new bug.
-                </para></listitem>
-            <listitem><para>
-                Choose the appropriate "Classification", "Product", and
-                "Component" for which the bug was found.
-                Bugs for the Yocto Project fall into one of several
-                classifications, which in turn break down into several
-                products and components.
-                For example, for a bug against the
-                <filename>meta-intel</filename> layer, you would choose
-                "Build System, Metadata &amp; Runtime", "BSPs", and
-                "bsps-meta-intel", respectively.
-                </para></listitem>
-            <listitem><para>
-                Choose the "Version" of the Yocto Project for which you found
-                the bug (e.g. &DISTRO;).
-                </para></listitem>
-            <listitem><para>
-                Determine and select the "Severity" of the bug.
-                The severity indicates how the bug impacted your work.
-                </para></listitem>
-            <listitem><para>
-                Choose the "Hardware" that the bug impacts.
-                </para></listitem>
-            <listitem><para>
-                Choose the "Architecture" that the bug impacts.
-                </para></listitem>
-            <listitem><para>
-                Choose a "Documentation change" item for the bug.
-                Fixing a bug might or might not affect the Yocto Project
-                documentation.
-                If you are unsure of the impact to the documentation, select
-                "Don't Know".
-                </para></listitem>
-            <listitem><para>
-                Provide a brief "Summary" of the bug.
-                Try to limit your summary to just a line or two and be sure
-                to capture the essence of the bug.
-                </para></listitem>
-            <listitem><para>
-                Provide a detailed "Description" of the bug.
-                You should provide as much detail as you can about the context,
-                behavior, output, and so forth that surrounds the bug.
-                You can even attach supporting files for output from logs by
-                using the "Add an attachment" button.
-                </para></listitem>
-            <listitem><para>
-                Click the "Submit Bug" button submit the bug.
-                A new Bugzilla number is assigned to the bug and the defect
-                is logged in the bug tracking system.
-                </para></listitem>
-        </orderedlist>
-        Once you file a bug, the bug is processed by the Yocto Project Bug
-        Triage Team and further details concerning the bug are assigned
-        (e.g. priority and owner).
-        You are the "Submitter" of the bug and any further categorization,
-        progress, or comments on the bug result in Bugzilla sending you an
-        automated email concerning the particular change or progress to the
-        bug.
-    </para>
-</section>
-
-<section id='how-to-submit-a-change'>
-    <title>Submitting a Change to the Yocto Project</title>
-
-    <para>
-        Contributions to the Yocto Project and OpenEmbedded are very welcome.
-        Because the system is extremely configurable and flexible, we recognize
-        that developers will want to extend, configure or optimize it for
-        their specific uses.
-    </para>
-
-    <para>
-        The Yocto Project uses a mailing list and a patch-based workflow
-        that is similar to the Linux kernel but contains important
-        differences.
-        In general, a mailing list exists through which you can submit
-        patches.
-        You should send patches to the appropriate mailing list so that they
-        can be reviewed and merged by the appropriate maintainer.
-        The specific mailing list you need to use depends on the
-        location of the code you are changing.
-        Each component (e.g. layer) should have a
-        <filename>README</filename> file that indicates where to send
-        the changes and which process to follow.
-    </para>
-
-    <para>
-        You can send the patch to the mailing list using whichever approach
-        you feel comfortable with to generate the patch.
-        Once sent, the patch is usually reviewed by the community at large.
-        If somebody has concerns with the patch, they will usually voice
-        their concern over the mailing list.
-        If a patch does not receive any negative reviews, the maintainer of
-        the affected layer typically takes the patch, tests it, and then
-        based on successful testing, merges the patch.
-    </para>
-
-    <para id='figuring-out-the-mailing-list-to-use'>
-        The "poky" repository, which is the Yocto Project's reference build
-        environment, is a hybrid repository that contains several
-        individual pieces (e.g. BitBake, Metadata, documentation,
-        and so forth) built using the combo-layer tool.
-        The upstream location used for submitting changes varies by
-        component:
-        <itemizedlist>
-            <listitem><para>
-                <emphasis>Core Metadata:</emphasis>
-                Send your patch to the
-                <ulink url='http://lists.openembedded.org/mailman/listinfo/openembedded-core'>openembedded-core</ulink>
-                mailing list.  For example, a change to anything under
-                the <filename>meta</filename> or
-                <filename>scripts</filename> directories should be sent
-                to this mailing list.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>BitBake:</emphasis>
-                For changes to BitBake (i.e. anything under the
-                <filename>bitbake</filename> directory), send your patch
-                to the
-                <ulink url='http://lists.openembedded.org/mailman/listinfo/bitbake-devel'>bitbake-devel</ulink>
-                mailing list.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>"meta-*" trees:</emphasis>
-                These trees contain Metadata.
-                Use the
-                <ulink url='https://lists.yoctoproject.org/listinfo/poky'>poky</ulink>
-                mailing list.
-                </para></listitem>
-        </itemizedlist>
-    </para>
-
-    <para>
-        For changes to other layers hosted in the Yocto Project source
-        repositories (i.e. <filename>yoctoproject.org</filename>), tools,
-        and the Yocto Project documentation, use the
-        <ulink url='https://lists.yoctoproject.org/listinfo/yocto'>Yocto Project</ulink>
-        general mailing list.
-        <note>
-            Sometimes a layer's documentation specifies to use a
-            particular mailing list.
-            If so, use that list.
-        </note>
-        For additional recipes that do not fit into the core Metadata, you
-        should determine which layer the recipe should go into and submit
-        the change in the manner recommended by the documentation (e.g.
-        the <filename>README</filename> file) supplied with the layer.
-        If in doubt, please ask on the Yocto general mailing list or on
-        the openembedded-devel mailing list.
-    </para>
-
-    <para>
-        You can also push a change upstream and request a maintainer to
-        pull the change into the component's upstream repository.
-        You do this by pushing to a contribution repository that is upstream.
-        See the
-        "<ulink url='&YOCTO_DOCS_GS_URL;#workflows'>Workflows</ulink>"
-        section in the Getting Started With Yocto Project Manual for additional
-        concepts on working in the Yocto Project development environment.
-    </para>
-
-    <para>
-        Two commonly used testing repositories exist for
-        OpenEmbedded-Core:
-        <itemizedlist>
-            <listitem><para>
-                <emphasis>"ross/mut" branch:</emphasis>
-                The "mut" (master-under-test) tree
-                exists in the <filename>poky-contrib</filename> repository
-                in the
-                <ulink url='&YOCTO_GIT_URL;'>Yocto Project source repositories</ulink>.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>"master-next" branch:</emphasis>
-                This branch is part of the main
-                "poky" repository in the Yocto Project source repositories.
-                </para></listitem>
-        </itemizedlist>
-        Maintainers use these branches to test submissions prior to merging
-        patches.
-        Thus, you can get an idea of the status of a patch based on
-        whether the patch has been merged into one of these branches.
-        <note>
-            This system is imperfect and changes can sometimes get lost in the
-            flow.
-            Asking about the status of a patch or change is reasonable if the
-            change has been idle for a while with no feedback.
-            The Yocto Project does have plans to use
-            <ulink url='https://en.wikipedia.org/wiki/Patchwork_(software)'>Patchwork</ulink>
-            to track the status of patches and also to automatically preview
-            patches.
-        </note>
-    </para>
-
-    <para>
-        The following sections provide procedures for submitting a change.
-    </para>
-
-    <section id='pushing-a-change-upstream'>
-        <title>Using Scripts to Push a Change Upstream and Request a Pull</title>
-
-        <para>
-            Follow this procedure to push a change to an upstream "contrib"
-            Git repository:
-            <note>
-                You can find general Git information on how to push a change
-                upstream in the
-                <ulink url='http://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows'>Git Community Book</ulink>.
-            </note>
-            <orderedlist>
-                <listitem><para>
-                    <emphasis>Make Your Changes Locally:</emphasis>
-                    Make your changes in your local Git repository.
-                    You should make small, controlled, isolated changes.
-                    Keeping changes small and isolated aids review,
-                    makes merging/rebasing easier and keeps the change
-                    history clean should anyone need to refer to it in
-                    future.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Stage Your Changes:</emphasis>
-                    Stage your changes by using the <filename>git add</filename>
-                    command on each file you changed.
-                    </para></listitem>
-                <listitem><para id='making-sure-you-have-correct-commit-information'>
-                    <emphasis>Commit Your Changes:</emphasis>
-                    Commit the change by using the
-                    <filename>git commit</filename> command.
-                    Make sure your commit information follows standards by
-                    following these accepted conventions:
-                    <itemizedlist>
-                        <listitem><para>
-                            Be sure to include a "Signed-off-by:" line in the
-                            same style as required by the Linux kernel.
-                            Adding this line signifies that you, the submitter,
-                            have agreed to the Developer's Certificate of
-                            Origin 1.1 as follows:
-                            <literallayout class='monospaced'>
-     Developer's Certificate of Origin 1.1
-
-     By making a contribution to this project, I certify that:
-
-     (a) The contribution was created in whole or in part by me and I
-         have the right to submit it under the open source license
-         indicated in the file; or
-
-     (b) The contribution is based upon previous work that, to the best
-         of my knowledge, is covered under an appropriate open source
-         license and I have the right under that license to submit that
-         work with modifications, whether created in whole or in part
-         by me, under the same open source license (unless I am
-         permitted to submit under a different license), as indicated
-         in the file; or
-
-     (c) The contribution was provided directly to me by some other
-         person who certified (a), (b) or (c) and I have not modified
-         it.
-
-     (d) I understand and agree that this project and the contribution
-         are public and that a record of the contribution (including all
-         personal information I submit with it, including my sign-off) is
-         maintained indefinitely and may be redistributed consistent with
-         this project or the open source license(s) involved.
-                            </literallayout>
-                            </para></listitem>
-                        <listitem><para>
-                            Provide a single-line summary of the change.
-                            and,
-                            if more explanation is needed, provide more
-                            detail in the body of the commit.
-                            This summary is typically viewable in the
-                            "shortlist" of changes.
-                            Thus, providing something short and descriptive
-                            that gives the reader a summary of the change is
-                            useful when viewing a list of many commits.
-                            You should prefix this short description with the
-                            recipe name (if changing a recipe), or else with
-                            the short form path to the file being changed.
-                            </para></listitem>
-                        <listitem><para>
-                            For the body of the commit message, provide
-                            detailed information that describes what you
-                            changed, why you made the change, and the approach
-                            you used.
-                            It might also be helpful if you mention how you
-                            tested the change.
-                            Provide as much detail as you can in the body of
-                            the commit message.
-                            <note>
-                                You do not need to provide a more detailed
-                                explanation of a change if the change is
-                                minor to the point of the single line
-                                summary providing all the information.
-                            </note>
-                            </para></listitem>
-                        <listitem><para>
-                            If the change addresses a specific bug or issue
-                            that is associated with a bug-tracking ID,
-                            include a reference to that ID in your detailed
-                            description.
-                            For example, the Yocto Project uses a specific
-                            convention for bug references - any commit that
-                            addresses a specific bug should use the following
-                            form for the detailed description.
-                            Be sure to use the actual bug-tracking ID from
-                            Bugzilla for
-                            <replaceable>bug-id</replaceable>:
-                            <literallayout class='monospaced'>
-     Fixes [YOCTO #<replaceable>bug-id</replaceable>]
-
-     <replaceable>detailed description of change</replaceable>
-                            </literallayout>
-                            </para></listitem>
-                    </itemizedlist>
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Push Your Commits to a "Contrib" Upstream:</emphasis>
-                    If you have arranged for permissions to push to an
-                    upstream contrib repository, push the change to that
-                    repository:
-                    <literallayout class='monospaced'>
-     $ git push <replaceable>upstream_remote_repo</replaceable> <replaceable>local_branch_name</replaceable>
-                    </literallayout>
-                    For example, suppose you have permissions to push into the
-                    upstream <filename>meta-intel-contrib</filename>
-                    repository and you are working in a local branch named
-                    <replaceable>your_name</replaceable><filename>/README</filename>.
-                    The following command pushes your local commits to the
-                    <filename>meta-intel-contrib</filename> upstream
-                    repository and puts the commit in a branch named
-                    <replaceable>your_name</replaceable><filename>/README</filename>:
-                    <literallayout class='monospaced'>
-     $ git push meta-intel-contrib <replaceable>your_name</replaceable>/README
-                    </literallayout>
-                    </para></listitem>
-                <listitem><para id='push-determine-who-to-notify'>
-                    <emphasis>Determine Who to Notify:</emphasis>
-                    Determine the maintainer or the mailing list
-                    that you need to notify for the change.</para>
-
-                    <para>Before submitting any change, you need to be sure
-                    who the maintainer is or what mailing list that you need
-                    to notify.
-                    Use either these methods to find out:
-                    <itemizedlist>
-                        <listitem><para>
-                            <emphasis>Maintenance File:</emphasis>
-                            Examine the <filename>maintainers.inc</filename>
-                            file, which is located in the
-                            <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
-                            at
-                            <filename>meta/conf/distro/include</filename>,
-                            to see who is responsible for code.
-                            </para></listitem>
-                        <listitem><para>
-                            <emphasis>Search by File:</emphasis>
-                            Using <ulink url='&YOCTO_DOCS_GS_URL;#git'>Git</ulink>,
-                            you can enter the following command to bring up a
-                            short list of all commits against a specific file:
-                            <literallayout class='monospaced'>
-     git shortlog -- <replaceable>filename</replaceable>
-                            </literallayout>
-                            Just provide the name of the file for which you
-                            are interested.
-                            The information returned is not ordered by history
-                            but does include a list of everyone who has
-                            committed grouped by name.
-                            From the list, you can see who is responsible for
-                            the bulk of the changes against the file.
-                            </para></listitem>
-                        <listitem><para>
-                            <emphasis>Examine the List of Mailing Lists:</emphasis>
-                            For a list of the Yocto Project and related mailing
-                            lists, see the
-                            "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>"
-                            section in the Yocto Project Reference Manual.
-                            </para></listitem>
-                    </itemizedlist>
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Make a Pull Request:</emphasis>
-                    Notify the maintainer or the mailing list that you have
-                    pushed a change by making a pull request.</para>
-
-                    <para>The Yocto Project provides two scripts that
-                    conveniently let you generate and send pull requests to the
-                    Yocto Project.
-                    These scripts are <filename>create-pull-request</filename>
-                    and <filename>send-pull-request</filename>.
-                    You can find these scripts in the
-                    <filename>scripts</filename> directory within the
-                    <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
-                    (e.g. <filename>~/poky/scripts</filename>).
-                    </para>
-
-                    <para>Using these scripts correctly formats the requests
-                    without introducing any whitespace or HTML formatting.
-                    The maintainer that receives your patches either directly
-                    or through the mailing list needs to be able to save and
-                    apply them directly from your emails.
-                    Using these scripts is the preferred method for sending
-                    patches.</para>
-
-                    <para>First, create the pull request.
-                    For example, the following command runs the script,
-                    specifies the upstream repository in the contrib directory
-                    into which you pushed the change, and provides a subject
-                    line in the created patch files:
-                    <literallayout class='monospaced'>
-     $ ~/poky/scripts/create-pull-request -u meta-intel-contrib -s "Updated Manual Section Reference in README"
-                    </literallayout>
-                    Running this script forms
-                    <filename>*.patch</filename> files in a folder named
-                    <filename>pull-</filename><replaceable>PID</replaceable>
-                    in the current directory.
-                    One of the patch files is a cover letter.</para>
-
-                    <para>Before running the
-                    <filename>send-pull-request</filename> script, you must
-                    edit the cover letter patch to insert information about
-                    your change.
-                    After editing the cover letter, send the pull request.
-                    For example, the following command runs the script and
-                    specifies the patch directory and email address.
-                    In this example, the email address is a mailing list:
-                    <literallayout class='monospaced'>
-     $ ~/poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@yoctoproject.org
-                    </literallayout>
-                    You need to follow the prompts as the script is
-                    interactive.
-                    <note>
-                        For help on using these scripts, simply provide the
-                        <filename>-h</filename> argument as follows:
-                        <literallayout class='monospaced'>
-     $ poky/scripts/create-pull-request -h
-     $ poky/scripts/send-pull-request -h
-                        </literallayout>
-                    </note>
-                    </para></listitem>
-            </orderedlist>
-        </para>
-    </section>
-
-    <section id='submitting-a-patch'>
-        <title>Using Email to Submit a Patch</title>
-
-        <para>
-            You can submit patches without using the
-            <filename>create-pull-request</filename> and
-            <filename>send-pull-request</filename> scripts described in the
-            previous section.
-            However, keep in mind, the preferred method is to use the scripts.
-        </para>
-
-        <para>
-            Depending on the components changed, you need to submit the email
-            to a specific mailing list.
-            For some guidance on which mailing list to use, see the
-            <link linkend='figuring-out-the-mailing-list-to-use'>beginning</link>
-            of this section.
-            For a description of all the available mailing lists, see the
-            "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
-            section in the Yocto Project Reference Manual.
-        </para>
-
-        <para>
-            Here is the general procedure on how to submit a patch through
-            email without using the scripts:
-            <orderedlist>
-                <listitem><para>
-                    <emphasis>Make Your Changes Locally:</emphasis>
-                    Make your changes in your local Git repository.
-                    You should make small, controlled, isolated changes.
-                    Keeping changes small and isolated aids review,
-                    makes merging/rebasing easier and keeps the change
-                    history clean should anyone need to refer to it in
-                    future.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Stage Your Changes:</emphasis>
-                    Stage your changes by using the <filename>git add</filename>
-                    command on each file you changed.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Commit Your Changes:</emphasis>
-                    Commit the change by using the
-                    <filename>git commit --signoff</filename> command.
-                    Using the <filename>--signoff</filename> option identifies
-                    you as the person making the change and also satisfies
-                    the Developer's Certificate of Origin (DCO) shown earlier.
-                    </para>
-
-                    <para>When you form a commit, you must follow certain
-                    standards established by the Yocto Project development
-                    team.
-                    See
-                    <link linkend='making-sure-you-have-correct-commit-information'>Step 3</link>
-                    in the previous section for information on how to
-                    provide commit information that meets Yocto Project
-                    commit message standards.
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Format the Commit:</emphasis>
-                    Format the commit into an email message.
-                    To format commits, use the
-                    <filename>git format-patch</filename> command.
-                    When you provide the command, you must include a revision
-                    list or a number of patches as part of the command.
-                    For example, either of these two commands takes your most
-                    recent single commit and formats it as an email message in
-                    the current directory:
-                    <literallayout class='monospaced'>
-     $ git format-patch -1
-                    </literallayout>
-                    or
-                    <literallayout class='monospaced'>
-     $ git format-patch HEAD~
-                    </literallayout></para>
-
-                    <para>After the command is run, the current directory
-                    contains a numbered <filename>.patch</filename> file for
-                    the commit.</para>
-
-                    <para>If you provide several commits as part of the
-                    command, the <filename>git format-patch</filename> command
-                    produces a series of numbered files in the current
-                    directory – one for each commit.
-                    If you have more than one patch, you should also use the
-                    <filename>--cover</filename> option with the command,
-                    which generates a cover letter as the first "patch" in
-                    the series.
-                    You can then edit the cover letter to provide a
-                    description for the series of patches.
-                    For information on the
-                    <filename>git format-patch</filename> command,
-                    see <filename>GIT_FORMAT_PATCH(1)</filename> displayed
-                    using the <filename>man git-format-patch</filename>
-                    command.
-                    <note>
-                        If you are or will be a frequent contributor to the
-                        Yocto Project or to OpenEmbedded, you might consider
-                        requesting a contrib area and the necessary associated
-                        rights.
-                    </note>
-                    </para></listitem>
-                <listitem><para>
-                    <emphasis>Import the Files Into Your Mail Client:</emphasis>
-                    Import the files into your mail client by using the
-                    <filename>git send-email</filename> command.
-                    <note>
-                        In order to use <filename>git send-email</filename>,
-                        you must have the proper Git packages installed on
-                        your host.
-                        For Ubuntu, Debian, and Fedora the package is
-                        <filename>git-email</filename>.
-                    </note></para>
-
-                    <para>The <filename>git send-email</filename> command
-                    sends email by using a local or remote Mail Transport Agent
-                    (MTA) such as <filename>msmtp</filename>,
-                    <filename>sendmail</filename>, or through a direct
-                    <filename>smtp</filename> configuration in your Git
-                    <filename>~/.gitconfig</filename> file.
-                    If you are submitting patches through email only, it is
-                    very important that you submit them without any whitespace
-                    or HTML formatting that either you or your mailer
-                    introduces.
-                    The maintainer that receives your patches needs to be able
-                    to save and apply them directly from your emails.
-                    A good way to verify that what you are sending will be
-                    applicable by the maintainer is to do a dry run and send
-                    them to yourself and then save and apply them as the
-                    maintainer would.</para>
-
-                    <para>The <filename>git send-email</filename> command is
-                    the preferred method for sending your patches using
-                    email since there is no risk of compromising whitespace
-                    in the body of the message, which can occur when you use
-                    your own mail client.
-                    The command also has several options that let you
-                    specify recipients and perform further editing of the
-                    email message.
-                    For information on how to use the
-                    <filename>git send-email</filename> command,
-                    see <filename>GIT-SEND-EMAIL(1)</filename> displayed using
-                    the <filename>man git-send-email</filename> command.
-                    </para></listitem>
-            </orderedlist>
-        </para>
-    </section>
-</section>
-</chapter>
-<!--
-vim: expandtab tw=80 ts=4
--->

documentation/dev-manual/dev-manual-qemu.xml

@@ -343,6 +343,40 @@
         </para>
     </section>
 
+    <section id='qemu-kvm-cpu-compatibility'>
+        <title>QEMU CPU Compatibility Under KVM</title>
+
+        <para>
+            By default, the QEMU build compiles for and targets 64-bit and x86
+            <trademark class='registered'>Intel</trademark> <trademark class='trademark'>Core</trademark>2
+            Duo processors and 32-bit x86
+            <trademark class='registered'>Intel</trademark> <trademark class='registered'>Pentium</trademark>
+            II processors.
+            QEMU builds for and targets these CPU types because they display
+            a broad range of CPU feature compatibility with many commonly
+            used CPUs.
+        </para>
+
+        <para>
+            Despite this broad range of compatibility, the CPUs could support
+            a feature that your host CPU does not support.
+            Although this situation is not a problem when QEMU uses software
+            emulation of the feature, it can be a problem when QEMU is
+            running with KVM enabled.
+            Specifically, software compiled with a certain CPU feature crashes
+            when run on a CPU under KVM that does not support that feature.
+            To work around this problem, you can override QEMU's runtime CPU
+            setting by changing the <filename>QB_CPU_KVM</filename>
+            variable in <filename>qemuboot.conf</filename> in the
+            <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory's</ulink>
+            <filename>deploy/image</filename> directory.
+            This setting specifies a <filename>-cpu</filename> option
+            passed into QEMU in the <filename>runqemu</filename> script.
+            Running <filename>qemu -cpu help</filename> returns a list of
+            available supported CPU types.
+        </para>
+    </section>
+
     <section id='qemu-dev-performance'>
         <title>QEMU Performance</title>
 

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

@@ -4,16 +4,386 @@
 
 <chapter id='dev-manual-start'>
 
-<title>Getting Started with the Yocto Project</title>
+<title>Setting Up to Use the Yocto Project</title>
 
 <para>
     This chapter provides procedures related to getting set up to use the
-    Yocto Project, working with Yocto Project source files, and building
+    Yocto Project.
-    an image.
+    You can learn about creating a team environment that develops using the
+    Yocto Project, how to set up a build host, how to locate Yocto Project
+    source repositories, and how to create local Git repositories.
 </para>
 
+<section id="usingpoky-changes-collaborate">
+    <title>Creating a Team Development Environment</title>
+
+    <para>
+        It might not be immediately clear how you can use the Yocto
+        Project in a team development environment, or scale it for a large
+        team of developers.
+        One of the strengths of the Yocto Project is that it is extremely
+        flexible.
+        Thus, you can adapt it to many different use cases and scenarios.
+        However, these characteristics can cause a struggle if you are trying
+        to create a working setup that scales across a large team.
+    </para>
+
+    <para>
+        To help you understand how to set up this type of environment,
+        this section presents a procedure that gives you the information
+        to learn how to get the results you want.
+        The procedure is high-level and presents some of the project's most
+        successful experiences, practices, solutions, and available
+        technologies that work well.
+        Keep in mind, the procedure here is a starting point.
+        You can build off it and customize it to fit any
+        particular working environment and set of practices.
+        <orderedlist>
+            <listitem><para>
+                <emphasis>Determine Who is Going to be Developing:</emphasis>
+                You need to understand who is going to be doing anything
+                related to the Yocto Project and what their roles would be.
+                Making this determination is essential to completing the
+                steps two and three, which are to get your equipment together
+                and set up your development environment's hardware topology.
+                </para>
+
+                <para>The following roles exist:
+                <itemizedlist>
+                    <listitem><para>
+                        <emphasis>Application Development:</emphasis>
+                        These types of developers do application level work
+                        on top of an existing software stack.
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Core System Development:</emphasis>
+                        These types of developers work on the contents of the
+                        operating system image itself.
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Build Engineer:</emphasis>
+                        This type of developer manages Autobuilders and
+                        releases.
+                        Not all environments need a Build Engineer.
+                        </para></listitem>
+                    <listitem><para>
+                        <emphasis>Test Engineer:</emphasis>
+                        This type of developer creates and manages automated
+                        tests needed to ensure all application and core
+                        system development meets desired quality standards.
+                        </para></listitem>
+                </itemizedlist>
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Gather the Hardware:</emphasis>
+                Based on the size and make-up of the team, get the hardware
+                together.
+                Any development, build, or test engineer should be using
+                a system that is running a supported Linux distribution.
+                Systems, in general, should be high performance (e.g. dual,
+                six-core Xeons with 24 Gbytes of RAM and plenty of disk space).
+                You can help ensure efficiency by having any machines used
+                for testing or that run Autobuilders be as high performance
+                as possible.
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Understand the Hardware Topology of the Environment:</emphasis>
+                Once you understand the hardware involved and the make-up
+                of the team, you can understand the hardware topology of the
+                development environment.
+                You can get a visual idea of the machines and their roles
+                across the development environment.
+
+<!--
+                The following figure shows a moderately sized Yocto Project
+                development environment.
+
+                <para role="writernotes">
+                Need figure.</para>
+-->
+
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Use Git as Your Source Control Manager (SCM):</emphasis>
+                Keeping your
+                <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
+                and any software you are developing under the
+                control of an SCM system that is compatible
+                with the OpenEmbedded build system is advisable.
+                Of the SCMs BitBake supports, the
+                Yocto Project team strongly recommends using
+                <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>.
+                Git is a distributed system that is easy to backup,
+                allows you to work remotely, and then connects back to the
+                infrastructure.
+                <note>
+                    For information about BitBake, see the
+                    <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
+                </note></para>
+
+                <para>It is relatively easy to set up Git services and create
+                infrastructure like
+                <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>,
+                which is based on server software called
+                <filename>gitolite</filename> with <filename>cgit</filename>
+                being used to generate the web interface that lets you view the
+                repositories.
+                The <filename>gitolite</filename> software identifies users
+                using SSH keys and allows branch-based
+                access controls to repositories that you can control as little
+                or as much as necessary.
+
+                <note>
+                   The setup of these services is beyond the scope of this
+                   manual.
+                   However, sites such as these exist that describe how to
+                   perform setup:
+                   <itemizedlist>
+                       <listitem><para>
+                           <ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>:
+                           Describes how to install <filename>gitolite</filename>
+                           on the server.
+                           </para></listitem>
+                       <listitem><para>
+                           <ulink url='http://gitolite.com'>Gitolite</ulink>:
+                            Information for <filename>gitolite</filename>.
+                            </para></listitem>
+                        <listitem><para>
+                            <ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>:
+                            Documentation on how to create interfaces and frontends
+                            for Git.
+                            </para></listitem>
+                    </itemizedlist>
+                </note>
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Set up the Application Development Machines:</emphasis>
+                As mentioned earlier, application developers are creating
+                applications on top of existing software stacks.
+                Following are some best practices for setting up machines
+                that do application development:
+                <itemizedlist>
+                    <listitem><para>
+                        Use a pre-built toolchain that
+                        contains the software stack itself.
+                        Then, develop the application code on top of the
+                        stack.
+                        This method works well for small numbers of relatively
+                        isolated applications.
+                        </para></listitem>
+                    <listitem><para>
+                        When possible, use the Yocto Project
+                        plug-in for the
+                        <trademark class='trade'>Eclipse</trademark> IDE
+                        and SDK development practices.
+                        For more information, see the
+                        "<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>"
+                        manual.
+                        </para></listitem>
+                    <listitem><para>
+                        Keep your cross-development toolchains updated.
+                        You can do this through provisioning either as new
+                        toolchain downloads or as updates through a package
+                        update mechanism using <filename>opkg</filename>
+                        to provide updates to an existing toolchain.
+                        The exact mechanics of how and when to do this are a
+                        question for local policy.
+                        </para></listitem>
+                    <listitem><para>
+                        Use multiple toolchains installed locally
+                        into different locations to allow development across
+                        versions.
+                        </para></listitem>
+                </itemizedlist>
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Set up the Core Development Machines:</emphasis>
+                As mentioned earlier, these types of developers work on the
+                contents of the operating system itself.
+                Following are some best practices for setting up machines
+                used for developing images:
+                <itemizedlist>
+                    <listitem><para>
+                        Have the Yocto Project build system itself available on
+                        the developer workstations so developers can run their own
+                        builds and directly rebuild the software stack.
+                        </para></listitem>
+                    <listitem><para>
+                        Keep the core system unchanged as much as
+                        possible and do your work in layers on top of the
+                        core system.
+                        Doing so gives you a greater level of portability when
+                        upgrading to new versions of the core system or Board
+                        Support Packages (BSPs).
+                        </para></listitem>
+                    <listitem><para>
+                        Share layers amongst the developers of a
+                        particular project and contain the policy configuration
+                        that defines the project.
+                        </para></listitem>
+                </itemizedlist>
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Set up an Autobuilder:</emphasis>
+                Autobuilders are often the core of the development
+                environment.
+                It is here that changes from individual developers are brought
+                together and centrally tested and subsequent decisions about
+                releases can be made.
+                Autobuilders also allow for "continuous integration" style
+                testing of software components and regression identification
+                and tracking.</para>
+
+                <para>See "<ulink url='http://autobuilder.yoctoproject.org'>Yocto Project Autobuilder</ulink>"
+                for more information and links to buildbot.
+                The Yocto Project team has found this implementation
+                works well in this role.
+                A public example of this is the Yocto Project
+                Autobuilders, which we use to test the overall health of the
+                project.</para>
+
+                <para>The features of this system are:
+                <itemizedlist>
+                    <listitem><para>
+                         Highlights when commits break the build.
+                         </para></listitem>
+                    <listitem><para>
+                        Populates an sstate cache from which
+                        developers can pull rather than requiring local
+                        builds.
+                        </para></listitem>
+                    <listitem><para>
+                        Allows commit hook triggers,
+                        which trigger builds when commits are made.
+                        </para></listitem>
+                    <listitem><para>
+                        Allows triggering of automated image booting
+                        and testing under the QuickEMUlator (QEMU).
+                        </para></listitem>
+                    <listitem><para>
+                        Supports incremental build testing and
+                        from-scratch builds.
+                        </para></listitem>
+                    <listitem><para>
+                        Shares output that allows developer
+                        testing and historical regression investigation.
+                        </para></listitem>
+                    <listitem><para>
+                        Creates output that can be used for releases.
+                        </para></listitem>
+                    <listitem><para>
+                        Allows scheduling of builds so that resources
+                        can be used efficiently.
+                        </para></listitem>
+               </itemizedlist>
+               </para></listitem>
+           <listitem><para>
+               <emphasis>Set up Test Machines:</emphasis>
+               Use a small number of shared, high performance systems
+               for testing purposes.
+               Developers can use these systems for wider, more
+               extensive testing while they continue to develop
+               locally using their primary development system.
+               </para></listitem>
+           <listitem><para>
+               <emphasis>Document Policies and Change Flow:</emphasis>
+               The Yocto Project itself uses a hierarchical structure and a
+                pull model.
+                Scripts exist to create and send pull requests
+                (i.e. <filename>create-pull-request</filename> and
+                <filename>send-pull-request</filename>).
+                This model is in line with other open source projects where
+                maintainers are responsible for specific areas of the project
+                and a single maintainer handles the final "top-of-tree" merges.
+                <note>
+                    You can also use a more collective push model.
+                    The <filename>gitolite</filename> software supports both the
+                    push and pull models quite easily.
+                </note></para>
+
+                <para>As with any development environment, it is important
+                to document the policy used as well as any main project
+                guidelines so they are understood by everyone.
+                It is also a good idea to have well structured
+                commit messages, which are usually a part of a project's
+                guidelines.
+                Good commit messages are essential when looking back in time and
+                trying to understand why changes were made.</para>
+
+                <para>If you discover that changes are needed to the core
+                layer of the project, it is worth sharing those with the
+                community as soon as possible.
+                Chances are if you have discovered the need for changes,
+                someone else in the community needs them also.
+                </para></listitem>
+            <listitem><para>
+                <emphasis>Development Environment Summary:</emphasis>
+                Aside from the previous steps, some best practices exist
+                within the Yocto Project development environment.
+                Consider the following:
+                <itemizedlist>
+                    <listitem><para>
+                        Use
+                        <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>
+                        as the source control system.
+                        </para></listitem>
+                    <listitem><para>
+                        Maintain your Metadata in layers that make sense
+                        for your situation.
+                        See the "<link linkend='understanding-and-creating-layers'>Understanding
+                        and Creating Layers</link>" section for more information on
+                        layers.
+                        </para></listitem>
+                    <listitem><para>
+                        Separate the project's Metadata and code by using
+                        separate Git repositories.
+                        See the
+                        "<ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
+                        section for information on these repositories.
+                        See the
+                        "<link linkend='locating-yocto-project-source-files'>Locating Yocto Project Source Files</link>"
+                        section for information on how to set up local Git
+                        repositories for related upstream Yocto Project
+                        Git repositories.
+                        </para></listitem>
+                    <listitem><para>
+                        Set up the directory for the shared state cache
+                        (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>)
+                        where it makes sense.
+                        For example, set up the sstate cache on a system used
+                        by developers in the same organization and share the
+                        same source directories on their machines.
+                        </para></listitem>
+                    <listitem><para>
+                        Set up an Autobuilder and have it populate the
+                        sstate cache and source directories.
+                        </para></listitem>
+                    <listitem><para>
+                        The Yocto Project community encourages you
+                        to send patches to the project to fix bugs or add features.
+                        If you do submit patches, follow the project commit
+                        guidelines for writing good commit messages.
+                        See the "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
+                        section.
+                        </para></listitem>
+                    <listitem><para>
+                        Send changes to the core sooner than later
+                        as others are likely to run into the same issues.
+                        For some guidance on mailing lists to use, see the list in the
+                        "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
+                        section.
+                        For a description of the available mailing lists, see the
+                        "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
+                        section in the Yocto Project Reference Manual.
+                        </para></listitem>
+                </itemizedlist>
+                </para></listitem>
+        </orderedlist>
+    </para>
+</section>
+
 <section id='setting-up-the-development-host-to-use-the-yocto-project'>
-    <title>Setting Up the Development Host to Use the Yocto Project</title>
+    <title>Preparing the Build Host</title>
 
     <para>
         This section provides procedures to set up your development host to
@@ -175,7 +545,7 @@
                     site.
                     </para></listitem>
                 <listitem><para>
-                    <emphasis>Go the Install Site for Your Platform:</emphasis>
+                    <emphasis>Go to the Install Site for Your Platform:</emphasis>
                     Click the link for the Docker edition associated with
                     your development host machine's native software.
                     For example, if your machine is running Microsoft
@@ -211,8 +581,8 @@
                     the type of the software you need to install.
                     </para></listitem>
                 <listitem><para>
-                    <emphasis>Optionally Orient Yourself With Dockers:</emphasis>
+                    <emphasis>Optionally Orient Yourself With Docker:</emphasis>
-                    If you are unfamiliar with Dockers and the container
+                    If you are unfamiliar with Docker and the container
                     concept, you can learn more here -
                     <ulink url='https://docs.docker.com/get-started/'></ulink>.
                     You should be able to launch Docker or the Docker Toolbox
@@ -248,25 +618,25 @@
     </section>
 </section>
 
-<section id='working-with-yocto-project-source-files'>
+<section id='locating-yocto-project-source-files'>
-    <title>Working With Yocto Project Source Files</title>
+    <title>Locating Yocto Project Source Files</title>
 
     <para>
-        This section contains procedures related to locating and securing
+        This section contains procedures related to locating Yocto Project
-        Yocto Project files.
+        files.
         You establish and use these local files to work on projects.
         <note><title>Notes</title>
             <itemizedlist>
                 <listitem><para>
                     For concepts and introductory information about Git as it
                     is used in the Yocto Project, see the
-                    "<ulink url='&YOCTO_DOCS_GS_URL;#git'>Git</ulink>"
+                    "<ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>"
-                    section in the Getting Started With Yocto Project Manual.
+                    section in the Yocto Project Overview and Concepts Manual.
                     </para></listitem>
                 <listitem><para>
                     For concepts on Yocto Project source repositories, see the
-                    "<ulink url='&YOCTO_DOCS_GS_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
+                    "<ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>"
-                    section in the Getting Started With Yocto Project Manual."
+                    section in the Yocto Project Overview and Concepts Manual."
                     </para></listitem>
             </itemizedlist>
         </note>
@@ -277,11 +647,11 @@
 
         <para>
             Working from a copy of the upstream Yocto Project
-            <ulink url='&YOCTO_DOCS_GS_URL;#source-repositories'>Source Repositories</ulink>
+            <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
             is the preferred method for obtaining and using a Yocto Project
             release.
             You can view the Yocto Project Source Repositories at
-            <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
+            <ulink url='&YOCTO_GIT_URL;'></ulink>.
             In particular, you can find the
             <filename>poky</filename> repository at
             <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/'></ulink>.
@@ -306,7 +676,7 @@
                 <listitem><para>
                     <emphasis>Find the URL Used to Clone the Repository:</emphasis>
                     At the bottom of the page, note the URL used to
-                    <ulink url='&YOCTO_DOCS_GS_URL;#git-commands-clone'>clone</ulink>
+                    <ulink url='&YOCTO_DOCS_OM_URL;#git-commands-clone'>clone</ulink>
                     that repository (e.g.
                     <filename>&YOCTO_GIT_URL;/poky</filename>).
                     <note>
@@ -459,36 +829,40 @@
             </orderedlist>
         </para>
     </section>
+</section>
+
+<section id='cloning-and-checking-out-branchs'>
+    <title>Cloning and Checking Out Branches</title>
+
+    <para>
+        To use the Yocto Project, you need a release of the Yocto Project
+        locally installed on your development system.
+        The locally installed set of files is referred to as the
+        <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+        in the Yocto Project documentation.
+    </para>
+
+    <para>
+        You create your Source Directory by using
+        <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink> to clone a local
+        copy of the upstream <filename>poky</filename> repository.
+        <note><title>Tip</title>
+            The preferred method of getting the Yocto Project Source
+            Directory set up is to clone the repository.
+        </note>
+        Working from a copy of the upstream repository allows you
+        to contribute back into the Yocto Project or simply work with
+        the latest software on a development branch.
+        Because Git maintains and creates an upstream repository with
+        a complete history of changes and you are working with a local
+        clone of that repository, you have access to all the Yocto
+        Project development branches and tag names used in the upstream
+        repository.
+    </para>
 
     <section id='cloning-the-poky-repository'>
         <title>Cloning the <filename>poky</filename> Repository</title>
 
-        <para>
-            To use the Yocto Project, you need a release of the Yocto Project
-            locally installed on your development system.
-            The locally installed set of files is referred to as the
-            <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
-            in the Yocto Project documentation.
-        </para>
-
-        <para>
-            You create your Source Directory by using
-            <ulink url='&YOCTO_DOCS_GS_URL;#git'>Git</ulink> to clone a local
-            copy of the upstream <filename>poky</filename> repository.
-            <note><title>Tip</title>
-                The preferred method of getting the Yocto Project Source
-                Directory set up is to clone the repository.
-            </note>
-            Working from a copy of the upstream repository allows you
-            to contribute back into the Yocto Project or simply work with
-            the latest software on a development branch.
-            Because Git maintains and creates an upstream repository with
-            a complete history of changes and you are working with a local
-            clone of that repository, you have access to all the Yocto
-            Project development branches and tag names used in the upstream
-            repository.
-        </para>
-
         <para>
             Follow these steps to create a local version of the
             upstream
@@ -507,11 +881,11 @@
                     <literallayout class='monospaced'>
      $ git clone git://git.yoctoproject.org/poky
      Cloning into 'poky'...
-     remote: Counting objects: 367178, done.
+     remote: Counting objects: 431956, done.
-     remote: Compressing objects: 100% (88161/88161), done.
+     remote: Compressing objects: 100% (101918/101918), done.
-     remote: Total 367178 (delta 272761), reused 366942 (delta 272525)
+     remote: Total 431956 (delta 322982), reused 431910 (delta 322936)
-     Receiving objects: 100% (367178/367178), 133.26 MiB | 6.40 MiB/s, done.
+     Receiving objects: 100% (431956/431956), 153.76 MiB | 6.86 MiB/s, done.
-     Resolving deltas: 100% (272761/272761), done.
+     Resolving deltas: 100% (322982/322982), done.
      Checking connectivity... done.
                     </literallayout>
                     Unless you specify a specific development branch or
@@ -523,8 +897,8 @@
                     branch based on a tag name, see the
                     "<link linkend='checking-out-by-branch-in-poky'>Checking Out By Branch in Poky</link>"
                     and
-                    <link linkend='checkout-out-by-tag-in-poky'>Checking Out By Tag in Poky</link>",
+                    <link linkend='checkout-out-by-tag-in-poky'>Checking Out By Tag in Poky</link>"
-                    respectively.</para>
+                    sections, respectively.</para>
 
                     <para>Once the repository is created, you can change to
                     that directory and check its status.
@@ -589,13 +963,12 @@
            .
            .
            .
-       remotes/origin/master-next
-       remotes/origin/master-next2
-       remotes/origin/morty
-       remotes/origin/pinky
-       remotes/origin/purple
-       remotes/origin/pyro
        remotes/origin/rocko
+       remotes/origin/rocko-next
+       remotes/origin/sumo
+       remotes/origin/sumo-next
+       remotes/origin/thud
+       remotes/origin/thud-next
                     </literallayout>
                     </para></listitem>
                 <listitem><para>
@@ -674,11 +1047,10 @@
         .
         .
         .
-     yocto-2.2
+     yocto-2.5.2
-     yocto-2.2.1
+     yocto-2.5.3
-     yocto-2.3
+     yocto-2.6
-     yocto-2.3.1
+     yocto-2.6.1
-     yocto-2.4
      yocto_1.5_M5.rc8
                     </literallayout>
                     </para></listitem>
@@ -706,306 +1078,6 @@
     </section>
 </section>
 
-<section id='dev-building-an-image'>
-    <title>Building an Image</title>
-
-    <para>
-        In the development environment, you need to build an image whenever
-        you change hardware support, add or change system libraries, or add
-        or change services that have dependencies.
-        Several methods exist that allow you to build an image within the
-        Yocto Project.
-        This section shows you how to build an image using BitBake from a
-        Linux host.
-        <note><title>Notes</title>
-            <itemizedlist>
-                <listitem><para>
-                    For information on how to build an image using
-                    <ulink url='&YOCTO_DOCS_REF_URL;#toaster-term'>Toaster</ulink>,
-                    see the
-                    <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster Manual</ulink>.
-                    </para></listitem>
-                <listitem><para>
-                    For information on how to use
-                    <filename>devtool</filename> to build images, see the
-                    "<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'>Using <filename>devtool</filename> in Your SDK Workflow</ulink>"
-                    section in the Yocto Project Application Development and
-                    the Extensible Software Development Kit (eSDK) manual.
-                    </para></listitem>
-                <listitem><para>
-                    For a practical example on how to build an image using the
-                    OpenEmbedded build system, see the
-                    "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
-                    section of the Yocto Project Quick Start.
-                    </para></listitem>
-            </itemizedlist>
-        </note>
-    </para>
-
-    <para>
-        The build process creates an entire Linux distribution from source
-        and places it in your
-        <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
-        under <filename>tmp/deploy/images</filename>.
-        For detailed information on the build process using BitBake, see the
-        "<ulink url='&YOCTO_DOCS_CM_URL;#images-dev-environment'>Images</ulink>"
-        section in the Yocto Project Concepts Manual.
-    </para>
-
-    <para>
-        The following figure and list overviews the build process:
-        <imagedata fileref="figures/bitbake-build-flow.png" width="7in" depth="4in" align="center" scalefit="1" />
-        <orderedlist>
-            <listitem><para>
-                <emphasis>Set up Your Host Development System to Support
-                Development Using the Yocto Project</emphasis>:
-                See the
-                "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
-                section in the Yocto Project Quick Start for options on how
-                to get a build host ready to use the Yocto Project.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>Initialize the Build Environment:</emphasis>
-                Initialize the build environment by sourcing the build
-                environment script (i.e.
-                <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>):
-                <literallayout class='monospaced'>
-     $ source &OE_INIT_FILE; [<replaceable>build_dir</replaceable>]
-                </literallayout></para>
-
-                <para>When you use the initialization script, the
-                OpenEmbedded build system uses <filename>build</filename> as
-                the default Build Directory in your current work directory.
-                You can use a <replaceable>build_dir</replaceable> argument
-                with the script to specify a different build directory.
-                <note><title>Tip</title>
-                    A common practice is to use a different Build Directory for
-                    different targets.
-                    For example, <filename>~/build/x86</filename> for a
-                    <filename>qemux86</filename> target, and
-                    <filename>~/build/arm</filename> for a
-                    <filename>qemuarm</filename> target.
-                </note>
-                </para></listitem>
-            <listitem><para>
-                <emphasis>Make Sure Your <filename>local.conf</filename>
-                File is Correct:</emphasis>
-                Ensure the <filename>conf/local.conf</filename> configuration
-                file, which is found in the Build Directory,
-                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 packaging format used during the build
-                (<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>),
-                and a centralized tarball download directory through the
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink> variable.
-                </para></listitem>
-            <listitem><para>
-                <emphasis>Build the Image:</emphasis>
-                Build the image using the <filename>bitbake</filename> command:
-                <literallayout class='monospaced'>
-     $ bitbake <replaceable>target</replaceable>
-                </literallayout>
-                <note>
-                    For information on BitBake, see the
-                    <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
-                </note>
-                The <replaceable>target</replaceable> is the name of the
-                recipe you want to build.
-                Common targets are the images in
-                <filename>meta/recipes-core/images</filename>,
-                <filename>meta/recipes-sato/images</filename>, etc. all found
-                in the
-                <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
-                Or, the target can be the name of a recipe for a specific
-                piece of software such as BusyBox.
-                For more details about the images the OpenEmbedded build
-                system supports, see the
-                "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
-                chapter in the Yocto Project Reference Manual.</para>
-
-                <para>As an example, the following command builds the
-                <filename>core-image-minimal</filename> image:
-                <literallayout class='monospaced'>
-     $ bitbake core-image-minimal
-                </literallayout>
-                Once an image has been built, it often needs to be installed.
-                The images and kernels built by the OpenEmbedded build system
-                are placed in the Build Directory in
-                <filename class="directory">tmp/deploy/images</filename>.
-                For information on how to run pre-built images such as
-                <filename>qemux86</filename> and <filename>qemuarm</filename>,
-                see the
-                <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
-                manual.
-                For information about how to install these images, see the
-                documentation for your particular board or machine.
-                </para></listitem>
-        </orderedlist>
-    </para>
-</section>
-
-<section id='speeding-up-the-build'>
-    <title>Speeding Up the Build</title>
-
-    <para>
-        Build time can be an issue.
-        By default, the build system uses simple controls to try and maximize
-        build efficiency.
-        In general, the default settings for all the following variables
-        result in the most efficient build times when dealing with single
-        socket systems (i.e. a single CPU).
-        If you have multiple CPUs, you might try increasing the default
-        values to gain more speed.
-        See the descriptions in the glossary for each variable for more
-        information:
-        <itemizedlist>
-            <listitem><para>
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename>:</ulink>
-                The maximum number of threads BitBake simultaneously executes.
-                </para></listitem>
-            <listitem><para>
-                <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename>:</ulink>
-                The number of threads BitBake uses during parsing.
-                </para></listitem>
-            <listitem><para>
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename>:</ulink>
-                Extra options passed to the <filename>make</filename> command
-                during the
-                <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>
-                task in order to specify parallel compilation on the
-                local build host.
-                </para></listitem>
-            <listitem><para>
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename>:</ulink>
-                Extra options passed to the <filename>make</filename> command
-                during the
-                <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
-                task in order to specify parallel installation on the
-                local build host.
-                </para></listitem>
-        </itemizedlist>
-        As mentioned, these variables all scale to the number of processor
-        cores available on the build system.
-        For single socket systems, this auto-scaling ensures that the build
-        system fundamentally takes advantage of potential parallel operations
-        during the build based on the build machine's capabilities.
-    </para>
-
-    <para>
-        Following are additional factors that can affect build speed:
-        <itemizedlist>
-            <listitem><para>
-                File system type:
-                The file system type that the build is being performed on can
-                also influence performance.
-                Using <filename>ext4</filename> is recommended as compared
-                to <filename>ext2</filename> and <filename>ext3</filename>
-                due to <filename>ext4</filename> improved features
-                such as extents.
-                </para></listitem>
-            <listitem><para>
-                Disabling the updating of access time using
-                <filename>noatime</filename>:
-                The <filename>noatime</filename> mount option prevents the
-                build system from updating file and directory access times.
-                </para></listitem>
-            <listitem><para>
-                Setting a longer commit:
-                Using the "commit=" mount option increases the interval
-                in seconds between disk cache writes.
-                Changing this interval from the five second default to
-                something longer increases the risk of data loss but decreases
-                the need to write to the disk, thus increasing the build
-                performance.
-                </para></listitem>
-            <listitem><para>
-                Choosing the packaging backend:
-                Of the available packaging backends, IPK is the fastest.
-                Additionally, selecting a singular packaging backend also
-                helps.
-                </para></listitem>
-            <listitem><para>
-                Using <filename>tmpfs</filename> for
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
-                as a temporary file system:
-                While this can help speed up the build, the benefits are
-                limited due to the compiler using
-                <filename>-pipe</filename>.
-                The build system goes to some lengths to avoid
-                <filename>sync()</filename> calls into the
-                file system on the principle that if there was a significant
-                failure, the
-                <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
-                contents could easily be rebuilt.
-                </para></listitem>
-            <listitem><para>
-                Inheriting the
-                <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-rm-work'><filename>rm_work</filename></ulink>
-                class:
-                Inheriting this class has shown to speed up builds due to
-                significantly lower amounts of data stored in the data
-                cache as well as on disk.
-                Inheriting this class also makes cleanup of
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
-                faster, at the expense of being easily able to dive into the
-                source code.
-                File system maintainers have recommended that the fastest way
-                to clean up large numbers of files is to reformat partitions
-                rather than delete files due to the linear nature of
-                partitions.
-                This, of course, assumes you structure the disk partitions and
-                file systems in a way that this is practical.
-                </para></listitem>
-        </itemizedlist>
-        Aside from the previous list, you should keep some trade offs in
-        mind that can help you speed up the build:
-        <itemizedlist>
-            <listitem><para>
-                Remove items from
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
-                that you might not need.
-                </para></listitem>
-            <listitem><para>
-                Exclude debug symbols and other debug information:
-                If you do not need these symbols and other debug information,
-                disabling the <filename>*-dbg</filename> package generation
-                can speed up the build.
-                You can disable this generation by setting the
-                <ulink url='&YOCTO_DOCS_REF_URL;#var-INHIBIT_PACKAGE_DEBUG_SPLIT'><filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename></ulink>
-                variable to "1".
-                </para></listitem>
-            <listitem><para>
-                Disable static library generation for recipes derived from
-                <filename>autoconf</filename> or <filename>libtool</filename>:
-                Following is an example showing how to disable static
-                libraries and still provide an override to handle exceptions:
-                <literallayout class='monospaced'>
-     STATICLIBCONF = "--disable-static"
-     STATICLIBCONF_sqlite3-native = ""
-     EXTRA_OECONF += "${STATICLIBCONF}"
-                </literallayout>
-                <note><title>Notes</title>
-                    <itemizedlist>
-                        <listitem><para>
-                            Some recipes need static libraries in order to work
-                            correctly (e.g. <filename>pseudo-native</filename>
-                            needs <filename>sqlite3-native</filename>).
-                            Overrides, as in the previous example, account for
-                            these kinds of exceptions.
-                            </para></listitem>
-                        <listitem><para>
-                            Some packages have packaging code that assumes the
-                            presence of the static libraries.
-                            If so, you might need to exclude them as well.
-                            </para></listitem>
-                    </itemizedlist>
-                </note>
-            </para></listitem>
-        </itemizedlist>
-    </para>
-</section>
 </chapter>
 <!--
 vim: expandtab tw=80 ts=4

documentation/dev-manual/dev-manual.xml

@@ -103,9 +103,24 @@
             </revision>
             <revision>
                 <revnumber>2.5</revnumber>
-                <date>April 2018</date>
+                <date>May 2018</date>
                 <revremark>Released with the Yocto Project 2.5 Release.</revremark>
             </revision>
+            <revision>
+                <revnumber>2.5.1</revnumber>
+                <date>September 2018</date>
+                <revremark>The initial document released with the Yocto Project 2.5.1 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>2.5.2</revnumber>
+                <date>January 2019</date>
+                <revremark>The initial document released with the Yocto Project 2.5.2 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>2.5.3</revnumber>
+                <date>&REL_MONTH_YEAR;</date>
+                <revremark>The initial document released with the Yocto Project 2.5.3 Release.</revremark>
+            </revision>
         </revhistory>
 
     <copyright>
@@ -128,24 +143,36 @@
                        is for the &YOCTO_DOC_VERSION; release of the
                        Yocto Project.
                        To be sure you have the latest version of the manual
-                       for this release, use the manual from the
+                       for this release, go to the
-                       <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>.
-                       </para></listitem>
-                   <listitem><para>
-                       For manuals associated with other releases of the Yocto
-                       Project, go to the
                        <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
-                       and use the drop-down "Active Releases" button
+                       and select the manual from that site.
-                       and choose the manual associated with the desired
+                       Manuals from the site are more up-to-date than manuals
-                       Yocto Project.
+                       derived from the Yocto Project released TAR files.
                        </para></listitem>
                    <listitem><para>
-                        To report any inaccuracies or problems with this
+                       If you located this manual through a web search, the
-                        manual, send an email to the Yocto Project
+                       version of the manual might not be the one you want
-                        discussion group at
+                       (e.g. the search might have returned a manual much
-                        <filename>yocto@yoctoproject.com</filename> or log into
+                       older than the Yocto Project version with which you
-                        the freenode <filename>#yocto</filename> channel.
+                       are working).
-                        </para></listitem>
+                       You can see all Yocto Project major releases by
+                       visiting the
+                       <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
+                       page.
+                       If you need a version of this manual for a different
+                       Yocto Project release, visit the
+                       <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
+                       and select the manual set by using the
+                       "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
+                       pull-down menus.
+                       </para></listitem>
+                   <listitem><para>
+                       To report any inaccuracies or problems with this
+                       manual, send an email to the Yocto Project
+                       discussion group at
+                       <filename>yocto@yoctoproject.com</filename> or log into
+                       the freenode <filename>#yocto</filename> channel.
+                       </para></listitem>
                </itemizedlist>
            </note>
     </legalnotice>
@@ -156,8 +183,6 @@
 
     <xi:include href="dev-manual-start.xml"/>
 
-    <xi:include href="dev-manual-newbie.xml"/>
-
     <xi:include href="dev-manual-common-tasks.xml"/>
 
     <xi:include href="dev-manual-qemu.xml"/>

documentation/getting-started/getting-started-style.css

@@ -1,988 +0,0 @@
-/*
-   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/getting-started-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;*/
-}
-
-/* This style defines how the permalink character
-   appears by itself and when hovered over with
-   the mouse. */
-
-[alt='Permalink'] { color: #eee; }
-[alt='Permalink']:hover { color: black; }
-
-
-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;
-}
-
-.writernotes {
-  color: red;
-}
-
-
-  /*********** /
- /  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-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/getting-started/getting-started.xml

@@ -1,94 +0,0 @@
-<!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='getting-started-manual' lang='en'
-      xmlns:xi="http://www.w3.org/2003/XInclude"
-      xmlns="http://docbook.org/ns/docbook"
-      >
-    <bookinfo>
-
-        <mediaobject>
-            <imageobject>
-                <imagedata fileref='figures/getting-started-title.png'
-                    format='SVG'
-                    align='left' scalefit='1' width='100%'/>
-            </imageobject>
-        </mediaobject>
-
-        <title>
-            Getting Started With Yocto Project
-        </title>
-
-        <authorgroup>
-            <author>
-                <firstname>Scott</firstname> <surname>Rifenbark</surname>
-                <affiliation>
-                    <orgname>Scotty's Documentation Services, INC</orgname>
-                </affiliation>
-                <email>srifenbark@gmail.com</email>
-            </author>
-        </authorgroup>
-
-        <revhistory>
-            <revision>
-                <revnumber>2.5</revnumber>
-                <date>April 2018</date>
-                <revremark>The initial document released with the Yocto Project 2.5 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><title>Manual Notes</title>
-               <itemizedlist>
-                   <listitem><para>
-                       This version of the
-                       <emphasis>Getting Started With Yocto Project Manual</emphasis>
-                       is for the &YOCTO_DOC_VERSION; release of the
-                       Yocto Project.
-                       To be sure you have the latest version of the manual
-                       for this release, use the manual from the
-                       <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>.
-                       </para></listitem>
-                   <listitem><para>
-                       For manuals associated with other releases of the Yocto
-                       Project, go to the
-                       <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
-                       and use the drop-down "Active Releases" button
-                       and choose the manual associated with the desired
-                       Yocto Project.
-                       </para></listitem>
-                   <listitem><para>
-                        To report any inaccuracies or problems with this
-                        manual, send an email to the Yocto Project
-                        discussion group at
-                        <filename>yocto@yoctoproject.com</filename> or log into
-                        the freenode <filename>#yocto</filename> channel.
-                        </para></listitem>
-               </itemizedlist>
-           </note>
-    </legalnotice>
-
-    </bookinfo>
-
-    <xi:include href="getting-started-intro.xml"/>
-
-    <xi:include href="getting-started-yp-intro.xml"/>
-
-    <xi:include href="getting-started-development-environment.xml"/>
-
-</book>
-<!--
-vim: expandtab tw=80 ts=4
--->

documentation/kernel-dev/kernel-dev-advanced.xml

@@ -21,7 +21,7 @@
     <para>
         Kernel Metadata exists in many places.
         One area in the Yocto Project
-        <ulink url='&YOCTO_DOCS_GS_URL;#source-repositories'>Source Repositories</ulink>
+        <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
         is the <filename>yocto-kernel-cache</filename> Git repository.
         You can find this repository grouped under the "Yocto Linux Kernel"
         heading in the
@@ -64,8 +64,7 @@
         <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>
         variable.
         This variable is typically set to the same value as the
-        <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+        <filename>MACHINE</filename> variable, which is used by
-        variable, which is used by
         <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>.
         However, in some cases, the variable might instead refer to the
         underlying platform of the <filename>MACHINE</filename>.
@@ -77,8 +76,7 @@
         Multiple Corei7-based BSPs could share the same "intel-corei7-64"
         value for <filename>KMACHINE</filename>.
         It is important to realize that <filename>KMACHINE</filename> is
-        just for kernel mapping, while
+        just for kernel mapping, while <filename>MACHINE</filename>
-        <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
         is the machine type within a BSP Layer.
         Even with this distinction, however, these two variables can hold
         the same value.
@@ -116,8 +114,7 @@
         used in assembling the configuration.
         If you do not specify a <filename>LINUX_KERNEL_TYPE</filename>,
         it defaults to "standard".
-        Together with
+        Together with <filename>KMACHINE</filename>,
-        <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
         <filename>LINUX_KERNEL_TYPE</filename> defines the search
         arguments used by the kernel tools to find the
         appropriate description within the kernel Metadata with which to
@@ -644,8 +641,7 @@
             aggregation concepts, and presents a detailed example using
             a BSP supported by the Yocto Project (i.e. BeagleBone Board).
             For complete information on BSP layer file hierarchy, see the
-            <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support
+            <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
-            Package (BSP) Developer's Guide</ulink>.
         </para>
 
         <section id='bsp-description-file-overview'>
@@ -856,7 +852,7 @@
 
             <para>
                 Now consider the "minnow" description for the "tiny" kernel
-                type (i.e. <filename>minnow-tiny.scc</filename>:
+                type (i.e. <filename>minnow-tiny.scc</filename>):
                 <literallayout class='monospaced'>
         define KMACHINE minnow
         define KTYPE tiny
@@ -1018,8 +1014,7 @@
 
         <para>
             If you modify the Metadata, you must not forget to update the
-            <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
+            <filename>SRCREV</filename> statements in the kernel's recipe.
-            statements in the kernel's recipe.
             In particular, you need to update the
             <filename>SRCREV_meta</filename> variable to match the commit in
             the <filename>KMETA</filename> branch you wish to use.
@@ -1227,9 +1222,13 @@
                 </para></listitem>
             <listitem><para>
                 <filename>define</filename>:
-                Defines variables, such as <filename>KMACHINE</filename>,
+                Defines variables, such as
-                <filename>KTYPE</filename>, <filename>KARCH</filename>,
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
-                and <filename>KFEATURE_DESCRIPTION</filename>.</para></listitem>
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>,
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink>,
+                and
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION'><filename>KFEATURE_DESCRIPTION</filename></ulink>.
+                </para></listitem>
             <listitem><para>
                 <filename>include SCC_FILE</filename>:
                 Includes an SCC file in the current file.

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

@@ -25,7 +25,7 @@
             Before you can do any kernel development, you need to be
             sure your build host is set up to use the Yocto Project.
             For information on how to get set up, see the
-            "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Setting Up to Use the Yocto Project</ulink>"
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#setting-up-the-development-host-to-use-the-yocto-project'>Preparing the Build Host</ulink>"
             section in the Yocto Project Development Tasks Manual.
             Part of preparing the system is creating a local Git
             repository of the
@@ -79,7 +79,7 @@
                         </literallayout>
                         <note>
                             The previous commands assume the
-                            <ulink url='&YOCTO_DOCS_GS_URL;#source-repositories'>Source Repositories</ulink>
+                            <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
                             (i.e. <filename>poky</filename>) have been cloned
                             using Git and the local repository is named
                             "poky".
@@ -303,7 +303,7 @@
                         </literallayout>
                         <note>
                             The previous commands assume the
-                            <ulink url='&YOCTO_DOCS_GS_URL;#source-repositories'>Source Repositories</ulink>
+                            <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
                             (i.e. <filename>poky</filename>) have been cloned
                             using Git and the local repository is named
                             "poky".
@@ -387,7 +387,7 @@
                         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>.
+                        <ulink url='&YOCTO_GIT_URL;'></ulink>.
                         </para>
 
                         <para>
@@ -1402,9 +1402,9 @@
      SRC_URI_append = " file://0001-calibrate.c-Added-some-printk-statements.patch"
                     </literallayout>
                     The
-                    <ulink url='&YOCTO_DOCS_REF_URL;var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
                     and
-                    <ulink url='&YOCTO_DOCS_REF_URL;var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
                     statements enable the OpenEmbedded build system to find
                     the patch file.</para>
 
@@ -1603,8 +1603,11 @@
             <title>Creating a&nbsp;&nbsp;<filename>defconfig</filename> File</title>
 
             <para>
-                A <filename>defconfig</filename> file is simply a
+                A <filename>defconfig</filename> file in the context of
-                <filename>.config</filename> renamed to "defconfig".
+                the Yocto Project is often a <filename>.config</filename>
+                file that is copied from a build or a
+                <filename>defconfig</filename> taken from the kernel tree
+                and moved into recipe space.
                 You can use a <filename>defconfig</filename> file
                 to retain a known set of kernel configurations from which the
                 OpenEmbedded build system can draw to create the final
@@ -1656,7 +1659,7 @@
                     after applying the existing defconfig file configurations.
                 </note>
                 For more information on configuring the kernel, see the
-                "<link link='changing-the-configuration'>Changing the Configuration</link>"
+                "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
                 section.
             </para>
         </section>
@@ -2418,7 +2421,7 @@
                 modules.
                 If your module <filename>Makefile</filename> uses a different
                 variable, you might want to override the
-                <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile()</filename></ulink>
+                <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>
                 step, or create a patch to
                 the <filename>Makefile</filename> to work with the more typical
                 <filename>KERNEL_SRC</filename> or
@@ -2494,7 +2497,7 @@
                     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>.
+                    <ulink url='&YOCTO_GIT_URL;'></ulink>.
                 </note>
                 To see a full range of the changes, use the
                 <filename>git whatchanged</filename> command and specify a

documentation/kernel-dev/kernel-dev-concepts-appx.xml

@@ -49,7 +49,7 @@
 
         <para>
             You can find a web interface to the Yocto Linux kernels in the
-            <ulink url='&YOCTO_DOCS_GS_URL;#source-repositories'>Source Repositories</ulink>
+            <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
             at
             <ulink url='&YOCTO_GIT_URL;'></ulink>.
             If you look at the interface, you will see to the left a
@@ -239,8 +239,8 @@
                         <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_GS_URL;#git'>Git</ulink>"
+                        "<ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>"
-                        section in the Getting Started With Yocto Project
+                        section in the Yocto Project Overview and Concepts
                         Manual.
                         The latter reference provides an overview of
                         Git and presents a minimal set of Git commands
@@ -382,7 +382,7 @@
                 generic kernel just for conceptual purposes.
                 Also keep in mind that this structure represents the Yocto
                 Project
-                <ulink url='&YOCTO_DOCS_GS_URL;#source-repositories'>Source Repositories</ulink>
+                <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
                 that are either pulled from during the build or established
                 on the host development system prior to the build by either
                 cloning a particular kernel's Git repository or by

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

@@ -108,7 +108,11 @@
         review and understand the following documentation:
         <itemizedlist>
             <listitem><para>
-                <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>
+                <ulink url='&YOCTO_DOCS_BRIEF_URL;'>Yocto Project Quick Build</ulink>
+                document.
+                </para></listitem>
+            <listitem><para>
+                <ulink url='&YOCTO_DOCS_OM_URL;'>Yocto Project Overview and Concepts Manual</ulink>.
                 </para></listitem>
             <listitem><para>
                 <ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'><filename>devtool</filename> workflow</ulink>
@@ -153,12 +157,15 @@
     <para>
         <orderedlist>
             <listitem><para>
-                <emphasis>Set Up Your Host Development System to Support
+
-                Development Using the Yocto Project:</emphasis>
+
+                <emphasis>Set up Your Host Development System to Support
+                Development Using the Yocto Project</emphasis>:
                 See the
-                "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>Setting Up to Use the Yocto Project</ulink>"
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-start'>Setting Up the Development Host to Use the Yocto Project</ulink>"
-                section in the Yocto Project Quick Start for options on how
+                section in the Yocto Project Development Tasks Manual for
-                to get a build host ready to use the Yocto Project.
+                options on how to get a build host ready to use the Yocto
+                Project.
                 </para></listitem>
             <listitem><para>
                 <emphasis>Set Up Your Host Development System for Kernel Development:</emphasis>

documentation/kernel-dev/kernel-dev-maint-appx.xml

@@ -14,7 +14,7 @@
             create Yocto Linux 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>
+            <ulink url='&YOCTO_GIT_URL;'>&YOCTO_GIT_URL;</ulink>
             and are 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 and feature in the
@@ -118,7 +118,7 @@
             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
+            <ulink url='&YOCTO_GIT_URL;'></ulink> given the
             introduction of a new top-level kernel feature or BSP.
             The following actions effectively provide the Metadata
             and create the tree that includes the new feature, patch, or BSP:
@@ -217,7 +217,7 @@
                         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>
+                        <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>
                         is the combination of all supported boards and
                         configurations.
                         </para></listitem>
@@ -231,7 +231,7 @@
                         </para></listitem>
                     <listitem><para>
                         The full kernel tree that you see on
-                        <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> is
+                        <ulink url='&YOCTO_GIT_URL;'></ulink> is
                         generated through repeating the above steps for all
                         valid BSPs.
                         The end result is a branched, clean history tree that

documentation/kernel-dev/kernel-dev.xml

@@ -88,9 +88,24 @@
             </revision>
             <revision>
                 <revnumber>2.5</revnumber>
-                <date>April 2018</date>
+                <date>May 2018</date>
                 <revremark>Released with the Yocto Project 2.5 Release.</revremark>
             </revision>
+            <revision>
+                <revnumber>2.5.1</revnumber>
+                <date>September 2018</date>
+                <revremark>The initial document released with the Yocto Project 2.5.1 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>2.5.2</revnumber>
+                <date>January 2019</date>
+                <revremark>The initial document released with the Yocto Project 2.5.2 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>2.5.3</revnumber>
+                <date>&REL_MONTH_YEAR;</date>
+                <revremark>The initial document released with the Yocto Project 2.5.3 Release.</revremark>
+            </revision>
         </revhistory>
 
     <copyright>
@@ -111,24 +126,36 @@
                        is for the &YOCTO_DOC_VERSION; release of the
                        Yocto Project.
                        To be sure you have the latest version of the manual
-                       for this release, use the manual from the
+                       for this release, go to the
-                       <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>.
-                       </para></listitem>
-                   <listitem><para>
-                       For manuals associated with other releases of the Yocto
-                       Project, go to the
                        <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
-                       and use the drop-down "Active Releases" button
+                       and select the manual from that site.
-                       and choose the manual associated with the desired
+                       Manuals from the site are more up-to-date than manuals
-                       Yocto Project.
+                       derived from the Yocto Project released TAR files.
                        </para></listitem>
                    <listitem><para>
-                        To report any inaccuracies or problems with this
+                       If you located this manual through a web search, the
-                        manual, send an email to the Yocto Project
+                       version of the manual might not be the one you want
-                        discussion group at
+                       (e.g. the search might have returned a manual much
-                        <filename>yocto@yoctoproject.com</filename> or log into
+                       older than the Yocto Project version with which you
-                        the freenode <filename>#yocto</filename> channel.
+                       are working).
-                        </para></listitem>
+                       You can see all Yocto Project major releases by
+                       visiting the
+                       <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
+                       page.
+                       If you need a version of this manual for a different
+                       Yocto Project release, visit the
+                       <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
+                       and select the manual set by using the
+                       "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
+                       pull-down menus.
+                       </para></listitem>
+                   <listitem><para>
+                       To report any inaccuracies or problems with this
+                       manual, send an email to the Yocto Project
+                       discussion group at
+                       <filename>yocto@yoctoproject.com</filename> or log into
+                       the freenode <filename>#yocto</filename> channel.
+                       </para></listitem>
                </itemizedlist>
            </note>
     </legalnotice>

documentation/mega-manual/mega-manual.xml

@@ -72,9 +72,24 @@
             </revision>
             <revision>
                 <revnumber>2.5</revnumber>
-                <date>April 2018</date>
+                <date>May 2018</date>
                 <revremark>Released with the Yocto Project 2.5 Release.</revremark>
             </revision>
+            <revision>
+                <revnumber>2.5.1</revnumber>
+                <date>September 2018</date>
+                <revremark>The initial document released with the Yocto Project 2.5.1 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>2.5.2</revnumber>
+                <date>January 2019</date>
+                <revremark>The initial document released with the Yocto Project 2.5.2 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>2.5.3</revnumber>
+                <date>&REL_MONTH_YEAR;</date>
+                <revremark>The initial document released with the Yocto Project 2.5.3 Release.</revremark>
+            </revision>
        </revhistory>
 
     <copyright>
@@ -95,24 +110,36 @@
                        is for the &YOCTO_DOC_VERSION; release of the
                        Yocto Project.
                        To be sure you have the latest version of the manual
-                       for this release, use the manual from the
+                       for this release, go to the
-                       <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>.
-                       </para></listitem>
-                   <listitem><para>
-                       For manuals associated with other releases of the Yocto
-                       Project, go to the
                        <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
-                       and use the drop-down "Active Releases" button
+                       and select the manual from that site.
-                       and choose the manual associated with the desired
+                       Manuals from the site are more up-to-date than manuals
-                       Yocto Project.
+                       derived from the Yocto Project released TAR files.
                        </para></listitem>
                    <listitem><para>
-                        To report any inaccuracies or problems with this
+                       If you located this manual through a web search, the
-                        manual, send an email to the Yocto Project
+                       version of the manual might not be the one you want
-                        discussion group at
+                       (e.g. the search might have returned a manual much
-                        <filename>yocto@yoctoproject.com</filename> or log into
+                       older than the Yocto Project version with which you
-                        the freenode <filename>#yocto</filename> channel.
+                       are working).
-                        </para></listitem>
+                       You can see all Yocto Project major releases by
+                       visiting the
+                       <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Releases</ulink>
+                       page.
+                       If you need a version of this manual for a different
+                       Yocto Project release, visit the
+                       <ulink url='&YOCTO_HOME_URL;/documentation'>Yocto Project documentation page</ulink>
+                       and select the manual set by using the
+                       "ACTIVE RELEASES DOCUMENTATION" or "DOCUMENTS ARCHIVE"
+                       pull-down menus.
+                       </para></listitem>
+                   <listitem><para>
+                       To report any inaccuracies or problems with this
+                       manual, send an email to the Yocto Project
+                       discussion group at
+                       <filename>yocto@yoctoproject.com</filename> or log into
+                       the freenode <filename>#yocto</filename> channel.
+                       </para></listitem>
                </itemizedlist>
            </note>
 
@@ -120,41 +147,32 @@
 
     </bookinfo>
 
-<!-- Includes yocto-project-qs -->
+<!-- Includes brief-yoctoprojectqs -->
 
     <para>
-        <imagedata fileref="figures/ypqs-title.png" width="100%" align="left" scalefit="1" />
+        <imagedata fileref="figures/bypqs-title.png" width="100%" align="left" scalefit="1" />
     </para>
 
     <xi:include
-        xmlns:xi="http://www.w3.org/2003/XInclude" href="../yocto-project-qs/qs.xml"/>
+        xmlns:xi="http://www.w3.org/2003/XInclude" href="../brief-yoctoprojectqs/brief-yoctoprojectqs.xml"/>
 
-<!-- Includes getting-started title image and then getting-started chapters -->
+<!-- Includes overview-manual title image and then overview-manual chapters -->
 
     <para>
-        <imagedata fileref="figures/getting-started-title.png" width="100%" align="left" scalefit="1" />
+        <imagedata fileref="figures/overview-manual-title.png" width="100%" align="left" scalefit="1" />
     </para>
 
     <xi:include
-        xmlns:xi="http://www.w3.org/2003/XInclude" href="../getting-started/getting-started-intro.xml"/>
+        xmlns:xi="http://www.w3.org/2003/XInclude" href="../overview-manual/overview-manual-intro.xml"/>
 
     <xi:include
-        xmlns:xi="http://www.w3.org/2003/XInclude" href="../getting-started/getting-started-yp-intro.xml"/>
+        xmlns:xi="http://www.w3.org/2003/XInclude" href="../overview-manual/overview-manual-yp-intro.xml"/>
 
     <xi:include
-        xmlns:xi="http://www.w3.org/2003/XInclude" href="../getting-started/getting-started-development-environment.xml"/>
+        xmlns:xi="http://www.w3.org/2003/XInclude" href="../overview-manual/overview-manual-development-environment.xml"/>
-
-<!-- Includes concepts-manual title image and then concepts-manual chapters -->
-
-    <para>
-        <imagedata fileref="figures/concepts-manual-title.png" width="100%" align="left" scalefit="1" />
-    </para>
 
     <xi:include
-        xmlns:xi="http://www.w3.org/2003/XInclude" href="../concepts-manual/concepts-manual-intro.xml"/>
+        xmlns:xi="http://www.w3.org/2003/XInclude" href="../overview-manual/overview-manual-concepts.xml"/>
-
-    <xi:include
-        xmlns:xi="http://www.w3.org/2003/XInclude" href="../concepts-manual/concepts-manual-concepts.xml"/>
 
 <!-- Includes dev-manual title image and then dev-manual chapters -->
 
@@ -166,8 +184,6 @@
         xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-intro.xml"/>
     <xi:include
         xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-start.xml"/>
-    <xi:include
-        xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-newbie.xml"/>
     <xi:include
         xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual-common-tasks.xml"/>
     <xi:include
@@ -196,7 +212,7 @@
     <xi:include
         xmlns:xi="http://www.w3.org/2003/XInclude" href="../sdk-manual/sdk-appendix-customizing-standard.xml"/>
     <xi:include
-        xmlns:xi="http://www.w3.org/2003/XInclude" href="../sdk-manual/sdk-appendix-mars.xml"/>
+        xmlns:xi="http://www.w3.org/2003/XInclude" href="../sdk-manual/sdk-appendix-neon.xml"/>
 
 <!-- Includes bsp-guide title image and then bsp-guide chapters -->