Build Howto

From XApple
Jump to: navigation, search

This document describes the procedures and tips for building the source code of the XApp-le Linux core SDK (covering uboot/kernel/initramfs), based on the Roseapple-Pi board. The methods to flash the built images to the SD card are also included.


Prepare the development environment

The following steps are for Linux machine on Intel CPU only, specifically on Ubuntu and CentOS 7.x as examples. We need to use cross-compile tool-chain to compile the OS image from an Intel CPU host machine. You can copy and paste the following shell commands during the build process.

Install the build arm toolchain on x86/amd64 build host

The ARM compiler toolchain on x86 host is used to generate binary files for the target ARM processors.


	$ sudo apt-get install -y make curl git  gcc-arm-linux-gnueabihf u-boot-tools device-tree-compiler

Libraries (Optional)

	$ sudo apt-get install build-essential lib32z1


Git on Centos 6.x is 1.7.1 which will fail the repo command that requires at least version 1.7.2. We can install and updated git by doing the following:

	$ sudo wget && sudo rpm -ivh epel-release-latest-6.noarch.rpm  
	$ rpm -ivh
	$ yum --enablerepo=rpmforge-extras install git-

Source: git to version 1.7.12 from rpmforge

Make sure EPEL repo is configured.

	$ sudo wget && sudo rpm -ivh epel-release-latest-7.noarch.rpm 

Install ARM toolchains on CentOS.

	$ sudo yum install -y gcc gcc-c++ gcc-arm-linux-gnu binutils-arm-linux-gnu

Make sure all the toolchain binaries exist after yum has been installed.

Download the source code

Install "repo" command

See repo in android project for usage detail.

	$ mkdir ~/bin
	$ PATH=~/bin:$PATH
	$ curl > ~/bin/repo
	$ chmod a+x ~/bin/repo

Prepare the build directory

	$ export SDK_ROOT=${HOME}/sdk_root && mkdir ${SDK_ROOT} && cd ${SDK_ROOT}

Download source code from Github

There are four repositories we need to pull down. This information is recorded in defaults.xml. repo command will parse the xml file to create .repo directory and later pull down all repositories by repo sync command.

Pull source tree with read-only https protocol.

	$ repo init -u
	$ repo sync
	$ repo start --all master

If the public key has been added to github, the following commands can be used instead. This method is preferred for the core XApp-le developers (writers), since the developer's account/password won't be asked repeatedly for the four contained repositories.

	$ repo init -u
	$ repo sync # to retrieve u-boot,linux repos.
	$ repo start --all master

Build the source code

	$ cd ${SDK_ROOT}/owl
	$ ./

	Select board type:
	     1. bubble_gum
             2. bubble_gum_nor
	     3. bubble_gum_sd
	     4. gb5_1080p
	     5. gb5_720p
	     6. gb5_wxga
             7. gb5_wxga_sd
	     8. gb5_xga
             9. lemaker_guitar

	Which would you like? [bubble_gum] 3
	s500 linux bubble_gum_sd configured.

Configure the kernel (Optional)

	Before building with 'make' you can configure the kernel if needed:
        For ubuntu type:
        $ make kernel-config
	For other distros depends which toolchain you use:
        $ make CROSS_COMPILE=arm-linux-gnueabihf- kernel-config or make CROSS_COMPILE=arm-linux-gnu- kernel-config


Then, type the 'make' command to build the images.

	$ make

The above config & make procedure can also be simply substituted by the following commands.

	$ cd ${SDK_ROOT}
	$ ./

Centos 6.x/7.x

ARM CPU toolchain on CentOS use different prefix(arm-linux-gnu-) for gcc,ld,ar and nm commands

#under sdk_root/owl
make CROSS_COMPILE=arm-linux-gnu-

Prepare to access the SD card

We need to partition and format the SD card on the host machine (PC). If the SD card is accessed through a built-in card reader on the PC, then the card's device name will typically be /dev/mmcblk0. However, if a USB to SD adaptor is used instead, the device name may appear to be /dev/sdX, where 'x' could be b, c, d, or other letters. Please specify 'X' cautiously.

One way to verify the actual device name is to use the 'dmesg' command to check the latest kernel message immediately after the SD card has been plugged into the PC.

Create GPT on the SD card

Note: Before proceeding to the following steps, make sure that no existing partitions on the SD card have been mounted on the PC.

        $ export SDCARD=/dev/mmcblk0
        if a built-in SD card reader is used, 
        $ export SDCARD=/dev/sdX
        in case that a SD-to-USB adapter has been used instead.

	$ sudo parted -s ${SDCARD} mklabel gpt
	$ sudo parted -s ${SDCARD} unit s mkpart primary fat32 16384 147455

To show the status of the created partition (assuming a 8G SD card is used):

	$ sudo parted -s ${SDCARD} unit s print

	Model: SD SD8GB (sd/mmc)
	Disk /dev/mmcblk0: 15564800s
	Sector size (logical/physical): 512B/512B
	Partition Table: gpt
	Number  Start   End      Size     File system  Name     Flags
	 1      16384s  147455s  131072s               primary  msftdata

Flash bootloader (mbrec) & uboot

	$ cd ${SDK_ROOT}/owl/out/s500_linux_bubble_gum_sd/images
	$ sudo dd if=bootloader.bin of=${SDCARD} bs=512 seek=4097
	$ sudo dd if=u-boot-dtb.img of=${SDCARD} bs=512 seek=6144

Flash the vfat boot partition, for kernel, dtb, initramfs, etc.

	$ cd ${SDK_ROOT}/owl/out/s500_linux_bubble_gum_sd/images
        $ sudo dd if=misc.img of=${SDCARD}p1
        if a built-in SD card reader is used, 
        $ sudo dd if=misc.img of=${SDCARD}1
        in case that a SD-to-USB adapter has been used instead.

