Introduction

This is the chapter web page to support the content in Chapter 7 of the book: Exploring BeagleBone – Tools and Techniques for Building with Embedded Linux. The summary introduction to the chapter is as follows:

To this point in the book, all of the code is built and executed directly on the BeagleBone. However, for larger projects this can be impractical, as you may need to manage many source files within a single project. In addition, compilation times can be slow on the BBB for building large projects. This chapter first describes how you can use your desktop computer to develop applications that can be deployed directly to the BBB. The Eclipse integrated development environment (IDE) is then introduced, which allows for advanced development capabilities, such as remote debugging. The chapter finishes by outlining how you can build a custom Linux kernel.

Learning Outcomes

After completing this chapter, you should be able to:

  • Install a cross‐compilation toolchain on desktop Linux that can be used to build applications for the BBB using your desktop PC.
  • Use a multiarch package manager to install multi‐architecture third party libraries that may be required for cross‐compilation.
  • Set up a change root on a Linux desktop computer that can be used to maintain an ARM Linux distribution.
  • Emulate the ARM architecture on the desktop PC using QEMU.
  • Install and configure the Eclipse integrated development environment (IDE) for cross‐compilation to build BBB applications.
  • Configure Eclipse for remote deployment of applications, remote debugging, GitHub integration, and automated documentation.
  • Describe the steps involved in building a custom Linux distribution and use external resources on the chapter web page to build a custom kernel.

Important Notes and Updates

Due to a current problem with the unstable Debian repositories, it is recommended that you remove the entries from the sources.list file after you have installed the cross-compilation toolchain as described in the chapter.

Unfortunately, it gets worse! Under Debian 7.0 — Emdebian.org did have ‘unstable’ packages (i.e., specifically for Debian Wheezy) that worked perfectly, as described in the chapter, but their server was compromised and the Wheezy packages now need to be restored. As of today (1st March 2015), this has not taken place and there is now a gap in the availability of cross-compilation toolchains for Debian Wheezy. I present below a guide for following the steps that are in the book using Debian 8.0 (code name Jessie). The only pages that are affected by this problem are pages 253 and 254 — however, the subsequent steps are reliant on the installation of a cross toolchain. Here is the statement from Debian.org:

Wheezy has unfortunately been poorly supported for cross-toolchains due to manpower shortage and us assuming multiarch crosstoolchains would be ready sooner so the old toolchains stopped being maintained too early. Sorry about that.

Emdebian.org is now back after an outage. So the existing Lenny and Squeeze crosstoolchains are available again, as are new multiarch-built cross-toolchains for Jessie. For unstable there are cross-toolchains in unstable now.

But Wheezy is still a gap. I tried rebuilding some toolchains for wheezy (with buildcross) and hit problems. If someone wanted to work on fixing that then emdebian would be happy to host them.

Installing a Toolchain for Debian 8 (Jessie)

[Added March 1st 2015] Page 252 in the book describes how to install a toolchain under Debian Wheezy. Unfortunately, due to the severe server problems that are described above on the Debian.org servers, you may have difficulty in following the steps described in the book until Debian.org resolve the problems with Debian Wheezy.

As a result, I have added the following step-by-step guide that describes how to complete the steps under Debian Jessie and I have added a warning to the web page for Chapter 3 that encourages readers to install Debian 8 (Jessie), rather than Debian 7 (Wheezy). The good news is that approach, which is only slightly different than the one presented in the book, will hopefully persist throughout the lifetime of the new Debian 8 release, which took place on the 25th of April 2015.

Debian 8 — Jessie (click to see a larger version)

C/C++ Cross-compilation on the BeagleBone Platform

This video introduces C/C++ cross-compilation on the BeagleBone platform under Debian (Jessie), and is applicable to any embedded Linux development. I show the steps that are necessary to set up a toolchain, the Eclipse CDT (Luna) environment and use the Target Management RSE (Remote System Environment) plugin to communicate with the BeagleBone. Finally, I demonstrate how you can set up a cross-platform debugging environment within Eclipse, where you can use gdbserver on the ARM device and gdb-multiarch on the client device to establish a full debugging environment.

