~jocave/snapcraft/plainbox-provider-plugin

# Snapcraft Tutorial

Let's make a snap from scratch using Snapcraft! We'll pick something a little

interesting: a webcam server.

## Preparation

You'll want a webcam and a Snappy device. We'll assume you have those,

but if you need help setting up a Snappy install, there is help

[online](https://developer.ubuntu.com/en/snappy/start/).

(Even if you don't have either of those, you can still follow along. You just

won't be able to use the final snap package you create. But you'll get to see

how Snapcraft works, which is still super rewarding.)

You should also install Snapcraft:

    $ sudo add-apt-repository ppa:snappy-dev/snapcraft-daily

    $ sudo apt-get update

    $ sudo apt-get install snapcraft

## Approach

This example is easy because we won't be doing much of the heavy lifting

ourselves. We're going to integrate a couple pieces of code together to make

an interesting app.

Namely, we'll combine a web server with a webcam program and combine

them to serve a new frame every ten seconds.

### The Web Server

Go has a simple web server in its standard libraries. So let's just use that.

It's trivial to write a complete (but basic) web server in a few lines:

    package main

    import "net/http"

    func main() {

        panic(http.ListenAndServe(":8080", http.FileServer(http.Dir("."))))

    }

This will serve the current directory on port `:8080`. If there is an 

`index.html` in the current directory, it will be served. Otherwise a 

directory listing will be shown.

I've provided the above code in a simple GitHub

[repository](https://github.com/mikix/golang-static-http).

### The Webcam Program

There is a webcam program provided in the Ubuntu archives called `fswebcam`.

It has a lot of neat features. But all we'll be needing for now is its ability

to take a webcam freeze frame and drop it to a file by calling it like so:

    $ fswebcam output.jpg

## Snapcraft Recipe

OK, let's create a Snapcraft recipe that combines the above programs into a

useful snap.

Snapcraft reads a single file, `snapcraft.yaml`, which tells it how to combine

code. It contains a list of `parts`, or pieces of code, and some metadata for

the final snap it will create. But let's not worry about the metadata yet.

### Web Server Part

Let's start with the web server.

    parts:

      golang-static-http:

        plugin: go1.4-project

        source: git://github.com/mikix/golang-static-http

You've got a `parts` list with one item, named `golang-static-http`, but we

could call it anything. That part has a few options. A `plugin` option that

tells Snapcraft how to interpret the part. In this case, it's a Go project

using Go 1.4. And finally, a `source` option telling Snapcraft where to

download the code.

Go ahead and create `snapcraft.yaml` with the above contents in an empty

directory.

Now we can build and "stage" this recipe. Staging just means putting the output

of the parts in a common folder that has the same layout as the snap we'll

eventually create. It lets you look at how the snap is constructed and make

sure everything is in place.

    $ snapcraft stage

You'll see a bunch of output, including Snapcraft downloading the Go compiler.

It will use this to compile the code found on GitHub. Eventually when it is

done, you'll be able to inspect the `./stage` folder and see the web server

executable sitting in `./stage/bin`:

    $ ls stage/bin

    golang-static-http

### Webcam Part

Now let's add the webcam program `fswebcam` to our snap. Edit `snapcraft.yaml`

to look like:

    parts:

      golang-static-http:

        plugin: go1.4-project

        source: git://github.com/mikix/golang-static-http

      fswebcam:

        plugin: ubuntu

We've added a new part called `fswebcam` handled by the `ubuntu` plugin. That

plugin will include an Ubuntu package and its dependencies into your snap. It

will use the name of the part as the package name to include.

Now let's stage our recipe again.

    $ snapcraft stage

You'll note that Snapcraft skipped downloading and building 

`golang-static-htpp` again because it knew it had already done so.

You'll also see Snapcraft downloading and unpacking all the Ubuntu packages

into your snap. If you look at `./stage`, you'll see a lot more files now:

    $ ls stage

    bin  etc  lib  usr  var

### Gluing the Parts Together

OK, so we have the two programs in our staging area. But how do we make them

work together?

We'll write a tiny little script that runs the server and `fswebcam` together:

    #!/bin/sh

    set -e

    cd "$SNAPP_APP_DATA_PATH"

    golang-static-http &

    while :; do

        fswebcam shot.jpeg

        sleep 10

    done

Save the above as `webcam-webui` and make it executable:

    $ chmod a+x webcam-webui

Alright, let's put this script in our snap too:

    parts:

      golang-static-http:

        plugin: go1.4-project

        source: git://github.com/mikix/golang-static-http

      fswebcam:

        plugin: ubuntu

      glue:

        plugin: copy

        files:

          webcam-webui: bin/webcam-webui

The `copy` plugin takes a list of files to just directly copy without building

or downloading anything. In this case, we just want to put our glue script in

the `bin/` directory.

If we run Snapcraft again, we won't be surprised:

    $ snapcraft stage

We should now see both the web server and our script in stage/bin (the webcam

program is in stage/usr/bin since it came from Ubuntu):

    $ ls stage/bin

    golang-static-http  webcam-webui

### Package Metadata

"But how do we actually make a snap?", you may be wondering. To do that, we

need some metadata files required by Snappy that describe how our code should

be installed and run.

You can read all about the [format of this metadata](https://developer.ubuntu.com/en/snappy/guides/packaging-format-apps/),

but we'll assume here that you're already familiar.

Let's make a new subdirectory called `meta` and put our Snappy package files

there. Here's the contents of `meta/package.yaml`:

    name: webcam-webui

    version: 1

    vendor: You <you@example.com>

    services:

    - name: webcam-webui

      start: bin/webcam-webui

And a very simple `meta/readme.md`:

    # Webcam web UI

    Exposes your webcam over a web UI

Now that we have that sorted, we can tell Snapcraft where to find our metadata:

    parts:

      golang-static-http:

        plugin: go1.4-project

        source: git://github.com/mikix/golang-static-http

      fswebcam:

        plugin: ubuntu

      glue:

        plugin: copy

        files:

          webcam-webui: bin/webcam-webui

    snappy-metadata: meta

And tell Snapcraft to actually make the snap package:

    $ snapcraft assemble

You should now have a `webcam-webui_1_amd64.snap` file sitting in your

directory (assuming you are running on amd64). Congratulations!

## Next steps

Well done, your first snap using snapcraft is ready. If you want to check out

a few examples for reference or to get inspired, have a look at the 

`examples` directory in the source directory of snapcraft:

    bzr branch lp:snapcraft

    cd snapcraft/examples

In `examples/` you can find a diverse set of examples which should help you 

get started on your own projects.

If you should have any more questions, ask us on

 * `#snappy` on `irc.freenode.net` or

 * the [snappy-app-devel](https://lists.ubuntu.com/mailman/listinfo/snappy-app-devel)

   mailing list