← Back to team overview

ubuntu-phone team mailing list archive

[Porting] How to create a system.img for your port



As the official porting guide is a little incomplete concerning the latest changes, I decided to put together an email with my findings. In the following, I will describe, how to manually create a system.img for the new loop-mounted flipped container layout.

Building the phablet-trusty Android tree for your device creates two files we need later:

 * The boot image with your kernel and the Ubuntu initrd.
 * The Android system image, including the Android initrd image as

You can find those files in the Android output directory out/target/product/DEVICE. In the following we will refer to them as boot.img and android-system.img respectively. Note that the system image is usually named system.img, but we don't want to confuse it with the Ubuntu Touch system image we are going to create.

We also need the Ubuntu root filesystem that can be downloaded from https://system-image.ubuntu.com/. The Android tree contains the script build/tools/get-tarball-url.py that prints the full URL of the latest full image available. In the following we will refer to the downloaded file as ubuntu-rootfs.tar.xz.

Now we start by allocating a huge sparse file and create an ext2 filesystem on it. Then we loop-mount the new image on directory system. Note that we can make it quite big with little cost, we are going to shrink it later.

   fallocate -l 2G system.img
   mke2fs -F system.img
   mkdir system
   sudo mount -o loop system.img system

The following steps are all run as root using sudo, so all permissions are preserved and new files are created as root. We need to extract the Ubuntu root filesystem and drop the Android system image at the right place.

   sudo tar -xJ --numeric-owner -f ubuntu-rootfs.tar.xz system
   sudo cp android-system.imgsystem/var/lib/lxc/android/system.img

Now is the time to drop the device-specific configuration files. Make sure, they are also created by user root.

Finally unmount the new image:

   sudo umount system
   rmdir system

Now we shrink the new 2 GB filesystem to its minimal size.

   e2fsck -yf system.img
   resize2fs -M system.img
   e2fsck -yf system.img

So far we have reduced the size of the filesystem, but not the size of the image file itself.

Run dumpe2fs and look for the values "Block size" and "Block count". Their product is the minimum image SIZE in bytes, we need for truncating the image file.

   dumpe2fssystem.img | less
   truncate -s SIZE system.img

The system.img is now fine for read-only mounting, but leaves no headroom for creating or editing files. If we want to mount the system image writable in "developer mode", we should add some free space to it, say 500 MB:

   truncate -s +500M system.img
   resize2fs system.img
   e2fsck -yf system.img

Now we can flash the boot.img mentioned above to the boot partition and and our new system.img to /data/system.img. Then reboot, and Ubuntu Touch should come up fine.

That's it! Hope it helps other porters...

Follow ups