Step 1: Initial configuration for a brand-new Debian Jessie image

The first step is to check that your version of Debian is somewhat consistent with the one that is described in this guide — you can test this using the following command:

Or, if you want to show off!

If it is not Jessie — e.g., Wheezy (7.x) is listed then please see the description on the Chapter 3 web page.

You should first install the sudo tool on your Linux distribution so that the desktop Linux steps are consistent with the remaining steps in the book chapter:

The visudo command allows you to add an entry for the main user (e.g., molloyd) to the /etc/sudoers file, as follows:

Step 2: Update the sources lists

As described on page 253, the list of sources must be updated and this is performed slightly differently under Debian Jessie than Debian Wheezy:

Add the line “deb http://emdebian.org/tools/debian jessie main” to the crosstools.list file as is echoed below:

Then use curl to install the emdebian toolchain archive key.

Step 3: Add an armhf foreign architecture and update

This step is useful later for installing cross-development libraries but it is a good time to perform it, and it is very important that you perform an update as follows:

Step 4: Install the Crossbuild tools

This step is performed in the book at the top of page 254, but it is actually more straightforward under Debian Jessie. The step to perform is:

Step 5: Test the installation

Similar steps can be performed to the steps in the book on pages 254 and 255, but they are presented here for completeness:

There was no requirement to add a symbolic link to the g++ and gcc executables as this is performed automatically. You can then build a test application, as follows:

If the testARM.cpp program builds correctly then all is in order. As described in the book, the failure on the last line is expected as my x86 desktop Debian distribution is not configured to execute ARM instructions.

However, you can transfer the binary executable file directly to the BBB so that it can be tested. For example:

Where you can see that it executed correctly on the BeagleBone. You are now ready to follow the other steps in the book, but I have added two optional steps that you can perform, which align with the remaining materials in the chapter.

Step 6: Testing Multiarch (optional)

As described on page 255, multi-package installs can be very useful for development and they are available under Debian Jessie, just as they are described under Debian Wheezy in the book. You can install a library as follows (please pay particular attention to the :armhf postfix):

Step 7: Emulating the armhf architecture using QEMU (optional)

As described in detail on page 258, it is possible to emulate the armhf architecture under the desktop machine architecture using QEMU. The same steps are available under Debian Jessie as are described in the book:

So, now you are hopefully up and running under Debian Jessie (version 8)with the same features that are described in the book for Debian Wheezy (version 7). The video that is listed on this page will be updated to account for these changes.

Installing a Toolchain for Debian 7 (Wheezy)

In this guide the Linaro (www.linaro.org) pre-built cross development tools are installed under Debian Wheezy. These steps will work under Jessie, but the solution is not as well integrated with the Debian distribution as the solution that is presented above. Use this guide if you absolutely, definitely have to have a cross-compilation toolchain under Debian 7 (Wheezy).

Step 1: Initial configuration for a brand-new Debian Wheezy image (Linaro)

The first step is to check that your version of Debian is somewhat consistent with the one that is described in this guide — you can test this using the following command:

I am assuming that sudo is installed. If not, please use the same steps as above for Debian Jessie.

Step 2: Update the sources list

As described on page 253, the list of sources must be updated and this is performed slightly differently under Debian Wheezy. The important thing here is to ensure that you have access to the latest version of the gcc compiler for amd64:

Add the line to the sources.list file that is echoed below.

Step 3: Add foreign architectures and update

This step is useful later for installing cross-development libraries but it is a good time to perform it, and it is very important that you perform an update as follows:

There are also important i386 packages that we need to install on the 64-bit architecture:

Step 4: Download the Linaro Toolchain

If you go to the Linaro release server at: http://releases.linaro.org/ you can determine the latest version. At this point http://releases.linaro.org/14.11/components/toolchain/binaries hosts the latest binary releases. For the BeagleBone we require the arm-linux-gnueabihf release. In this directory there is the gcc compiler, with the name gcc-linaro-4.9-2014.11-X86_64_arm-linux-gnueabihf.tar.xz. We can download this and decompress it as follows:

