Merge lp:~snappy-dev/snapcraft/docs into lp:~snappy-dev/snapcraft/core

[Michael Terry]

Add intro and tutorial docs.

The intro file explains Snappy and the general Snapcraft concepts a bit. It covers the same material as flow.md, so I dropped that file.

The tutorial file goes through crafting a webcam demo snap [1].

I want to add an installing/testing/uploading-to-store section too, but I want to get some experience using the webcam bit and dealing with apparmor for it (seeing if I can get kvm to use my laptop webcam or if I need to have a real USB webcam with a beaglebone). But that addition can happen in a separate branch.

This is taking over from lp:~mvo/snapcraft/docs-1 since mvo is on vacation.

[1] Very similar to https://developer.ubuntu.com/en/snappy/guides/appliance-builder-guide-webcam/

Add intro and tutorial docs.

The intro file explains Snappy and the general Snapcraft concepts a bit. It covers the same material as flow.md, so I dropped that file.

The tutorial file goes through crafting a webcam demo snap [1].

I want to add an installing/testing/uploading-to-store section too, but I want to get some experience using the webcam bit and dealing with apparmor for it (seeing if I can get kvm to use my laptop webcam or if I need to have a real USB webcam with a beaglebone). But that addition can happen in a separate branch.

This is taking over from lp:~mvo/snapcraft/docs-1 since mvo is on vacation.

[1] Very similar to https://developer.ubuntu.com/en/snappy/guides/appliance-builder-guide-webcam/

[Leo Arias (elopio)]

Cool.

review: Approve

=== renamed file 'README.md' => 'HACKING.md'
=== added file 'README.md'
--- README.md	1970-01-01 00:00:00 +0000
+++ README.md	2015-07-31 19:14:03 +0000
@@ -0,0 +1,7 @@
+# Snapcraft
+
+Snapcraft allows easy crafting of snap packages for the Ubuntu Core
+transactional system.
+
+See docs/intro.md for details about the concepts behind
+snapcraft. There is also a tutorial in docs/tutorial.md.
\ No newline at end of file

=== removed file 'docs/flow.md'
--- docs/flow.md	2015-07-02 17:27:53 +0000
+++ docs/flow.md	1970-01-01 00:00:00 +0000
@@ -1,27 +0,0 @@
-# Part Flow
-
-Each part has 3 major user-visible stages: build, stage, and snap.  Put respectively into parts/XXX, stage/, and snap/ directories.
-
-## Build
-
-There are actually several steps rolled into this one conceptual piece.
-
-### Pull (parts/XXX/src)
-
-This gets the source.
-
-### Build (parts/XXX/build and parts/XXX/install)
-
-This builds the source in build/ and does 'make install' or equivalent into install/.  Other parts that depend upon this one will be able to build against this part's install/ folder.
-
-## Stage
-
-This copies all files from parts/XXX/install into stage/ (or hardlinks them).  It complains if there would be any conflicts.
-
-## Snap
-
-This copies all files from stage/ to snap/ while filtering some files that shouldn't be delivered to end user.
-
-## Assemble
-
-This is a final last step, which basically runs "snappy build snap/"

