Manifestes d'installation

Un article de MDC.

[modifier] Introduction

Un manifeste d'installation est un fichier contenant les informations nécessaires au gestionnaire d'extensions pour installer le module complémentaire. Il contient des informations identifiant le module, sur l'auteur, l'endroit où trouver plus d'informations, la compatibilité avec les différentes versions des applications, comment il doit être mis à jour, etc.

Les manifestes d'installation sont des fichiers au format RDF/XML.

Le fichier doit être appelé install.rdf et être placé à la racine du fichier XPI du module.

[modifier] Structure

La structure de base d'un manifeste d'installation ressemble à ceci :

<?xml version="1.0"?>

<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:em="http://www.mozilla.org/2004/em-rdf#">
  <Description about="urn:mozilla:install-manifest">
    <!-- propriétés -->
  </Description>
</RDF>

Certaines propriétés sont obligatoires, d'autres facultatives. Certaines ont pour valeurs de simples chaînes de caractères, d'autres des ressources complexes.

[modifier] Propriétés obligatoires

Votre manifeste d'installation doit contenir ces propriétés, sinon votre extension risque de ne pas pouvoir s'installer.

[modifier] id

L'identifiant de l'extension, qui est :

• Un GUID (généré avec guidgen sous Windows, uuidgen avec un système Linux et makeuuid sous Solaris) (Firefox 1.0)
• Nouveau dans Firefox 1.5 Une chaîne de type : extensionname@organization.tld

Le second format est plus simple à générer et à manipuler. Firefox 1.5 vérifie que l'identifiant correspond à l'un des deux formats et refuse d'installer l'extension si l'identifiant est mal formé.

Exemples

<em:id>monextension@monsite.com</em:id>

<em:id>{daf44bf7-a45e-4450-979c-91cf07434c3d}</em:id>

[modifier] version

Une chaîne de version identifiant la version du module complémantaire fournie.

Pour Firefox/Thundebird 1.0, le format doit être conforme aux règles spécifiées dans Extension Versioning, Update and Compatibility. Pour Firefox/Thundebird 1.5, consultez Formats de versions pour le toolkit.

Exemples

<em:version>2.0</em:version>

<em:version>1.0.2</em:version>

<em:version>0.4.1.2005090112</em:version>

Firefox 1.5 / XULRunner 1.8 — les modules n'utilisant pas un format de version valide ne seront pas installés. Le format de version est sous une forme différente, bien que rétrocompatible, que sous la version 1.0 de Firefox.

Pour les modules hébergés sur addons.mozilla.org — Le site Mozilla Update peut réempaqueter votre module et corriger ou rejeter les chaînes de version mal formées.

[modifier] type

Une valeur entière qui représente le type d'extension.

Exemple

<em:type>2</em:type>

Nouveau dans Firefox 1.5 Cette propriété a été ajoutée à Firefox 1.5, et n'est obligatoire que pour les modules complémentaires autres que les extensions et les thèmes.

Nouveau dans Firefox 3 Firefox 2 et précédents acceptaient une valeur de 16 pour représenter des plugins. Celle-ci a été retirée dans Firefox 3.

[modifier] targetApplication

Un objet spécifiant l'application cible pour ce module complémentaire. Cela signifie que le module fonctionnera avec l'application identifiée par la propriété id (<em:id>) spécifiée, depuis la version minimale (<em:minVersion>) jusque et y compris la version maximale (<em:maxVersion>). Vous disposez d'une liste d'ID sur Versions valides de l'application. Ces chaînes de version sont au même format que la propriété version et seront comparées avec la version de l'application. Ceci permet par exemple à un auteur d'extension de préciser avec quelles versions de Firefox une extension a été testée.