Step 5: Test the installation

Similar steps can be performed to the steps in the book on pages 254 and 255, but they are presented here for completeness. We can go to the bin directory of the distribution and execute the gcc compiler.

Unfortunately, under Wheezy it is quite likely that this will fail with the message as above. To fix this problem you need to ensure the the sources.list is set as in Step 2 above and if you type the following you should see a version that is greater than 2.19. If not update and install libc6 as follows:

It is a bit unwieldy typing this each time so you can place this folder in a central location, or you can leave it in the user account and set an environment variable as follows when you are cross-compiling:

You can now build a test program and If the test.cpp program builds correctly then all is in order. As described in the book, the failure on the last line is expected as my x86 desktop Debian distribution is not configured to execute ARM instructions.

However, you can transfer the binary executable file directly to the BBB so that it can be tested. For example:

Where you can see that it executed correctly on the BeagleBone. You are now ready to follow the other steps in the book.

Additional Materials

Manual Kernel Build for the BBB

[updated March 2015] Please note that the following discussion is specific to the Debian armhf release. This process constantly evolves and it is highly likely that there will be changes required to the process listed here. Please check the website http://eewiki.net/display/linuxonarm/BeagleBone for updates to this process. The following discussion provides you with a guide to the steps involved in building a Linux kernel and deploying a Linux image to an SD card that can be used to boot your BBB.

Building Das U-Boot

The bootloader, discussed in Chapter 3, is the first component to be built. You can download the source code to your desktop machine using the following:

Go to https://github.com/eewiki/u-boot-patches and find the latest u-boot patch for the AM335x. Presently that is v2015.01. Therefore, ensure that you are using the same branch of u-boot (e.g., v2015.01). You can use any name for the branch name (EBBBoot in this case):

Download the u-boot patch for that branch (all on one line):

Then apply it to the current source code for u-boot:

Set up the build environment and then build u-boot:

After a short build process you will have the x-loader MLO file and the u-boot file that will allow you to boot your kernel image:

Install i386 support (if using amd64)

You must install the 32-bit libraries for the following packages in order to build the kernel. If this step works correctly then you will not have to install an i386 change root (as listed in the next step). To do this under Debian Jessie, perform the following steps:

Then, you must update the list of available packages and install the i368 libraries, as follows:

Installing a Change Root for i386 (no longer required under Jessie)

It can be difficult to build the Linux kernel on the Debian arm64 architecture due to the need for 32-bit libraries and tools. If you are using a 32-bit x86 Linux distribution, this step is not necessary. As Debian multiarch matures, this will not be as significant an issue; however, for the moment the easiest way to cross-build the Linux kernel is to install a change root for i386 and use that change root to build the Linux kernel. The steps to install the change root are quite similar to the change root that was installed earlier in this chapter for ARM, except applied to i386:

Copy the static QEMU emulator into the change root from your “regular” root and then change the root, as you did for the armhf change root:

Finally, install Git on the i386 change root:

Building the Linux Kernel

Next, you can checkout the source code for the Linux kernel and then build it using the RobertCNelson Git repository. This is performed within the /home directory of the i386 change root in change root mode:

I will checkout the Linux kernel version 3.18 so that I can test it, but choose whichever version you prefer:

Install any missing dependencies:

Then build the kernel when all dependencies are satisfied:

After the kernel begins building you will be presented with the kernel configuration tool displayed in Figure 7-13 (within the book) and below. This tool enables you to configure the kernel. For example, you can change the SPI options Device Drivers ⇒ “SPI Support” ⇒ enable “Debug support for SPI drivers.

Figure 7-13: (Jessie Build) The kernel configuration tool

After some time the Linux kernel will be built and you can see the files in the deploy directory as follows:

You now have a complete kernel; however, the kernel is only one part of a Linux distribution. The easiest way to put a file system in place is to download a very basic one that includes the key tools and libraries. Robert has also made a minimum file system available that can be used.

