(Created page with "== Introduction == Many times in a Plasma based application or addon there is the need to reference a set of files for consistent and easy access and redistribution. For instanc...")
A Plasma Package allows easy deployment and later referencing of a group of platform-independent files. Plasma Packages are used with wallpaper images and plugins, themes, Plasmoids, DataEngines, Runners, QML file sets, Plasma desktop scripting templates and other similar contexts. Plasma Package is therefore quite flexible and with very few rules can be extended to cover a wide variety of uses in applications that need a way to redistribute and/or reference sets of files easily.
Plasma Package is intended to be a simple system that does not include things more complex packaging systems such as the Debian package format or RPM provides. While Plasma Packages do not have the concept of things such as dependencies or architecture targets, it also does not require a complex system with a database and (slow) management applications.
Plasma Packages usually have two things in common: a metadata.desktop file and a contents/ directory.
The metadata.desktop is an INI format file which contains a description of the contents of the package. This includes translatable strings for user visible text such as a name and description as well as content that is programmatically useful such as, in the case of Plasmoids, the scripting API used to write the Plasmoid the Package contains.
In the case of Plasmoids, the metadata.desktop contains the following mandatory fields:
Optionally these fields can be added:
An example file can be seen here:
meta.desktop files for other Plasma components such as DataEngines, Runners and Wallpapers are very similar. It is recommended when creating new package types to adhere to the general style above as much as possible for consistency.
Packages may add additional top-level contents directories. This is used by Plasmoids to allow device-specific files to be made available. A package may also have no special content directory at all, though this is discouraged since it makes accidental overwriting of files such has the metadata or hash files very easy.
What appears within the contents directories is up to the Package itself. For Plasmoids, the following structure is supported:
New formats can be defined programmatically using PackageStructure plugins. PackageStructure plugins call addDirectoryDefinition and addFileDefinition methods which define a key string that can be used to reference that resource, the path within the contents directories that it is expected to exist at, supported mimetypes, descriptions suitable for showing to a user (e.g. in an IDE or package creator tool) and whether or not the resource is required. Contents directories are also defined by the PackageStructure plugin.
The structure can be created dynamically at run-time depending on the package itself. This is accomplished by reimplementing the pathChanged method. This also allows one PackageStructure object to be re-used multiple times.
Together, these mechanisms allow for virtually unlimited flexibility in how a Package is structured on disk and what it contains. This makes Plasma Package suitable for the wide variety of use cases it currently fulfills.
A Plasma Package may be signed with a GPG key. First, a SHA1 hash of the metadata.desktop file and the contents directories must be created and placed in a file called contents.hash that resides at the top level. A GPG signature of the contents.hash file can then be placed in a file called contents.hash.sig. This can then be used to verify the contents of the package at runtime.
Hashes may be generated with the plasmapkg tool as of version 0.2 with the --hash command line option.
A Plasma Package can be packed into one zip file that contains all the required files. The gzip format is also supported, though zip is generally recommended due to the ability to easily perform random access operations on zip archives. The resulting file is then suffixed with an appropriate identifying ending, such as ".plasmoid" in the case of plasmoids.
Installation can be done by hand, but generally this is accomplished either by using Plasma::PackageStructure::installPackage or with the plasmapkg command line utility. When a Plasma Package is installed, the archive is uncompressed and stored under the package root defined by the Package's structure definition. By default, this is $APPDATA/plasma/packages. By default, the metadata.desktop is copied into the the services directory so that it can easily be found later by KTrader to find all Plasmoids whether they are written in C++ or an interpreted language.