Note : Les versions de Firefox 1.0 à 1.0.6 ont toutes une version d'application de 1.0. Les mises à jour de sécurité et de stabilité de Firefox 1.5 ont une version d'application de 1.5.0.1, 1.5.0.2, etc. Les extensions compatibles avec Firefox ou Thunderbird 1.5 doivent donc spécifier un paramètre maxVersion de 1.5.0.* afin d'être automatiquement compatibles avec ces mises à jour de sécurité et de stabilité.

Les extensions compatibles avec Firefox 2 doivent spécifier un paramètre maxVersion de 2.0.0.*

Le manifeste d'installation doit spécifier au moins un de ces objets, et peut en spécifier plus si le module est destiné à plusieurs applications disposant du gestionnaire d'extensions (par exemple Firefox et Thunderbird)

Exemples

<em:targetApplication>
 <Description>
  <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id> 
  <em:minVersion>1.5</em:minVersion>
  <em:maxVersion>2.0.0.*</em:maxVersion>
 </Description>
</em:targetApplication>

Nouveau dans Firefox 3 Les applications basées sur Gecko 1.9 permettent d'utiliser l'id spécial toolkit@mozilla.org comme valeur de targetApplication pour indiquer que le module est compatible avec toute application toolkit dont la version du toolkit est entre minVersion et maxVersion.

[modifier] name

Le nom du module complémentaire, prévu pour être affiché dans l'interface utilisateur.

Exemple

<em:name>Mon Extension</em:name>

[modifier] Propriétés facultatives

En fonction des possibilités de votre extension, vous devrez peut-être préciser ces propriétés.

[modifier] localized

Nouveau dans Firefox 3 Permet de localiser le nom du module, sa description, ses contributeurs et d'autres métadonnées. La description localisée doit spécifier au moins un code em:locale indiquant les locales pour lesquelles cette information doit être utilisée.

Exemples

Ce code déclare un ensemble de métadonnées sur le module à afficher lorsque l'application s'exécute dans la locale de.

<em:localized>
  <Description>
    <em:locale>de</em:locale>
    <em:name>Tab Sidebar</em:name>
    <em:description>Zeigt in einer Sidebar Vorschaubilder der Inhalte aller offenen Tabs an.</em:description>
  </Description>
</em:localized>

Les propriétés suivantes qui sont décrites ailleurs dans cette page peuvent être utilisées dans la propriété localized :

• name
• description
• creator
• homepageURL
• developer
• translator
• contributor

De la documentation supplémentaire se trouve dans Localisation des descriptions d'extensions.

[modifier] description

Une courte description de l'extension qui est supposée s'afficher sur l'interface utilisateur. Cette description doit tenir sur une courte ligne de texte.

Exemples

<em:description>Outils avancés foo.</em:description>

[modifier] creator

Le nom du créateur/principal développeur — destiné à être affiché dans l'interface utilisateur.

Exemples

<em:creator>John Doe</em:creator>

ou

<em:creator>Équipe CoolExtension</em:creator>

[modifier] developer

Nouveau dans Firefox 2 Le ou les noms des co-développeurs. Vous pouvez définir une ou plusieurs valeurs s'il y a plusieurs développeurs.

Exemples

<em:developer>Jane Doe</em:developer>
<em:developer>Koos van der Merwe</em:developer>

[modifier] translator

Nouveau dans Firefox 2 Le ou les noms des traducteurs. Vous pouvez définir une ou plusieurs valeurs s'il y a plusieurs traducteurs.

Exemples

<em:translator>Janez Novak</em:translator>
<em:translator>Kari Nordmann</em:translator>

[modifier] contributor

Les noms des contributeurs supplémentaires. Vous pouvez définir un ou plusieurs noms s'il y a plusieurs contributeurs.

Exemples

<em:contributor>John Doe</em:contributor>

<em:contributor>John Doe</em:contributor>
<em:contributor>Jane Doe</em:contributor>
<em:contributor>Elvis Presley</em:contributor>

[modifier] homepageURL

Un lien hypertexte vers la page d'accueil de l'extension - prévu pour s'afficher sur l'interface utilisateur.

Exemples