Downloading a Root File System

Go to the site http://rcn-ee.net/rootfs/eewiki/minfs/and find a base image for your preferred distribution. For example, if you are using Debian 7.3 minimal for armhf you can download the following:

Preparing the SD Card

For the next steps you have to be certain of your SD card device. It is possible to use /dev/mmcblk0 on local Linux installations, but that is not always available. The alternative is to use lsblk to identify the drive. Removing and re-inserting the SD card will confirm your device identity.

Determine the SD card device identity on your Linux OS. In this case it is /dev/sdd, but /dev/sdX has been used in the following process to ensure that readers do not type in the steps verbatim, without checking their drive id. The following process will destroy the current data on the SD card.

First, unmount your SD card; otherwise, it will be seen as being busy by the OS. For example, the SD card that was used is a 2 GB card with an older BBB distribution:

Now, format the card (all contents will be lost):

Create the partition table using sfdisk (from Robert’s script):

Note that the “>” should appear as a sfdisk prompt after pressing Enter on the first line and that __EOF__ is two underscore characters on either side of EOF. Make the vFat and ext4 partitions:

Then, create two mount points (-p means generate no error if they already exist) and mount the two SD card partitions at these points:

Copying the Linux Image and Kernel Files

Next, you need to copy all the Linux files over to the SD card partitions. Some files are copied to the FAT partition and some to the Linux partition. Copy the u-boot files to the FAT partition:

Create a uEnv.txt file with the following content and copy it to the FAT partition. Note that the uenvcmd should all be on one single line:

Copy the files from the change root, but there is no need to use the chroot command. You can just browse to the location of the files on your “real” root. Therefore, the change root directory in this case is /wheezy-i386. Copy the root file system:

Next, go to the location of the deploy directory of the kernel that you built. It should look like this:

All of the following commands deploy the kernel files to the correct locations and take place in the /wheezy-i386/home/linux-dev/deploy directory:

Configuring the Linux Startup Settings

The kernel files are now all in place, and you can configure the image before you use it. The first task will be to edit the file system table (/etc/fstab) so that the SD card partitions are available as the startup file system:

You can also enable the network adapter and the serial terminal so that you will be able to connect to the BBB on boot:

To enable the serial terminal, edit the following line in /etc/inittab

using the following steps:

Finally, unmount the SD card and boot your BBB with the card:

Testing the New Image on the BBB

Remember to hold the boot button when you attach the power. You can use a USB Serial TTL cable, and if you watch with the terminal window you will see an output like the following:

You can log in with the username debian and the password temppwd:

The BBB is attached to the network with the address 192.168.1.114, which can be tested by connecting to the Apache web server, which is installed on this image and can be connected to as captured in the figure below. This Linux image occupies 358MB of the SD card:

itworks

Figure: Apache Server running on the new BBB image

Flashing the BBB eMMC with this Image

You now have a brand-new SD card image of Debian that can be used to boot the BBB. The last thing you might like to do is write this image to the BBB’s eMMC. Robert Nelson has written a script for this that you can execute directly on the BBB. First install Git on the BBB itself, as it is not present in the new Debian image by default:

Then clone Robert’s boot scripts:

Execute the beaglebone-black-eMMC-flasher.sh script as root:

If all goes well, you will see the following message a few minutes later (remember you are using a much smaller image than the standard image):

And the four LEDs are comfortingly blue! You can power down the BBB by holding the power button for about eight seconds. Remove the micro-SD card and press the power button again. Your BBB should boot using the new image.

Note that you can also use the update_kernel script to update the kernel to the latest version should it be required.

Errata

  • Page 261. (loc. 7667). In the first paragraph of the section “Configuring Eclipse for Cross-Compilation” the sentence “Then click Finish.” should not be present. The remaining instructions are complete and correct.
  • Page 263. The include paths has changed to “/usr/include/arm-linux-gnueabihf/” from “/usr/arm-linux-gnueabihf/include/”