diff --git a/documentation/dev-manual/dev-manual-cases.xml b/documentation/dev-manual/dev-manual-cases.xml
index 28d48d0c9e..ebc8eeca1e 100644
--- a/documentation/dev-manual/dev-manual-cases.xml
+++ b/documentation/dev-manual/dev-manual-cases.xml
@@ -14,6 +14,11 @@
target hardware.
+
+ This chapter presents an overview of the primary cases.
+ Supsequent appendices in the manual provide detailed explanations of the examples.
+
+
[WRITERS NOTE: What is undetermined at this point is how much of the entire development process
we include in this particular chapter.
@@ -52,702 +57,165 @@
see Yocto Project Terms in this manual.
+
+ The remainder of this section presents the basic steps to create a BSP basing it on an
+ existing BSP that ships with the Yocto Project.
+ You can reference BSP Development Case
+ for a detailed example that uses the Crown Bay BSP as a base BSP from which to start.
+
+
Here are the basic steps involved in creating a BSP:
- Be sure your host development system is set up to support
- development using the Yocto Project.
- See
+ Set up your host development system to support
+ development using the Yocto Project: See
The Linux Distributions section and
The Packages section both
in the Yocto Project Quick Start for requirements.
You will also need a release of Yocto Project installed on the host.
- Choose a BSP available with Yocto Project that most closely represents
- your hardware.
- Get set up with a base BSP.
- Make a copy of the existing BSP and isolate your work by creating a layer
- for your recipes.
- Make configuration and recipe changes to your new BSP layer.
- Prepare for the build.
- Select and configure the kernel.
- Identify the machine branch.
- Build the image.
+ Establish a local copy of the Yocto Project files on your
+ system: You need to have the Yocto Project files available on your host system.
+ Having the Yocto Project files on your system gives you access to the build
+ process and tools you need.
+ For information on how to get these files, see the
+ Getting Setup section in this manual.
+ Choose a Yocto Project-supported BSP as your base BSP:
+ The Yocto Project ships with several BSPs that support various hardware.
+ It is best to base your new BSP on an existing BSP rather than create all the
+ recipes and configuration files from scratch.
+ While it is possible to create everything from scratch, basing your new BSP
+ on something that is close is much easier.
+ Or, at a minimum, it gives you some structure with which to start.
+ At this point you need to understand your target hardware well enough to determine which
+ existing BSP it most closely matches.
+ Things to consider are your hardware’s on-board features such as CPU type and graphics support.
+ You should look at the README files for supported BSPs to get an idea of which one
+ you could use.
+ A generic Atom-based BSP to consider is the Crown Bay that does not support
+ the Intel® Embedded Media Graphics Driver (EMGD).
+ The remainder of this example uses that base BSP.
+ To see the supported BSPs, go to the Yocto Project
+ download page and click
+ on “BSP Downloads.”
+ Establish a local copy of the base BSP files: Having
+ the BSP files on your system gives you access to the build
+ process and tools you need.
+ For information on how to get these files, see
+ Getting Setup earlier in this manual.
+ Create your own BSP layer: Layers are ideal for
+ isolating and storing work for a given piece of hardware.
+ A layer is really just a location or area in which you place the recipes for your BSP.
+ In fact, a BSP is, in itself, a special type of layer.
+ Consider an application as another example that illustrates a layer.
+ Suppose you are creating an application that has library or other dependencies in
+ order for it to compile and run.
+ The layer, in this case, would be where all the recipes that define those dependencies
+ are kept. The key point for a layer is that it is an isolated area that contains
+ all the relevant information for the project that the Yocto Project build
+ system knows about.
+ The Yocto Project supports four BSPs that are part of the
+ Yocto Project release: atom-pc, beagleboard,
+ mpc8315e, and routerstationpro.
+ The recipes and configurations for these four BSPs are located and dispersed
+ within local Yocto Project files.
+ Consequently, they are not totally isolated in the spirit of layers unless you think
+ of meta-yocto as a layer itself.
+ On the other hand, BSP layers for Crown Bay, Emenlow, Jasper Forest,
+ N450, and Sugar Bay are isolated.
+ When you set up a layer for a new BSP you should follow a standard layout.
+ This layout is described in the
+
+ Example Filesystem Layout section of the Board Support Package (BSP) Development
+ Guide.
+ In the standard layout you will notice a suggested structure for recipes and
+ configuration information.
+ You can see the standard layout for the Crown Bay BSP in this example by examining the
+ directory structure of the meta-crownbay layer inside the
+ local Yocto Project files.
+ Make configuration and recipe changes to your new BSP
+ layer: The standard BSP layer structure organizes the files you need to edit in
+ conf and several recipes-* within the
+ BSP layer.
+ Configuration changes identify where your new layer is on the local system
+ and identify which kernel you are going to use.
+ Recipe changes include altering recipes (.bb files), removing
+ recipes you don't use, and adding new recipes that you need to support your hardware.
+
+ Prepare for the build: Once you have made all the
+ changes to your BSP layer there remains a few things
+ you need to do for the Yocto Project build system in order for it to create your image.
+ You need to get the build environment ready by sourcing an environment setup script
+ and you need to be sure two key configuration files are configured appropriately.
+ The entire process for building an image is overviewed in the
+
+ Building an Image section of the Yocto Project Quick Start.
+ You might want to reference this information.
+ Build the image: The Yocto Project uses the BitBake
+ tool to build images based on the type of image
+ you want to create.
+ You can find more information on BitBake
+ here.
+ The build process supports several types of images to satisfy different needs.
+ When you issue the BitBake command you provide a “top-level” recipe that essentially
+ starts the process off of building the type of image you want.
+ [WRITER'S NOTE: Consider moving this to the Poky Reference Manual.]
+ You can find these recipes in the meta/recipes-core/images and
+ meta/recipes-sato/images directories of your local Yocto Project
+ file structure (Git repository or extracted release tarball).
+ Although the recipe names are somewhat explanatory, here is a list that describes them:
+
+ Base – A foundational basic image without support
+ for X that can be reasonably used for customization.
+ Core – A foundational basic image with support for
+ X that can be reasonably used for customization.
+ Direct Disk – An image that you can copy directory to
+ the disk of the target device.
+ Live – An image you can run from a USB device or from
+ a CD without having to first install something.
+ Minimal – A small image without a GUI.
+ This image is not much more than a kernel with a shell.
+ Minimal Development – A Minimal image suitable for
+ development work.
+ Minimal Direct Disk – A Minimal Direct
+ Disk image.
+ Minimal RAM-based Initial Root Filesystem –
+ A minimal image
+ that has the initramfs as part of the kernel, which allows the
+ system to find the first “init” program more efficiently.
+ Minimal Live – A Minimal Live image.
+ Minimal MTD Utilities – A minimal image that has support
+ for the MTD utilities, which let the user interact with the MTD subsystem in
+ the kernel to perform operations on flash devices.
+ Sato – An image with Sato support, a mobile environment
+ and visual style that works well with mobile devices.
+ Sato Development – A Sato image suitable for
+ development work.
+ Sato Direct Disk – A Sato Direct
+ Disk image.
+ Sato Live – A Sato Live image.
+ Sato SDK – A Sato image that includes the Yocto Project
+ toolchain and development libraries.
+ Sato SDK Direct Disk – A Sato SDK Direct
+ Disk image.
+ Sato SDK Live – A Sato SDK Live
+ image.
+
+
- You can view a video presentation of the BSP creation process
- here.
- You can also find supplemental information in the
-
- Board Support Package (BSP) Development Guide.
- Finally, there is wiki page write up of the example located
-
- here you might find helpful.
-
- Setting Up Yocto Project
-
-
- You need to have the Yocto Project files available on your host system.
- You can get files through tarball extraction or by cloning the poky
- Git repository.
- Typically, cloning the Git repository is the method to use.
- This allows you to maintain a complete history of changes and facilitates you
- contributing back to the Yocto Project.
- However, if you just want a hierarchical file structure that contains the recipes
- and metadata that let you develop you can download tarballs from the
- download page.
-
-
-
- Regardless of the method you use this manual will refer to the resulting
- hierarchical set of files as "the local Yocto Project files."
-
-
-
- [WRITER'S NOTE: I need to substitute correct and actual filenames for the
- 1.1 release throughout this example once they become available.]
-
-
-
- If you download a tarball you can extract it into any directory you want using the
- tar command.
- For example, the following command extracts the Yocto Project 1.1 release tarball
- into the current working directory and sets up a file structure whose top-level
- directory is named poky-1.1:
-
- $ tar xfj poky-1.1.tar.bz2
-
-
-
-
- The following transcript shows how to clone the poky Git repository
- into the current working directory.
- The command creates the repository in a directory named poky:
-
- $ git clone git://git.yoctoproject.org/poky
- Initialized empty Git repository in /home/scottrif/poky/.git/
- remote: Counting objects: 107624, done.
- remote: Compressing objects: 100% (37128/37128), done.
- remote: Total 107624 (delta 73393), reused 99851 (delta 67287)
- Receiving objects: 100% (107624/107624), 69.74 MiB | 483 KiB/s, done.
- Resolving deltas: 100% (73393/73393), done.
-
-
-
-
- Once you have the local poky Git repository set up,
- you have many development branches from which you can work.
- From inside the repository you can see the branch names and the tag names used
- in the Git repository using either of the following two commands:
-
- $ git branch -a
- $ git tag -l
-
- For this example we are going to use the Yocto Project 1.1 Release,
- which maps to the 1.1 branch in the repository.
- These commands create a local branch named 1.1
- that tracks the remote branch of the same name.
-
-
- $ cd poky
- $ git checkout -b 1.1 origin/1.1
- Switched to a new branch '1.1'
-
-
-
-
-
- Choosing a Base BSP
-
-
- The Yocto Project ships with several BSPs that support various hardware.
- It is best to base your new BSP on an existing BSP rather than create all the
- recipes and configuration files from scratch.
- While it is possible to create everything from scratch, basing your new BSP
- on something that is close is much easier.
- Or, at a minimum, it gives you some structure with which to start.
-
-
-
- At this point you need to understand your target hardware well enough to determine which
- existing BSP it most closely matches.
- Things to consider are your hardware’s on-board features such as CPU type and graphics support.
- You should look at the README files for supported BSPs to get an idea of which one
- you could use.
- A generic Atom-based BSP to consider is the Crown Bay that does not support
- the Intel® Embedded Media Graphics Driver (EMGD).
- The remainder of this example uses that base BSP.
-
-
-
- To see the supported BSPs, go to the Yocto Project
- download page and click
- on “BSP Downloads.”
-
-
-
-
- Getting Your Base BSP
-
-
- You need to have the base BSP layer on your development system.
- Like the local Yocto Project files, you can get the BSP
- layer one of two ways:
- download the BSP tarball and extract it, or set up a local Git repository that
- has the Yocto Project BSP layers.
- You should use the same method that you used to get the local Yocto Project files earlier.
-
-
-
- If you are using tarball extraction, simply download the tarball for the base
- BSP you chose in the previous step and then extract it into any directory
- you choose using the tar command.
- Upon extraction, the BSP source directory (layer) will be named
- meta-<BSP_name>.
- The following command extracts the Crown Bay BSP into the current directory and names it
- meta-crownbay:
-
- $ tar xjf crownbay-noemgd-1.1.tar.bz2
-
-
-
-
- If you cloned a poky Git repository
- then you need to set up a different local Git repository
- (meta-intel) for the BSP.
- The meta-intel Git repository contains all the metadata
- that supports BSP creation.
- When you set up the meta-intel Git repository you can
- set it up anywhere you want.
- We will set up the repository inside the
- poky Git repository in this example.
-
-
-
- The following transcript shows the steps to clone the meta-intel
- Git repository inside the poky Git repository created earlier in this
- example.
-
- $cd poky
- $ git clone git://git.yoctoproject.org/meta-intel.git
- Initialized empty Git repository in /home/scottrif/poky/meta-intel/.git/
- remote: Counting objects: 1325, done.
- remote: Compressing objects: 100% (1078/1078), done.
- remote: Total 1325 (delta 546), reused 85 (delta 27)
- Receiving objects: 100% (1325/1325), 1.56 MiB | 330 KiB/s, done.
- Resolving deltas: 100% (546/546), done.
-
-
-
-
- Because meta-intel is its own Git repository you will want
- to be sure you are in the appropriate branch for your work.
- For this example we are going to use the 1.1 branch.
-
- $ cd meta-intel
- $ git checkout -b 1.1 origin/1.1
- Switched to a new branch 'bernard'
-
-
-
-
-
- Making a Copy of the Base BSP to Create Your New BSP Layer
-
-
- Now that you have the local Yocto Project files and the base BSP files you need to create a
- new layer for your BSP.
-
-
-
- Layers are ideal for isolating and storing work for a given piece of hardware.
- A layer is really just a location or area in which you place the recipes for your BSP.
- In fact, a BSP is, in itself, a special type of layer.
- Consider an application as another example that illustrates a layer.
- Suppose you are creating an application that has library or other dependencies in
- order for it to compile and run.
- The layer, in this case, would be where all the recipes that define those dependencies
- are kept. The key point for a layer is that it is an isolated area that contains
- all the relevant information for the project that the Yocto Project build system knows about.
-
-
-
- The Yocto Project supports four BSPs that are part of the
- Yocto Project release: atom-pc, beagleboard,
- mpc8315e, and routerstationpro.
- The recipes and configurations for these four BSPs are located and dispersed
- within local Yocto Project files.
- Consequently, they are not totally isolated in the spirit of layers unless you think
- of meta-yocto as a layer itself.
- On the other hand, BSP layers for Crown Bay, Emenlow, Jasper Forest,
- N450, and Sugar Bay are isolated.
-
-
-
- When you set up a layer for a new BSP you should follow a standard layout.
- This layout is described in the
-
- Example Filesystem Layout section of the Board Support Package (BSP) Development
- Guide.
- In the standard layout you will notice a suggested structure for recipes and
- configuration information.
- You can see the standard layout for the Crown Bay BSP in this example by examining the
- directory structure of the meta-crownbay layer inside the
- local Yocto Project files.
-
-
-
- To create your BSP layer you simply copy the meta-crownbay
- layer to a new layer.
- For this example the new layer will be named meta-mymachine.
- The name must follow the BSP layer naming convention, which is
- meta-<name>.
- The following example assumes your working directory is meta-intel
- inside the local Yocto Project files.
- If you downloaded and expanded a Crown Bay tarball then you simply copy the resulting
- meta-crownbay directory structure to a location of your choice.
- Good practice for a Git repository, however, is to just copy the new layer alongside
- the existing
- BSP layers in the meta-intel Git repository:
-
- $ cp -a meta-crownbay/ meta-mymachine
-
-
-
-
-
- Making Changes to Your BSP
-
-
- Right now you have two identical BSP layers with different names:
- meta-crownbay and meta-mymachine.
- You need to change your configurations so that they work for your new BSP and
- your particular hardware.
- We will look first at the configurations, which are all done in the layer’s
- conf directory.
-
-
-
- First, since in this example the new BSP will not support EMGD we will get rid of the
- crownbay.conf file and then rename the
- crownbay-noemgd.conf file to mymachine.conf.
- Much of what we do in the configuration directory is designed to help the Yocto Project
- build system work with the new layer and to be able to find and use the right software.
- The following two commands result in a single machine configuration file named
- mymachine.conf.
-
- $ rm meta-mymachine/conf/machine/crownbay.conf
- $ mv meta-mymachine/conf/machine/crownbay-noemgd.conf \
- meta-mymachine/conf/machine/mymachine.conf
-
-
-
-
- The next step makes changes to mymachine.conf itself.
- The only changes needed for this example are changes to the comment lines.
- Here we simply substitute the Crown Bay name with an appropriate name.
-
-
-
- Note that inside the mymachine.conf is the
- PREFERRED_PROVIDER_virtual/kernel statement.
- This statement identifies the kernel that the BSP is going to use.
- In this case the BSP is using linux-yocto, which is the
- current Linux Yocto kernel based on the Linux 2.6.37 release.
-
-
-
- The next configuration file in the new BSP layer we need to edit is layer.conf.
- This file identifies build information needed for the new layer.
- You can see the
-
- Layer Configuration File section in the Board Support Packages (BSP) Development Guide
- for more information on this configuration file.
- Basically, we are changing the existing statements to work with our BSP.
-
-
-
- The file contains these statements that reference the Crown Bay BSP:
-
- BBFILE_COLLECTIONS += "crownbay"
- BBFILE_PATTERN_crownbay := "^${LAYERDIR}/"
- BBFILE_PRIORITY_crownbay = "6"
-
-
-
-
- Simply substitute the machine string name crownbay
- with the new machine name mymachine to get the following:
-
- BBFILE_COLLECTIONS_mymachine += "mymachine"
- BBFILE_PATTERN_mymachine := "^${LAYERDIR}/"
- BBFILE_PRIORITY_mymachine = "6"
-
-
-
-
- Now we will take a look at the recipes in your new layer.
- The standard BSP structure has areas for BSP, graphics, core, and kernel recipes.
- When you create a BSP you use these areas for appropriate recipes and append files.
- Recipes take the form of .bb files.
- If you want to leverage the existing recipes the Yocto Project build system uses
- but change those recipes you can use .bbappend files.
- All new recipes and append files for your layer must go in the layer’s
- recipes-bsp, recipes-kernel,
- recipes-core, and
- recipes-graphics directories.
-
-
-
- First, let's look at recipes-bsp.
- For this example we are not adding any new BSP recipes.
- And, we only need to remove the formfactor we do not want and change the name of
- the remaining one that doesn't support EMGD.
- These commands take care of the recipes-bsp recipes:
-
- $ rm ‐rf meta-mymachine/recipes-graphics/xorg-xserver/*emgd*
- $ mv meta-mymachine/recipes-bsp/formfactor/formfactor/crownbay-noemgd/ \
- meta-mymachine/recipes-bsp/formfactor/formfactor/mymachine
-
-
-
-
- Now let's look at recipes-graphics.
- For this example we want to remove anything that supports EMGD and
- be sure to rename remaining directories appropriately.
- The following commands clean up the recipes-graphics directory:
-
- $ rm ‐rf meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-emgd*
- $ rm ‐rf meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay
- $ mv meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay-noemgd \
- meta-mymachine/recipes-graphics/xorg-xserver/xserver-xf86-config/mymachine
-
-
-
-
- At this point the recipes-graphics directory just has files that
- support Video Electronics Standards Association (VESA) graphics modes and not EMGD.
-
-
-
- Now let's look at changes in recipes-core.
- The file task-core-tools.bbappend in
- recipes-core/tasks appends the similarly named recipe
- located in the local Yocto Project files at
- meta/recipes-core/tasks.
- The "append" file in our layer right now is Crown Bay-specific and supports
- EMGD and non-EMGD.
- Here are the contents of the file:
-
- RRECOMMENDS_task-core-tools-profile_append_crownbay = " systemtap"
- RRECOMMENDS_task-core-tools-profile_append_crownbay-noemgd = " systemtap"
-
-
-
-
- The RRECOMMENDS statements list packages that
- extend usability.
- The first RRECOMMENDS statement can be removed, while the
- second one can be changed to reflect meta-mymachine:
-
- RRECOMMENDS_task-core-tools-profile_append_mymachine = " systemtap"
-
-
-
-
- Finally, let's look at recipes-kernel changes.
- Recall that the BSP uses the linux-yocto kernel as determined
- earlier in the mymachine.conf.
- The recipe for that kernel is not located in the
- BSP layer but rather in the local Yocto Project files at
- meta/recipes-kernel/linux and is
- named linux-yocto-2.6.37.bb.
- The SRCREV_machine and SRCREV_meta
- statements point to the exact commits used by the Yocto Project development team
- in their source repositories that identify the right kernel for our hardware.
-
-
-
- However, in the meta-mymachine layer in
- recipes-kernel/linux resides a .bbappend
- file named linux-yocto-2.6.37.bbappend that
- is appended to the recipe of the same name in meta/recipes-kernel/link.
- Thus, the SRCREV statements in the "append" file override
- the more general statements found in meta.
-
-
-
- The SRCREV statements in the "append" file currently identify
- the kernel that supports the Crown Bay BSP with and without EMGD support.
- Here are the statements:
-
- SRCREV_machine_pn-linux-yocto_crownbay ?= \
- "372c0ab135978bd8ca3a77c88816a25c5ed8f303"
- SRCREV_meta_pn-linux-yocto_crownbay ?= \
- "d5d3c6480d61f83503ccef7fbcd765f7aca8b71b"
-
- SRCREV_machine_pn-linux-yocto_crownbay-noemgd ?= \
- "372c0ab135978bd8ca3a77c88816a25c5ed8f303"
- SRCREV_meta_pn-linux-yocto_crownbay-noemgd ?= \
- "d5d3c6480d61f83503ccef7fbcd765f7aca8b71b"
-
-
-
-
- You will notice that there are two pairs of SRCREV statements.
- The top pair identifies the kernel that supports
- EMGD, which we don’t care about in this example.
- The bottom pair identifies the kernel that we will use:
- linux-yocto.
- At this point though, the unique commit strings all are still associated with
- Crown Bay and not meta-mymachine.
-
-
-
- To fix this situation in linux-yocto-2.6.37.bbappend
- we delete the two SRCREV statements that support
- EMGD (the top pair).
- We also change the remaining pair to specify mymachine
- and insert the commit identifiers to identify the kernel in which we
- are interested, which will be based on the atom-pc-standard
- kernel.
- Here are the final SRCREV statements:
-
- SRCREV_machine_pn-linux-yocto-_mymachine ?= \
- "fce17f046d3756045e4dfb49221d1cf60fcae329"
- SRCREV_meta_pn-linux-yocto-stable_mymachine ?= \
- "84f1a422d7e21fbc23a687035bdf9d42471f19e0"
-
-
-
-
- If you are familiar with Git repositories you probably won’t have trouble locating the
- exact commit strings in the Yocto Project source repositories you need to change
- the SRCREV statements.
- You can find all the machine and meta
- branch points (commits) for the linux-yocto-2.6.37 kernel
- here.
-
-
-
- If you need a little more assistance after going to the link then do the following:
-
- Expand the list of branches by clicking […]
- Click on the yocto/standard/common-pc/atom-pc
- branch
- Click on the commit column header to view the top commit
- Copy the commit string for use in the
- linux-yocto-2.6.37.bbappend file
-
-
-
-
- For the SRCREV statement that points to the meta
- branch use the same procedure except expand the meta
- branch in step 2 above.
-
-
-
- Also in the linux-yocto-2.6.37.bbappend file are
- COMPATIBLE_MACHINE, KMACHINE,
- and KERNEL_FEATURES statements.
- Two sets of these exist: one set supports EMGD and one set does not.
- Because we are not interested in supporting EMGD those three can be deleted.
- The remaining three must be changed so that mymachine replaces
- crownbay-noemgd and crownbay.
- Here is the final linux-yocto-2.6.37.bbappend file after all
- the edits:
-
- FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
-
- COMPATIBLE_MACHINE_mymachine = "mymachine"
- KMACHINE_mymachine = "yocto/standard/mymachine"
- KERNEL_FEATURES_append_mymachine += " cfg/smp.scc"
-
- SRCREV_machine_pn-linux-yocto_mymachine ?= \
- "fce17f046d3756045e4dfb49221d1cf60fcae329"
- SRCREV_meta_pn-linux-yocto_mymachine ?= \
- "84f1a422d7e21fbc23a687035bdf9d42471f19e0"
-
-
-
-
- In summary, the edits to the layer’s recipe files result in removal of any files and
- statements that do not support your targeted hardware in addition to the inclusion
- of any new recipes you might need.
- In this example, it was simply a matter of ridding the new layer
- meta-machine of any code that supported the EMGD features
- and making sure we were identifying the kernel that supports our example, which
- is the atom-pc-standard kernel.
- We did not introduce any new recipes to the layer.
-
-
-
- Finally, it is also important to update the layer’s README
- file so that the information in it reflects your BSP.
-
-
-
-
- Preparing for the Build
-
-
- Once you have made all the changes to your BSP layer there remains a few things
- you need to do for the Yocto Project build system in order for it to create your image.
- You need to get the build environment ready by sourcing an environment setup script
- and you need to be sure two key configuration files are configured appropriately.
-
-
-
- The entire process for building an image is overviewed in the
-
- Building an Image section of the Yocto Project Quick Start.
- You might want to reference this information.
- The remainder of this section will apply to our example of the
- meta-mymachine layer.
-
-
-
- To get ready to build your image that uses the new layer you need to do the following:
-
- Get the environment ready for the build by sourcing the environment
- script.
- The environment script is in the top-level of the local Yocto Project files
- directory structure.
- The script has the string
- init-build-env in the file’s name.
- For this example, the following command gets the build environment ready:
-
- $ source oe-init-build-env yocto-build
-
- When you source the script a build directory is created in the current
- working directory.
- In our example we were in the poky directory.
- Thus, entering the previous command created the yocto-build directory.
- If you do not provide a name for the build directory it defaults to
- build.
- The yocot-build directory contains a
- conf directory that has
- two configuration files you will need to check: bblayers.conf
- and local.conf.
- Check and edit the resulting local.conf file.
- This file minimally identifies the machine for which to build the image by
- configuring the MACHINE variable.
- For this example you must set the variable to mymachine as follows:
-
- MACHINE ??= “mymachine”
-
- You should also be sure any other variables in which you are interested are set.
- Some variables to consider are BB_NUMBER_THREADS
- and PARALLEL_MAKE, both of which can greatly reduce your build time
- if you are using a multi-threaded development system (e.g. values of
- 8 and j 6, respectively are optimal
- for a development machine that has four available cores).
- Update the bblayers.conf file so that it includes
- the path to your new BSP layer.
- In this example you need to include the pathname to meta-mymachine.
- For this example the
- BBLAYERS variable in the file would need to include the following path:
-
- $HOME/poky/meta-intel/meta-mymachine
-
-
-
-
-
- The appendix
-
- Reference: Variables Glossary in the Yocto Project Reference Manual has more information
- on configuration variables.
-
-
-
-
- Building the Image
-
-
- The Yocto Project uses the BitBake tool to build images based on the type of image
- you want to create.
- You can find more information on BitBake
- here.
-
-
-
- The build process supports several types of images to satisfy different needs.
- When you issue the BitBake command you provide a “top-level” recipe that essentially
- starts the process off of building the type of image you want.
-
-
-
- [WRITER'S NOTE: Consider moving this to the Poky Reference Manual.]
-
-
-
- You can find these recipes in the meta/recipes-core/images and
- meta/recipes-sato/images directories of your local Yocto Project
- file structure (Git repository or extracted release tarball).
- Although the recipe names are somewhat explanatory, here is a list that describes them:
-
- Base – A foundational basic image without support
- for X that can be reasonably used for customization.
- Core – A foundational basic image with support for
- X that can be reasonably used for customization.
- Direct Disk – An image that you can copy directory to
- the disk of the target device.
- Live – An image you can run from a USB device or from
- a CD without having to first install something.
- Minimal – A small image without a GUI.
- This image is not much more than a kernel with a shell.
- Minimal Development – A Minimal image suitable for
- development work.
- Minimal Direct Disk – A Minimal Direct Disk image.
- Minimal RAM-based Initial Root Filesystem – A minimal image
- that has the initramfs as part of the kernel, which allows the
- system to find the first “init” program more efficiently.
- Minimal Live – A Minimal Live image.
- Minimal MTD Utilities – A minimal image that has support
- for the MTD utilities, which let the user interact with the MTD subsystem in
- the kernel to perform operations on flash devices.
- Sato – An image with Sato support, a mobile environment
- and visual style that works well with mobile devices.
- Sato Development – A Sato image suitable for
- development work.
- Sato Direct Disk – A Sato Direct Disk image.
- Sato Live – A Sato Live image.
- Sato SDK – A Sato image that includes the Yocto Project
- toolchain and development libraries.
- Sato SDK Direct Disk – A Sato SDK Direct
- Disk image.
- Sato SDK Live – A Sato SDK Live image.
-
-
-
-
- The remainder of this section applies to our example of the meta-mymachine layer.
-
-
-
- To build the image for our meta-mymachine BSP enter the following command
- from the same shell from which you ran the setup script.
- You should run the bitbake command without any intervening shell commands.
- For example, moving your working directory around could cause problems.
- Here is the command for this example:
-
- $ bitbake –k core-image-sato-live
-
-
-
-
- This command specifies an image that has Sato support and that can be run from a USB device or
- from a CD without having to first install anything.
- The build process takes significant time and includes thousands of tasks, which are reported
- at the console.
- If the build results in any type of error you should check for misspellings in the
- files you changed or problems with your host development environment such as missing packages.
-
-
+
+ You can view a video presentation of the BSP creation process
+ here.
+ You can also find supplemental information in the
+
+ Board Support Package (BSP) Development Guide.
+ Finally, there is wiki page write up of the example located
+
+ here you might find helpful.
+
@@ -883,9 +351,9 @@
You need to have the Yocto Project files available on your host system.
- The process is identical to that described in getting the files in section
- "Setting Up Yocto Project" for
- the BSP development case.
+ The process is identical to that described in the
+ "Getting Setup" section earlier in this
+ manual.
Be sure to either set up a local Git repository for poky
or download and unpack the Yocto Project release tarball.