Yocto Project Quick Start
From Crashcourse Wiki
This page will give the reader a blisteringly fast description of how to use Yocto to build images for a BeagleBoard xM starting from scratch. There will be a minimum of editorializing -- if you need more info, here you go.
There will be a few additional notes at the end for the more ambitious. And I'm doing this on my fully-updated 64-bit Ubuntu 12.10 system -- your mileage may vary.
Any suggestions or corrections can be emailed to email@example.com.
BACK TO Yocto main page
Getting the Yocto source
Two choices, depending on whether you want the latest stable release or the cutting edge git master tree. If you want a recent tarball, here's the download directory, so just:
$ wget http://downloads.yoctoproject.org/releases/yocto/yocto-1.3/poky-danny-8.0.tar.bz2 $ tar xvjf poky-danny-8.0.tar.bz2
If you prefer to work with the cutting edge development content,
$ git clone git://git.yoctoproject.org/poky.git git
For the remainder of this Quick Start, we'll assume you used git although that should make minimal difference.
NOTE: It's probably worth mentioning that the primary difference between a fixed version tarball and a git clone is that the tarball will have some known and probably well-understood bugs, while the git clone will be more cutting edge with newer, cooler features but will almost certainly have unknown bugs. So it's a tradeoff. You've been warned.
Setting up your development host
The online Quick Start guide lists all of the packages your development host needs, so it's your job to see that they're installed.
In addition, on Ubuntu systems, you need to get the dash shell out of the way with:
$ sudo dpkg-reconfigure dash
and say "No." At that point, your dev host should be prepared.
NOTE: This might not be necessary anymore, I'll check.
MORE NOTE: Nope, it's not necessary anymore.
Building the documentation [OPTIONAL]
If you want to make sure you're reading the documentation that matches your content, you can build the manuals and guides for it. Pop into Yocto's documentation/ directory and read the Makefile, which describes commands like:
$ make DOC=bsp-guide $ make DOC=yocto-project-qs $ make pdf DOC=poky-ref-manual
and so on. Again, this step is entirely optional, but it might be worth trying just to verify that you've installed all the necessary typesetting packages to let you do this later.
In any event, back to building ...
The initial configuration
From the parent directory of your Yocto checkout, configure your environment while supplying a meaningful directory name representing the system you're about to build, such as (in our case):
$ source git/oe-init-build-env beagle
At that point, the beagle/ directory will be created for you, and you'll be placed inside it, where the real work starts. (If you don't supply that final directory name, it will be named build/ and will be created in your current working directory.)
Configuring your local.conf file
This is where you do all of your additional configuration -- manually editing the initial conf/local.conf file that was created for you here. With a minimum of explanation, here are the changes I made to represent that I wanted to build images for a BeagleBoard xM on my quad-core ASUS laptop:
BB_NUMBER_THREADS = "8" PARALLEL_MAKE = "-j 8" MACHINE ?= "beagleboard"
For now, that's all you really need for your xM build, but there's more in the next section that could speed things up immensely before you start the actual build.
Taking advantage of earlier downloaded tarballs [OPTIONAL]
A good deal that goes into a Yocto build is simply downloading all of the source, but if you already have access to a directory filled with appropriate tarballs, you can save time.
It may be that you've been working with another build system (OpenEmbedded, Angstrom, etc) for which you've built up a sizable directory of source tarballs. Or perhaps someone else has such a directory for which you have read access. You can take advantage of all those tarballs in one of two ways.
First, you can simply add the following content to your local.conf file, which represents where you want BitBake to go looking for all source tarballs before doing a download (the source mirror URL should obviously represent the location of the tarballs on your system):
SOURCE_MIRROR_URL ?= "file:///home/rpjday/y/src/dl/" INHERIT += "own-mirrors" BB_GENERATE_MIRROR_TARBALLS = "1" # BB_NO_NETWORK = "1"
A slight variation of that is to create a separate config file named site.conf containing much the same content (with the addition of the SCONF_VERSION line):
SCONF_VERSION = "1" SOURCE_MIRROR_URL ?= "file:///home/rpjday/y/src/dl/" INHERIT += "own-mirrors" BB_GENERATE_MIRROR_TARBALLS = "1" # BB_NO_NETWORK = "1"
and place that file (with exactly that name) in your conf directory -- that's typically a simpler solution than having to edit your local.conf for every new build. (Even easier is to have just one copy of that site.conf file somewhere and symlink to it for every new build.)
The final line of:
# BB_NO_NETWORK = "1"
can be uncommented if you want to test a build where all source must come from your local directory and you're not allowed to download anything from the Internet.
Finally, doing the build
Now that everything seems to be in place, you need to select a particular image to build (in our case, for your BeagleBoard xM), and if this is your first time with Yocto, it's worth trying one of the smallest and simplest ones:
$ bitbake core-image-minimal
then just kick back and wait for it to finish. But here are a couple variations if you want to play around.
First, you can fetch all the necessary sources without starting the build with:
$ bitbake -c fetchall core-image-minimal
This guarantees that you have all the sources for that bitbake target in case you need to disconnect from the net and run off somewhere, while still being able to do a build later offline.
Also, by default, bitbake will abort upon the first error, but you can tell it to keep going with:
$ bitbake -k core-image-minimal
In any event, if everything's worked until now, start the build.
The product of a Yocto build
If your build succeeds, this means that Yocto has produced whatever are the appropriate images for your board, and that might include a bootloader, kernel, root filesystem and so on -- the set of final images will depend on your board.
These final images are always found in the tmp/deploy/images/ in your current build directory, and here are the results for our BeagleBoard xM build:
$ ls -F core-image-minimal-beagleboard-20121120113536.rootfs.jffs2 core-image-minimal-beagleboard-20121120113536.rootfs.tar.bz2 core-image-minimal-beagleboard.jffs2@ core-image-minimal-beagleboard.tar.bz2@ MLO-beagleboard@ MLO-beagleboard-1.5.0+git1+9f94c6577e3a018b6b75cbe39f32bb331871f915-r0* modules-3.4.11-yocto-standard-r4.3-beagleboard.tgz README_-_DO_NOT_DELETE_FILES_IN_THIS_DIRECTORY.txt u-boot-beagleboard.bin@ u-boot-beagleboard-v2011.06+git6+b1af6f532e0d348b153d5c148369229d24af361a-r3.bin* u-boot.bin@ uImage@ uImage-3.4.11+git1+a201268353c030d9fafe00f2041976f7437d9386_1+449f7f520350700858f21a5554b81cc8ad23267d-r4.3-beagleboard-20121120113536.bin uImage-beagleboard.bin@ x-load-beagleboard-1.5.0+git1+9f94c6577e3a018b6b75cbe39f32bb331871f915-r0.bin.ift* x-load-beagleboard.bin.ift@ $
A number of the above will be symlinks to other files in the same directory, but the images should be self-explanatory. That is, if you're building for a BeagleBoard xM, it's your responsibility to know that what you need to create a bootable SD card is an MLO file, a U-Boot image, a kernel and so on, and additionally how to format the SD card for the xM, populate it, etc, etc. In short, Yocto will generate the objects you need, and it's up to you to know how to use them.
Does it boot?
Once you format an SD card properly and populate it with the images representing the X-loader, U-Boot loader, kernel and root filesystem, it will indeed boot a BeagleBoard xM (rev C), as I've tested it. However, in order to watch the boot process and drive a flat panel display, you should add a uEnv.txt file to the boot partition:
mpurate=auto dvimode="hd720 omapfb.vram=0:8M,1:4M,2:4M" vram=16M optargs="consoleblank=0" console="tty0 console=ttyO2,115200n8"