Skip to content

How to build an image

Jump to bottom
Pier Luigi Fiorini edited this page May 24, 2015 · 4 revisions

To build images you need mauibuild which is the Hawaii build system, takes care of building the Yocto base system and all the components specified by a manifest JSON file into their own tree.

Prepare the environment

Prerequisites

Hawaii base system is based on Poky 9.x (dylan), install the Essential packages as explained in the Required Packages for the Host Development System section of the reference manual before preceding.

You can also read the quick start guide to learn more about Yocto.

Also install the following packages:

  • autoconf
  • automake
  • python
  • python-gi
  • fontconfig
  • elfutils
  • bc

If you build disk images you will also need:

  • guestfish
  • guestfsd
  • guestmount
  • libguestfs-tools

To make live images install:

  • squashfs-tools
  • xorriso

To build the man pages on Debian and Ubuntu:

  • xlstproc
  • docbook
  • docbook-xml
  • docbook-xsl

To build the man pages on Fedora:

  • xsltproc
  • docbook-utils
  • docbook-style-xsl

A 64-bit host operating system is required.

You also need:

  • Linux 2.6.28 or newer
  • linux-user-chroot and ostree, follow the next sections for more information
  • gummiboot to make x86_64 live images, follow the next sections for more information

Disable colored output

Output is colored by default.

To turn colors off type this command before running mauibuild:

export ANSI_COLORS_DISABLED=1

Setup guestfs on Ubuntu

To build disk images on Ubuntu you will need to make a symbolic link to the right libguestfs path:

sudo ln -s /usr/lib/guestfs /usr/lib/x86_64-linux-gnu/guestfs

This was tested on Ubuntu 12.10 only, it might be different in another release.

Configure FUSE

If you run mauibuld with an unprivileged user (i.e. not root) and you want to build disk images, your user must be in the fuse group and FUSE must be configured to allow non-root users to specify the allow_other or allow_root mount options.

To add the currently logged-in user to the fuse group on Debian and Ubuntu systems:

sudo adduser $USER fuse

Now edit /etc/fuse.conf and uncomment user_allow_other.

Download and install linux-user-chroot

Install the following additional packages:

  • libtool

Here's how you download and install linux-user-chroot:

mkdir -p ~/git
cd ~/git
git clone git://git.gnome.org/linux-user-chroot
cd linux-user-chroot
./autogen.sh --prefix=/usr --enable-newnet-helper
make
sudo make install
sudo chmod +s /usr/bin/linux-user-chroot{,-newnet}

Download and install ostree

Install the following additional packages, on Debian and Ubuntu:

  • zlib1g-dev
  • libarchive-dev
  • libattr1-dev
  • libglib2.0-dev
  • libsoup2.4-dev
  • xsltproc
  • gtk-doc-tools

Or if you are on Fedora:

  • zlib-devel
  • libarchive-devel
  • libattr-devel
  • glib2-devel
  • libsoup-devel
  • xsltproc
  • gtk-doc-tools

Here's how you download and install ostree:

mkdir -p ~/git
cd ~/git
git clone git://git.gnome.org/ostree
cd ostree
git checkout ecb3f0de035c09d8b280ac116eeede483638fd5d # Until we support Deployment Model 2 (https://wiki.gnome.org/OSTree/DeploymentModel2)
git submodule init
git submodule update
./autogen.sh --prefix=/usr --with-libarchive --enable-documentation --enable-kernel-updates --enable-grub2-hook
make
sudo make install
sudo mkdir /ostree

Download and install gummiboot

If you distro has gummiboot packaged, install the package.

Otherwise, if you distro doesn't package gummiboot, here's how to build it.

gummiboot requires GNU Efi, unless you can install a package here's how to build it from sources:

mkdir -p ~/git
cd ~/git
git clone git://git.code.sf.net/p/gnu-efi/code gnu-efi-code
cd gnu-efi-code
cd gnu-efi-3.0
make
sudo make install PREFIX=/usr

gummiboot also requires the following packages on Debian and Ubuntu:

  • libblkid-dev

Or if you are on Fedora:

  • libblkid-devel

Build gummiboot:

mkdir -p ~/git
cd ~/git
git clone git://anongit.freedesktop.org/gummiboot
cd gummiboot
./autogen.sh c
make
sudo make install

Download the manifest

Create a directory and checkout the maui repository. Here's an example:

mkdir ~/git
cd ~/git
git clone git://github.com/mauios/maui.git

Install mauibuild

From the mauibuild checkout directory type:

./autogen.sh --enable-maintainer-mode
make
sudo make install

Configure mauibuild

mkdir -p ~/mauibuildwork
cd ~/mauibuildwork
ln -s ~/git/maui/manifest.json

First build

For the first build you need to fetch all components. However this has to be repeated every time you want to fetch a new version of the components.

The command below will mirror all the upstream git repositories and will make a source snapshot JSON file.

mauibuild make -n resolve -u -- --fetch-all

Components fetched by a typical Hawaii 0.1 build takes at least 2.2 GB.

The above command output is something like:

mauibuild: New source snapshot: /home/plfiorini/mauibuildwork/snapshots/2012.1-596f8b01afda69f919254c0c93c57f04ea01cbf8cdc222aebfb6b9fa4d823990.json

The source snapshot file is in the <workdir>/snapshots/<year>.<number>-<hash>.json format, where:

  • <workdir> is the directory where the build happens
  • <year> is the current year
  • <number> is a sequential number
  • <hash> a sha1 hash of the source snapshot

Build

Now build all the components:

mauibuild make -n build

This command will build the base system and components, and compose the following targets ready to be fetched by clients:

  • maui/buildmaster/x86_64-runtime, standard tree suitable for most users
  • maui/buildmaster/x86_64-runtime-debug, same with debugging information
  • maui/buildmaster/x86_64-devel, tree suitable for developers
  • maui/buildmaster/x86_64-devel-debug, same with debugging information
  • maui/buildmaster/x86_64-live, same as runtime plus tools for the live media

Tree names are in the <osname>/buildmaster/<arch>-<name> format where:

  • <osname> is the operating system name as specified in manifest.json
  • <arch> is the architecture (at this moment only x86_64 is supported), possible values are x86_64 and i686
  • <name> is the target name, possible values are: runtime, runtime-debug, devel and devel-debug

A fresh Hawaii 0.1 build takes about 6 hours on an Intel i5 2300 (download time not included) and produces a 4.5 GB OSTree repository.

Since tasks are chained after build other tasks will run:

  • bdiff, produces a JSON with differences between the previous and current builds
  • builddisks, creates or updates disks for QA tests
  • zdisks, compress disks created by the above task

Most people will want to avoid builddisks and zdisks, to do it run the build task this way:

mauibuild make -n build -x builddisks -x zdisks
Clone this wiki locally