/snapcraft

Documentation refresh. #221

Merged
merged 1 commit into from Jan 12, 2016
Commits
Jump to file or symbol
Failed to load files and symbols.
+237 −183
Split
View
8 docs/ros-snap.md
@@ -267,9 +267,9 @@ version: 1.0
summary: ROS Example
description: Contains talker/listener ROS packages and a .launch file.
-binaries:
+apps:
launch-project:
- exec: roslaunch listener talk_and_listen.launch
+ command: roslaunch listener talk_and_listen.launch
parts:
foo:
@@ -287,9 +287,9 @@ but let's focus on a few specific pieces.
```yaml
# ...
-binaries:
+apps:
launch-project:
- exec: roslaunch listener talk_and_listen.launch
+ command: roslaunch listener talk_and_listen.launch
# ...
```
View
139 docs/snapcraft-advanced-features.md
@@ -57,10 +57,12 @@ If you just intend to pull and build the source, take a look at the `gopaste`
example. In its `snapcraft.yaml` file you can find just this one `parts`
paragraph:
- parts:
- gopaste:
- plugin: go
- source: git://github.com/wisnij/gopaste/gopasted
+```yaml
+parts:
+ gopaste:
+ plugin: go
+ source: git://github.com/wisnij/gopaste/gopasted
+```
It starts off with the name of the specific part (`gopaste` here), the origin
of the part (it's a `git` URL) and how to build it (plugin: `go`).
@@ -73,13 +75,15 @@ An interesting example is `py2-project` because it defines two parts
`spongeshaker` using the `python2` plugin, and `make-project` using the
`make` plugin.
- parts:
- spongeshaker:
- plugin: python2
- source: git://github.com/markokr/spongeshaker.git
- make-project:
- plugin: make
- source: .
+```yaml
+parts:
+ spongeshaker:
+ plugin: python2
+ source: git://github.com/markokr/spongeshaker.git
+ make-project:
+ plugin: make
+ source: .
+```
The example above mixes and matches parts of different origin. Locally it
provides a binary we intend to ship (the `sha3sum.py` script) and a
@@ -106,16 +110,17 @@ If your app is comprised of multiple parts, it might be necessary to build
and stage parts in a particular order. This can be done by using the `after`
keyword:
- parts:
- pipelinetest:
- plugin: make
- source: lp:~mterry/+junk/pipelinetest
- after:
- - libpipeline
- libpipeline:
- plugin: autotools
- source: lp:~mterry/libpipeline/printf
-
+```yaml
+parts:
+ pipelinetest:
+ plugin: make
+ source: lp:~mterry/+junk/pipelinetest
+ after:
+ - libpipeline
+ libpipeline:
+ plugin: autotools
+ source: lp:~mterry/libpipeline/printf
+```
In the case of the `libpipeline` example above, the part named `pipelinetest`
will be built after `libpipeline`. Especially if you need specific
@@ -130,8 +135,10 @@ re-use parts which have worked well for them.
In the `downloader-with-wiki-parts` example, you can see that the `main`
part is built:
- after:
- - curl
+```yaml
+after:
+ - curl
+```
As we never define the `curl` part in the above example, `snapcraft` will
check the Ubuntu Wiki, which is where we currently host examples of
@@ -147,21 +154,25 @@ If you are planning to provide binaries and services to the users of your
apps, you need to specify them in your definition first. It's just a matter
of enumerating them.
-The `godd` example has one binary:
+The `godd` example has one app:
- binaries:
- godd:
- exec: ./bin/godd
+```yaml
+apps:
+ godd:
+ command: ./bin/godd
+```
The above will take care of making the script executable, adding it to the
user's path and install it in the right place.
For a simple service we can take a look at `gopaste`:
- services:
- gopaste:
- description: "gopaste"
- start: bin/gopasted
+```yaml
+apps:
+ gopaste:
+ command: bin/gopasted
+ daemon: simple
+```
You define a name for the service, describe it (so log messages are more
descriptive), declare how to run the service and that's it. For more
@@ -176,11 +187,13 @@ on the resulting `.snap` file. If you find that certain files should not be
shipped to the user (download size being just one factor), you can
explicitly tell `snapcraft` which files to snap:
- snap:
- - usr/lib/x86_64-linux-gnu/libgudev-1.0.so*
- - usr/lib/x86_64-linux-gnu/libobject-2.0.so*
- - usr/lib/x86_64-linux-gnu/libglib-2.0.so*
- - bin/godd*
+```yaml
+ snap:
+ - usr/lib/x86_64-linux-gnu/libgudev-1.0.so*
+ - usr/lib/x86_64-linux-gnu/libobject-2.0.so*
+ - usr/lib/x86_64-linux-gnu/libglib-2.0.so*
+ - bin/godd*
+```
Here `godd` further defines the list of files to be placed in the app
during the `snap` phase. As you can see above, globs (using asterisks as
@@ -189,26 +202,28 @@ directory structure.
In the `webcam-webui` example you can see the following part called `cam`:
- cam:
- plugin: go
- go-packages:
- - github.com/mikix/golang-static-http
- stage-packages:
- - fswebcam
- filesets:
- fswebcam:
- - usr/bin/fswebcam
- - lib
- - usr/lib
- go-server:
- - bin/golang-*
- stage:
- - $fswebcam
- - $go-server
- snap:
- - $fswebcam
- - $go-server
- - -usr/share/doc
+```yaml
+cam:
+ plugin: go
+ go-packages:
+ - github.com/mikix/golang-static-http
+ stage-packages:
+ - fswebcam
+ filesets:
+ fswebcam:
+ - usr/bin/fswebcam
+ - lib
+ - usr/lib
+ go-server:
+ - bin/golang-*
+ stage:
+ - $fswebcam
+ - $go-server
+ snap:
+ - $fswebcam
+ - $go-server
+ - -usr/share/doc
+```
In the `stage` definition you can see how named filesets are re-used
(`$fswebcam` and `$go-server`).
@@ -223,11 +238,13 @@ Snapping node.js apps has never been this easy. Take a look at the `shout`
example and see how short and sweet it is. To bundle node packages, you simply
do something like:
- parts:
- shout:
- plugin: nodejs
- node-packages:
- - shout
+```yaml
+parts:
+ shout:
+ plugin: nodejs
+ node-packages:
+ - shout
+```
`node-packages` simply lists which packages (including their dependencies) to
add to the snap.
View
68 docs/snapcraft-parts.md
@@ -14,28 +14,30 @@ seen at each step (making use of `filesets` or not). An example integrating
these concepts for a part called `example-part` using a hypothetical plugin
called `sample` would look like:
- parts:
- example-part:
- type: sample
- stage-packages:
- - gpg
- - wget
- organize:
- opt/bin: bin
- filesets:
- binaries:
- - bin/*
- - usr/bin/*
- headers:
- - *.h
- - -include
- stage:
- - $binaries
- - test/bin/test_app
- - $headers
- snap:
- - $binaries
-
+```yaml
+parts:
+ example-part:
+ type: sample
+ stage-packages:
+ - gpg
+ - wget
+ organize:
+ opt/bin: bin
+ filesets:
+ binaries:
+ - bin/*
+ - usr/bin/*
+ headers:
+ - *.h
+ - -include
+ stage:
+ - $binaries
+ - test/bin/test_app
+ - $headers
+ snap:
+ - $binaries
+```
+
In this example, imagine that the `sample` plugin actually builds something in
its private *build* location using its private *source* directory as a base,
and that it *installs* the usual set of files from its private install
@@ -78,10 +80,12 @@ where everything should look clean and crisp for a good quality snap.
Snapcraft includes support for Python 2.x and Python 3.x parts; here's how a
`snapcraft.yaml` parts section will look like:
- parts:
- spongeshaker:
- plugin: python3
- source: git://github.com/markokr/spongeshaker.git
+```yaml
+parts:
+ spongeshaker:
+ plugin: python3
+ source: git://github.com/markokr/spongeshaker.git
+```
A Python part will typically make sure required Python packages are installed
on the build host and embed the following pieces in your snap:
@@ -97,7 +101,7 @@ scripts generated by snapcraft or when running your app locally.
Python parts support standard snapcraft options and the requirements option
to point PIP at its requirements file.
-Why embed a Python runtime? While Snappy does currently include a Python
+Why embed a Python runtime? While Snappy does currently include a Python
runtime, this might not be the one you need, and it might be updated to a
different version or removed in a Snappy update. This is why applications
using Python should embed their copy of the Python runtime.
@@ -108,10 +112,12 @@ using Python should embed their copy of the Python runtime.
Snapcraft includes support for building parts with Apache Maven or Ant;
here's how a snapcraft.yaml parts section will look like:
- parts:
- webapp:
- plugin: maven
- source: git://github.com/lool/snappy-mvn-demo.git
+```yaml
+parts:
+ webapp:
+ plugin: maven
+ source: git://github.com/lool/snappy-mvn-demo.git
+```
A Maven part will typically:
View
50 docs/snapcraft-syntax.md
@@ -20,24 +20,42 @@ contain.
* `config` (string)
Path to the runnable in snap that will be used as the [Snappy config
interface](https://developer.ubuntu.com/snappy/guides/config-command/).
- * `services` (yaml subsection)
- A set of keys representing service names with values as defined by the
- [Snappy packaging spec](https://developer.ubuntu.com/snappy/guides/packaging-format-apps/).
- * `binaries` (yaml subsection)
- A set of keys representing binary names with values as defined by the
- [Snappy packaging spec](https://developer.ubuntu.com/snappy/guides/packaging-format-apps/).
+ * `apps` (yaml subsection)
+ A map of keys for applications. These are either daemons or command line
+ accessible binaries.
+ * `command` (string)
+ Specifies the internal command to expose. If it is a `daemon` this
+ command is used to start the service.
+ * `daemon` (string)
+ If present, integrates the runnable as a system service. Valid values are
+ `forking` and `simple`.
+ If set to `simple`, it is expected that the command configured is the main
+ process.
+ If set to `forking`, it is expected that the configured command will call
+ fork() as part of its start-up. The parent process is expected to exit
+ when start-up is complete and all communication channels are set up.
+ The child continues to run as the main daemon process. This is the
+ behavior of traditional UNIX daemons.
+ * `stop-command` (string)
+ Requires `daemon` to be specified and represents the command to run to
+ stop the service.
+ * `stop-timeout` (integer)
+ Requires `daemon` to be specified. It is the length of time in seconds
+ that the system will wait for the service to stop before terminating it
+ via `SIGTERM` (and `SIGKILL` if that doesn't work).
* `icon` (string)
Path to the icon that will be used for the snap.
- * `license` (yaml subsection)
- License the snap will carry.
- * `text` (string)
- The license text for the snap itself.
- * `accept-required` (boolean)
- If true, license acceptance is required for the package to be activated.
- A good example for this one is the Sun JRE/JDK being bundled in a snap.
- * `framework-policy` (string)
- A relative path to a directory containing additional policies, used if
- creating a framework and want to extend permissions to snap apps.
+ * `license` (string)
+ Path to a license file.
+ * `license-agreement` (string)
+ Requires `license` to be set. The only valid value for this entry is
+ `explicit` which requires the license to be accepted for the snap to
+ install.
@kyrofa

kyrofa Jan 12, 2016

Member

Yeah this reads well.
+ A good example for this one is the Sun JRE/JDK being bundled in a snap.
+ * `license-version` (string)
+ Requires `license` to be set. The version for the license.
+ A change in version when `license-accept` is set to `explicit` requires
+ a license to be reaccepted.
* `parts` (yaml subsection)
A map of part names to their own part configuration. Order in the file is
not relevant (to aid copy-and-pasting).
Oops, something went wrong.