← Back to branch summary

~snappy-dev/snapcraft/core

« back to all changes in this revision

Viewing changes to docs/snapcraft-advanced-features.md

  • Committer: Daniel Holbach
  • Date: 2015-09-28 13:53:17 UTC
  • mto: (217.1.1 snapcraft)
  • mto: This revision was merged to the branch mainline in revision 218.
  • Revision ID: daniel.holbach@canonical.com-20150928135317-j6gf3qqapq3r4cla
add a tour which details and explains relevant snapcraft features in the examples directory

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/snapcraft-advanced-features.md
 
1
# Snapcraft: Advanced features
 
2
 
 
3
Once you have built [your first snap](your-first-snap.md), you will probably
 
4
want to learn more about snapcraft's more advanced features. Having a look at 
 
5
our selection of examples is a good idea, as we want it to be a good showcase 
 
6
of what is possible and generally relevant.
 
7
 
 
8
## Examples
 
9
 
 
10
Our showcase can be found in the actual source of `snapcraft` itself. Check 
 
11
it out by simply running:
 
12
 
 
13
        bzr branch lp:snapcraft
 
14
        cd snapcraft/examples
 
15
 
 
16
Inspecting the source locally will make easier to build the examples and 
 
17
play around with them. (You can 
 
18
[view them online](https://bazaar.launchpad.net/~snappy-dev/snapcraft/core/files/head:/examples/)
 
19
as well.)
 
20
 
 
21
### Playing around with the examples
 
22
 
 
23
If you just checked out the `snapcraft` source and inspect the examples, you
 
24
can start off your explorations by reading the accompanying `snapcraft.yaml`
 
25
file and running:
 
26
 
 
27
        ../../bin/snapcraft
 
28
 
 
29
This will inform you of all the steps taken during the creation of the snap.
 
30
 
 
31
## Defining your parts
 
32
 
 
33
Once you have noted down all the general information about your snap
 
34
(like description, vendor information and everything else), naming
 
35
the individual parts will define the stucture of your `snapcraft.yaml` file.
 
36
Think of parts as individual components of your snap: Where do you pull them
 
37
from? How are they built? 
 
38
 
 
39
### Prerequisites during the build
 
40
 
 
41
The example named `downloader-with-wiki-parts` shows how very easily make sure
 
42
that its build dependencies are installed:
 
43
 
 
44
        build-packages: [libssl-dev]
 
45
 
 
46
The above will install the `libssl-dev` package from the Ubuntu archive before
 
47
an attempted build. If you need a specific version of libssl-dev or a custom 
 
48
build, you will need to specify a separate part.
 
49
 
 
50
Also note that the above will not define which libraries are shipped with the
 
51
app. It merely makes sure you have all the relevant build tools installed.
 
52
 
 
53
 
 
54
### Pulling and building
 
55
 
 
56
If you just intend to pull and build the source, take a look at the `gopaste`
 
57
example. In its `snapcraft.yaml` file you can find just this one `parts` 
 
58
paragraph:
 
59
 
 
60
        parts:
 
61
          gopaste:
 
62
            type: go-project
 
63
            source: git://github.com/wisnij/gopaste/gopasted
 
64
 
 
65
It starts off with the name of the specific part (`gopaste` here), the origin
 
66
of the part (it's a `git` URL) and how to build it (type: `go-project`).
 
67
Other possible scenarios would be Bazaar or Mercurial branches, or local
 
68
directories.
 
69
 
 
70
### Mixing and matching plugins
 
71
 
 
72
An interesting example is `py2-project` because it defines only one part
 
73
(`spongeshaker`), but uses plugins of two types (`python2-project` and 
 
74
`make-project) to assemble and build the snap:
 
75
 
 
76
        parts:
 
77
          spongeshaker:
 
78
            type: python2-project
 
79
            source: git://github.com/markokr/spongeshaker.git
 
80
          make-project:
 
81
            source: .
 
82
 
 
83
The example above mixes and matches parts of different origin. Locally it
 
84
provides a binary we intend to ship (the `sha3sum.py` script) and a 
 
85
`Makefile` (to install our script in the right place).
 
86
 
 
87
`spongeshaker` is a python library we will need to pull from git, build as
 
88
a python project and bundle along with our script.
 
89
 
 
90
A possible use-case for the above would be if you just intend to ship a small
 
91
binary which you maintain, but require a library you need to build from git
 
92
as opposed to simply including it from the Ubuntu archives.
 
93
 
 
94
What's happening during the `snapcraft` run is: 
 
95
 
 
96
1. Get `spongeshaker` from `git`.
 
97
1. Build it as a python project (which will include installing the python 
 
98
   library in the right place).
 
99
1. Running `make` (from the local `Makefile`) and thus installing our 
 
100
   `sha3sum.py` script in the right place.
 
101
 
 
102
### Putting your parts in order
 
103
 
 
104
If you app comprises of multiple parts, it might be necessary to build and
 
105
stage parts in a particular order. This can be done by using the `after`
 
106
keyword:
 
107
 
 
108
        parts:
 
109
            pipelinetest:
 
110
                type: make-project
 
111
                source: lp:~mterry/+junk/pipelinetest
 
112
                after:
 
113
                    - libpipeline
 
114
            libpipeline:
 
115
                type: autotools-project
 
116
                source: lp:~mterry/libpipeline/printf
 
117
 
 
118
 
 
119
In the case of the `libpipeline` example above, the part named `libpipeline`
 
120
will be built before `pipelinetest`. Especially if you need specific 
 
121
functionality during a build or as part of checks during the `snap` phase,
 
122
this will be handy.
 
123
 
 
124
### Re-using parts
 
125
 
 
126
With snapcraft we want to make it easy to learn from other app vendors and
 
127
re-use parts which have worked well for them.
 
128
 
 
129
In the `downloader-with-wiki-parts` example, you can see that the `main` 
 
130
part is built:
 
131
 
 
132
                after:
 
133
                    - curl
 
134
 
 
135
As we never define the `curl` part in the above example, `snapcraft` will
 
136
check the Ubuntu Wiki, which is where we currently host examples of 
 
137
successful snapcraft parts. The build order in this case would be `curl`,
 
138
then `main`.
 
139
 
 
140
 
 
141
## Finishing steps
 
142
 
 
143
### Individual files
 
144
 
 
145
If you are planning to provide binaries and servies to the users of your
 
146
apps, you need to specify them in your definition first. It's just a matter 
 
147
of enumerating them.
 
148
 
 
149
The `godd` example has one binary:
 
150
 
 
151
        binaries:
 
152
          godd:
 
153
            exec: ./bin/godd
 
154
 
 
155
The above will take care of making the script executable, adding it to the
 
156
user's path and install it in the right place.
 
157
 
 
158
For a simple service we can take a look at `gopaste`:
 
159
 
 
160
        services:
 
161
          gopaste:
 
162
            description: "gopaste"
 
163
            start: bin/gopasted
 
164
 
 
165
You define a name for the service, describe it (so log messages are more 
 
166
descriptive), declare how to run the service and that's it. For more 
 
167
thoughts on services and their security, visit the
 
168
[snappy policy](https://developer.ubuntu.com/en/snappy/guides/security-policy/).
 
169
 
 
170
 
 
171
### Limiting the number of installed files
 
172
 
 
173
To check the list of files included in your snap, you can use `dpkg -c` on 
 
174
the resulting `.snap` file. If you find that certain files should not be
 
175
shipped to the user (download size being just one factor), you can use 
 
176
`snapcraft`'s feature of defining specific filesets:
 
177
 
 
178
            snap:
 
179
             - usr/lib/x86_64-linux-gnu/libgudev-1.0.so*
 
180
             - usr/lib/x86_64-linux-gnu/libobject-2.0.so*
 
181
             - usr/lib/x86_64-linux-gnu/libglib-2.0.so*
 
182
             - bin/godd*
 
183
 
 
184
Here `godd` further defines the list of files to be placed in the app
 
185
during the `snap` phase. As you can see above, globs (using asterisks as
 
186
wildcard characters) are a good way of handling complexities within the
 
187
directory structure.
 
188
 
 
189