README for desktop-base ======================= 1. What’s provided 1.1. Themes packs 1.2. Debian logos 1.2.1. Debian logos icons 1.2.2. Debian logos images 1.3. Desktop files 1.4. Default configurations overrides 1.5. Plymouth boot splashes 2. How to switch themes 2.1. Global theme alternative 2.2. Individual alternatives 3. Theme pack structure 4. Contributing 4.1. Artists 4.2. Desktop environment maintainers 4.3. Notes and references 1. What’s provided 1.1. Theme packs Six theme packs are currently provided: - Emerald (default for Bookworm) - Homeworld (default for Bullseye) - futurePrototype (default for Buster) - Soft Waves (default for Stretch) - Lines (default for Jessie) - Joy (default for Wheezy) - Spacefun (default for Squeeze) These themes contain customization for GRUB, Plymouth, login managers like SDDM and LightDM, wallpapers and lock screen for desktop environments like GNOME, KDE’s Plasma 5, Xfce, Mate… See below for how to switch between themes and a detailed description of the theme packs structure. 1.2. Debian logos Three version of the logo are shipped as icons: - emblem-debian : the Debian logo in it’s original red-purple color - emblem-debian-symbolic: the Debian logo in a black+transparent format that desktop like GNOME can use and adapt the color depending on the context. - emblem-debian-white : the Debian logo in white We also ship 3 versions of the logo as images: - logo : logo alone - logo-text : logo + "Debian" name - logo-text-version: logo + "Debian" name + Debian version number All these images and logos are provided both in several bitmap resolutions (PNG) and also in vector form (SVG). The "vendor-logos" alternative is shipped with alternatives for both logo images and icons. It should be used by derivatives to replace by their own logos. The alternative has the following structure: - Main alternative /usr/share/images/vendor-logos -> /etc/alternatives/vendor-logos - Secondary alternatives /usr/share/icons/vendor/128x128/emblems: emblem-vendor.png -> /etc/alternatives/emblem-vendor-128 emblem-vendor-symbolic.png -> /etc/alternatives/emblem-vendor-symbolic-128 emblem-vendor-white.png -> /etc/alternatives/emblem-vendor-white-128 /usr/share/icons/vendor/256x256/emblems: emblem-vendor.png -> /etc/alternatives/emblem-vendor-256 emblem-vendor-symbolic.png -> /etc/alternatives/emblem-vendor-symbolic-256 emblem-vendor-white.png -> /etc/alternatives/emblem-vendor-white-256 /usr/share/icons/vendor/64x64/emblems: emblem-vendor.png -> /etc/alternatives/emblem-vendor-64 emblem-vendor-symbolic.png -> /etc/alternatives/emblem-vendor-symbolic-64 emblem-vendor-white.png -> /etc/alternatives/emblem-vendor-white-64 /usr/share/icons/vendor/scalable/emblems: emblem-vendor.svg -> /etc/alternatives/emblem-vendor-scalable emblem-vendor-symbolic.svg -> /etc/alternatives/emblem-vendor-symbolic-scalable emblem-vendor-white.svg -> /etc/alternatives/emblem-vendor-white-scalable 1.2.1. Debian logos icons Several sizes of logo icons are shipped: 64, 128, 256 and scalable (svg) They can be found in: /usr/share/icons/desktop-base/${size}x${size}/emblems/${emblem}.png /usr/share/icons/desktop-base/emblems/${emblem}.svg [Legacy] Several sizes of legacy logo icons are shipped: 16, 22, 32, 36, 48, 64, 128, 256 and scalable (svg) They can be found in: /usr/share/icons/hicolor/${size}x${size}/emblems/${emblem}.png /usr/share/icons/hicolor/${size}x${size}/emblems/${emblem}.icon /usr/share/icons/hicolor/scalable/emblems/${emblem}.svg /usr/share/icons/hicolor/scalable/emblems/${emblem}.icon These will be removed after buster. 1.2.2. Debian logos images The Debian logo images are shipped in: /usr/share/desktop-base/debian-logos/ A Debian security logo is also shipped in: /usr/share/pixmaps/debian-security.png 1.3. Desktop files /usr/share/desktop-base/debian-homepage.desktop /usr/share/desktop-base/debian-reference.desktop /usr/share/desktop-base/debian-security.desktop 1.4. Default configurations overrides desktop-base ships different files to override default theme configurations of various parts of the system and prefer the active Debian theme. See below « How to switch themes » for directions on how to configure these overridden defaults. - GRUB background and menu colors: /usr/share/desktop-base/grub_background.sh This alternative is used by /etc/grub.d/05_debian_theme provided by grub-common to correctly update the GRUB background with the Debian theme when running « update-grub ». - GNOME desktop wallpaper and lock screen: /usr/share/glib-2.0/schemas/10_desktop-base.gschema.override - Plasma 5 desktop wallpaper: /usr/share/plasma/shells/org.kde.plasma.desktop/contents/updates/desktop-base.js Plasma ensures this JavaScript script is run for every user once and only once for each Plasma version. It is run at user login time. See: https://userbase.kde.org/KDE_System_Administration/PlasmaDesktopScripting 1.5. Plymouth boot splashes desktop-base ships several Plymouth themes. To activate the default theme, install the plymouth and plymouth-themes packages and run: plymouth-set-default-theme homeworld and update the initrd by running: update-initramfs -u Then remember to add “splash” to your kernel command line. To do that permamently, edit /etc/default/grub and add splash to the GRUB_CMDLINE_LINUX_DEFAULT variable. For example: GRUB_CMDLINE_LINUX_DEFAULT="quiet splash" 2. How to switch themes 2.1. Global theme alternative The package provides a global alternative to switch themes all relevant elements to a given theme. This alternative is called « desktop-theme » and currently supports GRUB background, login manager background (SDDM, LightDM), Desktops wallpapers (GNOME, Plasma 5, Xfce, Mate…). You can change the theme pack selection with: update-alternatives --config desktop-theme Following a theme switch you’ll also need to run the GRUB menu update command: update-grub Plymouth theme switching is currently not supported inside theme packs so you’ll have to do it by hand for now with plymouth-set-default-theme command. 2.2. Individual alternatives In addition do the global theme alternative, desktop-base provides a series of finer grained alternatives to override specific elements of the theme packs. Each alternative can be switched with: update-alternative --config ${alternative-name} Selecting 0 will revert to the initial default of an alternative. Additional alternatives can be added with: update-alternatives --install ${target-file} \ ${alternative-name} \ ${alternative-file} ${priority} You may check the desktop-base postinst script for examples. The list of alternatives provided by desktop-base is explained below: - desktop-grub, alternative for: /usr/share/images/desktop-base/desktop-grub.png - desktop-grub.sh (sub-alternative of desktop-grub), alternative for: /usr/share/desktop-base/grub_background.sh The desktop-grub PNG file is used by the update-grub script to define the background for the GRUB boot menu. It defaults to the active theme selected via the desktop-theme alternative, and on top of that: - To the 16x9 / 1920x1080 version of the background for systems where EFI is in use (grub-efi installed). - To the 4x3 / 640x480 version otherwise. It’s possible to override this default behaviour by selecting the other ratio alternative pointing to /usr/share/desktop-base/active-theme/grub/* while still keeping the GRUB background automatically switching via the global desktop-theme alternative. The desktop-grub.sh script is sourced by update-grub to read the path to the background image and the menu colors to be used for grub. - desktop-login-background, alternative for: /usr/share/desktop-base/active-theme/login/background.svg This alternatives switches the login background for LightDM (default) and SDDM when the SDDM theme debian-theme is used (default when there’s no SDDM conf file). It defaults to the login background of the active theme selected via the desktop-theme alternative. - desktop-background, alternative for: /usr/share/images/desktop-base/desktop-background This is a single SVG file used by desktop environments that don’t require a more complex wallpaper setup (Xfce, MATE…). It defaults to the 1920x1080 version of the active theme wallpaper selected via the desktop-theme alternative. - desktop-background.xml, alternative for: /usr/share/images/desktop-base/desktop-background.xml - desktop-lockscreen.xml, alternative for: /usr/share/images/desktop-base/desktop-lockscreen.xml These two XML files are used by GNOME to set the wallpaper and lock screen for all users who didn’t otherwise chose a wallpaper or lock screen themselves. It defaults to the wallpaper and lock screen for the active theme selected via the desktop-theme alternative. - desktop-plasma5-wallpaper, alternative for: /usr/share/wallpapers/DebianTheme This alternative folder is used by Plasma 5 in Debian to select the wallpaper for all users who didn’t otherwise select a wallpaper themselves. It defaults to the wallpaper of the active theme selected via the desktop-theme alternative. 3. Theme pack structure A certain theme pack structure is expected in order to provide drop-in replacements for the default Debian theme that can be switched globally with the desktop-theme alternative. This paragraph describes the structure to mimic if you want to provide additional theme packs for Debian. A theme pack should contain the following elements: -> A section in the global package Makefile. You should be able to copy the section for an existing theme, just take care to replace all theme name occurrences with that of your new theme. At some point it would be desirable to have the Makefile parts inside each theme’s folders so the themes can be self contained, and the main Makefile will only have to detect the themes present in the sources. ./grub/Makefile ./grub/grub-4x3.svg ./grub/grub-16x9.svg -> SVG and Makefile used to produce the GRUB background images. The Makefile can be copy-pasted from and existing theme pack and should generate the PNGs corresponding to each SVG in the GRUB folder. For best compatibility grub-4x3.svg should generate a 640x480 PNG for used by system with classical BIOS. grub-16x9.svg should generate 1920x1080 PNG for used by more recent EFI firmwares. ./grub/grub_background.sh -> Shell file containing variables to configure GRUB. This file is sourced when running « update-grub ». ./plymouth/debian.png ./plymouth/logo.png … -> Assets used in the Plymouth splash screen ./plymouth/${theme}.plymouth -> Descriptor file for the Plymouth theme, a bit like .desktop files for applications. Copy and adapt to your needs. ./plymouth/${theme}.script -> Script handling everything plymouthy when splash is activated, from just after grub to display manager. It’s a massive amount of work to get everything right, including encrypted partitions password input, system messages, fsck feedback… so it’s highly recommended to start with an existing script and adapt the background setup and animation to the needs of your theme. ./login/background.svg -> To provide the login background alternative for LightDM, SDDM… ./gnome-wp-list.xml -> To make the wallpaper and lock screen selectable in GNOME preferences. This file describes a list of XML files, one for each image packs provided. GNOME uses these image packs to select the most appropriate version of a wallpaper depending on the user’s screen resolution. ./wallpaper/gnome-background.xml ./wallpaper/contents/images/2560x1440.svg ./wallpaper/contents/images/1280x720.svg ./wallpaper/contents/images/1920x1200.svg ./wallpaper/contents/images/1920x1080.svg ./wallpaper/contents/images/1280x800.svg ./wallpaper/contents/images/2560x1600.svg … ./wallpaper/metadata.desktop -> Wallpaper image pack, similar to the lock screen pack described above. ./lockscreen/gnome-background.xml ./lockscreen/contents/images ./lockscreen/contents/images/2560x1440.svg ./lockscreen/contents/images/1280x720.svg ./lockscreen/contents/images/1920x1080.svg … ./lockscreen/metadata.desktop -> Lock screen background image pack. The gnome-background.xml describes the available resolutions for the image, for use by GNOME. The metadata.desktop contains the description and license of the image pack for use by Plasma 5. The various files in the images folder are the provided resolutions and ratio of the image. They can be either PNG or SVG, and should be name according to their width and height as the example above so that Plasma 5 can select the correct version. There is no strict rule on which resolution and ratio should be provided and a single version could suffice as long as it’s appearance is not broken when cropped at different resolutions. ./sources -> Additional sources for theme elements that are not shipped as SVG in the binary package, or for visuals not strictly related to the desktop theme (CD covers, t-shirts…). 4. Contributing 4.1. Artists We need professional looking Debian artwork in the Desktop. If you want to help improve themes in Debian or provide additional theme proposals, you should monitor the Wiki page for artwork contests we run for each new Debian release: https://wiki.debian.org/DebianArt/Themes The debian-desktop mailing list (see below) is also a low-traffic source of information about what’s going on with desktop themes in Debian. If you’ve suggestions for a better artwork, create or edit the images and open a 'wishlist' bug against desktop-base in our Bug Tracking System (https://bugs.debian.org/). Please attach the source file, preferably in SVG or XCF format, and only propose work for which you’re the author. For us to be able to distribute your work in Debian, it will need to be under a free and open source licenses which permits reuse and modifications as required by the Debian Free Software Guidelines. See a more complete list of requirements here: https://wiki.debian.org/DebianDesktop/Artwork/Requirements 4.2. Desktop environment maintainers desktop-base is used by GNOME, KDE’s Plasma 5, Xfce, Mate… If you’re responsible for a desktop environment in Debian and want to use desktop-base artwork, improve the support for your DE, or add additional theming options use the layout described above and send your patch through the Bug Tracking System, or ping us on debian-desktop@lists.debian.org. We’re glad to help with theme packaging and improving the consistency of Debian themes over the desktop environments available in the archive. 4.3. Notes and references If you’re interested in working on Debian theming, you may be interested in the following references. - Information about the Debian Logo: https://www.debian.org/logos/ https://wiki.debian.org/DebianLogo - Archive and subscriptions to the debian-desktop mailing list: https://lists.debian.org/debian-desktop/