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

[Sergio Schvezov]

docs refresh

To run through the intro instead of going to the ppa, build a local copy from
these sources by running:

bzr bd; sudo dpkg -i ../build-area/snapcraft_0.2_all.deb

You can review the diff to inspect the changes, but I'd appreciate someone going through

http://bazaar.launchpad.net/~sergiusens/snapcraft/docs/view/head:/docs/your-first-snap.md

[lp:~sergiusens/snapcraft/docs]

184. By Sergio Schvezov on 2015-09-11

edit, remove list

[Sergio Schvezov (sergiusens)]

thanks for the review

[lp:~sergiusens/snapcraft/docs]

185. By Sergio Schvezov on 2015-09-14

review fixes

[Sergio Schvezov (sergiusens)]

review fixes are in 185

[lp:~sergiusens/snapcraft/docs]

186. By Sergio Schvezov on 2015-09-14

fool proof fix

187. By Sergio Schvezov on 2015-09-14

pedantic

188. By Sergio Schvezov on 2015-09-14

snap crafting all together now

[John Lenton (chipaca)]

You have earned an official stamp of approval.

review: Approve

=== modified file 'docs/intro.md'
--- docs/intro.md	2015-08-05 13:38:39 +0000
+++ docs/intro.md	2015-09-14 20:53:45 +0000
@@ -1,8 +1,8 @@
 # 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.
+easy to incorporate components from different sources and build technologies or
+solutions.
 
 # Snappy
 
@@ -17,8 +17,8 @@
 # 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
+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.
 
@@ -32,12 +32,12 @@
 build other parts. Each part is managed by a snapcraft plugin and parts
 are usually independent of each other.
 
-## Plugins
+## Type of a Part
 
-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.
+Each part has a `type` associated to it, this `type` provides the mechanism
+to handle it. The `type` a part has is extendable through plugins, there are
+a variety of plugins already included for python 2 and 3, go, java, and cmake or
+autotools based projects.
 
 ## Lifecycle
 

=== modified file 'docs/your-first-snap.md'
--- docs/your-first-snap.md	2015-09-07 13:30:05 +0000
+++ docs/your-first-snap.md	2015-09-14 20:53:45 +0000
@@ -15,7 +15,7 @@
 
 You should also install Snapcraft:
 
-    $ sudo add-apt-repository ppa:snappy-dev/snapcraft-daily
+    $ sudo add-apt-repository ppa:snappy-dev/tools
     $ sudo apt-get update
     $ sudo apt-get install snapcraft
 
@@ -28,6 +28,9 @@
 Namely, we'll combine a web server with a webcam program and combine
 them to serve a new frame every ten seconds.
 