<em:homepageURL>http://www.foo.com/</em:homepageURL>

[modifier] updateURL

Un lien vers un fichier manifeste indiquant ces mises à jour disponibles pour cette extension. Le format est décrit ci-dessous. S'il est activé, le gestionnaire d'extensions testera périodiquement ce fichier manifeste pour déterminer si de nouvelles versions sont disponibles.

Nouveau dans Firefox 3 Pour les applications Gecko 1.9, si un champ updateURL est spécifié il doit obligatoirement être une URL https, ou une clé de mise à jour doit être fournie pour des raisons de sécurité.

Votre serveur doit transmettre ce fichier avec le type text/rdf sinon le vérificateur des mises à jour ne fonctionnera pas. Le type text/xml semble également fonctionner (les projets sur mozdev.org).

Le gestionnaire d'extensions peut substituer les valeurs suivantes dans cette URL si vous souhaitez générer la réponse RDF dynamiquement grâce à un script PHP ou CGI :

Exemples

<em:updateURL>http://www.foo.com/update.cgi?id=%ITEM_ID%&amp;version=%ITEM_VERSION%</em:updateURL>
<em:updateURL>http://www.foo.com/extension/windows.rdf</em:updateURL>

Pour les extensions hébergées sur addons.mozilla.org : Il n'est pas utile de définir une propriété updateURL. Par défaut, les applications Mozilla utilisant le gestionnaire d'extension (telles que Firefox et Thunderbird) envoient leurs requêtes de mises à jour vers addons.mozilla.org en utilisant le service Web par défaut. À chaque fois que vous mettez en ligne une nouvelle version de votre extension ou que vous changez ses paramètres de compatibilités à travers l'interface d'auteurs, votre manifeste de mise à jour sera automatiquement généré.

Format du manifeste de mise à jour : Le manifeste de mise à jour est formé d'une source de données RDF/XML . Pour obtenir des exemples d'un manifeste de mise à jour, consultez Versions d'une extension, mise à jour et compatibilité et http://roachfiend.com/archives/2005/03/09/enabling-extension-updates/.

[modifier] updateKey

Pour s'assurer de la sécurité des données du RDF de mise à jour qui sont obtenues au travers du simple protocole HTTP, il est nécessaire d'utiliser une signature numérique afin de vérifier le contenu de ces données. Pour ce faire, vous devez fournir la partie publique de la clé cryptographique dans une entrée updateKey du fichier install.rdf du module complémentaire. Celle-ci peut être générée à l'aide de l'outil McCoy. Les éventuels sauts de ligne et espaces faisant partie de cette entrée seront ignorés.

Exemples

<em:updateKey>MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDK426erD/H3XtsjvaB5+PJqbhj
Zc9EDI5OCJS8R3FIObJ9ZHJK1TXeaE7JWqt9WUmBWTEFvwS+FI9vWu8058N9CHhD
NyeP6i4LuUYjTURnn7Yw/IgzyIJ2oKsYa32RuxAyteqAWqPT/J63wBixIeCxmysf
awB/zH4KaPiY3vnrzQIDAQAB</em:updateKey>

[modifier] optionsURL

L'URL chrome:// de la boîte de dialogue des options de l'extension. Cette adresse n'a d'utilité que pour les extensions. Lorsque cette propriété est définie, alors le bouton Options affichera cette boîte de dialogue pour l'extension sélectionnée dans le gestionnaire d'extensions.

Exemples

<em:optionsURL>chrome://myext/content/options.xul</em:optionsURL>

[modifier] aboutURL

L'URL chrome:// de la boîte de dialogue « À propos » de l'extension. Cette adresse n'a d'utilité que pour les extensions. Lorsque cette propriété est définie, alors le lien « À propos de…» du menu contextuel de l'extension sélectionnée dans le gestionnaire d'extensions affichera cette boîte de dialogue plutôt que celle par défaut.

Exemples

<em:aboutURL>chrome://myext/content/about.xul</em:aboutURL>

