General Device Building Overview [Was, Re: Looking for general device building overview]

Fri Sep 9 06:04:28 UTC 2016

Hi Mike,

On Thu, Sep 08, 2016 at 06:16:58PM -0400, MikeB wrote:
> I feel like I am stumbling around in the dark as I'm learning about getting
> Ubuntu-Core running on new devices.  I'm discovering things in a bottom-up
> direction and I think I'm not seeing some basic concepts that Canonical
> engineers take for granted.  I've trolled through the Ubuntu sites and
> mailing lists trying to get good overview and understanding about subjects
> but have come up empty or, at best, sparse.  Learning about concepts
> through a mailing list "keyhole" is very difficult.
> 
> I think I'm way off on my knowledge about the following.
> 
> * Assertions/Model Assertions - I see them mentioned, but have no idea what
> they are.
> * Gadgets - Again hear and see them a lot, but no clue what they are.  How
> can I create and use one for my target platforms.
> * ubuntu-image - No idea of its status or how to use it.
> * ubuntu-device-flash - Using it now from a recipe but don't know much else
> about it.  Is it obsolete?

> Any pointers to good overviews or documentation would be appreciated.

> Regards, Mike

These are some wonderfully timely questions, that I'm happy to help answer
for you!  This should also help with the problems of your other post, about
the image you've built with ubuntu-device-flash not letting snapd run.

To answer the last question first: up until this week, ubuntu-device-flash
has been The Way to make ubuntu-core images.  However, we've known for some
time that this needed to be replaced, and this in-progress replacement is
called ubuntu-image.

We haven't been writing much about the status of ubuntu-image here because
it's been pre-alpha, and would likely only add to people's frustrations
around image building. ;)  But the images released this week were all made
using ubuntu-image, which is a good indicator that it's now ready to be
shared more widely.

ubuntu-image is now available as a snap.  For the moment, it's only on the
edge channel and requires devmode, so it can be installed as:

  sudo snap install --channel=edge --devmode ubuntu-image

You can also find the source repository for ubuntu-image at:

  https://github.com/CanonicalLtd/ubuntu-image/

Now, ubuntu-image has a number of commandline options, most of which are
only of interest if you're working on ubuntu-image itself (we will clean up
the --help output soon).  The basic usage is just:

  UBUNTU_IMAGE_SKIP_COPY_UNVERIFIED_MODEL=1 \
      ubuntu-image -c edge my-model.assertion -o my_output.img

So, what is a model assertion?  Others can speak more authoritatively than I
can about the definition of a model assertion, but the summary is that this
is a text document declaring what should go into your image.  Instead of
specifying the gadget, kernel, and os snaps as commandline arguments to
ubuntu-device-flash, you declare these in the model assertion, which can
then be signed and referenced by the store and snapd.

If you are making your own image, you will need your own model assertion.

You can find some practical examples here:

  http://people.canonical.com/~vorlon/amd64-generic-model.assertion
  http://people.canonical.com/~vorlon/pi2-model.assertion

These are 90% of the way to what was used in producing this week's images,
which should be enough to get you going for your own local builds.  Note
that current snapd requires model assertions to be signed, so the above
include a signature - but the signature is not valid (and obviously won't be
valid when you make your changes), thus the need for setting
UBUNTU_IMAGE_SKIP_COPY_UNVERIFIED_MODEL=1.

And the main thing you're going to want to permute in your model assertion,
vs. one of our reference assertions, are the snaps that you're using.
You're already using a custom kernel snap; you will also want a custom
gadget snap.

A gadget snap is a snap that details how the kernel and os snap should be
combined into an image for a given device.  This includes partition layouts,
what bootloader snappy uses (grub or uboot), and how to integrate with the
firmware.

The backbone of a gadget snap is the meta/gadget.yaml.  You can find
documentation of this yaml file here:

  https://github.com/CanonicalLtd/ubuntu-image/blob/master/docs/gadget-yaml.rst

And you can find the source for the reference gadget snaps at:

  https://code.launchpad.net/~snappy-dev/snappy-hub/snappy-systems/

And since ubuntu-image is calling 'snap prepare-image' under the hood to
create your ubuntu-core root filesystem, this will also take care of all the
problems with /var/lib/snapd/seed in your other mail!

Hope that helps,
-- 
Steve Langasek                   Give me a lever long enough and a Free OS
Debian Developer                   to set it on, and I can move the world.
Ubuntu Developer                                    http://www.debian.org/
slangasek at ubuntu.com                                     vorlon at debian.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <https://lists.snapcraft.io/archives/devices/attachments/20160908/19349452/attachment.pgp>