Create the ext4 system partition (Optional)

	$ sudo parted ${SDCARD}

	Enter the following commands manually: "unit s mkpart primary ext4 147456 -1",
	then enter 'Yes' to fix the end sector number.

        $ sudo mkfs.ext4 -L system ${SDCARD}p2
        if a built-in SD card reader is used, 
        $ sudo mkfs.ext4 -L system ${SDCARD}2
        in case that a SD-to-USB adapter has been used instead.

	Any suitable root-fs can then be put into this system partition.

Create a simple debian armhf rootfs for the ext4 system partition (Optional)

	Install the required tools:

	$ sudo apt-get install qemu-user-static binfmt-support debootstrap

	Prepare the rootfs build directory:

	$ export rootfsdir=${HOME}/rootfs && mkdir ${rootfsdir}

	Retrieve the armhf packages to the rootfs build directory:

	$ export distro=jessie
	$ sudo debootstrap --arch=armhf --foreign ${distro} ${rootfsdir}

	$ sudo cp /usr/bin/qemu-arm-static ${rootfsdir}/usr/bin
	$ sudo cp /etc/resolv.conf ${rootfsdir}/etc

	Chroot in to the new rootfs and install, configure the packages:

	$ sudo chroot ${rootfsdir}

	# export distro=jessie
	# export LANG=C
	# /debootstrap/debootstrap --second-stage

	Once the package installation has finished, setup some basic support files:

	# cat << EOT > /etc/apt/sources.list
	deb ${distro} main contrib non-free
	deb ${distro}-updates main contrib non-free
	deb ${distro}/updates main contrib non-free

	# echo <<EOT >> /etc/network/interfaces
	allow-hotplug eth0
	iface eth0 inet dhcp

	# echo roseapple > /etc/hostname

	Update packages and install, configure the locales:

	# apt-get update  && apt-get dist-upgrade
	# apt-get install locales dialog
	# dpkg-reconfigure locales

	Leave the chroot environment:

	# exit

	Remove unneeded support files:

	$ sudo rm ${rootfsdir}/etc/resolv.conf
	$ sudo rm ${rootfsdir}/usr/bin/qemu-arm-static

	Now you can copy the armhf rootfs to the (ext4 system) partition (sd-card)

Copy the kernel modules to the rootfs (ext4 system) partition (Optional)

	$ sudo mount ${SDCARD}p2 /mnt
        if a built-in SD card reader is used, 
        $ sudo mount ${SDCARD}2 /mnt
        in case that a SD-to-USB adapter has been used instead.
	$ sudo rsync -avc ${SDK_ROOT}/owl/out/s500_linux_bubble_gum_sd/modules/lib/. /mnt/lib/.
        $ sudo sync
        $ sudo umount /mnt

        or if you prefer you can extract the ${SDK_ROOT}/owl/out/s500_linux_bubble_gum_sd/burn/modules.tgz in your rootfs instead.

Specify the root-fs partition in uenv.txt (Optional)

The content of uenv.txt in this partition may look like the following example, which was used for some Ubuntu testing root-fs image.

	uenvcmd=setenv os_type linux;
	bootargs=earlyprintk clk_ignore_unused selinux=0 scandelay console=ttyS2,115200n8 console=tty0 root=/dev/mmcblk0p2


  • The default content is different from this example.
  • In this example, assume /dev/mmcblk0p2 is the root-fs.
  • If the root-fs doesn't exist, the "root=" argument should be removed so that the kernel will boot with the initramfs only. Or, the 'debug' argument can be added in bootargs to force the kernel to enter a shell with initramfs.
  • The "console=ttyS2,115200n8" argument is used to enable the UART console. (Optional)
  • The "console=tty0" argument is used to enable the console associated with the display and a keyboard.

Supplementary Tips

Source code tree layout

You will see the following source tree after a successful git pull using the repo command. kernel, linux, owl and u-boot repositories are all pulled down from github. can be used to automate the whole image build process.

$ tree -L 2
├── kernel
    ├── android
│   ├── arch
│   ├── tools
│   ├── usr
│   └── virt
├── linux
│   ├── initramfs
│   ├── Makefile
│   ├── ramdisk.img
│   └── readme
├── owl
│   ├── readme.txt
│   ├── scripts
│   └── tools
└── u-boot
    ├── api
    ├── snapshot.commit
    ├── test
    └── tools

53 directories, 25 files

Partition Layout

	#0      +--------------------+
	        | MBR (unused)       |
	#1      +--------------------+
	        | GPT hdr & Entries  |
	#34     +--------------------+
	        |      .....         |
	#4097   +--------------------+
	        |  bootloader.bin    | /* bootstrap loader, to be loaded by BROM */
	        |      .....         |    
	#6144   +--------------------+
	        |  uboot.bin         | /* uboot, to be loaded by bootloader.bin */
	        |      .....         | 
	#16384  +--------------------+
	        |  uImage            | /* the first usable partition: */
	        |  kernel.dtb        | /* vfat, for kernel and initramfs */
	        |  ramdisk.img       |          
	        |  uenv.txt          |          
	        |  boot_logo.bmp.gz  |      
	        |      .....         |           
	#147456 +--------------------+ /* the second usable partition: */ 
	        |      .....         | /& typically ext4, for root-fs */
	        |                    | /* other linux filesystem also possible: btrfs */
	        |      .....         |

The four repositories included in the SDK can also be downloaded independently.

For example, the uboot and the kernel source can be downloaded by the following commands.

        $ git clone
        $ git clone
Personal tools