=== added file 'docs/intro.md'
--- docs/intro.md	1970-01-01 00:00:00 +0000
+++ docs/intro.md	2015-07-31 19:14:03 +0000
@@ -0,0 +1,92 @@
+# Intro
+
+Snapcraft allows easy crafting of packages for Snappy Ubuntu. It makes it
+easy to incorporate components from different sources like GitHub, Launchpad,
+or npm.
+
+# Snappy
+
+Snappy Ubuntu Core is a new rendition of Ubuntu with transactional updates — a
+minimal server image with the same libraries as today’s Ubuntu, but
+applications are provided through a simpler mechanism.
+
+Snappy apps and Ubuntu Core itself can be upgraded atomically and rolled back
+if needed. Apps are also strictly confined and sandboxed to safeguard your
+data and system.
+
+# Key concepts
+
+A .snap package for the Ubuntu Core system contains all its
+dependencies. This has a couple of advantages over traditional deb or
+rpm based dependency handling, the most important being that a
+developer can always be assured that there are no regressions triggered by
+changes to the system underneath their app.
+
+Snapcraft makes bundling these dependencies easy by allowing you to
+specify them as “parts” in the snapcraft.yaml file.
+
+## Parts
+
+A central aspect of a snapcraft recipe is a “part”. A part is a piece
+of software or data that the snap package requires to work or to
+build other parts. Each part is managed by a snapcraft plugin and parts
+are usually independent of each other.
+
+## Plugins
+
+Snapcraft plugins are written in Python and have a yaml
+description. A lot of default plugins are included, for example for
+projects written in Go, Java, Python or C. It is also possible
+to simply download binary content as part of the snapcraft recipe.
+
+## Lifecycle
+
+Each part goes through the following steps:
+
+### Pull
+
+The first is that each part is pulled. This step will download
+content, e.g. checkout a git repository or download a binary component
+like the Java SDK. Snapcraft will create a parts/ directory with
+sub-directories like parts/part-name/src for each part that contains
+the downloaded content.
+
+#### Build
+
+The next step is that each part is built in its parts/part-name/build
+directory and installs itself into parts/part-name/install.
+
+### Stage
+
+After the build of each part the parts are combined into a single
+directory tree that is called the “staging area”. It can be found
+under the ./stage directory.
+
+This ./stage directory is useful for building outside code that isn’t in the
+snapcraft.yaml recipe against the snap contents. For example, you might build a
+local project against the libraries in ./stage by running
+`snapcraft shell make`. Though in general, you are encouraged to add even local
+projects to snapcraft.yaml with a local `source:` path.
+
+### Snap
+
+The snap step moves the data into a ./snap directory. It contains only
+the content that will be put into the final snap package, unlike the staging
+area which may include some development files not destined for your package.
+
+The Snappy metadata information about your project will also now be placed in
+./snap/meta.
+
+This ./snap directory is useful for inspecting what is going into your snap
+and to make any final post-processing on snapcraft’s output.
+
+### Assemble
+
+The final step builds a snap package out of the snap directory. This .snap file
+can be uploaded to the Ubuntu Store and published directly to Snappy users.
+
+# Next
+
+After introducing the key concept of snapcraft it is probably a good
+time to look at the tutorial in docs/tutorial.md to see how it works
+for an example project.

=== added file 'docs/tutorial.md'
--- docs/tutorial.md	1970-01-01 00:00:00 +0000
+++ docs/tutorial.md	2015-07-31 19:14:03 +0000
@@ -0,0 +1,223 @@
+# 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 <[e-mail]>
+    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!

=== modified file 'examples/webcam-webui-snap/snapcraft.yaml'
--- examples/webcam-webui-snap/snapcraft.yaml	2015-07-15 16:26:06 +0000
+++ examples/webcam-webui-snap/snapcraft.yaml	2015-07-31 19:14:03 +0000
@@ -2,6 +2,10 @@
     golang-static-http:
         plugin: go1.4-project
         source: git://github.com/mikix/golang-static-http
-    ubuntu:
-        package: fswebcam
+    fswebcam:
+        plugin: ubuntu
+    glue:
+        plugin: copy
+        files:
+            webcam-webui: bin/webcam-webui
 snappy-metadata: meta

=== modified file 'examples/webcam-webui-snap/webcam-webui'
--- examples/webcam-webui-snap/webcam-webui	2015-06-25 13:22:56 +0000
+++ examples/webcam-webui-snap/webcam-webui	2015-07-31 19:14:03 +0000
@@ -2,9 +2,6 @@
 
 set -e
 
-export PATH="${SNAPP_APP_PATH}/bin:${SNAPP_APP_PATH}/usr/bin${PATH:+:$PATH}"
-export LD_LIBRARY_PATH="${SNAPP_APP_PATH}/lib/x86_64-linux-gnu:${SNAPP_APP_PATH}/usr/lib/x86_64-linux-gnu:${LD_LIBRARY_PATH}"
-
 cd "$SNAPP_APP_DATA_PATH"
 
 golang-static-http &
@@ -13,4 +10,3 @@
     fswebcam shot.jpeg
     sleep 10
 done
-