packaging/snap-kf5/Snapping.md

0001 # Snapping
0002
0003 To get started snapping an application against the KDE Frameworks 5 content
0004 snap you'll ideally want to start from a pre-existing snap.
0005
0006 ## Boilerplates
0007
0008 KF5 snaps are distinct in that they contain some bits of very important
0009 boilerplate. None of this requires changes really, but it is helpful to
0010 understand what is going on.
0011
0012 They define a plug linking to kf5
0013
0014 ```
0015 plugs:
0016     kde-frameworks-5-plug:
0017         content: kde-frameworks-5-all
0018         interface: content
0019         default-provider: kde-frameworks-5
0020         target: kf5
0021 ```
0022
0023 And each C++ `part` that has a build requirement on KF5 needs to pull in the
0024 development component
0025
0026 ```
0027 parts:
0028     babe:
0029         after:
0030         - kde-frameworks-5-dev
0031 ```
0032
0033 One `part` (ideally the one producing the app in question) needs
0034 to pull in the environment launcher.
0035
0036 ```
0037 parts:
0038     babe:
0039         after:
0040         - kde-frameworks-5-env
0041 ```
0042
0043 Lastly the relevant application defintions need to use the custom plug and
0044 start themselves through the environment launcher.
0045
0046 ```
0047 apps:
0048     babe:
0049         command: kf5-launch babe
0050         plugs:
0051         - kde-frameworks-5-plug
0052 ```
0053
0054 ## Dir structure
0055
0056 - Put snapcraft.yaml in a directory. For neon builds it should be in the main
0057   directory of the packaging repo.
0058 - Relative to the snapcraft.yaml you'll want to put the icon and desktop file
0059
0060 ```
0061 # paths to copy from vary of course
0062 mkdir -pv snap/gui/
0063 cp -v /usr/share/icons/breeze/apps/48/babe.svg       snap/gui/babe.svg
0064 cp -v /usr/share/applications/org.kde.babe.desktop   snap/gui/
0065 ```
0066
0067 ## Snapcrafting
0068
0069 To build snaps you want to use `snapcraft`. Currently this requires a special
0070 parts file to build. To use it simply
0071 `export SNAPCRAFT_PARTS_URI=https://metadata.neon.kde.org/snap/parts.yaml`.
0072
0073 To build simply run `snapcraft` and to clean the tree `snapcraft clean`.
0074
0075 ## Testing
0076
0077 To test a newly built snap it's easiest to simply `snap try` it (note: once you
0078 have a snap try-mounted you do not need to try on subsequent builds, you can
0079 change stuff in the prime dir as necessary).
0080
0081 ```
0082 snap remove babe
0083 snap try ./prime/
0084 /snap/bin/babe
0085 ```
0086
0087 On first start the snap will throw an error on CLI about not being able to find
0088 the framework and tell you a command to run to connect the plug.
0089
0090 ## Additional Reading
0091
0092 For additional information please check out https://docs.snapcraft.io/