Ceci est une ancienne révision du document !
Complexifier la syntaxe du wiki est globalement mauvais, modifier les brouillons d'autrui aussi.
Vu la nomenclature des logiciels Gnome, il va en falloir beaucoup de la redirection "crochets/nom du logiciel qui redirige vers la page nommée d'après le paquet/crochets" si on veut pouvoir les documenter proprement et clairement, plutôt que de faire des "crochets/nom_page/barre/absolument n'importe quoi/crochets" dégueulasses partout.
Globalement à chaque fois que j'écris un article je me sens obligé de clarifier le vocabulaire, c'est pas complètement par hasard.
Tutoriel : programmer une extension Gnome Shell
Ce tutoriel concerne les personnes intéressées dans la programmation d'extensions Gnome Shell.
Les informations présentées ici sont normalement valables au moins pour les versions 3.18 à 3.24 de Gnome Shell.
J'ai appris à faire des extensions "en autodidacte" et mes conseils sont sans aucun doute perfectibles, je ne suis en aucun cas une autorité en la matière.
Introduction
Qu'est Gnome Shell ?
Le vocabulaire autour de Gnome/Gnome 3/Gnome Shell est parfois confus.
Gnome est un ensemble de logiciels libres formant un environnement de bureau. Depuis la version 3 de cet environnement, Gnome Shell constitue le shell graphique de l'environnement Gnome, c'est-à-dire qu'il fournit l'interface graphique venant se greffer autour du gestionnaire de fenêtres (nommé Mutter).
Tous les 6 mois, aux alentours de l'équinoxe, une version stable de Gnome est diffusée, numérotée 3.xx, où xx est un numéro pair. Les distributeurs (les personnes qui mettent à disposition les paquets des distributions) mettent alors quelques jours à quelques mois avant de proposer ces paquets aux utilisateurs.
Vous pouvez connaître votre version de Gnome Shell en tapant
gnome-shell --version
Le code de Gnome Shell
L'interface Gnome Shell a la particularité d'être codée en javascript. Ce code est ensuite interprété par un moteur de rendu nommé Gjs (basé sur le moteur de rendu javascript de Firefox).
Vous le savez peut-être, javascript a la particularité d'autoriser le monkeypatching, c'est-à-dire qu'une fonction du code peut être réécrite à un autre endroit du code, dynamiquement. On peut donc modifier l'aspect et le comportement de la quasi-totalité des composants de l'interface Gnome Shell !
On va d'abord se procurer le code source de l'interface par défaut :
Rendez-vous à l'adresse https://github.com/GNOME/gnome-shell/tree/gnome-3-xx
où xx est votre version de Gnome Shell, cliquez sur le bouton vert pour télécharger le code source au format .zip et décompressez-le avec un gestionnaire d'archives.
La partie du code qui nous intéresse est dans le dossier ./js/ui
, vous pouvez ne conserver que ce dossier là si le reste vous encombre. Je vous conseille d'ailleurs de changer les permissions de ce dossier pour le mettre en lecture seule : nous n'allons jamais ni le modifier ni l'exécuter.
Javascript
Ce tutoriel n'est pas un cours sur le javascript, il est conseillé de se familiariser préalablement avec ce langage, qui n'est heureusement pas le plus compliqué en ce monde.
Ce n'est pas ici que vous apprendrez la syntaxe des conditionnelles et des affectations, ceci dit les explications fournies devraient vous suffire à suivre même si vous débutez.
Pré-requis
Les crashs
On va ici "jouer" avec Gnome Shell lui-même. Il est très très probable qu'on le fasse crasher à un moment ou à un autre, et il va donc falloir sérieusement améliorer la résilience aux crashs de votre installation.
Voici quelques idées ou astuces pour cela :
En cas de crash du gestionnaire de fenêtre
Utilisez des applications avec des boutons de fenêtre "CSD", de manière à ce que vous ne perdiez pas totalement le contrôle sur vos fenêtres en cas de disparition des barres de fenêtres.
Un terminal comme Terminix peut être utile par exemple.
En cas de crash de Gnome Shell
Tout d'abord, ayez des icônes sur le bureau.
Dans ~/.local/share/nautilus/scripts
, créez un fichier "Remplacer Gnome Shell" contenant seulement les lignes suivantes :
#!/bin/bash gnome-shell -r
Vous pouvez maintenant entièrement recharger Gnome Shell à partir du menu "clic-droit" fournit par Nautilus sur les fichiers, et donc notamment sur le bureau.
En cas de crash total de la session graphique
Avec Ctrl+Alt+F2
, vous pouvez vous accédez à une console (tty2) où vous pouvez vous connecter en ligne de commande et par exemple annuler la manipulation ayant généré le crash en 1er lieu.
Si vous n'êtes pas à l'aise en ligne de commande, installez Weston, il vous servira d'environnement de secours pouvant être lancé sur tty2 (par exemple) avec la commande weston
(cela utilise Wayland, et peut donc être lancé en parallèle d'un environnement sur Xorg).
Tester et débugguer
J'admets ne pas être un grand expert en débuggage, il existe probablement mieux que ce que je suggère ici.
Avec Alt+F2
, on trouve une fenêtre pour lancer des commandes. Cette fenêtre accepte des commandes "spéciales" internes à Gnome Shell.
Recharger
La commande r
recharge Gnome Shell, cela peut prendre quelques instants.
Les extensions notamment sont rechargées depuis le début, comme si l'ordinateur venait d'être allumé.
Looking Glass
La commande lg
ouvre Looking Glass, un outil dont on reparlera plus tard.
Voir les logs "en direct"
Entrer dans un terminal la commande
gnome-shell -r
C'est beaucoup plus "violent" que de simplement recharger Gnome Shell, et donc plus long. Toutes les erreurs émises entre autres par les extensions, mais aussi les messages ou les avertissements, apparaissent maintenant dans le terminal.
Pour pouvoir quitter le terminal, utilisez simplement le script qu'on a créé plus haut.
Un premier exemple
On peut créer une extension en forkant une extension existante, mais pour commencer, nous allons utiliser la méthode "classique" en lançant la commande
gnome-shell-extension-tool --create-extension
On vous demande un nom, une description et un identifiant ("uuid"). L'identifiant est souvent au format nom-extension@pseudo
, inspirez-vous des identifiants d'extensions existants dans ~/.local/share/gnome-shell/extensions/
(mettez ce dossier dans vos signets Nautilus d'ailleurs).
Analysons les fichiers ainsi créés (~/.local/share/gnome-shell/extensions/
votre-uuid/
) :
metadata.json
Ce fichier est obligatoire pour qu'une extension soit reconnue par Gnome Shell.
Entre accolades, on a une liste de propriétés au format "clef": valeur
séparées par des virgules.
Pour l'instant, il y a les clefs :
uuid
: obligatoire, doit correspondre au nom du dossier ;name
: obligatoire, apparaît dans gnome-tweak-tool ;description
: obligatoire, apparaît dans gnome-tweak-tool ;shell-version
: un tableau (array) de valeurs entre guillemets séparées par des virgules. Ce sont les versions de Gnome Shell que vous déclarez supporter. Cela aide les utilisateurs à faire leur "tri" sur le site officiel, mais avec les réglages d'Ubuntu par défaut, une extension peut être installée même sur une version non supportée.
extension.js
Ce fichier est obligatoire pour qu'une extension soit reconnue par Gnome Shell.
const St = imports.gi.St;
Le fichier commence par l'importation de ce dont on va se servir dans l'extension.
St (Shell Toolkit) fournit un certain nombre de composants indispensables (des entrées de texte, des labels, des icônes, des boutons, …).
De plus, tous les fichiers javascript correspondant au code source de l'interface (ui) Gnome Shell sont importables dans le code : ici, on rend accessibles le contenu de main.js et tweener.js (correspond aux animations).
const Main = imports.ui.main; const Tweener = imports.ui.tweener;
let text, button; function init() { button = new St.Bin({ style_class: 'panel-button', reactive: true, can_focus: true, x_fill: true, y_fill: false, track_hover: true }); let icon = new St.Icon({ icon_name: 'system-run-symbolic', style_class: 'system-status-icon' }); button.set_child(icon); button.connect('button-press-event', _showHello); }
Le code ci-dessus est appelé au démarrage de Gnome Shell, même si l'extension est désactivée. La fonction init ne doit donc JAMAIS modifier l'interface graphique ni son comportement. Ici, la variable button précédemment créée a simplement été initialisée (voir la documentation de St pour plus de détails sur la signification des paramètres nécessaires), et connectée à la fonction _showHello qu'on verra plus loin.
function enable() { Main.panel._rightBox.insert_child_at_index(button, 0); } function disable() { Main.panel._rightBox.remove_child(button); }
La fonction enable
est appelée si l'extension est activée. Elle apporte les modifications à l'interface. Toutes ces modifications doivent être annulées par la fonction disable
, qui est appelé quand on désactive une extension.
Ici, la modification consiste à ajouter un bouton en forme d'engrenage dans le panneau supérieur, le bouton étant celui qu'on a initialisé tout à l'heure. Cliquer sur le bouton déclenche la fonction suivante :
function _showHello() { if (!text) { text = new St.Label({ style_class: 'helloworld-label', text: "Hello, world!" }); Main.uiGroup.add_actor(text); } text.opacity = 255; let monitor = Main.layoutManager.primaryMonitor; text.set_position(monitor.x + Math.floor(monitor.width / 2 - text.width / 2), monitor.y + Math.floor(monitor.height / 2 - text.height / 2)); Tweener.addTween(text, { opacity: 0, time: 2, transition: 'easeOutQuad', onComplete: _hideHello }); }
Ici, on a plusieurs concepts intéressants : celui d'acteur, qui est lié à la bibliothèque Clutter. St est en fait une "surcouche" qui permet de rendre Clutter plus facile d'utilisation pour les usages courants de Gnome Shell, et d'uniformiser la manière d'y appliquer des thèmes.
Clutter fonctionne par la manipulation d'objets en 2D, nommés "acteurs", à l'intérieur d'un espace simulé en 3D. La classe de base d'un acteur est "ClutterActor", et tous les acteurs peuvent être positionnés, redimensionnés et tournés dans l'espace en 3D. La transparence est aussi gérée. Une transformation appliquée à l'acteur "parent" sera appliquée à ses acteurs "enfants". Voir la vraie documentation pour plus de détails.
Remarquez qu'on a appliqué à text
une propriété relative au style : vous trouverez une classe helloworld-label
dans le fichier stylesheet.css
Tweener concerne les animations, ici, on a une animation de disparition en fondu qui dure 2 secondes (d'ailleurs, si dans gnome-tweak-tool on désactive les animations, le bouton n'a plus aucun effet visible puisque le label disparaît sitôt apparu), animation à la fin de laquelle on appelle _hideHello
function _hideHello() { Main.uiGroup.remove_actor(text); text = null; }
C'était donc le fonctionnement de l'extension "Hello, World". Maintenant, on va chercher à faire une extension utile.
stylesheet.css
Ce fichier n'est pas obligatoire. Il gère le style de l'extension en utilisant le langage CSS.
Créons une vraie extension
Une idée
extension.js
S'adapter à l'utilisateur
Ajouter des paramètres
Ajouter des langues
prefs.js
Autre exemple d'extension
Ce dont je n'ai pas parlé ici
Parce que je préfère ne parler que de ce que je comprends à peu près, je n'ai pas abordé certains aspects du développement d'extensions pourtant très puissants. En voici quelques uns :
Clutter
Tweener
DBus
Publier l'extension
Un site de partage de code
Il est conseillé de publier le code sur une plateforme comme GitHub ou BitBucket, afin que d'autres personnes puissent collaborer au code source.
Le dépôt GitHub peut faire office de page de présentation de votre extension, l'onglet "Issues" permet de discuter des bugs ou des idées d'amélioration avec les utilisateurs de votre extension, et il est probable que des pull requests contenant notamment des traductions soient soumises à votre approbation.
La plateforme officielle
Quelques passionnés découvriront sans doute votre extension sur GitHub à un moment donné, mais pour que tous les utilisateurs trouvent votre extension si ils en ont besoin, il vous sera nécessaire de vous inscrire sur extensions.gnome.org et de cliquer sur "Add yours".
Le site vous demande un fichier votre@uuid.zip
contenant directement au moins les fichiers extension.js
et metadata.json
; soyez bien conscient que tout le code sera relu, et qu'il faut donc qu'il soit propre et compréhensible. Après validation (généralement, ça prend moins d'une semaine, vous serez averti par mail), vous pourrez ajouter une capture d'écran et un icône à la page de votre extension.
Pour mettre à jour l'extension, ne vous préoccupez pas du numéro de version dans metadata.json
(il change automatiquement), contentez-vous de ré-uploader un fichier votre@uuid.zip
selon exactement la même méthode. Si l'identifiant de l'extension est le même, le site sait qu'il faudra mettre à jour la page existante, et la mise à jour de l'extension sera proposée aux utilisateurs.