+> The resulting package is also part of the examples directory in the
+> [snapcraft sources](http://bazaar.launchpad.net/~snappy-dev/snapcraft/core/files/head:/examples/webcam-webui/)
+
 ### The Web Server
 
 Go has a simple web server in its standard libraries. So let's just use that.
@@ -40,11 +43,11 @@
         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 
+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
+This code is hosted on a simple GitHub
 [repository](https://github.com/mikix/golang-static-http).
 
 ### The Webcam Program
@@ -64,22 +67,53 @@
 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.
 
+### Initializing a project
+
+To get started with a base template create a folder that will hold your
+project, and initialize it:
+
+    $ mkdir webcam-webui
+    $ cd webcam-webui
+    $ snapcraft init
+
+then open the created snapcraft.yaml and edit the templated values for `name`,
+`version`, `vendor`, `summary` and `description`. You can make it look like
+this:
+
+    name: webcam-webui
+    version: 1
+    vendor: You <[e-mail]>
+    summary: Webcam web UI
+    description: Exposes your webcam over a web UI
+    icon: icon.png
+
+and copy over an icon to `icon.png` or change the path accordingly (if you
+change the path just make sure it is part of your project directory and that
+the path is relative to be able to share your snapcrafting):
+
+    $ cp /usr/share/icons/hicolor/64/mimetypes/text-x-apport.png ./icon.png
+
+If you run `snapcraft` now, it will complain about not having any `parts`.
+
+We will look more into this metadata in a bit, but first let's look at adding
+some `parts`.
+
 ### Web Server Part
 
 Let's start with the web server.
 
     parts:
-      golang-static-http:
-        plugin: go-project
+      cam:
+        type: go-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.
-And finally, a `source` option telling Snapcraft where to download the code.
+You've just defined a `part` inside `parts` named `cam`, but you
+could call it anything. That part has a two options: A `type` option that
+tells Snapcraft how to interpret the part (in this case, it's a Go project),
+and a `source` option telling Snapcraft where to download the code.
 
-Go ahead and create `snapcraft.yaml` with the above contents in an empty
-directory.
+Go ahead and append the above contents to your recently created
+`snapcraft.yaml`.
 
 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
@@ -88,7 +122,8 @@
 
     $ snapcraft stage
 
-You'll see a bunch of output, including Snapcraft downloading the Go compiler.
+You'll see a bunch of output, including Snapcraft downloading the Go compiler
+if not already installed on your host build environment.
 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`:
@@ -96,28 +131,26 @@
     $ ls stage/bin
     golang-static-http
 
-### Webcam Part
+### Adding an Ubuntu dependency to a part.
 
 Now let's add the webcam program `fswebcam` to our snap. Edit `snapcraft.yaml`
-to look like:
+to make the `cam` part look like:
 
     parts:
-      golang-static-http:
-        plugin: go-project
+      cam:
+        type: go-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.
+        stage-packages:
+          - fswebcam
+
+We've just added a new property to the `cam` part called `stage-packages` which
+contains a yaml list with any supporting Ubuntu package we want; in this case
+our list has one element with an entry for the `fswebcam` Ubuntu `deb` based
+package.
+
+Now let's stage our recipe again (and force it to go through the lifecycle).
+
+    $ snapcraft stage --force
 
 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:
@@ -125,7 +158,7 @@
     $ ls stage
     bin  etc  lib  usr  var
 
-### Gluing the Parts Together
+### A copy Part
 
 OK, so we have the two programs in our staging area. But how do we make them
 work together?
@@ -135,7 +168,7 @@
     #!/bin/sh
     set -e
 
-    cd "$SNAPP_APP_DATA_PATH"
+    cd "$SNAP_APP_DATA_PATH"
 
     golang-static-http &
 
@@ -151,19 +184,19 @@
 Alright, let's put this script in our snap too:
 
     parts:
-      golang-static-http:
-        plugin: go-project
+      cam:
+        type: go-project
         source: git://github.com/mikix/golang-static-http
-      fswebcam:
-        plugin: ubuntu
+        stage-packages:
+          - fswebcam
       glue:
-        plugin: copy
+        type: 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.
+A part of type `copy` 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:
 
@@ -175,26 +208,69 @@
     $ 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 to add some Snappy metadata that describes 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/),
+### Filesets
+
+Some files in `./stage` could be needed for building dependent parts during the
+staging phase and some of these would be useful for the resulting snap. In
+this case we don't need some of these for either staging or the resulting snap,
+so let's add some filesets for the snap.
+
+Edit `snapcraft.yaml` once more to make the `cam` part in `parts` to look like:
+
+    parts:
+      cam:
+        type: go-project
+        source: git://github.com/mikix/golang-static-http
+        stage-packages:
+          - fswebcam
+        filesets:
+          fswebcam:
+            - usr/bin/fswebcam
+            - lib
+            - usr/lib
+          go-server:
+            - bin/golang-*
+        snap:
+          - $fswebcam
+          - $go-server
+      glue:
+        type: copy
+        files:
+          webcam-webui: bin/webcam-webui
+
+What we did was add two `filesets`, one named `fswebcam` and another one named
+`go-server` and then added a `snap` entry referencing these two filesets with
+`$`. All these filesets are inclusion based filesets, you can use `*` to glob
+many files and directories (if `*` is the first character, it needs to be
+quoted e.g.; `'*'`). An exclusion can be added by prefixing the file
+with a `-`. Additionally, you don't need to define a fileset, you can explicitly
+mention the file, directory or match under `snap` or `stage`.
+
+### Extending the Metadata
+
+The defined values in `snapcraft.yaml` are used to build the corresponding
+`meta` directory that holds all the package information.
+
+You can read all about the resulting [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 add some metadata to our snapcraft file
+The templated values when `snapcraft init` was run did not hold any `parts`
+which we've filled along the way. It also did not define any `services` or
+`binaries` which we will be adding now
+
+Edit `snapcraft.yaml` once more and add the `services` and `binaries` entry,
+your resulting `snapcraft.yaml` should look very similar to:
 
     name: webcam-webui
     version: 1
     vendor: You <[e-mail]>
+    summary: Webcam web UI
+    description: Exposes your webcam over a web UI
+    icon: icon.png
     services:
     - name: webcam-webui
       start: bin/webcam-webui
-    summary: Webcam web UI
-    description: Exposes your webcam over a web UI
-    icon: icon.png
+
     parts:
       golang-static-http:
         plugin: go-project
@@ -206,13 +282,9 @@
         files:
           webcam-webui: bin/webcam-webui
 
-Copy a png icon of your choice into your current directory:
-
-    $ cp /usr/share/icons/hicolor/64/mimetypes/text-x-apport.png ./icon.png
-
 and tell Snapcraft to actually make the snap package:
 
-    $ snapcraft assemble
+    $ snapcraft
 
 You should now have a `webcam-webui_1_amd64.snap` file sitting in your
 directory (assuming you are running on amd64). Congratulations!
@@ -221,13 +293,13 @@
 ## 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 
+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 
+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
@@ -235,4 +307,3 @@
  * `#snappy` on `irc.freenode.net` or
  * the [snappy-app-devel](https://lists.ubuntu.com/mailman/listinfo/snappy-app-devel)
    mailing list
-

=== renamed directory 'examples/webcam-webui-snap' => 'examples/webcam-webui'
=== modified file 'examples/webcam-webui/snapcraft.yaml'
--- examples/webcam-webui-snap/snapcraft.yaml	2015-09-08 11:48:30 +0000
+++ examples/webcam-webui/snapcraft.yaml	2015-09-14 20:53:45 +0000
@@ -1,21 +1,31 @@
 name: webcam-webui
-version: 1.0.0
-vendor: Loïc Minier <[e-mail]>
-services:
- - name: webcam-webui
-   start: bin/webcam-webui
-   security-template: unconfined
+version: 1
+vendor: Vendor <[e-mail]>
 summary: Webcam web UI
 description: Exposes your webcam over a web UI
 icon: icon.png
+services:
+  - name: webcam-webui
+    start: bin/webcam-webui
 
 parts:
-    golang-static-http:
-        type: go-project
-        source: git://github.com/mikix/golang-static-http
-    glue:
-        type: copy
-        stage-packages:
-          - fswebcam
-        files:
-            webcam-webui: bin/webcam-webui
+  cam:
+    type: go-project
+    source: git://github.com/mikix/golang-static-http
+    stage-packages:
+      - fswebcam
+    filesets:
+      fswebcam:
+        - usr/bin/fswebcam
+        - lib
+        - usr/lib
+      go-server:
+        - bin/golang-*
+    snap:
+      - $fswebcam
+      - $go-server
+  glue:
+    type: copy
+    files:
+      webcam-webui: bin/webcam-webui
+

=== modified file 'examples/webcam-webui/webcam-webui'
--- examples/webcam-webui-snap/webcam-webui	2015-07-28 20:09:09 +0000
+++ examples/webcam-webui/webcam-webui	2015-09-14 20:53:45 +0000
@@ -1,8 +1,7 @@
 #!/bin/sh
-
 set -e
 
-cd "$SNAPP_APP_DATA_PATH"
+cd "$SNAP_APP_DATA_PATH"
 
 golang-static-http &