openSUSE:Packaging Branding
Build Service Tutorial 路 Tips & Tricks 路 Cross Distribution Howto 路 Packaging checks
Desktop menu categories 路 RPM Macros 路 Scriptlets 路 Init scripts 路 How to write good changes
Distribution Branding and Branding-Enabled Packages
Purpose of the Distribution Branding
To provide a way to change the look of the distribution without rebuilding any of the binary packages at all, we need a way to provide package branding separately.
These conventions should allow the following:
- Easy replacement of all branding contents.
- Figuring out which branding is used in a distribution to check that everything is properly branded (e.g.
rpm -qa '*-branding*' | grep -v openSUSEshould be empty on an openSUSE distribution). - Joe likes to create his own distribution called "Flocke" on openSUSE and likes to replace everywhere the green SUSE geeko with a white polar bear.
- SUSE likes to release distribution based on the openSUSE as SUSE Linux Enterprise Server. Frederic is tasked with changing all occurrences of "openSUSE" with "SUSE Linux Enterprise Server".
- Tara prefers the upstream branding of the various openSUSE projects and does not like to see openSUSE logos. She wants to change her system and replace the custom branding everything in an easy way.
Description of branding-enabled packages
Branding-enabled packages provide its branding in a separate package.
This technique is useful for:
- Providing custom branding images.
- Providing custom default bookmarks, feeds, channels, desktop icons, home pages.
Rules for packaging of branding enabled packages
- Branding image should exist in a separate file.
- No custom branding images are added to the package.
Package maintainer should split to two sub-packages - one with core files (foo) and one with branding provided by upstream (foo-branding-upstream). These packages are connected by version dependencies.
Branding and themes
There are two possible ways to customize packages look and feel - branding and themes. In the following proposal, branding is an exclusive package, which conflicts with all other relative branding packages. Theme is a package or set of files, which contains non-exclusive description of package look and feel.
At the same time, more themes could be installed, but only one branding. In this concept, branding of a theme-able package is a definition of the default theme.
Conventions
Package names
All branding packages names should consist from three parts - package core name, string "-branding-" and the branding name. A special branding name is created by default: "upstream". This is a branding provided by upstream (if it exists).
Non-conflicting theme packages should consist from three parts - package core name, string "-theme-" and the theme name.
Spec file comments
Each file should contain comment providing sufficient information for the artist. You can expect, that upstream branding will be available to the artist.
Each line of these comments should start by "#BRAND: " string followed by these information:
- spec source file name (mandatory). Spec source package file name should be unique for the whole distribution. For example, if the target file name is /usr/share/foo/splash/image.png, source package file name should be foo-splash-image.png and it should be copied to the correct target in %install phase.
- use case (mandatory, if it is not part of the file name itself, e. g. "about" - decoration of about dialog, "splash" - image displayed for a short time, when application is launching, "toolbar" - image in toolbar, "initial screen" - displayed when application is started before user starts to use it).
- required art, if any (mandatory, if the image should contains program name letters, branch number, required logm comment should say, what exactly has to be included)
- overlays, if any (mandatory, if the image is overlayed with any text in image, comment should say its size, color and position)
- dependencies, if any (mandatory, if you can customize your look using another file, you must mention it). Examples: "Width of foo-img1.png must be the same as width of foo-bg.png." "You can define overlay text color, size and and position in splash.xml."
- allowed file sizes (optional, if not present, artist has to follow upstream size)
- allowed file formats (optional, if not present, artist has to follow upstream file format)
- for branding of launcher icon it is preferred to create custom icon theme instead of branding
Note: If the package is branding-enabled, but no files are required for the default look and feel, the upstream branding is not created. But package maintainer is encouraged to create spec file comments describing a way to create a third party branding.
Branding packages version dependencies
Defining correct version dependencies
From version to version, package developers may decide to change sizes and types of images. On the other hand, it does not happen on every version update, and it is required not to force update of branding package in such case.
Suppose that version n has branding incompatible with previous version n-1 and the currect version is n+1, which is compatible with branding of n.
Then dependencies should look as follows:
foo.spec:
Version: n+1 # Verify, that the branding package is new enough: Requires: foo-branding >= n
If package can work without any branding, you can replace Requires by Recommends or remove this section at all.
foo-branding-myvendor.spec:
Provides: foo-branding = %{version}
# Do not allow to use this branding with incompatible old version:
Conflicts: foo < n
Package maintainer is responsible for choosing of correct versions. Note that not only upstream changes, but also packaging changes may introduce branding package incompatibility.
Branding supplement
Each branding package should supplement conjunction of branding main package and core package using packageand form. It allows to choose correct branding package, if more branding packages are available and only if the core package is installed, too. Branding supplement symbol consists of "branding-" string and symbolic name of the branding. Upstream branding symbolic name is "upstream".
foo-branding-myvendor.spec:
Supplements: packageand(foo:branding-myvendor)
If your branding package should be selected for more different brandings known by its name in time of packaging, you can provide more than one Supplements lines.
Branding package exclusivity
To define, that one branding package has file conflicts with each other branding packages providing branding for the same package, use otherproviders conflict form referring to the main branding virtual:
foo-branding-myvendor.spec:
Conflicts: otherproviders(foo-branding)
Branding main package
Branding main package or pattern provides resolvable branding-myvendor. The package provides virtual symbol branding.
Branding main package should contain at file /usr/etc/SUSE-brand for current Tumbleweed or /etc/SUSE-brand for openSUSE Leap 15.x. This file should consist from two or three lines:
- First line is the name of the brand
- Second line is the version with "
VERSION =" and the version string. - Optional third line defining allowed alternative brandings "
CO-BRANDS =" and list of space separated brandings (only main parts of package names are needed). Order takes importance.
It is convenient to derive the branding main package version from the openSUSE version.
Reserved branding names
Official openSUSE branding packages use branding name openSUSE.
Official branding packages common for all SUSE Linux Enterprise variants uses branding name SLE, SUSE Linux Enterprise Server specific branding uses name SLES, SUSE Linux Enterprise Desktop uses branding name SLED.
Special name is reserved for branding files that are part of the upstream package: upstream.
Third party branding packages do not use strings derived from SUSE trade marks, but they invent their own names. If they want to create only partial branding (e. g. for customization), they can use above mentioned names as CO-BRANDS.
Examples
Branding-enabled package
foo.spec:
Version: 2.5 Requires: foo-branding >= 2.4 %package branding-upstream Supplements: packageand(foo:branding-upstream) Provides: foo-branding = 2.5 Conflicts: otherproviders(foo-branding) Conflicts: foo < 2.4 #BRAND: foo-splash.png: png or jpg file, 300x400 pixels. Progress bar #BRAND: will be displayed in lower 24 pixels. Image should include #BRAND: package name "FOO" and version letters "2.4". #BRAND: foo-info.png: Background of about dialog. Black names will #BRAND: appear in the light stripe in the centre.
Branding package
foo-branding-myvendor.spec:
Version: 2.5 Supplements: packageand(foo:branding-myvendor) Provides: foo-branding = 2.5 Conflicts: foo < 2.4 Conflicts: otherproviders(foo-branding)
Branding main package
branding-Flocke.spec:
Version: 11.0.2 Provides: branding Conflicts: otherproviders(branding)
Note that the resolvable branding-Flocke is provided by the package name, so it does not need to be mentioned explicitly.
/etc/SUSE-brand file from branding-Flocke package:
Flocke VERSION = 15.1 CO-BRANDS = upstream
Third line says, that if Flocke branding of some packages is not available, branding-tool should pick upstream brandind as an alternative.
GNOME 2 packages branding (deprecated)
Packages using GConf ans its configuration backend could use package gconf2-branding-myvendor to provide all needed defaults in one bundle. All these settings can use separate vendor directory /etc/gconf/gconf.xml.vendor.
There are two possible ways to create this package:
- Standard packaging work using
gconftool-2command (seegconf2-branding-openSUSEpackage). - Using vendor defaults in SUSE version of gconf-editor and them packaging of
/etc/gconf/gconf.xml.vendordirectory.
Branding and themes
If package supports themes, branding is a definition of the default theme. I this case, two packages may exist: foo-theme-myvendor, which will define vendor supplied theme or themes, and foo-branding-myvendor, which set one of themes defined in foo-theme-myvendor as default and require this package.
Vendor can decide to merge both these packages to one package named foo-branding-myvendor. In this case, themes supplied by vendor can be used only if one of them is also selected by default.
Problems of branding bundles
It is technically possible to create branding bundle packages from particular branding packages.
But such bundles cause several important problems:
- Branding bundle may lock users to exact version of some packages.
- Possible security update which requires branding update will be hard blocked until update of the branding bundle.
Mini bundles
Sometimes it is useful to package several brandings or themes into one mini bundle package (e. g. if creating so called metathemes). In such case, it is useful practice to name this package using the lowest level package. If you decide to use another name, be sure, that it is in form "*-branding-" or "*-theme-*", so the branding tool is able to find them.
Orphan branding packages
Upper mentioned dependency scheme could cause orphan branding package, if user removes package itself. Possible solutions:
- Adding of cyclic dependency to main package in the branding package.
- Dedicated code in zypper.
Partial branding and selecting package second-in-order
Vendor can decide to provide only partial branding. It is not clean, which package from other available packages should be selected as second in order. Possible solution:
- Repository order feature in incoming version of libzypp (note that it will not help for update repository with a set of additional brandings for more products).
Note that second level providing the same information is the CO-BRANDS line in the /etc/SUSE-brand file. Order of CO-BRANDS should be consistent with order of repositories.
As SUSE-brand is just a text file, you can ensure that a proper branding will be installed by:
Suppose that you have a branding-Flocke package and a set of Flocke branding packages. But you do not have gimp-branding-Flocke package. You want to install gimp-branding-Polarbear instead. To accomplish this task, you can add following lines to branding-Flocke.spec:
Suggests: gimp-branding-Polarbear
It will suggest that package during installation.
If the package gimp-branding-Polarbear is under your control, you should prefer to add following line to gimp-branding-Polarbear.spec:
Supplements: packageand(gimp:branding-Flocke)
Partial branding and package replacement
There is a possible problem when vendor has a limited set of branding packages and then wants to provide branding for a another package. In this moment, second-in-order branding is already installed. Possible solutins:
- Use
Obsoletes: foo-branding-second_in_order - Wait for distro update and use repository order feature in incoming version of libzypp