[modifier] iconURL

Une URL chrome:// vers un icône 32x32 s'affichant dans la liste du gestionnaire d'extensions. Si cette propriété n'est pas définie, un icône par défaut sera utilisé.

<em:iconURL>chrome://myext/skin/icon.png</em:iconURL>

Note : Pour que l'exemple ci-dessus fonctionne, vous devez également ajouter une ligne skin package à votre fichier chrome.manifest. Voyez pour cela Enregistrement_chrome#skin_2. Vous pouvez également placer votre icône dans le répertoire spécifié dans la ligne content package.

[modifier] hidden

Une valeur booléenne indiquant si l'extension doit ou non s'afficher dans la liste des modules complémentaires. Elle est prévue pour les extensions installées dans une zone d'accès restreint (et ne fonctionnera donc pas pour les modules installés dans le profil). Elle sert aux fonctions d'intégration d'applications plus importantes pour lesquelles l'inscription d'une entrée dans la liste des extensions n'a aucun sens.

Exemples

<em:hidden>true</em:hidden>

[modifier] targetPlatform

Nouveau dans Firefox 1.5 Une chaîne de caractères définissant une plateforme supportée par l'extension. Elle contient soit la valeur de OS_TARGET seule ou soit cette valeur combinée avec TARGET_XPCOM_ABI séparée par un séparateur (_).

OS_TARGET est typiquement le résultat de la commande 'uname -s" d'une plateforme cible, par exemple :

• WINNT pour Windows NT, 2000, XP et suivant
• Linux pour toutes les versions de Linux
• Darwin pour toutes les versions de MacOS X
• SunOS pour toutes les versions de Solaris

Vous pouvez préciser plusieurs propriétés targetPlatform dans un manifeste. Si au moins une des valeurs correspond aux paramètres de compilation de l'application, l'extension sera installée, sinon l'utilisateur obtiendra un message d'erreur approprié.

Exemples

<em:targetPlatform>WINNT_x86-msvc</em:targetPlatform>
 
<em:targetPlatform>Linux</em:targetPlatform>
 
<em:targetPlatform>Darwin_ppc-gcc3</em:targetPlatform>
 
<em:targetPlatform>SunOS_sparc-sunc</em:targetPlatform>

Habituellement, vous n'utiliserez la spécification du système d'exploitation que pour des thèmes ou pour des extensions qui ne sont pas complètement multiplateformes. Pour des extensions incluant des composants binaires (compilés), vous ne devriez jamais utiliser l'OS seul, mais l'inclure dans les ABI avec lesquels vos composants ont été compilés. Si vous souhaitez inclure plusieurs versions des composants, vous devrez également utiliser des sous-répertoires spécifiques à une plateforme.

Notes

• Dans le même fichier manifeste, vous pouvez mélanger des valeurs avec et sans ABI. Si une valeur de système d'exploitation de l'application est rencontrée en lien avec une ABI spécifique, l'ABI sera considéré comme étant importante pour cet OS et l'application refusera d'installer l'extension si la combinaison OS/ABI n'est pas exactement trouvée. Ainsi, si tous les exemples du dessus étaient dans un manifeste, l'extension s'installerait sur n'importe quelle compilation de Linux, indépendamment de son ABI, mais pas sur une compilation Cygwin sous Windows.

• Il existe des compilations de Firefox et Thunderbird qui ne « connaissent » pas leur ABI (souvent des portages sur des plateformes rares, ou des compilations non officielles). Ces compilations refuseront d'installer toutes extensions nécessitant une ABI spécifique à leur plateforme.

Cette propriété a été ajoutée pour Firefox/Thunderbird 1.5. Les versions antérieures de ces applications ignoraient les restrictions et installaient l'extension quelle que soit la plateforme.

[modifier] requires

Nouveau dans Firefox 2 Cette balise a une syntaxe similaire à <em:targetApplication>. Si le module spécifié par la balise <em:id> n'est pas installé ou qu'il a une version incompatible, le gestionnaire d'extensions désactivera votre module et affichera le message « Requires additional items ». Vous pouvez ajouter autant de balises <em:requires> que vous voulez. Votre extension sera désactivée si au moins une des conditions spécifiées n'est pas remplie.

Exemple

<em:requires>
   <Description>
     <!-- Lightning -->
     <em:id>{e2fda1a4-762b-4020-b5ad-a41df1933103}</em:id>
     <em:minVersion>0.5pre</em:minVersion>
     <em:maxVersion>0.5pre</em:maxVersion>
   </Description>
 </em:requires>

Notes

• Actuellement, seuls <em:id>, <em:minVersion> et <em:maxVersion> sont analysés dans la balise <em:requires>.
• Il n'est actuellement pas possible d'ajouter des dépendances spécifiques à une <em:targetApplication>. Voir wikimo:Extension Manager:Extension Dependencies pour plus de détails.

Cette propriété a été ajoutée à Firefox/Thunderbird 2. Les versions précédentes de ces applications ignoreront les restrictions et installeront le module complémentaire sans prendre en compte les conditions.

[modifier] Référence des propriétés obsolètes

Ces propriétés étaient requises dans les anciennes versions du gestionnaire d'extensions, mais elles ont été remplacées avec des mécanismes nouveaux et plus performants.

[modifier] file

Firefox 1.0 Cette propriété pointait vers un fichier chrome .jar qui contenait les paquetages chrome nécessitant un enregistrement dans le registre Chrome.

La propriété <em:file> a une valeur complexe. l'URI de la valeur est urn:mozilla:extension:file:jarFile.jar où jarFile.jar a le même nom que le fichier jar contenant les fichiers du paquetage chrome. Elle peut aussi être le nom d'un répertoire contenant les fichiers du paquetage chrome, non-jarré (par exemple urn:mozilla:extension:file:directory). Dans les deux cas, le ou les fichiers référencés du paquetage chrome doivent être placés dans le sous-répertoire chrome à la racine du XPI.

Cet objet a une propriété package (avec le chemin du fichier jar ou du répertoire situant l'emplacement du fichier contents.rdf responsable de l'enregistrement du paquetage), une propriété locale (idem, mais pour l'enregistrement de la localisation) et une propriété skin (idem, mais pour l'enregistrement du thème graphique).

Avec les extensions pour Firefox 1.5, cette propriété n'est plus nécessaire. Le fichier chrome.manifest situé à la racine du XPI est utilisé pour localiser le chrome à enregistrer. S'il n'existe aucun fichier chrome.manifest, cette propriété continuera alors à être lue par le gestionnaire d'extensions et un chrome.manifest sera généré à partir de l'ancienne forme contents.rdf.

Exemples

<em:file>
 <Description about="urn:mozilla:extension:file:myext.jar">
  <em:package>content/myext/</em:package>
  <em:locale>locale/en-US/myext/</em:locale>
  <em:skin>skin/classic/myext/<em:skin>
 </Description>
</em:file>

Un manifeste d'installation peut définir plusieurs propriétés file, une pour chaque fichier jar ou sous-répertoire contenant des chrome à enregistrer.

[modifier] Glossaire

[modifier] zone d'accès restreint

Une zone d'accès restreint est un emplacement d'installation qui peut faire partie d'un compte à accès restreint, qu'il soit ou non réellement limité par les privilèges de l'utilisateur courant (consultez nsIInstallLocation::restricted). Pour l'instant, le dossier ($APPDIR)/extensions et l'emplacement d'installation du registre sous HKEY_LOCAL_MACHINE (voir Ajout d'extensions à l'aide du registre Windows pour plus de détails) sont des zones d'accès restreint.

Les emplacements d'installation ($PROFILE)/extensions et HKEY_CURRENT_USER, d'un autre côté, ne sont pas considérés comme des zones d'accès restreint.